The dnsmasq and dhcpd 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 the same OpenWrt program, 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.
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 domainneeded 1 option boguspriv 1 option filterwin2k 0 option localise_queries 1 option rebind_protection 1 option rebind_localhost 0 option local '/lan/' option domain 'lan' option expandhosts 1 option nonegcache 0 option authoritative 1 option readethers 1 option leasefile '/tmp/dhcp.leases' option resolvfile '/tmp/resolv.conf.auto'
domainenable dnsmasq to serve entries in
/etc/hostsas well as the DHCP client's names as if they were entered into the lan DNS domain.
expandhostsmake sure that requests for these local host names (and the reverse lookup) never get forwarded to the upstream DNS servers.
authoritativemakes the router the only DHCP server on this network; clients get their IP lease a lot faster this way.
leasefilestores the leases in a file, so that they can be picked up again if dnsmasq is restarted.
resolvfiletells dnsmasq to use this file to find upstream name servers; it gets created by the WAN DHCP client or the PPP client.
| ||boolean|| ||Add the local domain as search directive in resolv.conf.|
| ||boolean|| ||Add A and PTR records automatically for the local hostname.|
| ||list of file paths||(none)|| ||Additional host files to read for serving DNS responses|
| ||boolean|| || ||Force dnsmasq into authoritative mode. This speeds up DHCP leasing. Used if this is the only server on the network|
| ||list of IP addresses||(none)|| ||IP addresses to convert into NXDOMAIN responses (to counteract "helpful" upstream DNS servers that never return NXDOMAIN).|
| ||boolean|| || || Reject reverse lookups to private IP ranges where no corresponding entry exists in
| ||boolean|| || When set to
| ||integer|| || ||Size of dnsmasq query cache.|
| ||boolean|| || || Enable DBus messaging for dnsmasq.
Standard builds of dnsmasq on OpenWRT do not include DBus support.
|Specifies BOOTP options, in most cases just the file name|
| ||file path||(none)|| |
|Specify an external file with per host DHCP options|
| ||integer|| || ||Maximum number of DHCP leases|
| ||integer|| || ||Maximum number of concurrent connections|
| ||domain name||(none)|| ||DNS domain handed out to DHCP clients|
| ||boolean|| || ||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|
| ||boolean|| || |
| Validate DNS replies and cache DNSSEC data.
Requires the dnsmasq-full package.
| ||boolean|| || |
| 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.
| ||integer|| || ||Specify the largest EDNS.0 UDP packet which is supported by the DNS forwarder|
| ||boolean|| || |
|Enable the builtin TFTP server|
| ||boolean|| || || Add the local domain part to names found in
| ||boolean|| || ||Do not forward requests that cannot be answered by public name servers|
| ||boolean|| || |
| Do not resolve unqualifed local hostnames. Needs
| ||list of interface names||(all interfaces)|| || List of interfaces to listen on. If unspecified, dnsmasq will listen to all interfaces except those listed in
| ||file path||(none)|| ||Store DHCP leases in this file|
| ||string||(none)|| || Look up DNS entries for this domain from
| ||boolean|| || || Choose IP address to match the incoming interface if multiple addresses are assigned to a host name in
| ||boolean|| || |
|Accept DNS queries only from hosts whose address is on a local subnet, ie a subnet for which an interface exists on the server.|
| ||boolean|| || ||Log the results of DNS queries, dump cache on SIGUSR1|
| ||boolean|| || ||Don't daemonize the dnsmasq process|
| ||boolean|| || || Don't read DNS names from
| ||boolean|| || ||Disable caching of negative "no such domain" responses|
| ||boolean|| || || Don't read upstream servers from
| ||list of interface names||(none)|| ||Interfaces dnsmasq should not listen on.|
| ||boolean|| || ||Bind only configured interface addresses, instead of the wildcard address.|
| ||port number|| || || Listening port for DNS queries, disables DNS server functionality if set to
| ||integer||(none)|| ||Use a fixed port for outbound DNS queries|
| ||boolean|| || || Read static lease entries from
| ||boolean|| || |
|Enables DNS rebind attack protection by discarding upstream RFC1918 responses|
| ||boolean|| || |
|Allows upstream 127.0.0.0/8 responses, required for DNS based blacklist services, only takes effect if rebind protection is enabled|
| ||list of domain names||(none)|| |
|List of domains to allow RFC1918 responses for, only takes effect if rebind protection is enabled|
| ||file path|| || ||Specifies an alternative resolv file|
| ||list of strings||(none)|| ||List of DNS servers to forward requests to. See the dnsmasq man page for syntax details.|
| ||boolean|| || || Obey order of DNS servers in
| ||directory path||(none)|| |
|Specifies the TFTP root directory|
Sections of the type
dhcp specify per interface lease pools and settings for serving DHCP requests.
Typically there is at least one section of this type present in the
/etc/config/dhcp file to cover the lan interface.
You can disable a lease pool for a specific interface by specifying the
ignore option in the corresponding section.
A minimal example of a
dhcp section is listed below:
config 'dhcp' 'lan' option 'interface' 'lan' option 'start' '100' option 'limit' '150' option 'leasetime' '12h' option ra server option dhcpv6 server
lanspecifies the OpenWrt interface that is served by this DHCP pool
100is the offset from the network address, in the default configuration
150is the maximum number of addresses that may be leased, in the default configuration
12hspecifies the time to live for handed out leases, twelve hours in this example
serverdefines the mode for IPv6 configuration (RA & DHCPv6)
Below is a listing of legal options for
| ||list of strings||no||(none)||The ID dhcp_option here must be with written with an underscore. OpenWrt will translate this to –dhcp-option, with a hyphen, as ultimately used by dnsmasq. Multiple option values can be given for this network-id, with a a space between them and the total string between "". E.g. '26,1470' or 'option:mtu, 1470' that can assign an MTU per DHCP. Your client must accept MTU by DHCP for this to work. Or "3,192.168.1.1 6,192.168.1.1" to give out gateway and dns server addresses.|
| ||boolean||no|| || Dynamically allocate client addresses, if set to
| ||boolean||no|| ||Forces DHCP serving on the specified interface even if another DHCP server is detected on the same network segment|
| ||boolean||no|| || Specifies whether dnsmasq should ignore this pool if set to
| ||string||no|| || Specifies whether DHCPv6 server should be enabled (
| ||string||no|| || Specifies whether Router Advertisements should be enabled (
| ||string||no|| || Specifies whether NDP should be relayed
| ||boolean||no||0||Specifies whether DHCPv6, RA and NDP in relay mode is a master interface or not.|
| ||logical interface name||yes||(none)|| Specifies the interface associated with this DHCP address pool; must be one of the interfaces defined in
| ||string||yes|| || Specifies the lease time of addresses handed out to clients, for example
| ||integer||yes|| ||Specifies the maximum allowable address that may be leased to clients, calculated as network address + "start" + "limit". The maximum number of leased addresses is limit+1|
| ||string||no|| (value of ||The dhcp functionality defined in the dhcp section is limited to the interface indicated here through its network-id. In case omitted the system tries to know the network-id via the 'interface' setting in this dhcp section, through consultation of /etc/config/network. Some IDs get assigned dynamically, are not provided by network, but still can be set here.|
| ||integer||yes|| ||Specifies the offset from the network address of the underlying interface to calculate the minimum address that may be leased to clients. It may be greater than 255 to span subnets.|
This departs from 'ifname' and 'network' as used in /etc/config/network and in /etc/config/wireless, so double check!
You can assign fixed IP addresses to hosts on your network, based on their MAC (hardware) address.
The configuration options in this section are used to construct a
-G option for dnsmasq.
config host option ip '192.168.1.2' option mac '00:11:22:33:44:55' option name 'mypc'This adds the fixed IP address 192.168.1.2 and the name "mypc" for a machine with the (Ethernet) hardware address 00:11:22:33:44:55.
config host option ip '192.168.1.3' option mac '11:22:33:44:55:66,aa:bb:cc:dd:ee:ff' option name 'mylaptop'This adds the fixed IP address 192.168.1.3 and the name "mylaptop" for a machine with the (Ethernet) hardware address 11:22:33:44:55:66 or aa:bb:cc:dd:ee:ff. Note that this is unreliable if more than one of the listed mac addresses is on the network simultaneously. It's useful for cases such as a laptop with both wireless and wired interfaces, provided that only one will be active at a given time.
| ||string||yes||(none)||'ignore' or the IP address to be used for this host.|
| ||string||no||(none)||The hardware address(es) of this host, separated by commas.|
| ||string||no||(none)||The IPv6 interface identifier (address suffix) as hexadecimal number (max. 8 chars)|
| ||string||no||(none)||The DHCPv6-DUID of this host.|
| ||string||no||(none)||Optional hostname to assign.|
| ||string||no||(none)||Set the given tag for matching hosts.|
| ||boolean||no|| ||Add static forward and reverse DNS entries for this host.|
| ||boolean||no|| ||Force broadcast DHCP response.|
As well as adding
host sections, you can also enable the
dnsmasq section option
readethers, and add entries to the
You can specify an alternative default Gateway
config 'dhcp' 'lan' option 'interface' 'lan' option 'start' '100' option 'limit' '150' option 'leasetime' '12h' list 'dhcp_option' '3,192.168.1.2'
use the list 'dhcp_option' '3,192.168.1.2' to set the default gateway. A list of options can be found here here
Some hosts support booting over the network. DHCP/BOOTP is used to tell the host which file to boot and the server to load it from. Each client can only receive one set of filename and server address options. If different hosts should boot different files, or boot from different servers, you can use network-ids to map options to each client.
Usually, you need to set additional DHCP options (through
dhcp_option) for further stages of the boot process. See the dnsmasq man page for details on the syntax of the
The configuration options in this section are used to construct a
-M option for dnsmasq.
config boot linux option filename '/tftpboot/pxelinux.0' option serveraddress '192.168.1.2' option servername 'fileserver' list dhcp_option 'option:root-path,192.168.1.2:/data/netboot/root'This tells the client to load pxelinux.0 from the server at 192.168.1.2, and mount root from /data/netboot/root on the same server.
| ||list of strings||no||(none)||Additional options to be added for this network-id. If you specify this, you also need to specify the network-id.|
| ||string||yes||(none)||The filename the host should request from the boot server.|
| ||string||no||(none)||The network-id these boot options should apply to. Applies to all clients if left unspecified.|
| ||string||yes||(none)||The IP address of the boot server.|
| ||string||yes||(none)||The hostname of the boot server.|
DHCP can provide the client with numerous options, such as the domain name, NTP servers, network booting options, etc. While some settings are applicable to all hosts in a network segment, other are more specific and apply only to a group of hosts, or even only a single one. dnsmasq offers to group DHCP options and their values by a network-id, an alphanumeric identifier, and sending options only to hosts which have been tagged with that network-id.
In OpenWrt, you can tag hosts by the DHCP range they're in (section
dhcp), or a number of options the client might send with their DHCP request. In each of these sections, you can use the
dhcp_option list to add DHCP options to be sent to hosts with this network-id.
Each classifying section has two configuration options: the value of the DHCP option used to distinguish clients, and the network-id that these clients should be tagged with. Here's a template:
option classifier 'value'
option networkid 'network-id'
list dhcp_option 'DHCP-option'
classifier can be one of these values:
| ||Hardware address of the client|
| ||String sent by the client representing the vendor of the client. dnsmasq performs a substring match on the vendor class string using this value.|
| ||String sent by the client representing the user of the client. dnsmasq performs a substring match on the user class string using this value.|
| ||Matches the circuit ID as sent by the relay agent, as defined in RFC3046.|
| ||Matches the remote ID as sent by the relay agent, as defined in RFC3046.|
| ||Matches the subscriber ID as sent by the relay agent, as defined in RFC3993.|
An example using the 'mac' classifier to create a tagged network for openvpn would look like this in the config file:
config mac 'opnvpn' option mac '00:FF:*:*:*:*' option networkid 'opnvpn' list dhcp_option '3'
And like this in UCI
dhcp.opnvpn=mac dhcp.opnvpn.mac=00:FF:*:*:*:* dhcp.opnvpn.networkid=opnvpn dhcp.opnvpn.dhcp_option=3
DHCP-option adds a DHCP option for this network-id. See the dnsmsq man page for a complete explanation of the syntax of the
It is possible to mix the traditional
/etc/dnsmasq.conf configuration file with the options found in
dnsmasq.conf file does not exist by default but will be processed by dnsmasq on startup if it is present. Note that 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:
DNS needs TCP and UDP port 53 open on the firewall. DHCP needs UDP ports 67 and 68 open from your zone to/from the firewall. See http://wiki.openwrt.org/doc/recipes/guest-wlan and http://www.thekelleys.org.uk/dnsmasq/docs/dnsmasq-man.html (viz "–dhcp-alternate-port") for more information.
Define a static lease for a host with MAC addresses
00:11:22:33:44:55 (handy when you use both wired and wireless connection on the same computer/laptop - of course, you can use just one MAC address) and assign the IP address
192.168.1.230 and the hostname
example-host to it. We call this MAC address hot swap, since IP address stay same, but MAC address changes.
config 'host' option 'name' 'example-host' option 'ip' '192.168.1.230' option 'mac' '00:a0:24:5a:33:69 00:11:22:33:44:55'
Windows 7 has introduced a new Microsoft-enhanced feature. It won't assign IP address obtained from a DHCP server to an interface, if the IP was used before for another interface, even if that other interface is NOT active currently (i.e. cable disconnected). This behaviour is unique and was not reported for older Windows versions, Mac OS nor Linux.
If you try configure MAC address hot swap on your router, Windows 7 clients will end up in an infinite DORA loop.
config 'host' option 'name' 'example-host' option 'ip' '192.168.1.230' option 'mac' '00:a0:24:5a:33:69 00:11:22:33:44:55 02:a0:24:5a:33:69 02:11:22:33:44:55'
If you want to distribute IPv4 addresses to known clients only (static leases), use:
config dhcp 'lan' ... option dynamicdhcp 0
With this, dnsmasq will consider static leases defined in "config host" blocks and in /etc/ethers, and refuse to hand out any IPv4 address to unknown clients.
Note that you shouldn't use this as a security feature to prevent unwanted clients from connecting. A client can simply configure a static IP in the right range to have access to the network.
Define a custom domain name and the corresponding PTR record - assigns the IP address
192.168.1.140 to the domain name
typhoon and construct an appropriate reverse record
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' '192.168.1.140'
To define an SRV record for SIP over UDP, with the default port of 5060 on the host pbx.mydomain.com, with a class of 0 and a weight of 10 one would use:
config 'srvhost' option srv '_sip._udp.mydomain.com' option target 'pbx.mydomain.com' option port 5060 option class 0 option weight 10
To specify that the web server also doubles as the FTP server (at least in name), one might use:
config 'cname' option cname 'ftp' option target 'www'
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 firstname.lastname@example.org 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 'my.host.com' option pref 10
will mitigate the issues caused by split-horizon.
Direct BOOTP requests to the TFTP server at the IP address
192.168.1.2 and use
/tftpboot/pxelinux.0 as boot file name.
config 'boot' option 'filename' 'pxelinux.0' option 'servername' 'data' option 'serveraddress' '192.168.1.2'
Multiple DHCP options can be configured under a single dhcp_option object. In this case, option 66 (tftp-server) and option 150 (multiple tftp servers) were used for a Cisco Callmanager deployment.
config 'dhcp' 'lan' option 'interface' 'lan' option 'start' '62' option 'limit' '192' option 'leasetime' '600h' list 'dhcp_option' '66,172.16.60.64' list 'dhcp_option' '150,172.16.60.64'
If you need multiple DNS forwarders with different configurations or DHCP server with different sets of lease files, have a look at this patch. Multiple dnsmasq "named" instances can be configured:
config 'dnsmasq' 'hotspot' option nonwildcard '1' # Tell dnsmasq to bind specific address(es) option resolvfile '/tmp/resolv.conf.hotspot' ...
Your configs are usally active for all instances, but you can limit them to single instances by:
config 'dhcp' 'lan' option 'interface' 'lan' option 'dnsmasq_config' 'hotspot' config 'host' option 'name' 'chef' option 'mac' '00:00:00:00:00:00' option 'ip' '192.168.1.66' option 'dnsmasq_config' 'hotspot'
The web interface (luci) has not been updated for this patch yet.
In DHCP pool limit setting, the start and limit values do *not* refer to the "last digit", they're relative offsets to the network address.
config dhcp lan option interface lan option start 1441793 option limit 253Test:
root@OpenWrt:~# ipcalc.sh 10.0.0.1 255.0.0.0 1441793 253 IP=10.0.0.1 NETMASK=255.0.0.0 BROADCAST=10.255.255.255 NETWORK=10.0.0.0 PREFIX=8 START=10.22.0.1 END=10.22.0.254 root@OpenWrt:~#
Assign different dhcp-options to a single MAC address:
uci batch <<'EOF' add dhcp mac set dhcp.@mac[-1].mac=00:11:22:33:44:55 set dhcp.@mac[-1].networkid=someone add_list dhcp.@mac[-1].dhcp_option=6,192.168.1.3,192.168.1.2,192.168.1.1 add_list dhcp.@mac[-1].dhcp_option=3,192.168.1.2 add_list dhcp.@mac[-1].dhcp_option=44,192.168.1.3 commit dhcp EOF uci commit dhcp /etc/init.d/dnsmasq reloadWhere 6=DNS, 3=Default Gateway, 44=WINS
Assign different dhcp-options to multiple hosts:
config host option name 'j400' option mac '00:21:63:75:aa:17' option ip '10.11.12.14' option tag 'vpn' # assign tag "vpn" to this host config host option name 'j500' option mac '01:22:64:76:bb:18' option ip '10.11.12.15' option tag 'vpn' # assign tag "vpn" to this host config tag 'vpn' # match tag "vpn" list dhcp_option '6,188.8.131.52,184.108.40.206' # assign arbritary extra dhcp options to this tag
Convert to procd: etc/init.d/dnsmasq restart
This is useful when you just want to hand out addresses to clients, without doing any DNS.
config dnsmasq ... option port 0 option domain ''
The second option prevents dnsmasq from giving out a domain name and DNS search list to clients: this is useless without DNS resolving.
Of course, you will want to hand out the address of a DNS resolver to clients:
config dhcp lan option interface lan ... list dhcp_option "6,220.127.116.11,6,18.104.22.168" list dns "2001:913::8" list dns "2001:910:800::12"
The `dhcp_option` entry is meant for dnsmasq, while the more elegant `dns` entries are understood by odhcpd. By default, odhcpd is only used for IPv6, but if you also use odhcpd for IPv4, you can just use `dns` entries for everything.
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).
First, dnsmasq must be turned on for the internal interface:
Now that dnsmasq is enabled, the DHCP portion of dnsmasq needs to be turned off.
This change will turn off just DHCP but leave DNS services available on the specified interface.
config dnsmasq option domainneeded '1' option localise_queries '1' option local '/lan/' option domain 'lan' option expandhosts '1' option authoritative '1' option readethers '1' option leasefile '/tmp/dhcp.leases' option resolvfile '/tmp/resolv.conf.auto' list server '/subdomain.example.com/192.0.2.1' #be careful that some options should be absent (or set to False) #to allow the forwarding towards the "so defined" private networks #http://en.wikipedia.org/wiki/Private_network list server '/example.com/22.214.171.124' option rebind_protection '0'