Section: Maintenance Commands (8)

Index?action=index Return to Main Contents


dnsmasq - A lightweight DHCP and caching DNS server.


dnsmasq [OPTION]...


dnsmasq is a lightweight DNS, TFTP, PXE, router advertisement and DHCP server. It is intended to provide coupled DNS and DHCP service to a LAN.

Dnsmasq accepts DNS queries and either answers them from a small, local, cache or forwards them to a real, recursive, DNS server. It loads the contents of /etc/hosts so that local hostnames which do not appear in the global DNS can be resolved and also answers DNS queries for DHCP configured hosts. It can also act as the authoritative DNS server for one or more domains, allowing local names to appear in the global DNS. It can be configured to do DNSSEC validation.

The dnsmasq DHCP server supports static address assignments and multiple networks. It automatically sends a sensible default set of DHCP options, and can be configured to send any desired set of DHCP options, including vendor-encapsulated options. It includes a secure, read-only, TFTP server to allow net/PXE boot of DHCP hosts and also supports BOOTP. The PXE support is full featured, and includes a proxy mode which supplies PXE information to clients whilst DHCP address allocation is done by another server.

The dnsmasq DHCPv6 server provides the same set of features as the DHCPv4 server, and in addition, it includes router advertisements and a neat feature which allows nameing for clients which use DHCPv4 and stateless autoconfiguration only for IPv6 configuration. There is support for doing address allocation (both DHCPv6 and RA) from subnets which are dynamically delegated via DHCPv6 prefix delegation.

Dnsmasq is coded with small embedded systems in mind. It aims for the smallest possible memory footprint compatible with the supported functions, and allows uneeded functions to be omitted from the compiled binary.


Note that in general missing parameters are allowed and switch off functions, for instance "--pid-file" disables writing a PID file. On BSD, unless the GNU getopt library is linked, the long form of the options does not work on the command line; it is still recognised in the configuration file.

