User Tools

Site Tools


DNS configuration

The dns configuration is located in /etc/config/dhcp and controls both DNS and DHCP server options on the device (both DHCP and DNS services are implemented using dnsmasq).

In the default configuration this file contains one common section to specify DNS and daemon related options and one or more DHCP pools to define DHCP serving on network interfaces.


Possible section types of the dhcp configuration file are defined below. Not all types may appear in the file and most of them are only needed for special configurations. The common ones are the Common Options, the DHCP Pools and Static Leases.

Common Options

The config section type dnsmasq determines values and options relevant to the overall operation of dnsmasq and the DHCP options on all interfaces served. The following table lists all available options, their default value, as well as the corresponding dnsmasq command line option. See the dnsmasq man page for further details.

These are the default settings for the common options:

config 'dnsmasq'
    option  local               '/lan/'
    option  domain              'lan'
    option  leasefile           '/tmp/dhcp.leases'
    option  resolvfile          '/tmp/'
    option  domainneeded        1
    option  boguspriv           1
    option  filterwin2k         0
    option  localise_queries    1
    option  rebind_protection   1
    option  rebind_localhost    0
    option  expandhosts         1
    option  nonegcache          0
    option  authoritative       1
    option  readethers          1
  • Options:
    • local and domain enable dnsmasq to serve entries in /etc/hosts, as well as DHCP client's names if configured under lan domain.
    • domainneeded, boguspriv, localise_queries, and expandhosts ensure requests for local host names are not forwarded to upstream DNS servers.
    • authoritative makes router the only DHCP server on this network; clients get their IP lease a lot faster this way.
    • leasefile stores leases in a file so they can be picked up again if dnsmasq is restarted.
    • resolvfile tells dnsmasq to use this file to find upstream name servers; it gets created by the WAN DHCP or PPP client.
    • enable_tftp and tftp_root turn on the TFTP server and serve files from tftp_root.
      • May need to set server's IP on client, changing it by setting serverip (e.g. setenv serverip

All Options

