Dnsmasq DNS & DHCP

Dnsmasq is a lightweight and easy to configure DNS forwarder and DHCPv4/DHCPv6 server.

It is considered the replacement for ISC-DHCP in small and medium sized setups and synergizes well with Unbound DNS, our standard enabled forward/resolver service.

Our system setup wizard configures Unbound DNS for DNS and Dnsmasq for DHCPv4, DHCPv6 and Router Advertisements.

Considerations before deployment

DNS Service

Dnsmasq can be combined with Unbound to act as a “connector”, in which case DHCP leases which have their hostnames registered in Dnsmasq may be queried directly by Unbound.

Since Dnsmasq does not restart on configuration changes and does not need custom scripts to register DNS, it is very resilient and easy to manage.

In the configuration examples further below, we will always combine Unbound with Dnsmasq.

DHCP Service

Dnsmasq is the perfect DHCP server for small and medium sized setups (less than 1000 unique clients). The configuration is straight forward, and since it can register the DNS names of leases, it can replicate the simplicity known from consumer routers.

If HA for DHCP is a requirement, split pools can be configured for two Dnsmasq instances. With a dhcp reply delay, the secondary instance will only answer when the first instance is unresponsive. DHCPv6 and Router Advertisements are also an option for small HA setups that do not have fast failover requirements, as IPv6 failover can take up to 30 seconds with available configuration options.

For larger enterprise setups, KEA DHCP can be a viable alternative. It supports lease synchronisation via REST API, which means both DHCP servers keep track of all existing leases and do not need split pools. It is also far more scalable if there are thousands of leases.

The tradeoff using KEA DHCP is a more complicated setup, especially when custom DHCP options are needed. DNS registration is also not possible.

With this in mind, pick the right choice for your setup. When in doubt, our advise is to use Dnsmasq.

General Settings

Most settings are pretty straightforward here when the service is enabled, it should just start forwarding dns requests when received from the network. DHCP requires at least one dhcp-range and matching dhcp-options.

General

DNS

DNS Query Forwarding

DHCP

ISC / KEA DHCP (legacy)

DNS Settings

Hosts (Host Overrides)

Domains (Domain Overrides)

DHCP Settings

DHCP ranges

RA Modes

This is what the RA Flags (Bits) mean:

• M - Managed address configuration:
  The client should use stateful DHCPv6 to obtain an IPv6 address (and implicitly O information).

• O - Other configuration:
  The client should use DHCPv6 to obtain other information (e.g., DNS server, Domain).

• A - Autonomous address-configuration:
  The client can use SLAAC to self-assign an IPv6 address based on the advertised prefix.

DHCP options

DHCP boot

DHCP tags

Advanced settings

To configure options that are not available in the gui one can add custom configuration files on the firewall itself. Files can be added in /usr/local/etc/dnsmasq.conf.d/, these should use as extension .conf (e.g. custom-options.conf). When more files are placed inside the directory, all will be included in alphabetical order.

Configuration examples

DHCPv4 with DNS registration

Dnsmasq can be used as a DNS forwarder. Though in our recommended setup, we will not use it as our default DNS server.

We will use Unbound as primary DNS server for our clients, and only forward some internal zones to Dnsmasq which manages the hostnames of DHCP registered leases.

This requires Dnsmasq to run with a non-standard port other than 53.

• Go to Services › Dnsmasq DNS & DHCP › General and set:

• Press Apply

Afterwards we can configure Unbound to forward the zones to Dnsmasq.

• Go to Services › Unbound DNS › General and set:

• Press Apply

• Go to Services › Unbound DNS › Query Forwarding and create an entry for each DHCP range you plan to configure.

In our example, we configure query forwarding for 2 networks:

• lan.internal - 192.168.1.0/24
• guest.internal - 192.168.10.0/24

lan.internal

• Press Save and add next

• Press Save and Apply

guest.internal

• Press Save and add next

• Press Save and Apply

Now that we have the DNS infrastructure set up, we can configure DHCP.

• Go to Services › Dnsmasq DNS & DHCP › General and set:

• Press Apply

As next step we define the DHCP ranges for our interfaces.

• Go to Services › Dnsmasq DNS & DHCP › DHCP ranges and set:

LAN

• Press Save and Apply

GUEST

• Press Save and Apply

This is an incomplete overview which highlights some default DHCP options:

Now that the setup is complete, the following will happen in regards of DHCP and DNS.

