Learn DNS and DHCP Configuration with ease

1. DNS and DHCP configuration
The dnsmasq configuration is located in /etc/config/dhcp and controls both DNS and DHCP server options on the device. 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.
Sections
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 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'
 Options local and domain enable dnsmasq to serve entries in /etc/hosts as well as the DHCP client's names as if they were
entered into the lan DNS domain.
 Options domainneeded, boguspriv, localise_queries, and expandhosts make sure that requests for these local host names
(and the reverse lookup) never get forwarded to the upstream DNS servers.
 Option authoritative makes the router the only DHCP server on this network; clients get their IP lease a lot faster this way.
 Option leasefile stores the leases in a file, so that they can be picked up again if dnsmasq is restarted.
 Option resolvfile tells dnsmasq to use this file to find upstream name servers; it gets created by the WAN DHCP client or
the PPP client.
Name Type Required Default Option Description
addnhosts
list of file
paths
no (none) -H
Additional host files to read for serving DNS
responses
authoritative boolean no 0 -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
no (none) -B
IP addresses to convert into NXDOMAIN responses
(to counteract "helpful" upstream DNS servers that
never return NXDOMAIN).
boguspriv boolean no 0 -b
Reject reverse lookups to private IP ranges where no
corresponding entry exists in /etc/hosts
cachelocal boolean no 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 no 150 -c Size of dnsmasq query cache.
dbus boolean no 0 -1
Enable DBus messaging for dnsmasq.
Standard builds of dnsmasq on OpenWRT do not
include DBus support.
dhcp_boot string no (none) --dhcp-boot
Specifies BOOTP options, in most cases just the file
name
dhcphostsfile file path no (none)
--dhcp-
hostsfile Specify an external file with per host DHCP options
dhcpleasemax integer no 150 -X Maximum number of DHCP leases
dnsforwardmax integer no 150 -0 (zero) Maximum number of concurrent connections
domain
domain
name
no (none)' -s DNS domain handed out to DHCP clients
domainneeded boolean no 0 -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

