User Tools

Site Tools


DNS and DHCP configuration examples


This guide provides most common Dnsmasq and odhcpd tuning scenarios adapted for OpenWrt.

Static leases

Add a fixed IPv4 address, IPv6 interface identifier (address suffix) 123 and name mydesktop for a machine with the MAC address 11:22:33:44:55:66 or aa:bb:cc:dd:ee:ff and DUID 000100004fd454041c6f65d26f43.

uci add dhcp host
uci set dhcp.@host[-1].name="mydesktop"
uci set dhcp.@host[-1].mac="11:22:33:44:55:66 aa:bb:cc:dd:ee:ff"
uci set dhcp.@host[-1].ip=""
uci set dhcp.@host[-1].duid="000100004fd454041c6f65d26f43"
uci set dhcp.@host[-1].hostid="123"
uci commit dhcp
/etc/init.d/dnsmasq restart
/etc/init.d/odhcpd restart

Reconnect your clients to apply the changes.

Add multiple host entries, one per MAC address or DUID, if you plan connect more than one interface simultaneously, otherwise it's unreliable.

See also: odhcpd leases

MAC filtering

If you want to distribute IPv4 addresses to known clients only (static leases), use:

uci set dhcp.lan.dynamicdhcp="0"
uci commit dhcp
/etc/init.d/dnsmasq restart

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.

DHCP options

DHCP options can be configured under via dhcp_option. Use an alternative default gateway, DNS server and NTP server.

uci add_list dhcp.lan.dhcp_option="3,"
uci add_list dhcp.lan.dhcp_option="6,"
uci add_list dhcp.lan.dhcp_option="42,"
uci commit dhcp
/etc/init.d/dnsmasq restart

A list of options can be found here.

Client classifying and individual options

An example using the mac classifier to create a tagged network for VPN to assign different DHCP options. Use custom default gateway and DNS, disable WINS.

uci set dhcp.mac_vpn="mac"
uci set dhcp.mac_vpn.mac="00:FF:*:*:*:*"
uci set dhcp.mac_vpn.networkid="vpn"
uci add_list dhcp.mac_vpn.dhcp_option="3,"
uci add_list dhcp.mac_vpn.dhcp_option="6,"
uci add_list dhcp.mac_vpn.dhcp_option="44"
uci commit dhcp
/etc/init.d/dnsmasq restart

Assign different DHCP options to multiple hosts.

uci set dhcp.j400="host"
uci set"j400"
uci set	dhcp.j400.mac="00:21:63:75:aa:17"
uci set	dhcp.j400.ip=""
uci set	dhcp.j400.tag="vpn"
uci set dhcp.j500="host"
uci set"j500"
uci set	dhcp.j500.mac="01:22:64:76:bb:18"
uci set	dhcp.j500.ip=""
uci set	dhcp.j500.tag="vpn"
uci set dhcp.vpn="tag"
uci set dhcp.vpn.dhcp_option="6,,"
uci commit dhcp
/etc/init.d/dnsmasq restart

DHCP pool for 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 / is
  • the start address is 22 x /16 subnets away: (2^16) * 22 = 1441792
  • + 1441792 + 1 = → start = 1441793
  • - = 253 → limit = 253
# 1441793 253
uci set dhcp.lan.start="1441793"
uci set dhcp.lan.limit="253"
uci commit dhcp
/etc/init.d/dnsmasq restart


Define a custom domain name and the corresponding PTR record - assigns the IPv4 address and IPv6 address fdce::123 to the domain name mylaptop and construct an appropriate reverse records. You can also use this to rebind domain names. It works like an entry in /etc/hosts but more flexible and integrated.

uci add dhcp domain
uci set dhcp.@domain[-1].name="mylaptop"
uci set dhcp.@domain[-1].ip=""
uci add dhcp domain
uci set dhcp.@domain[-1].name="mylaptop"
uci set dhcp.@domain[-1].ip="fdce::123"
uci commit dhcp
/etc/init.d/dnsmasq restart


Return on query domain local and subdomain *.local.

uci add_list dhcp.@dnsmasq[0].address="/local/"
uci commit dhcp
/etc/init.d/dnsmasq restart


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:

uci add dhcp srvhost
uci set	dhcp.@srvhost[-1].srv=""
uci set	dhcp.@srvhost[-1].target=""
uci set	dhcp.@srvhost[-1].port="5060"
uci set	dhcp.@srvhost[-1].class="0"
uci set	dhcp.@srvhost[-1].weight="10"
uci commit dhcp
/etc/init.d/dnsmasq restart


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:

uci add dhcp cname
uci set	dhcp.@cname[-1].cname=""
uci set	dhcp.@cname[-1].target=""
uci commit dhcp
/etc/init.d/dnsmasq restart

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.

Mitigate the issues caused by split-horizon:

uci add dhcp mxhost
uci set	dhcp.@mxhost[-1].domain="yyy.zzz"
uci set	dhcp.@mxhost[-1].relay=""
uci set	dhcp.@mxhost[-1].pref="10"
uci commit dhcp
/etc/init.d/dnsmasq restart

TFTP boot

Direct BOOTP requests to the TFTP server. Tell the client to load pxelinux.0 from the server at, and mount root from /data/netboot/root on the same server.

uci set dhcp.linux="boot"
uci set dhcp.linux.filename="/tftpboot/pxelinux.0"
uci set dhcp.linux.serveraddress=""
uci set dhcp.linux.servername="fileserver"
uci add_list dhcp.linux.dhcp_option="option:root-path,"
uci commit dhcp
/etc/init.d/dnsmasq restart

Multiple DHCP/DNS server/forwarder instances

If you need multiple DNS forwarders with different configurations or DHCP server with different sets of lease files.

Running multiple dnsmasq instances as DNS forwarder and/or DHCPv4 server, each having their own configuration and lease list can be configured by creating multiple dnsmasq sections. Typically in such configs each dnsmasq section will be bound to a specific interface by using the interface list; assigning sections like dhcp, host, etc. to a specific dnsmasq instance is done by the instance option. By default dnsmasq adds the loopback interface to the interface list to listen when the --interface option is used; therefore the loopback interface needs to be excluded in one of the dnsmasq instances by using the notinterface list.

These are example settings for multiple dnsmasq instances each having their own dhcp section. dnsmasq instance lan_dns is bound to the lan interface while the dnsmasq instance guest_dns is bound to the guest interface.

# Remove default instances
while uci -q delete dhcp.@dnsmasq[-1]; do :; done
while uci -q delete dhcp.@dhcp[-1]; do :; done
# Use network interface names for DHCP/DNS instance names
for INST in lan guest
uci set dhcp.${INST}_dns="dnsmasq"
uci set dhcp.${INST}_dns.domainneeded="1"
uci set dhcp.${INST}_dns.boguspriv="1"
uci set dhcp.${INST}_dns.filterwin2k="0"
uci set dhcp.${INST}_dns.localise_queries="1"
uci set dhcp.${INST}_dns.rebind_protection="1"
uci set dhcp.${INST}_dns.rebind_localhost="1"
uci set dhcp.${INST}_dns.local="/${INST}/"
uci set dhcp.${INST}_dns.domain="${INST}"
uci set dhcp.${INST}_dns.expandhosts="1"
uci set dhcp.${INST}_dns.nonegcache="0"
uci set dhcp.${INST}_dns.authoritative="1"
uci set dhcp.${INST}_dns.readethers="1"
uci set dhcp.${INST}_dns.leasefile="/tmp/dhcp.leases.${INST}"
uci set dhcp.${INST}_dns.resolvfile="/etc/resolv.conf.${INST}"
uci set dhcp.${INST}_dns.nonwildcard="1"
uci add_list dhcp.${INST}_dns.interface="${INST}"
uci add_list dhcp.${INST}_dns.notinterface="loopback"
uci set dhcp.${INST}="dhcp"
uci set dhcp.${INST}.instance="${INST}_dns"
uci set dhcp.${INST}.interface="${INST}"
uci set dhcp.${INST}.start="100"
uci set dhcp.${INST}.limit="150"
uci set dhcp.${INST}.leasetime="12h"
ln -s -f /tmp/ /etc/resolv.conf.${INST}
uci -q delete dhcp.@dnsmasq[0].notinterface
uci commit dhcp
/etc/init.d/dnsmasq restart

The LuCI web interface has not been updated to support multiple dnsmasq instances.

Disabling DNS role

This is useful when you just want to hand out addresses to clients, without doing any DNS by dnsmasq.

uci -q delete dhcp.@dnsmasq[0].domain
uci set dhcp.@dnsmasq[0].port="0"
uci commit dhcp
/etc/init.d/dnsmasq restart

The second option prevents dnsmasq from giving out a domain name and DNS search list to clients: this is useless without DNS resolving.

If you want to remove DNS role from OpenWrt completely, you should send the address of a DNS resolver to clients:

uci -q delete dhcp.lan.dhcp_option
uci -q delete dhcp.lan.dns
uci add_list dhcp.lan.dhcp_option="6,,"
uci add_list dhcp.lan.dns="2001:4860:4860::8888"
uci add_list dhcp.lan.dns="2001:4860:4860::8844"
uci commit dhcp
/etc/init.d/dnsmasq restart
/etc/init.d/odhcpd restart

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 DHCPv6, but if you also use odhcpd for DHCPv4, you can just use dns entries for everything.

Disabling DHCP role

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.

uci set dhcp.lan.ignore="1"
uci commit dhcp
/etc/init.d/dnsmasq restart
/etc/init.d/odhcpd restart

Replacing Dnsmasq with odhcpd and Unbound

Use odhcpd for both DHCPv4 and DHCPv6 replacing Dnsmasq.

opkg update
opkg remove dnsmasq odhcpd-ipv6only
opkg install odhcpd
uci -q delete dhcp.@dnsmasq[0]
uci set dhcp.lan.dhcpv4="server"
uci set dhcp.odhcpd.maindhcp="1"
uci commit dhcp
/etc/init.d/odhcpd restart

Slave DNS server role

On your OpenWrt router add (peerdns=“1”) - or replace ISP DNS with (peerdns=“0”) - your master DNS server address (eg. a local one at or a public DNS provider).

OpenWrt acts as a slave caching DNS server by default proposing itself as DNS server for DHCP clients. This allows better performance and management of DNS functionality on your local network. Every received DNS query not currently in cache is forwarded by default to master DNS servers chosen from those ones defined for each network interface.

If you want to use a custom master DNS server for upstream DNS queries while OpenWrt router keeps acting as slave DNS server you have to change the upstream DNS providers.

DNS forwarding

Forward DNS queries to specific servers.

uci add_list dhcp.@dnsmasq[0].server=""
uci add_list dhcp.@dnsmasq[0].server=""
uci commit dhcp
/etc/init.d/dnsmasq restart

Disable resolvfile option limiting upstream resolvers to server option. Also makes local system to not use dnsmasq.

uci set dhcp.@dnsmasq[0].noresolv="1"
uci commit dhcp
/etc/init.d/dnsmasq restart

Enforce local system to use dnsmasq if it is enabled along with noresolv option.

uci set dhcp.@dnsmasq[0].localuse="1"
uci commit dhcp
/etc/init.d/dnsmasq restart

Conditional DNS forwarding

Forward DNS queries for a specific domain and all its subdomains to a different server. More specific domains take precedence over less specific domains allowing to combine with unconditional forwarding from above.

uci add_list dhcp.@dnsmasq[0].server="/"
uci commit dhcp
/etc/init.d/dnsmasq restart

DNS filtering

Simple DNS-based content filtering.

# Blacklist
uci -q delete dhcp.@dnsmasq[0].server
uci add_list dhcp.@dnsmasq[0].server="/"
uci add_list dhcp.@dnsmasq[0].server="/"
uci commit dhcp
/etc/init.d/dnsmasq restart
# Whitelist
uci -q delete dhcp.@dnsmasq[0].server
uci add_list dhcp.@dnsmasq[0].server="/"
uci add_list dhcp.@dnsmasq[0].server="/"
uci add_list dhcp.@dnsmasq[0].server="/#/"
uci commit dhcp
/etc/init.d/dnsmasq restart

See also: Ad blocking

Change upstream DNS providers

OpenWrt uses “peerdns” servers automatically obtained from IP connection setup as its upstream DNS servers. These are the same being used by the local dnsmasq slave DNS role. You can change them to any other DNS provider or even to a different local DNS server you have running already in your network. Make sure selected provider supports DNSSEC validation if required. Specify several servers to improve fault tolerance.

# Configure DNS provider
uci -q delete network.wan.dns
uci add_list network.wan.dns=""
uci add_list network.wan.dns=""
# Configure DNS6 provider
uci -q delete network.wan6.dns
uci add_list network.wan6.dns="2001:4860:4860::8888"
uci add_list network.wan6.dns="2001:4860:4860::8844"
# Optional: Disable peerdns
# warning: the DNS resolver on this router will stop working if all above selected servers goes offline
#          keep peerdns="1" to let peerdns act as fallback
uci set network.wan.peerdns="0"
uci set network.wan6.peerdns="0"
# Save and apply
uci commit network
/etc/init.d/network restart
This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.More information about cookies
docs/guide-user/base-system/dhcp_configuration.txt · Last modified: 2020/05/26 19:49 by lukepicci