1. A new device (e.g. a smartphone) joins the LAN network and sends a DHCP Discover broadcast.
2. Dnsmasq receives this broadcast on port 67 and responds with a DHCP offer, containing an available IP address and DHCP options for router[3] and dns-server[6].
3. The device sends a DHCP request to request the available IP address, and possibly send its own hostname.
4. Dnsmasq acknowledges the request.

Our smartphone now has the following IP configuration:

• IP address: 192.168.1.100
• Default Gateway: 192.168.1.1
• DNS Server: 192.168.1.1

At the same time, Dnsmasq registers the DNS hostname of the smartphone (if it exists). Since we configured the FQDN option and domain in the DHCP range, the name of the smartphone will be: smartphone.lan.internal..

When a client queries Unbound for exactly smartphone.lan.internal., the configured query forwarding sends the request to the DNS server responsible for lan.internal. which is our configured Dnsmasq listening on 127.0.0.1:53053. Dnsmasq responds to this query and will resolve the current A record of smartphone.lan.internal. to 192.168.1.100, sending this information to Unbound which in return sends the response back to the client that initially queried.

As you can see, this is a highly integrated and simple setup which leverages just the available DHCP and DNS standards with no trickery involved.

DHCPv6 and Router Advertisements

DHCPv6 and Router Advertisements can run at the same time as DHCPv4, just specify another range.

In this example, we add a DHCPv6 range and Router Advertisements to our LAN interface. The following configuration sets stateless DHCPv6 and SLAAC. This means clients will use a SLAAC address but query additional DHCPv6 options, e.g. DNS Server.

• Go to Services › Dnsmasq DNS & DHCP › DHCP ranges and set:

With the mode set to slaac, clients will generate a SLAAC address and an additional DHCPv6 address (stateful DHCPv6). If clients should only generate a SLAAC address, set the mode to ra-stateless (stateless DHCPv6).

As final step, go to Services › Dnsmasq DNS & DHCP › General and enable Router Advertisements.

Press Apply to activate the new configuration.

DHCP reservations

A DHCP reservation will always assign the same IPv4 and IPv6 addresses to a client.

For an IPv4 reservation, a DHCPv4 range should exist. If this DHCPv4 range should only serve reservations, set it to static.

For an IPv6 reservation, a DHCPv6 range must be configured which sets slaac as Router Advertisement option. This sets the A bit so that clients can generate a SLAAC address and receive an additional DHCPv6 lease. If a different Router Advertisement daemon is used, ensure it runs in Assisted mode.

Here are a few examples for DHCP reservations. This assumes we already created ranges for LAN and GUEST as outlined in the previous sections.

Go to Services › Dnsmasq DNS & DHCP › Hosts

IPv4

• Press Save and Apply

IPv6

• Press Save and Apply

IPv4 + IPv6 (dual stack)

• Press Save and Apply

DHCP tags

When a DHCP Discover enters a network interface, Dnsmasq will automatically set a tag with the interface name.

Additionally, tags can be set on DHCP requests by clients when they send the options they need.

There are two kinds of operations, set a tag and match a tag.

You can manually configure additional tags in Services › Dnsmasq DNS & DHCP › DHCP tags.

• Setting these tags can be done in multiple spots, e.g., DHCP ranges, DHCP options / match, and Host Overrides.
• Matching one or multiple tags is mostly relevant in DHCP options.

As example, you could configure VoIP phones to receive a TFTP server option when they have a specific vendor id.

Go to Services › Dnsmasq DNS & DHCP › DHCP tags

Go to Services › Dnsmasq DNS & DHCP › DHCP options

Now a tag will be set if a DHCP request is sent by a VoIP phone that includes the vendor class option. If the vendor ID string matches, Dnsmasq will look up any configuration that will match this tag. As next step we assign a TFTP server to this tag.

Go to Services › Dnsmasq DNS & DHCP › DHCP options

This ensures that only clients identifying as VoIP phones receive the appropriate TFTP server information via option 150. You can add additional options under the same tag if they should be offered to the VOIP phones.

DHCP boot

In a network, we have different clients that should receive different boot images depending on if they require a BIOS or EFI boot.

By using DHCP tags, we can configure this behavior by matching DHCP options and combining them with a DHCP boot directive.

Go to Services › Dnsmasq DNS & DHCP › DHCP tags and create two tags:

BIOS Tag

EFI Tag

Go to Services › Dnsmasq DNS & DHCP › DHCP options