Name Type Default Option Description
add_local_domain boolean 1 Add the local domain as search directive in resolv.conf.
add_local_hostname boolean 1 Add A, AAAA, & PTR records only on DHCP served LAN.
:!: enhanced function available on Trunk with option add_local_fqdn
add_local_fqdn integer 1 Add A, AAAA, & PTR records only on DHCP served LAN.
:!: add_local_fqdn on Trunk but not 17.01.0
0: Disable.
1: Hostname on Primary Address.
2: Hostname on All Addresses.
3: FDQN on All Addresses.
4: on All Addresses.
add_wan_fqdn integer 0 Labels WAN interfaces like add_local_fqdn instead of your ISP assigned default which may be obscure. WAN is inferred from config dhcp sections with option ignore 1 set, so they do not need to be named WAN
:!: add_wan_fqdn on Trunk but not 17.01.0
addnhosts list of file paths (none) -H Additional host files to read for serving DNS responses
authoritative boolean 1 -K Force dnsmasq into authoritative mode. This speeds up DHCP leasing. Used if this is the only server on the network
bogusnxdomain list of IP addresses (none) -B IP addresses to convert into NXDOMAIN responses (to counteract “helpful” upstream DNS servers that never return NXDOMAIN).
boguspriv boolean 0 -b Reject reverse lookups to private IP ranges where no corresponding entry exists in /etc/hosts
cachelocal boolean 1 When set to 0, use each network interface's dns address in the local /etc/resolv.conf. Normally, only the loopback address is used, and all queries go through dnsmasq.
cachesize integer 150 -c Size of dnsmasq query cache.
dbus boolean 0 -1 Enable DBus messaging for dnsmasq.
:!: Standard builds of dnsmasq on OpenWrt do not include DBus support.
dhcp_boot string (none) --dhcp-boot Specifies BOOTP options, in most cases just the file name. You can also use: “file name, tftp server name, tftp ip address
dhcphostsfile file path (none) --dhcp-hostsfile Specify an external file with per host DHCP options
dhcpleasemax integer 150 -X Maximum number of DHCP leases
dnsforwardmax integer 150 -0 (zero) Maximum number of concurrent connections
domain domain name (none) -s DNS domain handed out to DHCP clients
domainneeded boolean 1 -D Tells dnsmasq never to forward queries for plain names, without dots or domain parts, to upstream nameservers. If the name is not known from /etc/hosts or DHCP then a “not found” answer is returned
dnssec boolean 0 --dnssec Validate DNS replies and cache DNSSEC data.
:!: Requires the dnsmasq-full package.
dnsseccheckunsigned boolean 0 --dnssec-check-unsigned Check the zones of unsigned replies to ensure that unsigned replies are allowed in those zones. This protects against an attacker forging unsigned replies for signed DNS zones, but is slower and requires that the nameservers upstream of dnsmasq are DNSSEC-capable.
:!: Requires the dnsmasq-full package.
:!: Caution: If you use this option on a device that doesn't have a hardware clock, dns resolution may break after a reboot of the device due to an incorrect system time.
ednspacket_max integer 1280 -P Specify the largest EDNS.0 UDP packet which is supported by the DNS forwarder
enable_tftp boolean 0 --enable-tftp Enable the builtin TFTP server
expandhosts boolean 1 -E Add the local domain part to names found in /etc/hosts
filterwin2k boolean 0 -f Do not forward requests that cannot be answered by public name servers
fqdn boolean 0 --dhcp-fqdn Do not resolve unqualifed local hostnames. Needs domain to be set.
interface list of interface names (all interfaces) -i List of interfaces to listen on. If unspecified, dnsmasq will listen to all interfaces except those listed in notinterface. Note that dnsmasq listens on loopback by default.
leasefile file path (none) -l (ell) Store DHCP leases in this file
local string (none) -S Look up DNS entries for this domain from /etc/hosts. This follows the same syntax as server entries, see the man page.
localise_queries boolean 0 -y Choose IP address to match the incoming interface if multiple addresses are assigned to a host name in /etc/hosts. :!: Note well the spelling of this option.
localservice boolean 1 --local-service Accept DNS queries only from hosts whose address is on a local subnet, ie a subnet for which an interface exists on the server.
logqueries boolean 0 -q Log the results of DNS queries, dump cache on SIGUSR1
nodaemon boolean 0 -d Don't daemonize the dnsmasq process
nohosts boolean 0 -h Don't read DNS names from /etc/hosts
nonegcache boolean 0 -N Disable caching of negative “no such domain” responses
noresolv boolean 0 -R Don't read upstream servers from /etc/resolv.conf
notinterface list of interface names (none) -I (eye) Interfaces dnsmasq should not listen on.
nonwildcard boolean 0 -z Bind only configured interface addresses, instead of the wildcard address.
port port number 53 -p Listening port for DNS queries, disables DNS server functionality if set to 0
queryport integer (none) -Q Use a fixed port for outbound DNS queries
readethers boolean 0 -Z Read static lease entries from /etc/ethers, re-read on SIGHUP
rebind_protection boolean 1 --stop-dns-rebind Enables DNS rebind attack protection by discarding upstream RFC1918 responses
rebind_localhost boolean 0 --rebind-localhost-ok Allows upstream responses, required for DNS based blacklist services, only takes effect if rebind protection is enabled
rebind_domain list of domain names (none) --rebind-domain-ok List of domains to allow RFC1918 responses for, only takes effect if rebind protection is enabled
resolvfile file path /etc/resolv.conf -r Specifies an alternative resolv file
server list of strings (none) -S List of DNS servers to forward requests to. See the dnsmasq man page for syntax details.
strictorder boolean 0 -o Obey order of DNS servers in /etc/resolv.conf
tftp_root directory path (none) --tftp-root Specifies the TFTP root directory

Using plain dnsmasq.conf

It is possible to mix the traditional /etc/dnsmasq.conf configuration file with the options found in /etc/config/dhcp.

The dnsmasq.conf file does not exist by default but will be processed by dnsmasq on startup if it is present.

  • NOTE: Options in /etc/config/dhcp take precendence over dnsmasq.conf since they are translated to command line arguments.

You can have dnsmasq execute a script on every action: dhcp-script = /sbin/

DNS Ports

DNS needs TCP and UDP port 53 open on the firewall. See Guest WLAN and dnsmasq Man (viz –dhcp-alternate-port) for more information.


Custom Domain

Define a custom domain name and the corresponding PTR record - assigns the IP address to the domain name typhoon and construct an appropriate reverse record It works like an entry in /etc/hosts but more flexible and integrated.

:!: Note that this currently only works for IPv4 addresses and that this functionality is not present in release prior to 8.09.2 .

:!: Note that reverse records are not properly generated at present. (Barrier Breaker 14.07-RC2)

config 'domain'
    option  name    'typhoon'
    option  ip

another example: redirect

    # resolves to 
config 'domain'
    option  name    ''
    option  ip


To define an SRV record for SIP over UDP, with the default port of 5060 on the host, with a class of 0 and a weight of 10 one would use:

config 'srvhost'
    option  srv       ''
    option  target    ''
    option  port      5060
    option  class     0
    option  weight    10


A Canonical Name record specifes that a domain name is an alias for another domain, the “canonical” domain. To specify that the web server also doubles as the FTP server, one might use:

