DHCP and DNS configuration /etc/config/dhcp

See also: DHCP and DNS examples, dnsmasq, odhcpd

OpenWrt uses dnsmasq and odhcpd to serve DNS/DHCP and DHCPv6 by default.

Dnsmasq serves as a downstream caching DNS server advertising itself to 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 to the upstream DNS servers.

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 default configuration 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 of the type dnsmasq specify per dnsmasq instance the values and options relevant to the overall operation of the dnsmasq instance 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 '1'
	option local '/lan/'
	option domain 'lan'
	option expandhosts '1'
	option nonegcache '0'
	option cachesize '1000'
	option authoritative '1'
	option readethers '1'
	option leasefile '/tmp/dhcp.leases'
	option resolvfile '/tmp/resolv.conf.d/resolv.conf.auto'
	option nonwildcard '1'
	option localservice '1'
	option ednspacket_max '1232'
	option filter_aaaa '0'
	option filter_a '0'

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 192.168.1.10).

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 this would mean start leasing addresses from 192.168.1.100
• 150 is the maximum number of addresses that may be leased, in the default configuration this would mean leasing addresses up to 192.168.1.249
• 12h specifies the time to live for handed out leases, twelve hours in this example
• server defines the mode for IPv6 configuration (RA & DHCPv6)

Below is a listing of legal options for dhcp sections.

Name	Type	Required	Default	Description
dhcp_option	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. A list of options can be found here (note that dnsmasq does not support all options listed there). A list of the symbolic option names that dnsmasq recognises can be found by running dnsmasq --help dhcp.
dhcp_option_force	list of strings	no	(none)	Exactly the same as dhcp_option (note the underscores), but it will be translated to --dhcp-option-force, meaning that the DHCP option will be sent regardless on whether the client requested it. dhcp_option_force available since 18.06
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
dhcpv4	string	no	(none)	Specifies whether DHCPv4 server should be enabled (server) or disabled (disabled)
dhcpv6	string	no	(none)	Specifies whether DHCPv6 server should be enabled (server), relayed (relay) or disabled (disabled)
dns	list	no	<local address>	DNS servers to announce on the network. Only IPv6 addresses are accepted. To configure IPv4 DNS servers, use dhcp_option.
dns_service	boolean	no	1	Announce the IPv6 address of interface as DNS service if the list of dns option is empty. dns_service available since 21.02
ra	string	no	(none)	Specifies whether Router Advertisements should be enabled (server), relayed (relay) or disabled (disabled)
ra_default	integer	no	0	Default router lifetime in the RA message will be set if default route is present and a global IPv6 address (0) or if default route is present but no global IPv6 address (1) or neither of both conditions (2)
ra_flags	list of strings	no	other-config	List of RA flags to be advertised in RA messages: managed-config - get address and other information from DHCPv6 server. If this flag is set, other-config flag is redundant. other-config - get other configuration from DHCPv6 server (such as DNS servers). See here for details. home-agent - see here for details. none. OpenWrt since version 21.02 configures managed-config and other-config by default.
ra_slaac	boolean	no	1	Announce SLAAC for a prefix (that is, set the A flag in RA messages).
ra_management	integer	no	1	This option is deprecated. Use ra_flags and ra_slaac options instead. RA management mode : no M-Flag but A-Flag (0), both M and A flags (1), M flag but not A flag (2)
ra_offlink	bool	no	0	Announce prefixes as offlink (1) in RAs
ra_preference	string	no	medium	Announce routes with either high (high), medium (medium) or low (low) priority in RAs
ra_mininterval	integer	no	200	Minimum time interval between RAs (in seconds)
ra_maxinterval	integer	no	600	Maximum time interval between RAs (in seconds)
ra_lifetime	integer	no	1800	Advertised router lifetime (in seconds)
ra_useleasetime	bool	no	0	Limit the preferred and valid lifetimes of the prefixes in the RA messages to the configured DHCP leasetime
ra_hoplimit	integer	no	0	Advertised current hop limit (0-255)
ra_reachabletime	integer	no	0	Advertised reachable time (in milliseconds) (0-3600000)
ra_retranstime	integer	no	0	Advertised NS retransmission time (in milliseconds) (0-60000)
ra_mtu	integer	no	(none)	Maximum advertised MTU
ra_dns	boolean	no	1	Announce DNS configuration in RA messages (RFC8106)
ndp	string	no	(none)	Specifies whether NDP should be relayed (relay) or disabled (disabled)
ndproxy_routing	bool	no	1	Learn routes from NDP
ndproxy_slave	bool	no	0	Ignore neighbor messages on slave enabled (1) interfaces
master	boolean	no	0	Specifies whether DHCPv6, RA and NDP in relay mode is a master interface or not.
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 size of the address pool (e.g. with start=100, limit=150, maximum address will be .249)
networkid	string	no	(value of interface)	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.
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.
instance	dnsmasq instance	no	(none)	Dnsmasq instance to which the dhcp section is bound; if not specified the section is valid for all dnsmasq instances.
tag	list of tag names	no	(none)	List of tags that dnsmasq needs to match to use with --dhcp-range.