We will match the DHCP option client-arch[93] which has multiple possibilities when it comes to the client architecture. Value 0 matches x86 BIOS and value 7 matches EFI BC (EFI x64). Choose the correct values to match your specific clients.

BIOS Match Tag

EFI Match Tag

Go to Services › Dnsmasq DNS & DHCP › DHCP options › DHCP boot

Create two boot entries that serve the correct image to matching clients. We assume the requests are on LAN, though it can be left empty if these boot images should be served on any interfaces. Adjust IP addresses and filenames to fit your environment.

BIOS Boot

EFI Boot

Apply the new configuration, and check the PXE boot server if clients request the correct boot image files.

DHCPv4 for small HA setups

In addition to the setup described above, Dnsmasq can be a viable option in a HA setup in small and medium sized network environments.

In contrast to KEA DHCP, it does not offer lease synchronization. Each Dnsmasq instance is a separate entity.

The main tricks to make this work are the following options:

• Go to Services › Dnsmasq DNS & DHCP › General:

Set this on the current master:

Set this on the current backup:

• Go to Services › Dnsmasq DNS & DHCP › DHCP ranges:

With LAN as example, set this on the current master:

Set this on the current backup:

With this setup, a simple and efficient HA setup with automatic DNS registration is possible. Yet for larger scalable setups with big IP address ranges in many VLANs, KEA DHCP might be the better choice due to its robust HA synchronization options.

DHCPv6 and Router Advertisements for small HA setups

Just as with DHCPv4, the same type of configuration can be done for DHCPv6 with a few minor adjustments.

Since IPv6 uses DAD (Duplicate Address Detection), you do not need to create separate pools. SLAAC and DAD will take care of avoiding duplicates.

Special care must be taken for the Router Advertisements. Since both master and backup will send them at the same time, the current default gateway must be determined by priority and router lifetime.

• Go to Services › Dnsmasq DNS & DHCP › DHCP ranges:

Set this on the current master:

Set this on the current backup:

As final step, go to Services › Dnsmasq DNS & DHCP › General

Enable the checkbox Router Advertisements on both master and backup and apply the configuration.

Both master and backup will now advertise their link local addresses as default gateway. As long as clients receive the RA priority high packets, they prefer the master as the current IPv6 default gateway. When the master goes offline, the RA interval is sent every 10 seconds, yet after 30 seconds the RA router lifetime will be reached and the master will be deprecated from the clients routing table. The backup will now be installed as new IPv6 default route.

As soon as the master comes back online, the higher RA priority will make clients shift back eventually.

Dnsmasq as primary DNS resolver

This is a small complementory section how to configure Dnsmasq as the primary DNS resolver for your network combined with Unbound as recurser.

It is useful if you rely on features like dynamic IPv6 networks with PTR records registered via DHCP, or the Firewall Alias (IPset) feature.

The drawbacks are Unbound Statistics or Blocklist features based on client IP, as the client will always be 127.0.0.1.

The benefits are a less complicated configuration and less adjustments in Unbound if new networks get introduced.

• Go to Services › Unbound DNS › General and set:

• Go to Services › Dnsmasq DNS & DHCP › General and set:

• Go to Services › Dnsmasq DNS & DHCP › Domains and set:

Apply the configuration and test DNS resolution with a client.

Firewall Alias (IPset)

Dnsmasq has a powerful feature, it can add resolved IP addresses to firewall aliases.

This is quite useful in restricted networks or to gather statistics.

As example, you provide a guest network, but users should only access example.com. With a normal firewall alias, this might be challenging, as the domain might use multiple subdomains that serve additional content. It could also use a CDN to load balance content across different servers with dynamically changing IP addresses per client.

With a Dnsmasq managed alias, this becomes rather simple as it will automatically add new IPv4 and IPv6 addresses as soon as they are requested by clients.

A requirement to use this feature is that Dnsmasq is your primary DNS server for all clients, and access to any other DNS servers is blocked. A different approach is to do query forwarding from Unbound to Dnsmasq for the domains that should be added to its managed firewall aliases, with the caveat that Dnsmasq then must use an external resolver to prevent a query loop.

In the following example, Dnsmasq is our primary DNS resolver, and it forwards queries to 127.0.0.1:53053 on which Unbound listens.

• Go to Firewall › Aliases:

After creating the alias, go to Services › Dnsmasq DNS & DHCP › Domains:

As final step, create a firewall rule with the dnsmasq_example_com alias as destination.