Read and syntax check configuration file(s). Exit with code 0 if all is OK, or a non-zero code otherwise. Do not start up dnsmasq.:
-h, --no-hosts
Don't read the hostnames in /etc/hosts.:
-H, --addn-hosts=<file>
Additional hosts file. Read the specified file as well as /etc/hosts. If -h is given, read only the specified file. This option may be repeated for more than one additional hosts file. If a directory is given, then read all the files contained in that directory.:
-E, --expand-hosts
Add the domain to simple names (without a period) in /etc/hosts in the same way as for DHCP-derived names. Note that this does not apply to domain names in cnames, PTR records, TXT records etc.:
-T, --local-ttl=<time>
When replying with information from /etc/hosts or the DHCP leases file dnsmasq by default sets the time-to-live field to zero, meaning that the requester should not itself cache the information. This is the correct thing to do in almost all situations. This option allows a time-to-live (in seconds) to be given for these replies. This will reduce the load on the server at the expense of clients using stale data under some circumstances.:
Negative replies from upstream servers normally contain time-to-live information in SOA records which dnsmasq uses for caching. If the replies from upstream servers omit this information, dnsmasq does not cache the reply. This option gives a default value for time-to-live (in seconds) which dnsmasq uses to cache negative replies even in the absence of an SOA record.:
Set a maximum TTL value that will be handed out to clients. The specified maximum TTL will be given to clients instead of the true TTL value if it is lower. The true TTL value is however kept in the cache to avoid flooding the upstream DNS servers.:
Set a maximum TTL value for entries in the cache.:
Set the TTL value returned in answers from the authoritative server.:
-k, --keep-in-foreground
Do not go into the background at startup but otherwise run as normal. This is intended for use when dnsmasq is run under daemontools or launchd.:
-d, --no-daemon
Debug mode: don't fork to the background, don't write a pid file, don't change user id, generate a complete cache dump on receipt on SIGUSR1, log to stderr as well as syslog, don't fork new processes to handle TCP queries. Note that this option is for use in debugging only, to stop dnsmasq daemonising in production, use -k.:
-q, --log-queries
Log the results of DNS queries handled by dnsmasq. Enable a full cache dump on receipt of SIGUSR1.:
-8, --log-facility=<facility>
Set the facility to which dnsmasq will send syslog entries, this defaults to DAEMON, and to LOCAL0 when debug mode is in operation. If the facility given contains at least one '/' character, it is taken to be a filename, and dnsmasq logs to the given file, instead of syslog. If the facility is '-' then dnsmasq logs to stderr. (Errors whilst reading configuration will still go to syslog, but all output from a successful startup, and all output whilst running, will go exclusively to the file.) When logging to a file, dnsmasq will close and reopen the file when it receives SIGUSR2. This allows the log file to be rotated without stopping dnsmasq.:
Enable asynchronous logging and optionally set the limit on the number of lines which will be queued by dnsmasq when writing to the syslog is slow. Dnsmasq can log asynchronously: this allows it to continue functioning without being blocked by syslog, and allows syslog to use dnsmasq for DNS queries without risking deadlock. If the queue of log-lines becomes full, dnsmasq will log the overflow, and the number of messages lost. The default queue length is 5, a sane value would be 5-25, and a maximum limit of 100 is imposed.:
-x, --pid-file=<path>
Specify an alternate path for dnsmasq to record its process-id in. Normally /var/run/
-u, --user=<username>
Specify the userid to which dnsmasq will change after startup. Dnsmasq must normally be started as root, but it will drop root privileges after startup by changing id to another user. Normally this user is "nobody" but that can be over-ridden with this switch.:
-g, --group=<groupname>
Specify the group which dnsmasq will run as. The defaults to "dip", if available, to facilitate access to /etc/ppp/resolv.conf which is not normally world readable.:
-v, --version
Print the version number.:
-p, --port=<port>
Listen on <port> instead of the standard DNS port (53). Setting this to zero completely disables DNS function, leaving only DHCP and/or TFTP.:
-P, --edns-packet-max=<size>
Specify the largest EDNS.0 UDP packet which is supported by the DNS forwarder. Defaults to 4096, which is the RFC5625-recommended size.:
-Q, --query-port=<query_port>
Send outbound DNS queries from, and listen for their replies on, the specific UDP port <query_port> instead of using random ports. NOTE that using this option will make dnsmasq less secure against DNS spoofing attacks but it may be faster and use less resources. Setting this option to zero makes dnsmasq use a single port allocated to it by the OS: this was the default behaviour in versions prior to 2.43.:
Do not use ports less than that given as source for outbound DNS queries. Dnsmasq picks random ports as source for outbound queries: when this option is given, the ports used will always to larger than that specified. Useful for systems behind firewalls.:
-i, --interface=<interface name>
Listen only on the specified interface(s). Dnsmasq automatically adds the loopback (local) interface to the list of interfaces to use when the --interface option is used. If no --interface or --listen-address options are given dnsmasq listens on all available interfaces except any given in --except-interface options. IP alias interfaces (eg "eth1:0") cannot be used with --interface or --except-interface options, use --listen-address instead. A simple wildcard, consisting of a trailing '*', can be used in --interface and --except-interface options.:
-I, --except-interface=<interface name>
Do not listen on the specified interface. Note that the order of --listen-address --interface and --except-interface options does not matter and that --except-interface options always override the others.:
Enable DNS authoritative mode for queries arriving at an interface or address. Note that the interface or address need not be mentioned in --interface or --listen-address configuration, indeed --auth-server will overide these and provide a different DNS service on the specified interface. The <domain> is the "glue record". It should resolve in the global DNS to a A and/or AAAA record which points to the address dnsmasq is listening on. When an interface is specified, it may be qualified with "/4" or "/6" to specify only the IPv4 or IPv6 addresses associated with the interface.:
Accept DNS queries only from hosts whose address is on a local subnet, ie a subnet for which an interface exists on the server. This option only has effect is there are no --interface --except-interface, --listen-address or --auth-server options. It is intended to be set as a default on installation, to allow unconfigured installations to be useful but also safe from being used for DNS amplification attacks.:
-2, --no-dhcp-interface=<interface name>
Do not provide DHCP or TFTP on the specified interface, but do provide DNS service.:
-a, --listen-address=<ipaddr>
Listen on the given IP address(es). Both --interface and --listen-address options may be given, in which case the set of both interfaces and addresses is used. Note that if no --interface option is given, but --listen-address is, dnsmasq will not automatically listen on the loopback interface. To achieve this, its IP address,, must be explicitly given as a --listen-address option.:
-z, --bind-interfaces
On systems which support it, dnsmasq binds the wildcard address, even when it is listening on only some interfaces. It then discards requests that it shouldn't reply to. This has the advantage of working even when interfaces come and go and change address. This option forces dnsmasq to really bind only the interfaces it is listening on. About the only time when this is useful is when running another nameserver (or another instance of dnsmasq) on the same machine. Setting this option also enables multiple instances of dnsmasq which provide DHCP service to run in the same machine.:
Enable a network mode which is a hybrid between --bind-interfaces and the default. Dnsmasq binds the address of individual interfaces, allowing multiple dnsmasq instances, but if new interfaces or addresses appear, it automatically listens on those (subject to any access-control configuration). This makes dynamically created interfaces work in the same way as the default. Implementing this option requires non-standard networking APIs and it is only available under Linux. On other platforms it falls-back to --bind-interfaces mode.:
-y, --localise-queries
Return answers to DNS queries from /etc/hosts which depend on the interface over which the query was received. If a name in /etc/hosts has more than one address associated with it, and at least one of those addresses is on the same subnet as the interface to which the query was sent, then return only the address(es) on that subnet. This allows for a server to have multiple addresses in /etc/hosts corresponding to each of its interfaces, and hosts will get the correct address based on which network they are attached to. Currently this facility is limited to IPv4.:
-b, --bogus-priv
Bogus private reverse lookups. All reverse lookups for private IP ranges (ie 192.168.x.x, etc) which are not found in /etc/hosts or the DHCP leases file are answered with "no such domain" rather than being forwarded upstream.:
-V, --alias=[<old-ip>]|[<start-ip>-<end-ip>],<new-ip>[,<mask>]
Modify IPv4 addresses returned from upstream nameservers; old-ip is replaced by new-ip. If the optional mask is given then any address which matches the masked old-ip will be re-written. So, for instance --alias=,, will map to and to This is what Cisco PIX routers call "DNS doctoring". If the old IP is given as range, then only addresses in the range, rather than a whole subnet, are re-written. So --alias=,, maps> to>
-B, --bogus-nxdomain=<ipaddr>
Transform replies which contain the IP address given into "No such domain" replies. This is intended to counteract a devious move made by Verisign in September 2003 when they started returning the address of an advertising web page in response to queries for unregistered names, instead of the correct NXDOMAIN response. This option tells dnsmasq to fake the correct response when it sees this behaviour. As at Sept 2003 the IP address being returned by Verisign is
-f, --filterwin2k
Later versions of windows make periodic DNS requests which don't get sensible answers from the public DNS and can cause problems by triggering dial-on-demand links. This flag turns on an option to filter such requests. The requests blocked are for records of types SOA and SRV, and type ANY where the requested name has underscores, to catch LDAP requests.:
-r, --resolv-file=<file>
Read the IP addresses of the upstream nameservers from <file>, instead of /etc/resolv.conf. For the format of this file see (5). The only lines relevant to dnsmasq are nameserver ones. Dnsmasq can be told to poll more than one resolv.conf file, the first file name specified overrides the default, subsequent ones add to the list. This is only allowed when polling; the file with the currently latest modification time is the one used.:
-R, --no-resolv
Don't read /etc/resolv.conf. Get upstream servers only from the command line or the dnsmasq configuration file.:
-1, --enable-dbus[=<service-name>]
Allow dnsmasq configuration to be updated via DBus method calls. The configuration which can be changed is upstream DNS servers (and corresponding domains) and cache clear. Requires that dnsmasq has been built with DBus support. If the service name is given, dnsmasq provides service at that name, rather than the default which is
-o, --strict-order
By default, dnsmasq will send queries to any of the upstream servers it knows about and tries to favour servers that are known to be up. Setting this flag forces dnsmasq to try each query with each server strictly in the order they appear in /etc/resolv.conf:
By default, when dnsmasq has more than one upstream server available, it will send queries to just one server. Setting this flag forces dnsmasq to send all queries to all available servers. The reply from the server which answers first will be returned to the original requester.:
Enable code to detect DNS forwarding loops; ie the situation where a query sent to one of the upstream server eventually returns as a new query to the dnsmasq instance. The process works by generating TXT queries of the form <hex>.test and sending them to each upstream server. The hex is a UID which encodes the instance of dnsmasq sending the query and the upstream server to which it was sent. If the query returns to the server which sent it, then the upstream server through which it was sent is disabled and this event is logged. Each time the set of upstream servers changes, the test is re-run on all of them, including ones which were previously disabled.:
Reject (and log) addresses from upstream nameservers which are in the private IP ranges. This blocks an attack where a browser behind a firewall is used to probe machines on the local network.:
Exempt from rebinding checks. This address range is returned by realtime black hole servers, so blocking it may disable these services.:
Do not detect and block dns-rebind on queries to these domains. The argument may be either a single domain, or multiple domains surrounded by '/', like the --server syntax, eg. --rebind-domain-ok=/domain1/domain2/domain3/:
-n, --no-poll
Don't poll /etc/resolv.conf for changes.:
Whenever /etc/resolv.conf is re-read or the upstream servers are set via DBus, clear the DNS cache. This is useful when new nameservers may have different data than that held in cache.:
-D, --domain-needed
Tells dnsmasq to never forward A or AAAA queries for plain names, without dots or domain parts, to upstream nameservers. If the name is not known from /etc/hosts or DHCP then a "not found" answer is returned.:
:-S, --local, --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>]

