See also: DNS and DHCP configuration /etc/config/dhcp, DNS encryption, DNS hijacking

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

Add a fixed IPv4 address 192.168.1.123, 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="192.168.1.123"
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

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 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,192.168.1.2"
uci add_list dhcp.lan.dhcp_option="6,172.16.60.64"
uci add_list dhcp.lan.dhcp_option="42,172.16.60.64"
uci commit dhcp
/etc/init.d/dnsmasq restart

A list of options can be found here.

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,192.168.1.2"
uci add_list dhcp.mac_vpn.dhcp_option="6,192.168.1.3"
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	dhcp.j400.name="j400"
uci set	dhcp.j400.mac="00:21:63:75:aa:17"
uci set	dhcp.j400.ip="10.11.12.14"
uci set	dhcp.j400.tag="vpn"
uci set dhcp.j500="host"
uci set	dhcp.j500.name="j500"
uci set	dhcp.j500.mac="01:22:64:76:bb:18"
uci set	dhcp.j500.ip="10.11.12.15"
uci set	dhcp.j500.tag="vpn"
uci set dhcp.vpn="tag"
uci set dhcp.vpn.dhcp_option="6,8.8.8.8,8.8.4.4"
uci commit dhcp
/etc/init.d/dnsmasq restart

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

# 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
 
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 192.168.1.123 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="192.168.1.123"
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 10.10.10.1 on query domain local and subdomain *.local.

uci add_list dhcp.@dnsmasq[0].address="/local/10.10.10.1"
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 pbx.mydomain.com, with a class of 0 and a weight of 10 one would use:

uci add dhcp srvhost
uci set	dhcp.@srvhost[-1].srv="_sip._udp.mydomain.com"
uci set	dhcp.@srvhost[-1].target="pbx.mydomain.com"
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="ftp.example.com"
uci set	dhcp.@cname[-1].target="www.example.com"
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="my.host.com"
uci set	dhcp.@mxhost[-1].pref="10"
uci commit dhcp
/etc/init.d/dnsmasq restart

Direct BOOTP requests to the TFTP server. Tell 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.

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

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
do
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/resolv.conf.auto /etc/resolv.conf.${INST}
done
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.

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,8.8.8.8,8.8.4.4"
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.

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

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

On your OpenWrt router add (peerdns=“1”) - or replace ISP DNS with (peerdns=“0”) - your master DNS server address (eg. a local one at 192.168.1.2 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.

Forward DNS queries to specific servers.

uci add_list dhcp.@dnsmasq[0].server="8.8.8.8"
uci add_list dhcp.@dnsmasq[0].server="8.8.4.4"
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

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="/example.com/192.168.2.1"
uci commit dhcp
/etc/init.d/dnsmasq restart

Simple DNS-based content filtering.

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

See also: Ad blocking

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="8.8.8.8"
uci add_list network.wan.dns="8.8.4.4"
 
# 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