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

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.

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

--hostsdir=
Read all the hosts files contained in the directory. New or changed files are read
automatically. See --dhcp-hostsdir for details.

-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 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 situa‐
tions. 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.

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

--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 flooding 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.

-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. If the argument "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.

-8, --log-facility=
Set the facility to which dnsmasq will send syslog entries, this defaults to DAE‐
MON, 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-async[=]
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 num‐
ber 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 nor‐
mally be started as root, but it will drop root privileges after startup by chang‐
ing 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 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=
Listen on instead of the standard DNS port (53). Setting this to zero com‐
pletely 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 4096, which is the RFC5625-recommended size.

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

--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 to larger 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. 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=
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-inter‐
face options always override the others.

--auth-server=,|
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 dif‐
ferent DNS service on the specified interface. The 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 quali‐
fied with "/4" or "/6" to specify only the IPv4 or IPv6 addresses associated with
the interface.

--local-service
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=
Do not provide DHCP or TFTP on the specified interface, but do provide DNS service.

-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 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 name‐
server (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 plat‐
forms 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 corre‐
sponding 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=[]|[-],[,]
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=
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 64.94.110.11

-B, --ignore-address=
Ignore replies to A-record queries which include the specified address. 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 arrive.

-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=
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 cur‐
rently 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 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
uk.org.thekelleys.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 dns‐
masq 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 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 pre‐
viously disabled.

--stop-dns-rebind
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.

--rebind-localhost-ok
Exempt 127.0.0.0/8 from rebinding checks. This address range is returned by real‐
time 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/domain3/

-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 IP address of upstream servers directly. Setting this flag does not sup‐
press reading of /etc/resolv.conf, use -R 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.inter‐
nal.thekelleys.org.uk at 192.168.1.1 then giving the flag -S /internal.thekel‐
leys.org.uk/192.168.1.1 will send all queries for internal machines to that name‐
server, everything else will go to the servers in /etc/resolv.conf. An empty domain
specification, // 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 -S flag is allowed, with repeated
domain or ipaddr parts as required.

More specific domains take precendence 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 to 1.2.3.4, except *www.google.com, which will go to 2.3.4.5

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 to 1.2.3.4, except *www.google.com which will be forwarded as usual.

Also permitted is a -S flag which gives a domain but no IP address; this tells dns‐
masq 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 upstream servers. local is a
synonym for server to make configuration files clearer in this case.

IPv6 addresses may include a %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 nameserver. It should be an ip-address, which should belong to
the machine on which dnsmasq is running otherwise this server line will be logged
and then ignored, or an interface name. 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. 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 address. Forcing queries to an interface
is not implemented on all platforms supported by dnsmasq.

--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

-A, --address=//[domain/][]
Specify an IP address to return for any host in the given domains. Queries in the
domains are never forwarded and always replied to with the specified IP address
which may be IPv4 or IPv6. To give both IPv4 and IPv6 addresses for a domain, use
repeated -A flags. Note that /etc/hosts and DHCP leases override this for individ‐
ual 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 was as for --server, with the additional facility that /#/ matches any
domain. Thus --address=/#/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 address
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.

--ipset=//[domain/][,]
Places the resolved IP addresses of queries for the specified domains in the speci‐
fied netfilter ip sets. Domains and subdomains are matched in the same way as
--address. These ip sets must already exist. See ipset(8) for more details.

-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 useful for directing mail from
systems on a LAN to a central server. The preference value is optional, and
defaults 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 con‐
taining the MX target for MX queries on the hostname of the machine on which dns‐
masq 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 --domain. 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
numbers are in a different order. More than one SRV record for a given ser‐
vice/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 appearing 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

-Y, --txt-record=[[,],]
Return a TXT DNS record. The value of TXT record is a set of strings, so any num‐
ber may be included, delimited 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.

--cname=,
Return a CNAME record which indicates that is really . There are
significant limitations on the target; it must be a DNS name which is known to dns‐
masq from /etc/hosts (or additional hosts files), from DHCP, from --interface-name
or from another --cname. If the target does not satisfy this criteria, the whole
cname is ignored. The cname must be unique, but it is permissable to have more than
one cname pointing to the same target.

--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 a DNS record associating the name with the primary address on 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 constant, 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-existent, 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.

--synth-domain=,[,]
Create artificial A/AAAA and PTR records for an address range. The records use the
address, with periods (or colons for IPv6) replaced with dashes.

An example should make this clearer. --synth-domain=thekel‐
leys.org.uk,192.168.0.0/24,internal- 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, but IPv6 addresses may start with '::' but DNS
labels may not start with '-' so in this case if no prefix is configured a zero is
added in front of the label. ::1 becomes 0--1.

The address range can be of the form , or /

--add-mac
Add the MAC address of the requestor to DNS queries which are forwarded upstream.
This may be used to DNS filtering 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.

--add-subnet[[=],]
Add the subnet address of the requestor to the DNS queries which are forwarded
upstream. The amount of the address forwarded depends on the prefix length parame‐
ter: 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 default is zero for both IPv4 and IPv6. Note that upstream
nameservers may be configured to return different results based on this informa‐
tion, but the dnsmasq cache does not take account. If a dnsmasq instance is config‐
ured such that different results may be encountered, caching should be disabled.

-c, --cache-size=
Set the size of dnsmasq's cache. The default is 150 names. Setting the cache size
to zero disables caching.

-N, --no-negcache
Disable negative caching. Negative caching allows dnsmasq to remember "no such
domain" answers from upstream nameservers and answer identical queries without for‐
warding them again.

-0, --dns-forward-max=
Set the maximum number of concurrent DNS queries. The default value is 150, which
should be fine for most setups. 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.

--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 vali‐
dated 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 reduce 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. In the default mode, this menas that
all replies will be marked as untrusted. If --dnssec-check-unsigned is set and the
upstream servers don't support DNSSEC, then DNS service will be entirely broken.

--trust-anchor=[],,,,,
Provide DS records to act a trust anchors for DNSSEC validation. Typically these
will be the DS record(s) for Zone Signing key(s) of the root zone, but trust
anchors for limited domains are also possible. The current root-zone trust anchors
may be downloaded from https://data.iana.org/root-anchors/root-anchors.xml

--dnssec-check-unsigned
As a default, dnsmasq does not check that unsigned DNS replies are legitimate: 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. If this flag is set, dnsmasq will check the zones
of unsigned replies, to ensure that unsigned replies are allowed in those zones.
The cost of this is more upstream queries and slower performance. See also the
warning about upstream servers in the section on --dnssec

--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 deter‐
mine the correct time typically requires use of NTP and therefore DNS, but validat‐
ing 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 SIGHUP. 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 SIGHUP should be sent to dnsmasq, which
enables time checking, and purges the cache of DNS records which have not been
throughly checked.

--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 specified 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 created after dnsmasq has dropped root, so it must be in a
location writable by the unprivileged user that dnsmasq runs as.

--proxy-dnssec
Copy the DNSSEC Authenticated Data bit from upstream servers to downstream clients
and cache it. 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.

--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=[,[/][,[/].....]]
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.

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 answered.

--auth-soa=[,[,[,[,]]]]
Specify fields in the SOA record associated with authoritative zones. Note that
this is optional, all the values 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 dnsmasq.

--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, then AXFR requests will be accepted from any secondary.

--conntrack
Read the Linux connection track mark associated with incoming DNS queries and set
the same mark value on upstream traffic used to answer those queries. This allows
traffic generated by dnsmasq to be associated with the queries which cause it, use‐
ful for bandwidth accounting and firewalling. Dnsmasq must have conntrack support
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:,][,|con‐
structor:][,][,][,]

