Manual: dnsmasq
DNSMASQ(8) System Manager's Manual DNSMASQ(8)
NAME
dnsmasq - A lightweight DHCP and caching DNS server.
SYNOPSIS
dnsmasq [OPTION]...
DESCRIPTION
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-encapsuā
lated 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 naming 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 unneeded functions to be omitted from the compiled binary.
OPTIONS
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.
--test 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.
-w, --help
Display all command-line options. --help dhcp will display known DHCPv4 configuration options, and --help
dhcp6 will display DHCPv6 options.
-h, --no-hosts
Don't read the hostnames in /etc/hosts.
-H, --addn-hosts=
Additional hosts file. Read the specified file as well as /etc/hosts. If --no-hosts 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 in alphabetical order.
--hostsdir=
Read all the hosts files contained in the directory. New or changed files are read automatically and modified
and deleted files have removed records automatically deleted.
-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=
When replying with information from /etc/hosts or configuration 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.
--dhcp-ttl=
As for --local-ttl, but affects only replies with information from DHCP leases. If both are given, --dhcp-ttl
applies for DHCP information, and --local-ttl for others. Setting this to zero eliminates the effect of --loā
cal-ttl for DHCP.
--neg-ttl=
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 reā
ply. 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.
--max-ttl=
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 floodā
ing the upstream DNS servers.
--max-cache-ttl=
Set a maximum TTL value for entries in the cache.
--min-cache-ttl=
Extend short TTL values to the time given when caching them. Note that artificially extending TTL values is in
general a bad idea, do not do it unless you have a good reason, and understand what you are doing. Dnsmasq
limits the value of this option to one hour, unless recompiled.
--auth-ttl=
Set the TTL value returned in answers from the authoritative server.
--fast-dns-retry=[[,]]
Under normal circumstances, dnsmasq relies on DNS clients to do retries; it does not generate timeouts itself.
Setting this option instructs dnsmasq to generate its own retries starting after a delay which defaults to
1000ms. If the second parameter is given this controls how long the retries will continue for otherwise this
defaults to 10000ms. Retries are repeated with exponential backoff. Using this option increases memory usage
and network bandwidth. If not otherwise configured, this option is activated with the default parameters when
--dnssec is set.
-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
--keep-in-foreground.
-q, --log-queries
Log the results of DNS queries handled by dnsmasq. Enable a full cache dump on receipt of SIGUSR1. If the arā
gument "extra" is supplied, ie --log-queries=extra then the log has extra information at the start of each
line. This consists of a serial number which ties together the log lines associated with an individual query,
and the IP address of the requestor. If the argument "proto" is supplied, this shows everything that "extra"
does and also the network protocol used to communicate the queries. Logging of only queries to the authoritaā
tive server can be configured with --log-queries=auth
-8, --log-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.
--log-debug
Enable extra logging intended for debugging rather than information.
--log-async[=]
Enable asynchronous logging and optionally set the limit on the number of lines which will be queued by dnsā
masq when writing to the syslog is slow. Dnsmasq can log asynchronously: this allows it to continue functionā
ing without being blocked by syslog, and allows syslog to use dnsmasq for DNS queries without risking deadā
lock. 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=
Specify an alternate path for dnsmasq to record its process-id in. Normally /var/run/dnsmasq.pid.
-u, --user=
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=
Specify the group which dnsmasq will run as. The default is "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=
Listen on 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=
Specify the largest EDNS.0 UDP packet which is supported by the DNS forwarder. Defaults to 1232, which is the
recommended size following the DNS flag day in 2020. Only increase if you know what you are doing.
-Q, --query-port=
Send outbound DNS queries from, and listen for their replies on, the specific UDP 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 alloā
cated to it by the OS: this was the default behaviour in versions prior to 2.43.
--port-limit=<#ports>
By default, when sending a query via random ports to multiple upstream servers or retrying a query dnsmasq
will use a single random port for all the tries/retries. This option allows a larger number of ports to be
used, which can increase robustness in certain network configurations. Note that increasing this to more than
two or three can have security and resource implications and should only be done with understanding of those.
--min-port=
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 be larger than that specified.
Useful for systems behind firewalls. If not specified, defaults to 1024.
--max-port=
Use ports lower 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 be lower than that specified. Useful
for systems behind firewalls.
-i, --interface=
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. On
Linux, when --bind-interfaces or --bind-dynamic are in effect, IP alias interface labels (eg "eth1:0") are
checked, rather than interface names. In the degenerate case when an interface has one address, this amounts
to the same thing but when an interface has multiple addresses it allows control over which of those addresses
are accepted. The same effect is achievable in default mode by using --listen-address. A simple wildcard,
consisting of a trailing '*', can be used in --interface and --except-interface options.
-I, --except-interface=
Do not listen on the specified interface. Note that the order of --listen-address --interface and --except-inā
terface options does not matter and that --except-interface options always override the others. The comments
about interface labels for --listen-address apply here.
--auth-server=,[|...]
Enable DNS authoritative mode for queries arriving at an interface or address. Note that the interface or adā
dress need not be mentioned in --interface or --listen-address configuration, indeed --auth-server will overā
ride these and provide a different DNS service on the specified interface. The is the "glue record".
It should resolve in the global DNS to an A and/or AAAA record which points to the address dnsmasq is listenā
ing 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. Since any defined authoritative zones are also available as part of
the normal recusive DNS service supplied by dnsmasq, it can make sense to have an --auth-server declaration
with no interfaces or address, but simply specifying the primary external nameserver.
--local-service[=net|host]
Without parameter or with net parameter, restricts service to connected network. Accept DNS queries only from
hosts whose address is on a local subnet, ie a subnet for which an interface exists on the server. With host
parameter, listens only on lo interface and accepts queries from localhost only. This option only has effect
if 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=
Do not provide DHCP, TFTP or router advertisement on the specified interface, but do provide DNS service.
--no-dhcpv4-interface=
Disable only IPv4 DHCP on the specified interface.
--no-dhcpv6-interface=
Disable IPv6 DHCP and router advertisement on the specified interface.
-a, --listen-address=
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,
127.0.0.1, 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 interā
faces. It then discards requests that it shouldn't reply to. This has the advantage of working even when inā
terfaces 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.
--bind-dynamic
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 and --interface-name and --dynamic-host which depend on the inā
terface over which the query was received. If a name 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 and return all the available addresses otherwise. 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 upā
stream. The set of prefixes affected is the list given in RFC6303, for IPv4 and IPv6. Enabling this also subā
tly alters DNSSEC validation for reverse lookups in the private ranges such that a non-secure DS record is acā
cepted as proof that the range is not signed. This works around behaviour by the public DNS services which
seem not to return validated proof-of-non-existence for DS records in these domains.
-V, --alias=[]|[-],[,]
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=1.2.3.0,6.7.8.0,255.255.255.0 will map 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. 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=192.168.0.10-192.168.0.40,10.0.0.0,255.255.255.0 maps
192.168.0.10->192.168.0.40 to 10.0.0.10->10.0.0.40
-B, --bogus-nxdomain=[/prefix]
Transform replies which contain the specified address or subnet into "No such domain" replies. IPv4 and IPv6
are supported. 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, inā
stead 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 64.94.110.11
--ignore-address=[/prefix]
Ignore replies to A or AAAA queries which include the specified address or subnet. No error is generated,
dnsmasq simply continues to listen for another reply. This is useful to defeat blocking strategies which rely
on quickly supplying a forged answer to a DNS request for certain domain, before the correct answer can arā
rive.
-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 type ANY where the requested name has underscores, to catch LDAP reā
quests, and for all records of types SOA and SRV.
--filter-A
Remove A records from answers. No IPv4 addresses will be returned.
--filter-AAAA
Remove AAAA records from answers. No IPv6 addresses will be returned.
--filter-rr=[,...]
Remove records of the specified type(s) from answers. The otherwise-nonsensical --filter-rr=ANY has a special
meaning: it filters replies to queries for type ANY. Everything other than A, AAAA, MX and CNAME records are
removed. Since ANY queries with forged source addresses can be used in DNS amplification attacks (replies to
ANY queries can be large) this defangs such attacks, whilst still supporting the one remaining possible use of
ANY queries. See RFC 8482 para 4.3 for details.
--cache-rr=[,...]
By default, dnsmasq caches A, AAAA, CNAME and SRV DNS record types. This option adds other record types to
the cache. The RR-type can be given as a name such as TXT or MX or a decimal number. A single --cache-rr opā
tion can take a comma-separated list of RR-types and more than one --cache-rr option is allowed. Use --cache-
rr=ANY to enable caching for all RR-types.
-r, --resolv-file=
Read the IP addresses of the upstream nameservers from , instead of /etc/resolv.conf. For the format of
this file see resolv.conf(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[=]
Allow dnsmasq configuration to be updated via DBus method calls. The configuration which can be changed is upā
stream 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
uk.org.thekelleys.dnsmasq
--enable-ubus[=]
Enable dnsmasq UBus interface. It sends notifications via UBus on DHCPACK and DHCPRELEASE events. Furthermore
it offers metrics and allows configuration of Linux connection track mark based filtering. When DNS query
filtering based on Linux connection track marks is enabled UBus notifications are generated for each resolved
or filtered DNS query. Requires that dnsmasq has been built with UBus support. If the service name is given,
dnsmasq provides service at that namespace, rather than the default which is dnsmasq
-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
--all-servers
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.
--dns-loop-detect
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 .test and sending them to each upstream server. The hex is a UID which encodes the instance of dnsā
masq 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.
--stop-dns-rebind
Reject (and log) addresses from upstream nameservers which are in the private ranges. This blocks an attack
where a browser behind a firewall is used to probe machines on the local network. For IPv6, the private range
covers the IPv4-mapped addresses in private space plus all link-local (LL) and site-local (ULA) addresses.
--rebind-localhost-ok
Exempt 127.0.0.0/8 and ::1 from rebinding checks. This address range is returned by realtime black hole
servers, so blocking it may disable these services.
--rebind-domain-ok=[]|[[//[/]
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/doā
main3/
-n, --no-poll
Don't poll /etc/resolv.conf for changes.
--clear-on-reload
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/]][[#]][@][@[#]]
Specify upstream servers directly. Setting this flag does not suppress reading of /etc/resolv.conf, use --no-
resolv to do that. If one or more optional domains are given, that server is used only for those domains and
they are queried only using the specified server. This is intended for private nameservers: if you have a
nameserver on your network which deals with names of the form xxx.internal.thekelleys.org.uk at 192.168.1.1
then giving the flag --server=/internal.thekelleys.org.uk/192.168.1.1 will send all queries for internal maā
chines to that nameserver, everything else will go to the servers in /etc/resolv.conf. An empty domain speciā
fication, // has the special meaning of "unqualified names only" ie names without any dots in them. A non-
standard port may be specified as part of the IP address using a # character. More than one --server flag is
allowed, with repeated domain or ipaddr parts as required.
More specific domains take precedence over less specific domains, so: --server=/google.com/1.2.3.4
--server=/www.google.com/2.3.4.5 will send queries for google.com and gmail.google.com to 1.2.3.4, but
www.google.com will go to 2.3.4.5
Matching of domains is normally done on complete labels, so /google.com/ matches google.com and www.google.com
but NOT supergoogle.com. This can be overridden with a * at the start of a pattern only: /*google.com/ will
match google.com and www.google.com AND supergoogle.com. The non-wildcard form has priority, so if
/google.com/ and /*google.com/ are both specified then google.com and www.google.com will match /google.com/
and /*google.com/ will only match supergoogle.com.
For historical reasons, the pattern /.google.com/ is equivalent to /google.com/ if you wish to match any subā
domain of google.com but NOT google.com itself, use /*.google.com/
The special server address '#' means, "use the standard servers", so --server=/google.com/1.2.3.4
--server=/www.google.com/# will send queries for google.com and its subdomains to 1.2.3.4, except
www.google.com (and its subdomains) which will be forwarded as usual.
Also permitted is a -S flag which gives a domain but no IP address; this tells dnsmasq that a domain is local
and it may answer queries from /etc/hosts or DHCP but should never forward queries on that domain to any upā
stream servers. --local is a synonym for --server to make configuration files clearer in this case.
IPv6 addresses may include an %interface scope-id, eg fe80::202:a412:4512:7bbf%eth0.
The optional string after the @ character tells dnsmasq how to set the source of the queries to this nameā
server. It can either be an ip-address, an interface name or both. The ip-address should belong to the machine
on which dnsmasq is running, otherwise this server line will be logged and then ignored. If an interface name
is given, then queries to the server will be forced via that interface; if an ip-address is given then the
source address of the queries will be set to that address; and if both are given then a combination of ip-adā
dress and interface name will be used to steer requests to the server. The query-port flag is ignored for any
servers which have a source address specified but the port may be specified directly as part of the source adā
dress. Forcing queries to an interface is not implemented on all platforms supported by dnsmasq.
Upstream servers may be specified with a hostname rather than an IP address. In this case, dnsmasq will try
to use the system resolver to get the IP address of a server during startup. If name resolution fails, startā
ing dnsmasq fails, too. If the system's configuration is such that the system resolver sends DNS queries
through the dnsmasq instance which is starting up then this will time-out and fail.
--rev-server=[/][,][#][@][@[#]]
This is functionally the same as --server, but provides some syntactic sugar to make specifying address-to-
name queries easier. For example --rev-server=1.2.3.0/24,192.168.0.1 is exactly equivalent to
--server=/3.2.1.in-addr.arpa/192.168.0.1 Allowed prefix lengths are 1-32 (IPv4) and 1-128 (IPv6). If the preā
fix length is omitted, dnsmasq substitutes either 32 (IPv4) or 128 (IPv6).
-A, --address=/[/...]/[]
Specify an IP address to return for any host in the given domains. A (or AAAA) queries in the domains are
never forwarded and always replied to with the specified IP address which may be IPv4 or IPv6. To give multiā
ple addresses or both IPv4 and IPv6 addresses for a domain, use repeated --address flags. Note that
/etc/hosts and DHCP leases override this for individual names. A common use of this is to redirect the entire
doubleclick.net domain to some friendly local web server to avoid banner ads. The domain specification works
in the same way as for --server, with the additional facility that /#/ matches any domain. Thus --adā
dress=/#/1.2.3.4 will always return 1.2.3.4 for any query not answered from /etc/hosts or DHCP and not sent to
an upstream nameserver by a more specific --server directive. As for --server, one or more domains with no adā
dress returns a no-such-domain answer, so --address=/example.com/ is equivalent to --server=/example.com/ and
returns NXDOMAIN for example.com and all its subdomains. An address specified as '#' translates to the NULL
address of 0.0.0.0 and its IPv6 equivalent of :: so --address=/example.com/# will return NULL addresses for
example.com and its subdomains. This is partly syntactic sugar for --address=/example.com/0.0.0.0 and --adā
dress=/example.com/:: but is also more efficient than including both as separate configuration lines. Note
that NULL addresses normally work in the same way as localhost, so beware that clients looking up these names
are likely to end up talking to themselves.
Note that the behaviour for queries which don't match the specified address literal changed in version 2.86.
Previous versions, configured with (eg) --address=/example.com/1.2.3.4 and then queried for a RR type other
than A would return a NoData answer. From 2.86, the query is sent upstream. To restore the pre-2.86 behavā
iour, use the configuration --address=/example.com/1.2.3.4 --local=/example.com/
--ipset=/[/...]/[,...]
Places the resolved IP addresses of queries for one or more domains in the specified Netfilter IP set. If mulā
tiple setnames are given, then the addresses are placed in each of them, subject to the limitations of an IP
set (IPv4 addresses cannot be stored in an IPv6 IP set and vice versa). Domains and subdomains are matched in
the same way as --address. These IP sets must already exist. See ipset(8) for more details.
--nftset=/[/...]/[(6|4)#[#]#[,[(6|4)#[#]#]...]
Similar to the --ipset option, but accepts one or more nftables sets to add IP addresses into. These sets
must already exist. See nft(8) for more details. The family, table and set are passed directly to the nft. If
the spec starts with 4# or 6# then only A or AAAA records respectively are added to the set. Since an nftset
can hold only IPv4 or IPv6 addresses, this avoids errors being logged for addresses of the wrong type.
--connmark-allowlist-enable[=]
Enables filtering of incoming DNS queries with associated Linux connection track marks according to individual
allowlists configured via a series of --connmark-allowlist options. Disallowed queries are not forwarded; they
are rejected with a REFUSED error code. DNS queries are only allowed if they do not have an associated Linux
connection track mark, or if the queried domains match the configured DNS patterns for the associated Linux
connection track mark. If no allowlist is configured for a Linux connection track mark, all DNS queries assoā
ciated with that mark are rejected. If a mask is specified, Linux connection track marks are first bitwise
ANDed with the given mask before being processed.
--connmark-allowlist=[/][,[/...]]
Configures the DNS patterns that are allowed in DNS queries associated with the given Linux connection track
mark. If a mask is specified, Linux connection track marks are first bitwise ANDed with the given mask before
they are compared to the given connection track mark. Patterns follow the syntax of DNS names, but additionā
ally allow the wildcard character "*" to be used up to twice per label to match 0 or more characters within
that label. Note that the wildcard never matches a dot (e.g., "*.example.com" matches "api.example.com" but
not "api.us.example.com"). Patterns must be fully qualified, i.e., consist of at least two labels. The final
label must not be fully numeric, and must not be the "local" pseudo-TLD. A pattern must end with at least two
literal (non-wildcard) labels. Instead of a pattern, "*" can be specified to disable allowlist filtering for
a given Linux connection track mark entirely.
-m, --mx-host=[[,],]
Return an MX record named pointing to the given hostname (if given), or the host specified in the
--mx-target switch or, if that switch is not given, the host on which dnsmasq is running. The default is useā
ful for directing mail from systems on a LAN to a central server. The preference value is optional, and deā
faults to 1 if not given. More than one MX record may be given for a host.
-t, --mx-target=
Specify the default target for the MX record returned by dnsmasq. See --mx-host. If --mx-target is given, but
not --mx-host, then dnsmasq returns a MX record containing the MX target for MX queries on the hostname of the
machine on which dnsmasq is running.
-e, --selfmx
Return an MX record pointing to itself for each local machine. Local machines are those in /etc/hosts or with
DHCP leases.
-L, --localmx
Return an MX record pointing to the host given by --mx-target (or the machine on which dnsmasq is running) for
each local machine. Local machines are those in /etc/hosts or with DHCP leases.
-W, --srv-host=<_service>.<_prot>[.],[[,[,[,]]]]
Return a SRV DNS record. See RFC2782 for details. If not supplied, the domain defaults to that given by --doā
main. The default for the target domain is empty, and the default for port is one and the defaults for weight
and priority are zero. Be careful if transposing data from BIND zone files: the port, weight and priority numā
bers are in a different order. More than one SRV record for a given service/domain is allowed, all that match
are returned.
--host-record=[,....],[],[][,]
Add A, AAAA and PTR records to the DNS. This adds one or more names to the DNS with associated IPv4 (A) and
IPv6 (AAAA) records. A name may appear in more than one --host-record and therefore be assigned more than one
address. Only the first address creates a PTR record linking the address to the name. This is the same rule as
is used reading hosts-files. --host-record options are considered to be read before host-files, so a name apā
pearing there inhibits PTR-record creation if it appears in hosts-file also. Unlike hosts-files, names are not
expanded, even when --expand-hosts is in effect. Short and long names may appear in the same --host-record,
eg. --host-record=laptop,laptop.thekelleys.org,192.168.0.1,1234::100
If the time-to-live is given, it overrides the default, which is zero or the value of --local-ttl. The value
is a positive integer and gives the time-to-live in seconds.
--dynamic-host=,[IPv4-address],[IPv6-address],
Add A, AAAA and PTR records to the DNS in the same subnet as the specified interface. The address is derived
from the network part of each address associated with the interface, and the host part from the specified adā
dress. For example --dynamic-host=example.com,0.0.0.8,eth0 will, when eth0 has the address 192.168.78.x and
netmask 255.255.255.0 give the name example.com an A record for 192.168.78.8. The same principle applies to
IPv6 addresses. Note that if an interface has more than one address, more than one A or AAAA record will be
created. The TTL of the records is always zero, and any changes to interface addresses will be immediately reā
flected in them.
-Y, --txt-record=[[,],]
Return a TXT DNS record. The value of TXT record is a set of strings, so any number may be included, delimā
ited by commas; use quotes to put commas into a string. Note that the maximum length of a single string is 255
characters, longer strings are split into 255 character chunks.
--ptr-record=[,]
Return a PTR DNS record.
--naptr-record=,,,,,[,]
Return an NAPTR DNS record, as specified in RFC3403.
--caa-record=,,,
Return a CAA DNS record, as specified in RFC6844.
--cname=,[,][,]
Return a CNAME record which indicates that is really . There is a significant limitation on
the target; it must be a DNS record which is known to dnsmasq and NOT a DNS record which comes from an upā
stream server. The cname must be unique, but it is permissible to have more than one cname pointing to the
same target. Indeed it's possible to declare multiple cnames to a target in a single line, like so:
--cname=cname1,cname2,target
If the time-to-live is given, it overrides the default, which is zero or the value of --local-ttl. The value
is a positive integer and gives the time-to-live in seconds.
--dns-rr=,,[]
Return an arbitrary DNS Resource Record. The number is the type of the record (which is always in the C_IN
class). The value of the record is given by the hex data, which may be of the form 01:23:45 or 01 23 45 or
012345 or any mixture of these.
--interface-name=,[/4|/6]
Return DNS records associating the name with the address(es) of the given interface. This flag specifies an A
or AAAA record for the given name in the same way as an /etc/hosts line, except that the address is not conā
stant, but taken from the given interface. The interface may be followed by "/4" or "/6" to specify that only
IPv4 or IPv6 addresses of the interface should be used. If the interface is down, not configured or non-exisā
tent, an empty record is returned. The matching PTR record is also created, mapping the interface address to
the name. More than one name may be associated with an interface address by repeating the flag; in that case
the first instance is used for the reverse address-to-name mapping. Note that a name used in --interface-name
may not appear in /etc/hosts.
--synth-domain=,[,[*]]
Create artificial A/AAAA and PTR records for an address range. The records either seqential numbers or the adā
dress, with periods (or colons for IPv6) replaced with dashes.
An examples should make this clearer. First sequential numbers. --synth-domain=thekelā
leys.org.uk,192.168.0.50,192.168.0.70,internal-* results in the name internal-0.thekelleys.org.uk. returning
192.168.0.50, internal-1.thekelleys.org.uk returning 192.168.0.51 and so on. (note the *) The same principle
applies to IPv6 addresses (where the numbers may be very large). Reverse lookups from address to name behave
as expected.
Second, --synth-domain=thekelleys.org.uk,192.168.0.0/24,internal- (no *) will result in a query for interā
nal-192-168-0-56.thekelleys.org.uk returning 192.168.0.56 and a reverse query vice versa. The same applies to
IPv6; the representation doesn't use the :: compression feature or the special representation of V4 mapped
IPv6 addresses as these can generate illegal domain names, so all domains are of the form interā
nal-1000-0000-0000-0000-0000-0000-0000-0008.example.com
The address range can be of the form , or / in both
forms of the option. For IPv6 the start and end addresses must fall in the same /64 network, or prefix-length
must be greater than or equal to 64 except that shorter prefix lengths than 64 are allowed only if non-sequenā
tial names are in use.
--dumpfile=
Specify the location of a pcap-format file which dnsmasq uses to dump copies of network packets for debugging
purposes. If the file exists when dnsmasq starts, it is not deleted; new packets are added to the end. The
file may be a named-pipe which Wireshark is listening to.
--dumpmask=
Specify which types of packets should be added to the dumpfile. The argument should be the OR of the bitmasks
for each type of packet to be dumped: it can be specified in hex by preceding the number with 0x in the norā
mal way. Each time a packet is written to the dumpfile, dnsmasq logs the packet sequence and the mask repreā
senting its type. The current types are: 0x0001 - DNS queries from clients, 0x0002 DNS replies to clients,
0x0004 - DNS queries to upstream, 0x0008 - DNS replies from upstream, 0x0010 - queries send upstream for
DNSSEC validation, 0x0020 - replies to queries for DNSSEC validation, 0x0040 - replies to client queries which
fail DNSSEC validation, 0x0080 replies to queries for DNSSEC validation which fail validation, 0x1000 -
DHCPv4, 0x2000 - DHCPv6, 0x4000 - Router advertisement, 0x8000 - TFTP.
--add-mac[=base64|text]
Add the MAC address of the requestor to DNS queries which are forwarded upstream. This may be used to DNS filā
tering by the upstream server. The MAC address can only be added if the requestor is on the same subnet as the
dnsmasq server. Note that the mechanism used to achieve this (an EDNS0 option) is not yet standardised, so
this should be considered experimental. Also note that exposing MAC addresses in this way may have security
and privacy implications. The warning about caching given for --add-subnet applies to --add-mac too. An alterā
native encoding of the MAC, as base64, is enabled by adding the "base64" parameter and a human-readable encodā
ing of hex-and-colons is enabled by added the "text" parameter.
--strip-mac
Remove any MAC address information already in downstream queries before forwarding upstream.
--add-cpe-id=
Add an arbitrary identifying string to DNS queries which are forwarded upstream.
--add-subnet[[=[/]][,[/]]]
Add a subnet address to the DNS queries which are forwarded upstream. If an address is specified in the flag,
it will be used, otherwise, the address of the requestor will be used. The amount of the address forwarded deā
pends on the prefix length parameter: 32 (128 for IPv6) forwards the whole address, zero forwards none of it
but still marks the request so that no upstream nameserver will add client address information either. The deā
fault is zero for both IPv4 and IPv6. Note that upstream nameservers may be configured to return different reā
sults based on this information, but the dnsmasq cache does not take account. Caching is therefore disabled
for such replies, unless the subnet address being added is constant.
For example, --add-subnet=24,96 will add the /24 and /96 subnets of the requestor for IPv4 and IPv6 reā
questors, respectively. --add-subnet=1.2.3.4/24 will add 1.2.3.0/24 for IPv4 requestors and ::/0 for IPv6 reā
questors. --add-subnet=1.2.3.4/24,1.2.3.4/24 will add 1.2.3.0/24 for both IPv4 and IPv6 requestors.
--strip-subnet
Remove any subnet address already present in a downstream query before forwarding it upstream. If --add-subnet
is set this also ensures that any downstream-provided subnet is replaced by the one added by dnsmasq. Otherā
wise, dnsmasq will NOT replace an existing subnet in the query.
--umbrella[=[deviceid:][,orgid:][,assetid:]]
Embeds the requestor's IP address in DNS queries forwarded upstream. If device id or, asset id or organizaā
tion id are specified, the information is included in the forwarded queries and may be able to be used in filā
tering policies and reporting. The order of the id attributes is irrelevant, but they must be separated by a
comma. Deviceid is a sixteen digit hexadecimal number, org and asset ids are decimal numbers.
-c, --cache-size=
Set the size of dnsmasq's cache. The default is 150 names. Setting the cache size to zero disables caching.
Note: huge cache size impacts performance.
-N, --no-negcache
Disable negative caching. Negative caching allows dnsmasq to remember "no such domain" answers from upstream
nameservers and answer identical queries without forwarding them again.
--no-round-robin
Dnsmasq normally permutes the order of A or AAAA records for the same name on successive queries, for load-
balancing. This turns off that behaviour, so that the records are always returned in the order that they are
received from upstream.
--do-0x20-encode, --no-0x20-encode
Dnsmasq can scramble the case of letters in DNS queries it sends upstream as a security feature. This techā
nique can interact badly with rare broken DNS servers which don't preserve the case of the query in their reā
ply. The first time a reply is returned which matches the query in all respects except case, a warning will be
logged. If this coincides with DNS not functioning, it is necessary to disable the feature. As at version
2.91, 0x20 encoding is disabled by default, and must be enabled with --do-0x20-encode. The default may change
in the future, so to be sure of its status after an upgrade, set --do-0x20-encode or --no-0x20-encode in your
config. --no-0x20-encode overrides --do-x20-encode or a future default 0x20-encode enable.
--use-stale-cache[=]
When set, if a DNS name exists in the cache, but its time-to-live has expired, dnsmasq will return the data
anyway. (It attempts to refresh the data with an upstream query after returning the stale data.) This can imā
prove speed and reliability. It comes at the expense of sometimes returning out-of-date data and less effiā
cient cache utilisation, since old data cannot be flushed when its TTL expires, so the cache becomes mostly
least-recently-used. To mitigate issues caused by massively outdated DNS replies, the maximum overaging of
cached records can be specified in seconds (defaulting to not serve anything older than one day). Setting the
TTL excess time to zero will serve stale cache data regardless how long it has expired.
-0, --dns-forward-max=
Set the maximum number of concurrent DNS queries. The default value is 150, which should be fine for most seā
tups. The only known situation where this needs to be increased is when using web-server log file resolvers,
which can generate large numbers of concurrent queries. This parameter actually controls the number of concurā
rent queries per server group, where a server group is the set of server(s) associated with a single domain.
So if a domain has its own server via --server=/example.com/1.2.3.4 and 1.2.3.4 is not responding, but queries
for *.example.com cannot go elsewhere, then other queries will not be affected. On configurations with many
such server groups and tight resources, this value may need to be reduced.
--dnssec
Validate DNS replies and cache DNSSEC data. When forwarding DNS queries, dnsmasq requests the DNSSEC records
needed to validate the replies. The replies are validated and the result returned as the Authenticated Data
bit in the DNS packet. In addition the DNSSEC records are stored in the cache, making validation by clients
more efficient. Note that validation by clients is the most secure DNSSEC mode, but for clients unable to do
validation, use of the AD bit set by dnsmasq is useful, provided that the network between the dnsmasq server
and the client is trusted. Dnsmasq must be compiled with HAVE_DNSSEC enabled, and DNSSEC trust anchors proā
vided, see --trust-anchor. Because the DNSSEC validation process uses the cache, it is not permitted to reā
duce the cache size below the default when DNSSEC is enabled. The nameservers upstream of dnsmasq must be
DNSSEC-capable, ie capable of returning DNSSEC records with data. If they are not, then dnsmasq will not be
able to determine the trusted status of answers and this means that DNS service will be entirely broken.
--trust-anchor=,[,][,,,]
Provide DS records to act a trust anchors for DNSSEC validation. The class defaults to IN. Typically these
will be the DS record(s) for Key Signing key(s) (KSK) of the root zone, but trust anchors for limited domains
are also possible. A negative trust anchor (ie. proof that a DS record doesn't exist) may be configured be
specifying only the name or only the name and class. This can be useful for forcing dnsmasq to treat zones
delegated using --server=// as unsigned. The current root-zone trust anchors may be downā
loaded from https://data.iana.org/root-anchors/root-anchors.xml
--dnssec-check-unsigned[=no]
As a default, dnsmasq checks that unsigned DNS replies are legitimate: this entails possible extra queries
even for the majority of DNS zones which are not, at the moment, signed. If --dnssec-check-unsigned=no appears
in the configuration, then such replies they are assumed to be valid and passed on (without the "authentic
data" bit set, of course). This does not protect against an attacker forging unsigned replies for signed DNS
zones, but it is fast.
Versions of dnsmasq prior to 2.80 defaulted to not checking unsigned replies, and used --dnssec-check-unsigned
to switch this on. Such configurations will continue to work as before, but those which used the default of no
checking will need to be altered to explicitly select no checking. The new default is because switching off
checking for unsigned replies is inherently dangerous. Not only does it open the possibility of forged
replies, but it allows everything to appear to be working even when the upstream namesevers do not support
DNSSEC, and in this case no DNSSEC validation at all is occurring.
--dnssec-no-timecheck
DNSSEC signatures are only valid for specified time windows, and should be rejected outside those windows.
This generates an interesting chicken-and-egg problem for machines which don't have a hardware real time
clock. For these machines to determine the correct time typically requires use of NTP and therefore DNS, but
validating DNS requires that the correct time is already known. Setting this flag removes the time-window
checks (but not other DNSSEC validation.) only until the dnsmasq process receives SIGINT. The intention is
that dnsmasq should be started with this flag when the platform determines that reliable time is not currently
available. As soon as reliable time is established, a SIGINT should be sent to dnsmasq, which enables time
checking, and purges the cache of DNS records which have not been thoroughly checked.
Earlier versions of dnsmasq overloaded SIGHUP (which re-reads much configuration) to also enable time validaā
tion.
If dnsmasq is run in debug mode (--no-daemon flag) then SIGINT retains its usual meaning of terminating the
dnsmasq process.
--dnssec-timestamp=
Enables an alternative way of checking the validity of the system time for DNSSEC (see --dnssec-no-timecheck).
In this case, the system time is considered to be valid once it becomes later than the timestamp on the speciā
fied file. The file is created and its timestamp set automatically by dnsmasq. The file must be stored on a
persistent filesystem, so that it and its mtime are carried over system restarts. The timestamp file is creā
ated after dnsmasq has dropped root, so it must be in a location writable by the unprivileged user that dnsā
masq runs as.
--proxy-dnssec
Copy the DNSSEC Authenticated Data bit from upstream servers to downstream clients. This is an alternative to
having dnsmasq validate DNSSEC, but it depends on the security of the network between dnsmasq and the upstream
servers, and the trustworthiness of the upstream servers. Note that caching the Authenticated Data bit corā
rectly in all cases is not technically possible. If the AD bit is to be relied upon when using this option,
then the cache should be disabled using --cache-size=0. In most cases, enabling DNSSEC validation within dnsā
masq is a better option. See --dnssec for details.
--dnssec-limits=[,.......]
Override the default resource limits applied to DNSSEC validation. Cryptographic operations are expensive and
crafted domains can DoS a DNSSEC validator by forcing it to do hundreds of thousands of such operations. To
avoid this, the dnsmasq validation code applies limits on how much work will be expended in validation. If any
of the limits are exceeded, the validation will fail and the domain treated as BOGUS. There are four limits,
in order(default values in parens): number a signature validation fails per RRset(20), number of signature
validations and hash computations per query(200), number of sub-queries to fetch DS and DNSKEY RRsets per
query(40), and the number of iterations in a NSEC3 record(150). The maximum values reached during validation
are stored, and dumped as part of the stats generated by SIGUSR1. Supplying a limit value of 0 leaves the deā
fault in place, so --dnssec-limits=0,0,20 sets the number of sub-queries to 20 whilst leaving the other limits
at default values.
--dnssec-debug
Set debugging mode for the DNSSEC validation, set the Checking Disabled bit on upstream queries, and don't
convert replies which do not validate to responses with a return code of SERVFAIL. Note that setting this may
affect DNS behaviour in bad ways, it is not an extra-logging flag and should not be set in production.
--auth-zone=[,[/][,[/].....][,exclude:[/]].....]
Define a DNS zone for which dnsmasq acts as authoritative server. Locally defined DNS records which are in the
domain will be served. If subnet(s) are given, A and AAAA records must be in one of the specified subnets.
As alternative to directly specifying the subnets, it's possible to give the name of an interface, in which
case the subnets implied by that interface's configured addresses and netmask/prefix-length are used; this is
useful when using constructed DHCP ranges as the actual address is dynamic and not known when configuring dnsā
masq. The interface addresses may be confined to only IPv6 addresses using /6 or to only IPv4 using
/4. This is useful when an interface has dynamically determined global IPv6 addresses which should
appear in the zone, but RFC1918 IPv4 addresses which should not. Interface-name and address-literal subnet
specifications may be used freely in the same --auth-zone declaration.
It's possible to exclude certain IP addresses from responses. It can be used, to make sure that answers conā
tain only global routeable IP addresses (by excluding loopback, RFC1918 and ULA addresses).
The subnet(s) are also used to define in-addr.arpa and ip6.arpa domains which are served for reverse-DNS
queries. If not specified, the prefix length defaults to 24 for IPv4 and 64 for IPv6. For IPv4 subnets, the
prefix length should be have the value 8, 16 or 24 unless you are familiar with RFC 2317 and have arranged the
in-addr.arpa delegation accordingly. Note that if no subnets are specified, then no reverse queries are anā
swered.
--auth-soa=[,[,[,[,]]]]
Specify fields in the SOA record associated with authoritative zones. Note that this is optional, all the valā
ues are set to sane defaults.
--auth-sec-servers=[,[,...]]
Specify any secondary servers for a zone for which dnsmasq is authoritative. These servers must be configured
to get zone data from dnsmasq by zone transfer, and answer queries for the same authoritative zones as dnsā
masq.
--auth-peer=[,[,...]]
Specify the addresses of secondary servers which are allowed to initiate zone transfer (AXFR) requests for
zones for which dnsmasq is authoritative. If this option is not given but --auth-sec-servers is, then AXFR reā
quests will be accepted from any secondary. Specifying --auth-peer without --auth-sec-servers enables zone
transfer but does not advertise the secondary in NS records returned by dnsmasq.
--conntrack
Read the Linux connection track mark associated with incoming DNS queries and set the same mark value on upā
stream traffic used to answer those queries. This allows traffic generated by dnsmasq to be associated with
the queries which cause it, useful for bandwidth accounting and firewalling. Dnsmasq must have conntrack supā
port compiled in and the kernel must have conntrack support included and configured. This option cannot be
combined with --query-port.
-F, --dhcp-range=[tag:[,tag:],][set:,][,|[,[,]]][,]
-F, --dhcp-range=[tag:[,tag:],][set:,][,|constructor:][,][,][,]
Enable the DHCP server. Addresses will be given out from the range to and from statiā
cally defined addresses given in --dhcp-host options. If the lease time is given, then leases will be given
for that length of time. The lease time is in seconds, or minutes (eg 45m) or hours (eg 1h) or days (2d) or
weeks (1w) or "infinite". If not given, the default lease time is one hour for IPv4 and one day for IPv6. The
minimum lease time is two minutes. For IPv6 ranges, the lease time maybe "deprecated"; this sets the preferred
lifetime sent in a DHCP lease or router advertisement to zero, which causes clients to use other addresses, if
available, for new connections as a prelude to renumbering.
This option may be repeated, with different addresses, to enable DHCP service to more than one network. For
directly connected networks (ie, networks on which the machine running dnsmasq has an interface) the netmask
is optional: dnsmasq will determine it from the interface configuration. For networks which receive DHCP serā
vice via a relay agent, dnsmasq cannot determine the netmask itself, so it should be specified, otherwise dnsā
masq will have to guess, based on the class (A, B or C) of the network address. The broadcast address is alā
ways optional. It is always allowed to have more than one --dhcp-range in a single subnet.
For IPv6, the parameters are slightly different: instead of netmask and broadcast address, there is an opā
tional prefix length which must be equal to or larger then the prefix length on the local interface. If not
given, this defaults to 64. Unlike the IPv4 case, the prefix length is not automatically derived from the inā
terface configuration. The minimum size of the prefix length is 64.
IPv6 (only) supports another type of range. In this, the start address and optional end address contain only
the network part (ie ::1) and they are followed by constructor:. This forms a template which deā
scribes how to create ranges, based on the addresses assigned to the interface. For instance
--dhcp-range=::1,::400,constructor:eth0
will look for addresses on eth0 and then create a range from ::1 to ::400. If the interface
is assigned more than one network, then the corresponding ranges will be automatically created, and then depā
recated and finally removed again as the address is deprecated and then deleted. The interface name may have a
final "*" wildcard. Note that just any address on eth0 will not do: it must not be an autoconfigured or priā
vacy address, or be deprecated.
If a --dhcp-range is only being used for stateless DHCP and/or SLAAC, then the address can be simply ::
--dhcp-range=::,constructor:eth0
The optional set: sets an alphanumeric label which marks this network so that DHCP options may be speciā
fied on a per-network basis. When it is prefixed with 'tag:' instead, then its meaning changes from setting a
tag to matching it. Only one tag may be set, but more than one tag may be matched.
The optional keyword may be static which tells dnsmasq to enable DHCP for the network specified, but
not to dynamically allocate IP addresses: only hosts which have static addresses given via --dhcp-host or from
/etc/ethers will be served. A static-only subnet with address all zeros may be used as a "catch-all" address
to enable replies to all Information-request packets on a subnet which is provided with stateless DHCPv6, ie
--dhcp-range=::,static
For IPv4, the may be proxy in which case dnsmasq will provide proxy-DHCP on the specified subnet. (See
--pxe-prompt and --pxe-service for details.)
For IPv6, the mode may be some combination of ra-only, slaac, ra-names, ra-stateless, ra-advrouter, off-link.
ra-only tells dnsmasq to offer Router Advertisement only on this subnet, and not DHCP.
slaac tells dnsmasq to offer Router Advertisement on this subnet and to set the A bit in the router advertiseā
ment, so that the client will use SLAAC addresses. When used with a DHCP range or static DHCP address this reā
sults in the client having both a DHCP-assigned and a SLAAC address.
ra-stateless sends router advertisements with the O and A bits set, and provides a stateless DHCP service. The
client will use a SLAAC address, and use DHCP for other configuration information.
ra-names enables a mode which gives DNS names to dual-stack hosts which do SLAAC for IPv6. Dnsmasq uses the
host's IPv4 lease to derive the name, network segment and MAC address and assumes that the host will also have
an IPv6 address calculated using the SLAAC algorithm, on the same network segment. The address is pinged, and
if a reply is received, an AAAA record is added to the DNS for this IPv6 address. Note that this is only hapā
pens for directly-connected networks, (not one doing DHCP via a relay) and it will not work if a host is using
privacy extensions. ra-names can be combined with ra-stateless and slaac.
ra-advrouter enables a mode where router address(es) rather than prefix(es) are included in the advertiseā
ments. This is described in RFC-3775 section 7.2 and is used in mobile IPv6. In this mode the interval option
is also included, as described in RFC-3775 section 7.3.
off-link tells dnsmasq to advertise the prefix without the on-link (aka L) bit set.
-G, --dhcp-host=[][,id:|*][,set:][,tag:][,][,][,][,ignore]
Specify per host parameters for the DHCP server. This allows a machine with a particular hardware address to
be always allocated the same hostname, IP address and lease time. A hostname specified like this overrides any
supplied by the DHCP client on the machine. It is also allowable to omit the hardware address and include the
hostname, in which case the IP address and lease times will apply to any machine claiming that name. For examā
ple --dhcp-host=00:20:e0:3b:13:af,wap,infinite tells dnsmasq to give the machine with hardware address
00:20:e0:3b:13:af the name wap, and an infinite DHCP lease. --dhcp-host=lap,192.168.0.199 tells dnsmasq to
always allocate the machine lap the IP address 192.168.0.199.
Addresses allocated like this are not constrained to be in the range given by the --dhcp-range option, but
they must be in the same subnet as some valid dhcp-range. For subnets which don't need a pool of dynamically
allocated addresses, use the "static" keyword in the --dhcp-range declaration.
It is allowed to use client identifiers (called client DUID in IPv6-land) rather than hardware addresses to
identify hosts by prefixing with 'id:'. Thus: --dhcp-host=id:01:02:03:04,..... refers to the host with client
identifier 01:02:03:04. It is also allowed to specify the client ID as text, like this: --dhcp-host=id:clienā
tidastext,.....
A single --dhcp-host may contain an IPv4 address or one or more IPv6 addresses, or both. IPv6 addresses must
be bracketed by square brackets thus: --dhcp-host=laptop,[1234::56] IPv6 addresses may contain only the host-
identifier part: --dhcp-host=laptop,[::56] in which case they act as wildcards in constructed DHCP ranges,
with the appropriate network part inserted. For IPv6, an address may include a prefix length: --dhcp-host=lapā
top,[1234:50/126] which (in this case) specifies four addresses, 1234::50 to 1234::53. This (an the ability to
specify multiple addresses) is useful when a host presents either a consistent name or hardware-ID, but varyā
ing DUIDs, since it allows dnsmasq to honour the static address allocation but assign a different address for
each DUID. This typically occurs when chain netbooting, as each stage of the chain gets in turn allocates an
address.
Note that in IPv6 DHCP, the hardware address may not be available, though it normally is for direct-connected
clients, or clients using DHCP relays which support RFC 6939.
For DHCPv4, the special option id:* means "ignore any client-id and use MAC addresses only." This is useful
when a client presents a client-id sometimes but not others.
If a name appears in /etc/hosts, the associated address can be allocated to a DHCP lease, but only if a
--dhcp-host option specifying the name also exists. Only one hostname can be given in a --dhcp-host option,
but aliases are possible by using CNAMEs. (See --cname ). Note that /etc/hosts is NOT used when the DNS server
side of dnsmasq is disabled by setting the DNS server port to zero.
More than one --dhcp-host can be associated (by name, hardware address or UID) with a host. Which one is used
(and therefore which address is allocated by DHCP and appears in the DNS) depends on the subnet on which the
host last obtained a DHCP lease: the --dhcp-host with an address within the subnet is used. If more than one
address is within the subnet, the result is undefined. A corollary to this is that the name associated with a
host using --dhcp-host does not appear in the DNS until the host obtains a DHCP lease.
The special keyword ignore tells dnsmasq never to offer a DHCP lease to a machine. The machine can be speciā
fied by hardware address, client ID or hostname. For example: --dhcp-host=00:20:e0:3b:13:af,ignore. This can
be useful when there is another DHCP server on the network which should be used by some machines.
The set: construct sets the tag whenever this --dhcp-host directive is in use. This can be used to selecā
tively send DHCP options just for this host. More than one tag can be set in a --dhcp-host directive (but not
in other places where set: is allowed). When a host matches any --dhcp-host directive (or one implied by
/etc/ethers) then the special tag known is set. This allows dnsmasq to be configured to ignore requests from
unknown machines using --dhcp-ignore=tag:!known. If the host matches only a --dhcp-host directive which canā
not be used because it specifies an address on a different subnet, the tag known-othernet is set.
The tag: construct filters which dhcp-host directives are used. More than one tag can be provided. In
this case, the request must match all tags. Tagged directives are used in preference to untagged ones. Note
that one of , or still must be specified (can be a wildcard).
Ethernet addresses (but not client-ids) may have wildcard bytes, so for example --dhcp-
host=00:20:e0:3b:13:*,ignore will cause dnsmasq to ignore the given range of hardware addresses. Note that the
"*" will need to be escaped or quoted on a command line, but not in the configuration file.
Hardware addresses normally match any network (ARP) type, but it is possible to restrict them to a single ARP
type by preceding them with the ARP-type (in HEX) and "-". so --dhcp-host=06-00:20:e0:3b:13:af,1.2.3.4 will
only match a Token-Ring hardware address, since the ARP-address type for token ring is 6.
As a special case, in DHCPv4, it is possible to include more than one hardware address. eg: --dhcp-
host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2. This allows an IP address to be associated with multiā
ple hardware addresses, and gives dnsmasq permission to abandon a DHCP lease to one of the hardware addresses
when another one asks for a lease. Beware that this is a dangerous thing to do: it will only work reliably if
only one of the hardware addresses is active at any time and there is no way for dnsmasq to enforce this. It
is, for instance, useful to allocate a stable IP address to a laptop which has both wired and wireless interā
faces.
--dhcp-hostsfile=
Read DHCP host information from the specified file. If a directory is given, then read all the files contained
in that directory in alphabetical order. The file contains information about one host per line. The format of
a line is the same as text to the right of '=' in --dhcp-host. The advantage of storing DHCP host information
in this file is that it can be changed without re-starting dnsmasq: the file will be re-read when dnsmasq reā
ceives SIGHUP.
--dhcp-optsfile=
Read DHCP option information from the specified file. If a directory is given, then read all the files conā
tained in that directory in alphabetical order. The advantage of using this option is the same as for --dhcp-
hostsfile: the --dhcp-optsfile will be re-read when dnsmasq receives SIGHUP. Note that it is possible to enā
code the information in a --dhcp-boot flag as DHCP options, using the options names bootfile-name, server-ip-
address and tftp-server. This allows these to be included in a --dhcp-optsfile.
--dhcp-hostsdir=
This is equivalent to --dhcp-hostsfile, except for the following. The path MUST be a directory, and not an inā
dividual file. Changed or new files within the directory are read automatically, without the need to send
SIGHUP. If a file is deleted or changed after it has been read by dnsmasq, then the host record it contained
will remain until dnsmasq receives a SIGHUP, or is restarted; ie host records are only added dynamically. The
order in which the files in a directory are read is not defined.
--dhcp-optsdir=
This is equivalent to --dhcp-optsfile, with the differences noted for --dhcp-hostsdir.
-Z, --read-ethers
Read /etc/ethers for information about hosts for the DHCP server. The format of /etc/ethers is a hardware adā
dress, followed by either a hostname or dotted-quad IP address. When read by dnsmasq these lines have exactly
the same effect as --dhcp-host options containing the same information. /etc/ethers is re-read when dnsmasq
receives SIGHUP. IPv6 addresses are NOT read from /etc/ethers.
-O, --dhcp-option=[tag:,[tag:,]][encap:,][vi-encap:,][vendor:[],][|opā
tion:|option6:|option6:],[[,]]
Send various extra options to DHCP clients. By default, dnsmasq sends some standard options to DHCP clients,
the netmask and broadcast address are set to the same as the host running dnsmasq, and the DNS server and deā
fault route are set to the address of the machine running dnsmasq. (Equivalent rules apply for IPv6.) If the
domain name option has been set, that is sent. This configuration allows these defaults to be overridden, or
other options specified. The option to be sent may be given as a decimal number or as option:.
Option numbers are specified in RFC2132 and subsequent RFCs. The set of option-names known by dnsmasq can be
discovered by running dnsmasq --help dhcp. For example, to set the default route option to 192.168.4.4, use
--dhcp-option=3,192.168.4.4 or --dhcp-option=option:router,192.168.4.4 and to set the time-server address to
192.168.0.4, use --dhcp-option=42,192.168.0.4 or --dhcp-option=option:ntp-server,192.168.0.4. The special adā
dress 0.0.0.0 means "the address of the system running dnsmasq".
An option without data is valid, and includes just the option without data. (There is only one option with a
zero length data field currently defined for DHCPv4, 80:rapid commit, so this feature is not very useful in
practice). Options for which dnsmasq normally provides default values can be omitted by defining the option
with no data. These are netmask, broadcast, router, DNS server, domainname and hostname. Thus, for DHCPv4
--dhcp-option = option:router will result in no router option being sent, rather than the default of the host
on which dnsmasq is running. For DHCPv6, the same is true of the options DNS server and refresh time.
Data types allowed are comma separated dotted-quad IPv4 addresses, []-wrapped IPv6 addresses, a decimal numā
ber, colon-separated hex digits and a text string. If the optional tags are given then this option is only
sent when all the tags are matched.
Special processing is done on a text argument for option 119, to conform with RFC 3397. Text or dotted-quad IP
addresses as arguments to option 120 are handled as per RFC 3361. Dotted-quad IP addresses which are followed
by a slash and then a netmask size are encoded as described in RFC 3442.
IPv6 options are specified using the option6: keyword, followed by the option number or option name. The IPv6
option name space is disjoint from the IPv4 option name space. IPv6 addresses in options must be bracketed
with square brackets, eg.
--dhcp-option=option6:ntp-server,[1234::56]. For IPv6, [::] means "the global address of the machine running
dnsmasq", whilst [fd00::] is replaced with the ULA, if it exists, and [fe80::] with the link-local address.
Be careful: data-type suitability for the option number sent is not checked. It is quite possible to persuade
dnsmasq to generate illegal DHCP packets with injudicious use of this flag. When the value is a decimal numā
ber, dnsmasq must determine how large the data item is. It does this by examining the option number and/or the
value, but can be overridden by appending a single letter flag as follows: b = one byte, s = two bytes, i =
four bytes. This is mainly useful with encapsulated vendor class options (see below) where dnsmasq cannot deā
termine data size from the option number. Option data which consists solely of periods and digits will be inā
terpreted by dnsmasq as an IP address, and inserted into an option as such. To force a literal string, use
quotes. For instance when using option 66 to send a literal IP address as TFTP server name, it is necessary to
do --dhcp-option=66,"1.2.3.4".
Encapsulated Vendor-class options may also be specified (IPv4 only) using --dhcp-option: for instance --dhcp-
option=vendor:PXEClient,1,0.0.0.0 sends the encapsulated vendor class-specific option "mftp-address=0.0.0.0"
to any client whose vendor-class matches "PXEClient". The vendor-class matching is substring based (see
--dhcp-vendorclass for details). If a vendor-class option (number 60) is sent by dnsmasq, then that is used
for selecting encapsulated options in preference to any sent by the client. It is possible to omit the vendorā
class completely; --dhcp-option=vendor:,1,0.0.0.0 in which case the encapsulated option is always sent.
Options may be encapsulated (IPv4 only) within other options: for instance --dhcp-option=encap:175, 190,
iscsi-client0 will send option 175, within which is the option 190. If multiple options are given which are
encapsulated with the same option number then they will be correctly combined into one encapsulated option.
encap: and vendor: may not both be set in the same --dhcp-option.
The final variant on encapsulated options is "Vendor-Identifying Vendor Options" as specified by RFC3925.
These are denoted like this: --dhcp-option=vi-encap:2, 10, text The number in the vi-encap: section is the
IANA enterprise number used to identify this option. This form of encapsulation is supported in IPv6.
The address 0.0.0.0 is not treated specially in encapsulated options.
--dhcp-option-force=[tag:,[tag:,]][encap:,][vi-encap:,][vendor:[],],[[,]]
This works in exactly the same way as --dhcp-option except that the 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.
--dhcp-option-pxe=[tag:,[tag:,]][encap:,][vi-encap:,],[[,]]
A variant of --dhcp-option which defines options only sent in reply to PXE clients. In addition, such options
are sent in reply to PXE clients when dnsmasq is acting as a PXE proxy, unlike other options. A typical use-
case is option 175, sent to iPXE.
--dhcp-no-override
(IPv4 only) Disable re-use of the DHCP servername and filename fields as extra option space. If it can, dnsā
masq moves the boot server and filename information (from --dhcp-boot) out of their dedicated fields into DHCP
options. This make extra space available in the DHCP packet for options but can, rarely, confuse old or broken
clients. This flag forces "simple and safe" behaviour to avoid problems in such a case.
--leasequery[=[/]]
Enable RFC 4388 leasequery. The dnsmasq DHCP server will answer LEASEQUERY messages from DHCP relays when this
option is given. If an address or subnet is given, only queries from a relay at that source are allowed. Reā
peat the --leasequery option to specify multiple allowed sources. To correctly answer lease queries it is
necessary to store extra data in the lease database, and this is also enabled by the --leasequery option. The
extra fields (agent-info and vendorclass) are stored in the leases file in a somewhat backwards compatible
manner. Enabling and then disabling leasequery will not cause problems; the extra information will be aged
out of the database. However, enabling leasequery in release 2.92 or later, storing leases which come via DHCP
relays which add option-82 agent-info data, and then moving back to a pre-2.92 dnsmasq binary may cause probā
lems reading the leases file. As of release 2.92, leasequery is only supported for DHCPv4.
--dhcp-relay=