Notes:

• interface is a logical interface / network name, i.e. lan, wan, wifi etc. (section names in /etc/config/network), NOT a layer 3 device name like eth0, eth1, wlan0 etc. (the ifname IDs in /etc/config/network).
• networkid is a layer 3 device name, i.e. eth0, eth1, wlan0 etc., not a network name (lan, wan, wifi etc.).

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 using the host section. The configuration options in this section are used to construct a -G option for dnsmasq.

Note: one of mac (can use wildcards), duid or name must be specified.

You can also enable the readethers option in the dnsmasq section and add entries to the /etc/ethers file.

Some hosts support booting over the network (PXE booting). Sections of the type boot specify how 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 tags aka 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 an -M option for dnsmasq.

*Note*: odhcp currently lacks support root-path specification. If you need this functionality, disable odhcpd and use dnsmasq instead.

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 tag (aka 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.
force	bool	no	(none)	dhcp_option will always be sent even if the client does not ask for it in the parameter request list. This is sometimes needed, for example when sending options to PXELinux.
instance	dnsmasq instance	no	(none)	Dnsmasq instance to which the boot section is bound. If not specified the section is valid for all dnsmasq instances.

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, others are more specific and are relevant only to a group of hosts, or even only a single one. dnsmasq offers to group DHCP options and their values by a tag, internally named networkid, which is an alphanumeric identifier, and sending options only to hosts which have been tagged with that networkid.

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 tag (or networkid).

You can use the following classifying sections:

Each classifying section (except tag) has one configuration option: which tag it will be assigned.

E.g. a mac section with an mac entry that exactly matches your ethernet MAC, and a tag (aka networkid) of green will be tagged green.

tag classifying sections have one configuration option: values of DHCP options to assign to this tag.

E.g. continuing the previous example, green tagged DHCP clients can be selectively forced to receive a dhcp_option if there is a tag entry with tag value of green, where a list of dhcp_option is also supplied, and force is set.

Requires the dnsmasq-full package.

dnsmasq can automatically populate Netfilter IP sets with resolved addresses of the specified domains. This feature can be enabled using ipset option in the dnsmasq section, or, with a more convenient syntax, using a dedicated ipset section. Every ipset section contains names of the IP sets to populate (name, multiple IP set names can be specified in one section), and domains whose resolved addresses should be added to the specified IP sets (domain). Example:

dhcp ipset
	list name 'ss_rules_dst_forward'
	list name 'ss_rules6_dst_forward'
	list domain 'linkedin.com'
	list domain 'telegram.org'

If you are routing between two interfaces (i.e. they are not bridged) then you will find that clients on the far end of the network sending DHCP requests get no response, as the DHCP broadcast cannot be routed between interfaces.

This can be solved without setting up an independent DHCP server for the far subnet by configuring dnsmasq to act as a DHCP relay. In this configuration it listens for DHCP requests as normal, forwards them to a remote DHCP server, then any response it receives it broadcasts back in the original subnet.

This configuration allows a single DHCP server to handle address assignments across a large network broken up into multiple subnets.

As of October 2021 LuCI does not have an interface for this so the configuration file must be manually edited.

Example DHCP relay configuration:

config relay 'id'
	option interface 'lan'
	option local_addr '1.1.1.1'
	option server_addr '2.2.2.2'