Dnsmasq

dnsmasq is a simple DNS, DHCP, and TFTP server. Due to its small footprint and versatility, it can be found in many consumer network devices (like routers, as part of DD-WRT, OpenWRT) and also as part of existing projects (such as libvirt, Pi-hole).

Quick Usage

dnsmasq can take its configuration entirely from a configuration file or command arguments. On embedded systems with no writable filesystem, it is possible to configure and run dnsmasq solely by command arguments which will be used in the examples below.

Converting the command arguments into a configuration file is as simple as taking out the leading double dashes -- from every argument, saving each argument as its own line in a file, and specifying the configuration file with -C configfile.

By default, dnsmasq will read /etc/dnsmasq.conf first. On a clean install, this file typically specifies the user and group the process should run as only.

As a DHCP server

Refer to the DHCP options section to understand the DHCP option numbers used in the examples below. You can always mix different options together to enable any of the following examples together.

To run dnsmasq as a DHCP server with a lease pool between 192.168.192.11 through 192.168.192.250 with a 1 hour lease time and 192.168.192.10 as the DNS server and gateway:

## Runs only a DHCP server
## --port=0 to disable DNS
# dnsmasq --no-daemon --port=0 \
  --dhcp-range=192.168.192.11,192.168.192.250,1h \
  --dhcp-option=6,192.168.192.10 \
  --dhcp-option=3,192.168.192.10

Lease time must be given as seconds (no unit), minutes (m), or hours (h). You must convert days or weeks into hours. 1 day as 24h, or 1 week as 168h.

As a DNS relay server

To run dnsmasq as a DNS relay on port 5353:

# dnsmasq --no-daemon --port=5353

As a TFTP server

To run dnsmasq as a standalone TFTP server:

## Runs a TFTP server serving from /tftpboot
# dnsmasq --no-daemon --port=0 \
  --enable-tftp \
  --tftp-root=/tftpboot

As a DHCP, DNS, and TFTP server

Run dnsmasq with all the options listed in the examples above together.

## Runs a DHCP, DNS, and TFTP server
# dnsmasq --no-daemon --port=53 \
  --dhcp-range=192.168.192.11,192.168.192.250,1h \
  --dhcp-option=6,192.168.192.10 \
  --dhcp-option=3,192.168.192.10 \
  --enable-tftp \
  --tftp-root=/tftpboot

DHCP Options

To get a list of options that you can pass to --dhcp-option, run dnsmasq --help dhcp. You will get a list of option numbers and their associated options keywords.

DHCP options are specified using the --dhcp-option argument and is specified by the decimal number, or as option:option-name.

## dnsmasq --dhcp-option=<option number>,<value>
## Eg: set router to 10.1.1.1
# dnsmasq --dhcp-option=3,10.1.1.1

## dnsmasq --dhcp-option=option:<option name>,<value>
## Eg: set router to 10.1.1.1
# dnsmasq --dhcp-option=option:router,10.1.1.1

## IPv6 options require the option6 keyword 
## dnsmasq --dhcp-option=option6:<option name>,<value>

Known DHCP options:
  1 netmask
  2 time-offset
  3 router
  6 dns-server
  7 log-server
  9 lpr-server
 12 hostname
 13 boot-file-size
 15 domain-name
 16 swap-server
 17 root-path
 18 extension-path
 19 ip-forward-enable
 20 non-local-source-routing
 21 policy-filter
 22 max-datagram-reassembly
 23 default-ttl
 26 mtu
 27 all-subnets-local
 28 broadcast
 31 router-discovery
 32 router-solicitation
 33 static-route
 34 trailer-encapsulation
 35 arp-timeout
 36 ethernet-encap
 37 tcp-ttl
 38 tcp-keepalive
 40 nis-domain
 41 nis-server
 42 ntp-server
 44 netbios-ns
 45 netbios-dd
 46 netbios-nodetype
 47 netbios-scope
 48 x-windows-fs
 49 x-windows-dm
 50 requested-address
 54 server-identifier
 60 vendor-class
 64 nis+-domain
 65 nis+-server
 66 tftp-server
 67 bootfile-name
 68 mobile-ip-home
 69 smtp-server
 70 pop3-server
 71 nntp-server
 74 irc-server
 77 user-class
 93 client-arch
 94 client-interface-id
 97 client-machine-id
119 domain-search
120 sip-server
121 classless-static-route

PXE Boot

The next-server DHCP option is defined using the --dhcp-option-force=66,xx.xx.xx.xx option. The use of --dhcp-option-force is required to ensure the IP address passed to this option is treated as a string.

DHCP boot options are specified with the --dhcp-boot or -M options. The parameter these options take are: 1. the filename, 2. server name (optional), 3. tftp server address (optional). The addresses if not provided will default to dnsmasq's address.

Eg. to run dnsmasq as a DHCP server but use a remote TFTP server at 10.1.1.54:

# dnsmasq --port=0 \
  --dhcp-range=192.168.1.1,192.168.1.10,1h \
  --dhcp-option-force=66,10.1.1.54 \
  --dhcp-boot=/pxelinux.0,,10.1.1.54

Here is a working example of a PXE boot config that I've used on a RaspberryPi. Dnsmasq here also acts as the TFTP server serving from /tftpboot.

port=0
interface=eth0
bind-interfaces
dhcp-range=10.130.4.110,10.130.4.169,24h

dhcp-boot=/pxelinux.0
dhcp-option-force=66,10.130.4.254

enable-tftp
tftp-root=/tftpboot

Other Notes

Use -x pidfile to specify a PID file and -k to run in the foreground.

See Also

• Project website: http://www.thekelleys.org.uk/dnsmasq/doc.html