2. Name Type Required Default Option Description
ednspacket_max integer no 1280 -P
Specify the largest EDNS.0 UDP packet which is
supported by the DNS forwarder
enable_tftp boolean no 0
--enable-
tftp Enable the builtin TFTP server
expandhosts boolean no 0 -E
Add the local domain part to names found in
/etc/hosts
filterwin2k boolean no 0 -f
Do not forward requests that cannot be answered by
public name servers
interface
list of
interface
names
no (all interfaces) -i
List of interfaces to listen on. If unspecified,
dnsmasq will listen to all interfaces except those
listed in notinterface.
leasefile file path no (none) -l (ell) Store DHCP leases in this file
local string no (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 no 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.
logqueries boolean no 0 -q
Log the results of DNS queries, dump cache on
SIGUSR1
nodaemon boolean no 0 -d Don't daemonize the dnsmasq process
nohosts boolean no 0 -h Don't read DNS names from /etc/hosts
nonegcache boolean no 0 -N
Disable caching of negative "no such domain"
responses
noresolv boolean no 0 -R
Don't read upstream servers from
/etc/resolv.conf
notinterface
list of
interface
names
no (none) -I (eye) Interfaces dnsmasq should not listen on.
nonwildcard boolean no 0 -z
Bind only configured interface addresses, instead of
the wildcard address.
port
port
number
no 53 -p
Listening port for DNS queries, disables DNS server
functionality if set to 0
queryport integer no (none) -Q Use a fixed port for outbound DNS queries
readethers boolean no 0 -Z
Read static lease entries from /etc/ethers, re-read
on SIGHUP
resolvfile file path no /etc/resolv.conf -r Specifies an alternative resolv file
server
list of
strings
no (none) -S
List of DNS servers to forward requests to. See the
dnsmasq man page for syntax details.
strictorder boolean no 0 -o Obey order of DNS servers in /etc/resolv.conf
tftp_root
directory
path
no (none) --tftp-root Specifies the TFTP root directory
rebind_protection boolean no 1
--stop-dns-
rebind
Enables DNS rebind attack protection by discarding
upstream RFC1918 responses
rebind_localhost boolean no 0
--rebind-
localhost-
ok
Allows upstream 127.0.0.0/8 responses, required for
DNS based blacklist services, only takes effect if
rebind protection is enabled
rebind_domain
list of
domain
names
no (none)
--rebind-
domain-ok
List of domains to allow RFC1918 responses for,
only takes effect if rebind protection is enabled
DHCP Pools
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'
 lan specifies the OpenWrt interface that is served by this DHCP pool
 100 is the offset from the network address, in the default configuration 192.168.1.100
 150 is the maximum number of addresses that may be leased, in the default configuration 192.168.1.250
 12h specifies the time to live for handed out leases, twelve hours in this example
Below is a listing of legal options for dhcp sections.

3. Name Type Required Default Description
dhcp_option list of strings no (none)
Additional options to be added for this network-id. For example with '26,1470'
or 'option:mtu, 1470' you can assign an MTU per DHCP. Your client must
accept MTU by DHCP for this to work
dynamicdhcp boolean no 1
Dynamically allocate client addresses, if set to 0 only clients present in the
ethers files are served
force boolean no 0
Forces DHCP serving on the specified interface even if another DHCP server
is detected on the same network segment
ignore boolean no 0 Specifies whether dnsmasq should ignore this pool if set to 1
interface
logical
interface
name
yes (none)
Specifies the interface associated with this DHCP address pool; must be one of
the interfaces defined in /etc/config/network
leasetime string yes 12h
Specifies the lease time of addresses handed out to clients, for example 12h or
30m
limit integer yes 150
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
networkid string no
(value of
interface)
Assigns a network-id to all clients that obtain an IP address from this pool.
start integer yes 100
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.
Static Leases
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
Name Type Required Default Description
ip string yes (none) The IP address to be used for this host.
mac string yes (none) The hardware address of this host.
name string no (none) Optional hostname to assign.
As well as adding host sections, you can also enable the dnsmasq section option readethers, and add entries to the /etc/ethers
file.
Note: uci requires you to specify MAC address(es) of mypc client, however dnsmasq itself don't. IP address is then assigned to DHCP
client according to the name he uses, not the MAC address he has. If you decide to go this way, you will need to edit
/etc/dnsmasq.conf file. Details can be found in dnsmasq man page in --dhcp-host description. See the ticket for updates.
DHCP OPTION example to set an alternative default gateway
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
Booting Options
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 O option.
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'

4. 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.
Name Type Required Default Description
dhcp_option
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.
filename string yes (none) The filename the host should request from the boot server.
networkid string no (none)
The network-id these boot options should apply to. Applies to all clients if left
unspecified.
serveraddress string yes (none) The IP address of the boot server.
servername string yes (none) The hostname of the boot server.
Classifying Clients And Assigning Individual Options
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:
config classifier option classifier 'value' option networkid 'network-id' list dhcp_option 'DHCP-option'
The placeholder classifier can be one of these values:
Classifier Description
mac Hardware address of the client
vendorclass
String sent by the client representing the vendor of the client. dnsmasq performs a substring match on the vendor class
string using this value.
userclass
String sent by the client representing the user of the client. dnsmasq performs a substring match on the user class string
using this value.
circuitid Matches the circuit ID as sent by the relay agent, as defined in RFC3046.
remoteid Matches the remote ID as sent by the relay agent, as defined in RFC3046.
subscrid Matches the subscriber ID as sent by the relay agent, as defined in RFC3993.
DHCP-option adds a DHCP option for this network-id. See the dnsmsq man page for a complete explanation of the syntax of the -O
option.
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 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:
dhcp-script=/sbin/action.sh
Examples
Static Lease (MAC address hot swap)
Define a static lease for a host with MAC addresses 00:a0:24:5a:33:69 and 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'
Troubleshooting
Windows 7 has bringed new Microsoft-enhanced feature. It won't assign IP address obtained from DHCP server to an interface, if
the IP was used before for another interface, despite the another interface is NOT active currently (i.e. cable is out). 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 infinite DORA loop.

5. Solution:
1. Create bridge from wireless and ethernet interface on your client
o its trivial, google it
o you will have to add MAC address of the bridge to /etc/config/dhcp
 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'
o Since the bridge will probably take and alter your ethernet MAC address, you will loose SLAAC on wifi interface,
making your laptop IPv6-disabled when only wireless is up.
2. Another solution is IPv6 friendly, but it involves user interaction, but you dont need to create network bridge nor add MAC
address to dnsmasq config file.
o When you plug-in ethernet cable, disable wireless interface in control panel (power off wireless won't do it).
o When you unplug ethernet cable, enable wireless and disable ethernet.
o Its not that painful if you don't have to do it every day.
Notes:
 http://answers.microsoft.com/en-us/windows/forum/windows_7-networking/windows-7-refuses-dhcp-addresses-if-they-
were/1b72b289-0f58-492f-afb8-e76c80a81f00
Custom Domain
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 140.1.168.192.in-addr.arpa.
Note that this currently only works for IPv4 addresses and that this functionality is not present in release prior to 8.09.2 .
config 'domain'
option 'name' 'typhoon'
option 'ip' '192.168.1.140'
SRV RR for SIP
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
CNAME RR
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'
MX RR
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.
Adding:
config 'mxhost'
option domain 'yyy.zzz'
option relay 'my.host.com'
option pref 10
will mitigate the issues caused by split-horizon.
TFTP Boot
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

6. 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'
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
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.
Assigning DHCP pool to a subnet in a large network
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.
 the network address of 10.0.0.1 / 255.0.0.0 is 10.0.0.0
 the 10.22.0.1 start address is 22 x /16 subnets away: (2^16) * 22 = 1441792
 10.0.0.0 + 1441792 + 1 = 10.22.0.1 → start = 1441793
 10.22.0.254 - 10.22.0.1 = 253 → limit = 253
config dhcp lan
option interface lan
option start 1441793
option limit 253
Test:
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:~#