Enable the DHCP server. Addresses will be given out from the range to
and from statically 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 "infinite". If not
given, the default lease time is one hour. The minimum lease time is two minutes.
For IPv6 ranges, the lease time maybe "deprecated"; this sets the preferred life‐
time 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 dnsmasq will have to guess, based on the class (A, B or C)
of the network address. The broadcast address is always 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 optional 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 interface
configuration. The mimimum 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 con‐
structor:. This forms a template which describes 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 corre‐
sponding ranges will be automatically created, and then deprecated 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 privacy 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 specified 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-state‐
less, 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 advertisement, so that the client will use SLAAC addresses. When
used with a DHCP range or static DHCP address this results 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 happens 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 advertisements. 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:][,][,][,][,ignore]
Specify per host parameters for the DHCP server. This allows a machine with a par‐
ticular 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 example --dhcp-host=00:20:e0:3b:13:af,wap,infi‐
nite 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:cli‐
entidastext,.....

A single dhcp-host may contain an IPv4 address or an IPv6 address, 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 appropri‐
ate network part inserted. 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 ).

The special keyword "ignore" tells dnsmasq to never offer a DHCP lease to a
machine. The machine can be specified by hardware address, client ID or hostname,
for instance --dhcp-host=00:20:e0:3b:13:af,ignore This is 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 selectively 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 config‐
ured to ignore requests from unknown machines using --dhcp-ignore=tag:!known Ether‐
net 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 a 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 hard‐
ware 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 multiple 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 allo‐
cate a stable IP address to a laptop which has both wired and wireless interfaces.

--dhcp-hostsfile=
Read DHCP host information from the specified file. If a directory is given, then
read all the files contained in that directory. 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
receives SIGHUP.

--dhcp-optsfile=
Read DHCP option information from the specified file. If a directory is given,
then read all the files contained in that directory. 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 encode the information in a