config 'cname'
    option  cname     ''
    option  target    ''

Note that it is necessary to use fully qualified domain names.


If you're running the mail server for your domain behind a firewall (and therefore, with split-horizon for your own domain) then you might need to convince that mailer that it's actually authoritative for your domain.

If sendmail tells you “Domain of sender address xxx@yyy.zzz does not exist” this is because it isn't finding an MX record confirming that it's an MX relay for that domain.


config 'mxhost'
    option  domain    'yyy.zzz'
    option  relay     ''
    option  pref      10

will mitigate the issues caused by split-horizon.


Direct BOOTP requests to the TFTP server at the IP address and use /tftpboot/pxelinux.0 as boot file name.

config 'boot'
    option  filename        'pxelinux.0'
    option  servername      'data'
    option  serveraddress

Multiple DHCP/DNS server/forwarder instances

If you need multiple DNS forwarders with different configurations or DHCP server with different sets of lease files, have a look at this: multiple_dhcpdns_serverforwarder_instances

The web interface (luci) has not been updated for this PR yet.

Enabling DNS without enabling DHCP

dnsmasq can be used to provide clients with a DNS server, but not with DHCP (for example, if DHCP is already supplied by a separate server).

  1. dnsmasq must be turned on for the internal interface:
    1. Network → Interfaces: Click desired internal interface to select it
    2. DHCP Server: Click Setup DHCP Server, which enables both DHCP and DNS
  2. DHCP portion of dnsmasq needs to be turned off.
    1. Network → Interfaces: Click desired internal interface to select it
    2. DHCP Server: Enable option Ignore interface
    3. Save & Apply

This change will turn off just DHCP but leave DNS services available on the specified interface.

Several DNS servers

  # NOTE:
    # Some options should be absent, or set to 0, to allow 
    # forwarding towards private networks ('boguspriv')
      # See: 

config dnsmasq
    option  local                 '/lan/'
    option  domain                'lan'
    option  leasefile             '/tmp/dhcp.leases'
    option  resolvfile            '/tmp/'
    list    server                '/'
    list    server                '/'
    option  domainneeded          1
    option  localise_queries      1
    option  expandhosts           1
    option  authoritative         1
    option  readethers            1
    option  rebind_protection     0

Conditional DNS Forwarding for Windows Active Directory Domains / DNS Dependent Directory Based Authentication Services

  1. Install dnsmasq using your local package manager
  2. Edit /etc/dnsmasq.conf
    1. Tells dnsmasq to forward anything with the domain of remote.local to DNS server (example)
      • server = /remote.local/
    2. Listen only to requests coming from the local machine
      • listen-address =
    3. Do not cache anything
      • cache-size = 0
  3. Edit /etc/resolv.conf
    1. Local LAN Domain
      • hostname.lan
    2. local dnsmasq server
      • nameserver
    3. Your main dns server (dnsmasq will forward all requests to this example server)
      • nameserver
  4. Start dnsmasq
  5. Test: Ping a local server and remote server using the FQDN
    • All DNS requests will be forwarded to, except any matching *.remote.local. server.remote.local will be forwarded to
    # Define Domain and Domain Controller IPs via 'list server'

config dnsmasq
    option  domain              'example.local'
    option  leasefile           '/tmp/dhcp.leases'
    option  resolvfile          '/etc/resolv.conf'
    option  local               '/example.local/192.168.1.X'
    list    server              '/'
    list    server              '/'
    list    server              '/'
    list    server              '/'
    option  localise_queries    1
    option  rebind_protection   0
    option  authoritative       1
    option  localservice        1
    option  dnssec              0
    option  cachesize           0
    option  readethers          1
    option  logqueries          1
    option  fliterwin2k         1 
    option  boguspriv           1

config dhcp 'lan'
    option  interface           'lan'
    option  start               100
    option  limit               150
    option  leasetime           '12h'

Now on to the finalization of the /etc/resolv.conf Traditionally /etc/resolv.conf is populated via symlink based on interface settings which get inserted via script into /tmp/resolv.conf. We're going to disable this symlink because without doing so it would override our static settings.

You'll want to remove /etc/resolv.conf That will remove the resolv.conf symlink. Then we will add the ip address of the secondary DNS and external resolving address inside the /etc/resolv.conf file finally establishing conditional forwarding, something that should be specified for easy configuration via the GUI.

rm /etc/resolv.conf

echo "domain example.local" >> /etc/resolv.conf
echo "nameserver" >> /etc/resolv.conf
echo "nameserver" >> /etc/resolv.conf
    # Define Domain & Public DNS below. 

domain        example.local
docs/guide-user/base-system/dns_configuration.txt · Last modified: 2019/03/26 07:42 by vgaetera