and two records in the external DNS

eth0 is the external network interface on which dnsmasq is listening, and has (globally accessible) address

Note that the external IP address may well be dynamic (ie assigned from an ISP by DHCP or PPP) If so, the A record must be linked to this dynamic assignment by one of the usual dynamic-DNS systems.

A more complex, but practically useful configuration has the address record for the globally accessible IP address residing in the authoritative zone which dnsmasq is serving, typically at the root. Now we have,eth0,


The A record for has now become a glue record, it solves the chicken-and-egg problem of finding the IP address of the nameserver for when the A record is within that zone. Note that this is the only role of this record: as dnsmasq is now authoritative from it too must provide this record. If the external address is static, this can be done with an /etc/hosts entry or --host-record.,eth0,,


If the external address is dynamic, the address associated with must be derived from the address of the relevant interface. This is done using interface-name Something like:,eth0,eth0,,eth0


(The "eth0" argument in auth-zone adds the subnet containing eth0's dynamic address to the zone, so that the interface-name returns the address in outside queries.)

Our final configuration builds on that above, but also adds a secondary DNS server. This is another DNS server which learns the DNS data for the zone by doing zones transfer, and acts as a backup should the primary server become inaccessible. The configuration of the secondary is beyond the scope of this man-page, but the extra configuration of dnsmasq is simple:



Adding auth-sec-servers enables zone transfer in dnsmasq, to allow the secondary to collect the DNS data. If you wish to restrict this data to particular hosts then

auth-peer=<IP address of secondary>


will do so.

Dnsmasq acts as an authoritative server for and domains associated with the subnets given in auth-zone declarations, so reverse (address to name) lookups can be simply configured with a suitable NS record, for instance in this example, where we allow addresses.

Note that at present, reverse ( and zones are not available in zone transfers, so there is no point arranging secondary servers for reverse lookups.

When dnsmasq is configured to act as an authoritative server, the following data is used to populate the authoritative zone.

--mx-host, --srv-host, --dns-rr, --txt-record, --naptr-record , as long as the record names are in the authoritative domain.

--cname as long as the record name is in the authoritative domain. If the target of the CNAME is unqualified, then it is qualified with the authoritative zone name.

IPv4 and IPv6 addresses from /etc/hosts (and --addn-hosts ) and --host-record and --interface-name provided the address falls into one of the subnets specified in the --auth-zone.

Addresses of DHCP leases, provided the address falls into one of the subnets specified in the --auth-zone. (If contructed DHCP ranges are is use, which depend on the address dynamically assigned to an interface, then the form of --auth-zone which defines subnets by the dynamic address of an interface should be used to ensure this condition is met.)

In the default mode, where a DHCP lease has an unqualified name, and possibly a qualified name constructed using --domain then the name in the authoritative zone is constructed from the unqualified name and the zone's domain. This may or may not equal that specified by --domain. If --dhcp-fqdn is set, then the fully qualified names associated with DHCP leases are used, and must match the zone's domain.



0 - Dnsmasq successfully forked into the background, or terminated normally if backgrounding is not enabled.

1 - A problem with configuration was detected.

2 - A problem with network access occurred (address in use, attempt to use privileged ports without permission).

3 - A problem occurred with a filesystem operation (missing file/directory, permissions).

4 - Memory allocation failure.

5 - Other miscellaneous problem.

11 or greater - a non zero return code was received from the lease-script process "init" call. The exit code from dnsmasq is the script's exit code with 10 added.


The default values for resource limits in dnsmasq are generally conservative, and appropriate for embedded router type devices with slow processors and limited memory. On more capable hardware, it is possible to increase the limits, and handle many more clients. The following applies to dnsmasq-2.37: earlier versions did not scale as well.


Dnsmasq is capable of handling DNS and DHCP for at least a thousand clients. The DHCP lease times should not be very short (less than one hour). The value of --dns-forward-max can be increased: start with it equal to the number of clients and increase if DNS seems slow. Note that DNS performance depends too on the performance of the upstream nameservers. The size of the DNS cache may be increased: the hard limit is 10000 names and the default (150) is very low. Sending SIGUSR1 to dnsmasq makes it log information which is useful for tuning the cache size. See the NOTES section for details.

The built-in TFTP server is capable of many simultaneous file transfers: the absolute limit is related to the number of file-handles allowed to a process and the ability of the select() system call to cope with large numbers of file handles. If the limit is set too high using --tftp-max it will be scaled down and the actual limit logged at start-up. Note that more transfers are possible when the same file is being sent than when each transfer sends a different file.

It is possible to use dnsmasq to block Web advertising by using a list of known banner-ad servers, all resolving to or, in /etc/hosts or an additional hosts file. The list can be very long, dnsmasq has been tested successfully with one million names. That size file needs a 1GHz processor and about 60Mb of RAM.


Dnsmasq can be compiled to support internationalisation. To do this, the make targets "all-i18n" and "install-i18n" should be used instead of the standard targets "all" and "install". When internationalisation is compiled in, dnsmasq will produce log messages in the local language and support internationalised domain names (IDN). Domain names in /etc/hosts, /etc/ethers and /etc/dnsmasq.conf which contain non-ASCII characters will be translated to the DNS-internal punycode representation. Note that dnsmasq determines both the language for messages and the assumed charset for configuration files from the LANG environment variable. This should be set to the system default value by the script which is responsible for starting dnsmasq. When editing the configuration files, be careful to do so using only the system-default locale and not user-specific one, since dnsmasq has no direct way of determining the charset in use, and must assume that it is the system default.





/etc/resolv.conf /var/run/dnsmasq/resolv.conf /etc/ppp/resolv.conf /etc/dhcpc/resolv.conf







hosts?(5), resolver?(5)


This manual page was written by Simon Kelley <[email protected]>.