--dhcp-hostsdir=
This is equivalent to dhcp-hostsfile, except for the following. The path MUST be a
directory, and not an individual file. Changed or new files within the directory
are read automatically, without the need to send SIGHUP. If a file is deleted for
changed after it has been read by dnsmasq, then the host record it contained will
remain until dnsmasq recieves a SIGHUP, or is restarted; ie host records are only
added dynamically.

--dhcp-optsdir=
This is equivalent to dhcp-optsfile, with the differences noted for --dhcp-hosts‐
dir.

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

-Z, --read-ethers
Read /etc/ethers for information about hosts for the DHCP server. The format of
/etc/ethers is a hardware address, 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:,][ven‐
dor:[],][|option:|option6:|option6:],[[,]]
Specify different or 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 default 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:" The 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, do --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, do --dhcp-option = 42,192.168.0.4 or --dhcp-option = option:ntp-
server, 192.168.0.4 The special address 0.0.0.0 is taken to mean "the address of
the machine running dnsmasq".

Data types allowed are comma separated dotted-quad IPv4 addresses, []-wrapped IPv6
addresses, a decimal number, 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 num‐
ber 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: no checking is done that the correct type of data for the option number
is sent, it is quite possible to persuade dnsmasq to generate illegal DHCP packets
with injudicious use of this flag. When the value is a decimal number, 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 fol‐
lows: b = one byte, s = two bytes, i = four bytes. This is mainly useful with
encapsulated vendor class options (see below) where dnsmasq cannot determine data
size from the option number. Option data which consists solely of periods and dig‐
its will be interpreted 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 encapsu‐
lated vendor class-specific option "mftp-address=0.0.0.0" to any client whose ven‐
dor-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 vendorclass 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: are 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:,][ven‐
dor:[],],[[,]]
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-no-override
(IPv4 only) Disable re-use of the DHCP servername and filename fields as extra
option space. If it can, dnsmasq 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 bro‐
ken clients. This flag forces "simple and safe" behaviour to avoid problems in such
a case.

--dhcp-relay=,[,,[enterprise:,]
Map from a vendor-class string to a tag. Most DHCP clients provide a "vendor class"
which represents, in some sense, the type of host. This option maps vendor classes
to tags, so that DHCP options may be selectively delivered to different classes of
hosts. For example dhcp-vendorclass=set:printers,Hewlett-Packard JetDirect will
allow options to be set only for HP printers like so: --dhcp-option=tag:print‐
ers,3,192.168.4.4 The vendor-class string is substring matched against the vendor-
class supplied by the client, to allow fuzzy matching. The set: prefix is optional
but allowed for consistency.

Note that in IPv6 only, vendorclasses are namespaced with an IANA-allocated enter‐
prise number. This is given with enterprise: keyword and specifies that only ven‐
dorclasses matching the specified number should be searched.

-j, --dhcp-userclass=set:,
Map from a user-class string to a tag (with substring matching, like vendor
classes). Most DHCP clients provide a "user class" which is configurable. This
option maps user classes to tags, so that DHCP options may be selectively delivered
to different classes of hosts. It is possible, for instance to use this to set a
different printer server for hosts in the class "accounts" than for hosts in the
class "engineering".

-4, --dhcp-mac=set:,
Map from a MAC address to a tag. The MAC address may include wildcards. For example
--dhcp-mac=set:3com,01:34:23:*:*:* will set the tag "3com" for any host whose MAC
address matches the pattern.

--dhcp-circuitid=set:,, --dhcp-remoteid=set:,
Map from RFC3046 relay agent options to tags. This data may be provided by DHCP
relay agents. The circuit-id or remote-id is normally given as colon-separated hex,
but is also allowed to be a simple string. If an exact match is achieved between
the circuit or agent ID and one provided by a relay agent, the tag is set.

dhcp-remoteid (but not dhcp-circuitid) is supported in IPv6.

--dhcp-subscrid=set:,
(IPv4 and IPv6) Map from RFC3993 subscriber-id relay agent options to tags.

--dhcp-proxy[=]......
(IPv4 only) A normal DHCP relay agent is only used to forward the initial parts of
a DHCP interaction to the DHCP server. Once a client is configured, it communicates
directly with the server. This is undesirable if the relay agent is adding extra
information to the DHCP packets, such as that used by dhcp-circuitid and dhcp-
remoteid. A full relay implementation can use the RFC 5107 serverid-override
option to force the DHCP server to use the relay as a full proxy, with all packets
passing through it. This flag provides an alternative method of doing the same
thing, for relays which don't support RFC 5107. Given alone, it manipulates the
server-id for all interactions via relays. If a list of IP addresses is given, only
interactions via relays at those addresses are affected.

--dhcp-match=set:,

Go-to-top