"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "man/dnsmasq.8" between
dnsmasq-2.80.tar.gz and dnsmasq-2.81.tar.xz

About: Dnsmasq is a lightweight caching DNS forwarder and DHCP server.

dnsmasq.8  (dnsmasq-2.80):dnsmasq.8  (dnsmasq-2.81.tar.xz)
skipping to change at line 197 skipping to change at line 197
--auth-server=<domain>,[<interface>|<ip-address>...] --auth-server=<domain>,[<interface>|<ip-address>...]
Enable DNS authoritative mode for queries arriving at an interface or address. Note that the 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, interface or address need not be mentioned in --interface or --listen-address configuration,
indeed --auth-server will override these and provide a different D NS service on the specified indeed --auth-server will override these and provide a different D NS service on the specified
interface. The <domain> is the "glue record". It should resolve i n the global DNS to an A and/or interface. The <domain> is the "glue record". It should resolve i n the global DNS to an A and/or
AAAA record which points to the address dnsmasq is listening on. W hen an interface is specified, AAAA record which points to the address dnsmasq is listening on. W hen an interface is specified,
it may be qualified with "/4" or "/6" to specify only the IPv4 or IPv6 addresses associated with 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 avai lable as part of the normal the interface. Since any defined authoritative zones are also avai lable as part of the normal
recusive DNS service supplied by dnsmasq, it can make sense to ha ve an --auth-server declaration recusive DNS service supplied by dnsmasq, it can make sense to ha ve an --auth-server declaration
with no interfaces or address, but simply specifying the glue reco rd. with no interfaces or address, but simply specifying the primary e xternal nameserver.
--local-service --local-service
Accept DNS queries only from hosts whose address is on a local sub net, ie a subnet for which an Accept DNS queries only from hosts whose address is on a local sub net, ie a subnet for which an
interface exists on the server. This option only has effe ct if there are no --interface, interface exists on the server. This option only has effe ct if there are no --interface,
--except-interface, --listen-address or --auth-server options. It is intended to be set as a --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 default on installation, to allow unconfigured installations to be useful but also safe from
being used for DNS amplification attacks. being used for DNS amplification attacks.
-2, --no-dhcp-interface=<interface name> -2, --no-dhcp-interface=<interface name>
Do not provide DHCP or TFTP on the specified interface, but do pro vide DNS service. Do not provide DHCP or TFTP on the specified interface, but do pro vide DNS service.
skipping to change at line 293 skipping to change at line 293
-R, --no-resolv -R, --no-resolv
Don't read /etc/resolv.conf. Get upstream servers only from the co mmand line or the dnsmasq con- Don't read /etc/resolv.conf. Get upstream servers only from the co mmand line or the dnsmasq con-
figuration file. figuration file.
-1, --enable-dbus[=<service-name>] -1, --enable-dbus[=<service-name>]
Allow dnsmasq configuration to be updated via DBus method calls. The configuration which can be Allow dnsmasq configuration to be updated via DBus method calls. The configuration which can be
changed is upstream DNS servers (and corresponding domains) and ca che clear. Requires that dns- changed is upstream DNS servers (and corresponding domains) and ca che clear. Requires that dns-
masq has been built with DBus support. If the service name is giv en, dnsmasq provides service at masq has been built with DBus support. If the service name is giv en, dnsmasq provides service at
that name, rather than the default which is uk.org.thekelleys.dnsm asq that name, rather than the default which is uk.org.thekelleys.dnsm asq
--enable-ubus --enable-ubus[=<service-name>]
Enable dnsmasq UBus interface. It sends notifications via UBus on DHCPACK and DHCPRELEASE events. Enable dnsmasq UBus interface. It sends notifications via UBus on DHCPACK and DHCPRELEASE events.
Furthermore it offers metrics. Requires that dnsmasq has been bui Furthermore it offers metrics. Requires that dnsmasq has been
lt with UBus support. 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 -o, --strict-order
By default, dnsmasq will send queries to any of the upstream serv ers it knows about and tries to By default, dnsmasq will send queries to any of the upstream serv ers it knows about and tries to
favour servers that are known to be up. Setting this flag forces d nsmasq to try each query with favour servers that are known to be up. Setting this flag forces d nsmasq to try each query with
each server strictly in the order they appear in /etc/resolv.conf each server strictly in the order they appear in /etc/resolv.conf
--all-servers --all-servers
By default, when dnsmasq has more than one upstream server ava ilable, it will send queries to By default, when dnsmasq has more than one upstream server ava ilable, it will send queries to
just one server. Setting this flag forces dnsmasq to send all quer ies to all available servers. just one server. Setting this flag forces dnsmasq to send all quer ies to all available servers.
The reply from the server which answers first will be returned to the original requester. The reply from the server which answers first will be returned to the original requester.
skipping to change at line 317 skipping to change at line 319
--dns-loop-detect --dns-loop-detect
Enable code to detect DNS forwarding loops; ie the situation w here a query sent to one of the Enable code to detect DNS forwarding loops; ie the situation w here a query sent to one of the
upstream server eventually returns as a new query to the dnsmasq i nstance. The process works by upstream server eventually returns as a new query to the dnsmasq i nstance. The process works by
generating TXT queries of the form <hex>.test and sending them t o each upstream server. The hex generating TXT queries of the form <hex>.test and sending them t o each upstream server. The hex
is a UID which encodes the instance of dnsmasq sending the query a nd the upstream server to which is a UID which encodes the instance of dnsmasq sending the query a nd the upstream server to which
it was sent. If the query returns to the server which sent it, t hen the upstream server through it was sent. If the query returns to the server which sent it, t hen the upstream server through
which it was sent is disabled and this event is logged. Each time the set of upstream servers 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 w ere previously disabled. changes, the test is re-run on all of them, including ones which w ere previously disabled.
--stop-dns-rebind --stop-dns-rebind
Reject (and log) addresses from upstream nameservers which are Reject (and log) addresses from upstream nameservers which are in
in the private IP ranges. This the private ranges. This blocks
blocks an attack where a browser behind a firewall is used to prob an attack where a browser behind a firewall is used to probe machi
e machines on the local net- nes on the local network. For
work. IPv6, the private range covers the IPv4-mapped addresses in pr
ivate space plus all link-local
(LL) and site-local (ULA) addresses.
--rebind-localhost-ok --rebind-localhost-ok
Exempt 127.0.0.0/8 from rebinding checks. This address range is Exempt 127.0.0.0/8 and ::1 from rebinding checks. This address ra
returned by realtime black hole nge is returned by realtime
servers, so blocking it may disable these services. black hole servers, so blocking it may disable these services.
--rebind-domain-ok=[<domain>]|[[/<domain>/[<domain>/] --rebind-domain-ok=[<domain>]|[[/<domain>/[<domain>/]
Do not detect and block dns-rebind on queries to these domains. Th e argument may be either a sin- Do not detect and block dns-rebind on queries to these domains. Th e argument may be either a sin-
gle domain, or multiple domains surrounded by '/', like the --server syntax, eg. --rebind- gle domain, or multiple domains surrounded by '/', like the --s erver syntax, eg. --rebind-
domain-ok=/domain1/domain2/domain3/ domain-ok=/domain1/domain2/domain3/
-n, --no-poll -n, --no-poll
Don't poll /etc/resolv.conf for changes. Don't poll /etc/resolv.conf for changes.
--clear-on-reload --clear-on-reload
Whenever /etc/resolv.conf is re-read or the upstream servers are s et via DBus, clear the DNS 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 dat a than that held in cache. cache. This is useful when new nameservers may have different dat a than that held in cache.
-D, --domain-needed -D, --domain-needed
Tells dnsmasq to never forward A or AAAA queries for plain names Tells dnsmasq to never forward A or AAAA queries for plain names,
, without dots or domain parts, without dots or domain parts,
to upstream nameservers. If the name is not known from /etc/hosts to upstream nameservers. If the name is not known from /etc/h
or DHCP then a "not found" osts or DHCP then a "not found"
answer is returned. answer is returned.
-S, --local, --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>][@<source- ip>|<interface>[#<port>]] -S, --local, --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>][@<source- ip>|<interface>[#<port>]]
Specify IP address of upstream servers directly. Setting this fl Specify IP address of upstream servers directly. Setting this flag
ag does not suppress reading of does not suppress reading of
/etc/resolv.conf, use --no-resolv to do that. If one or more optio /etc/resolv.conf, use --no-resolv to do that. If one or more o
nal domains are given, that ptional domains are given, that
server is used only for those domains and they are queried only u server is used only for those domains and they are queried only us
sing the specified server. This ing the specified server. This
is intended for private nameservers: if you have a nameserver on y is intended for private nameservers: if you have a nameserver o
our network which deals with n your network which deals with
names of the form xxx.internal.thekelleys.org.uk at 192.16 names of the form xxx.internal.thekelleys.org.uk at 192.168.
8.1.1 then giving the flag 1.1 then giving the flag
--server=/internal.thekelleys.org.uk/192.168.1.1 will send all que --server=/internal.thekelleys.org.uk/192.168.1.1 will send all q
ries for internal machines to ueries for internal machines to
that nameserver, everything else will go to the servers in /etc/re solv.conf. DNSSEC validation is that nameserver, everything else will go to the servers in /etc/re solv.conf. DNSSEC validation is
turned off for such private nameservers, UNLESS a --trust-anchor i turned off for such private nameservers, UNLESS a --trust-anchor
s specified for the domain in is specified for the domain in
question. An empty domain specification, // has the special mean question. An empty domain specification, // has the special meanin
ing of "unqualified names only" g of "unqualified names only"
ie names without any dots in them. A non-standard port may be spec ified as part of the IP address ie names without any dots in them. A non-standard port may be spec ified as part of the IP address
using a # character. More than one --server flag is allowed, with repeated domain or ipaddr using a # character. More than one --server flag is allowed, wit h repeated domain or ipaddr
parts as required. parts as required.
More specific domains take precedence over less More specific domains take precedence over less
specific domains, so: specific domains, so:
--server=/google.com/1.2.3.4 --server=/www.google.com/2.3.4.5 wil --server=/google.com/1.2.3.4 --server=/www.google.com/2.3.4.5 will
l send queries for *.google.com send queries for *.google.com
to 1.2.3.4, except *www.google.com, which will go to 2.3.4.5 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 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 --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. which will be forwarded as usual.
Also permitted is a -S flag which gives a domain but no IP address Also permitted is a -S flag which gives a domain but no IP add
; this tells dnsmasq that a ress; this tells dnsmasq that a
domain is local and it may answer queries from /etc/hosts o domain is local and it may answer queries from /etc/hosts or DH
r DHCP but should never forward CP but should never forward
queries on that domain to any upstream servers. --local is a syno queries on that domain to any upstream servers. --local is a sy
nym for --server to make con- nonym for --server to make con-
figuration files clearer in this case. figuration files clearer in this case.
IPv6 addresses may include an %interface scope-id, eg fe80::202:a4 12:4512:7bbf%eth0. IPv6 addresses may include an %interface scope-id, eg fe80::202:a4 12:4512:7bbf%eth0.
The optional string after the @ character tells dnsmasq how to s et the source of the queries to The optional string after the @ character tells dnsmasq how to set the source of the queries to
this nameserver. It can either be an ip-address, an interface name or both. The ip-address should this nameserver. 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 belong to the machine on which dnsmasq is running, otherwise this
server line will be logged and server line will be logged and
then ignored. If an interface name is given, then queries to the s then ignored. If an interface name is given, then queries to the
erver will be forced via that server will be forced via that
interface; if an ip-address is given then the source address of interface; if an ip-address is given then the source address of th
the queries will be set to that e queries will be set to that
address; and if both are given then a combination of ip-address an address; and if both are given then a combination of ip-address
d interface name will be used and interface name will be used
to steer requests to the server. The query-port flag is ignor to steer requests to the server. The query-port flag is ignored f
ed for any servers which have a or any servers which have a
source address specified but the port may be specified directly as source address specified but the port may be specified directly
part of the source address. as part of the source address.
Forcing queries to an interface is not implemented on all platform s supported by dnsmasq. Forcing queries to an interface is not implemented on all platform s supported by dnsmasq.
--rev-server=<ip-address>/<prefix-len>,<ipaddr>[#<port>][@<source-ip>|<in --rev-server=<ip-address>/<prefix-len>[,<ipaddr>][#<port>][@<source-ip>|<
terface>[#<port>]] interface>[#<port>]]
This is functionally the same as --server, but provides some syn This is functionally the same as --server, but provides some synta
tactic sugar to make specifying ctic sugar to make specifying
address-to-name queries easier. For example --rev-server=1.2.3.0/2 4,192.168.0.1 is exactly equiv- address-to-name queries easier. For example --rev-server=1.2.3.0/2 4,192.168.0.1 is exactly equiv-
alent to --server=/3.2.1.in-addr.arpa/192.168.0.1 alent to --server=/3.2.1.in-addr.arpa/192.168.0.1
-A, --address=/<domain>[/<domain>...]/[<ipaddr>] -A, --address=/<domain>[/<domain>...]/[<ipaddr>]
Specify an IP address to return for any host in the given domai ns. Queries in the domains are 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 addres s which may be IPv4 or IPv6. To never forwarded and always replied to with the specified IP addres s which may be IPv4 or IPv6. To
give both IPv4 and IPv6 addresses for a domain, use repeated --ad give both IPv4 and IPv6 addresses for a domain, use repeated --add
dress flags. To include multi- ress flags. To include multi-
ple IP addresses for a single query, use --addn-hosts=<path> inste ple IP addresses for a single query, use --addn-hosts=<path> ins
ad. Note that /etc/hosts and tead. Note that /etc/hosts and
DHCP leases override this for individual names. A common use of DHCP leases override this for individual names. A common use of th
this is to redirect the entire is is to redirect the entire
doubleclick.net domain to some friendly local web server to avoid banner ads. The domain specifi- doubleclick.net domain to some friendly local web server to avoid banner ads. The domain specifi-
cation works in the same was as for --server, with the additiona cation works in the same was as for --server, with the additional
l facility that /#/ matches any facility that /#/ matches any
domain. Thus --address=/#/1.2.3.4 will always return 1.2.3.4 for domain. Thus --address=/#/1.2.3.4 will always return 1.2.3.4
any query not answered from for any query not answered from
/etc/hosts or DHCP and not sent to an upstream nameserver by a mo /etc/hosts or DHCP and not sent to an upstream nameserver by a mor
re specific --server directive. e specific --server directive.
As for --server, one or more domains with no address returns As for --server, one or more domains with no address retu
a no-such-domain answer, so rns a no-such-domain answer, so
--address=/example.com/ is equivalent to --server=/example.com/ --address=/example.com/ is equivalent to --server=/example.com/ an
and returns NXDOMAIN for exam- d returns NXDOMAIN for exam-
ple.com and all its subdomains. An address specified as '#' transl ple.com and all its subdomains. An address specified as '#' tr
ates to the NULL address of anslates to the NULL address of
0.0.0.0 and its IPv6 equivalent of :: so --address=/example.com/# 0.0.0.0 and its IPv6 equivalent of :: so --address=/example.com/#
will return NULL addresses for will return NULL addresses for
example.com and its subdomains. This is partly syntactic sugar for --address=/example.com/0.0.0.0 example.com and its subdomains. This is partly syntactic sugar for --address=/example.com/0.0.0.0
and --address=/example.com/:: but is also more efficient than incl uding both as seperate configu- and --address=/example.com/:: but is also more efficient than incl uding both as separate configu-
ration lines. Note that NULL addresses normally work in the same w ay as localhost, so beware that ration lines. Note that NULL addresses normally work in the same w ay as localhost, so beware that
clients looking up these names are likely to end up talking to the mselves. clients looking up these names are likely to end up talking to the mselves.
--ipset=/<domain>[/<domain>...]/<ipset>[,<ipset>...] --ipset=/<domain>[/<domain>...]/<ipset>[,<ipset>...]
Places the resolved IP addresses of queries for one or more domain s in the specified Netfilter IP Places the resolved IP addresses of queries for one or more domain s in the specified Netfilter IP
set. If multiple setnames are given, then the addresses are placed set. If multiple setnames are given, then the addresses are pla
in each of them, subject to ced in each of them, subject to
the limitations of an IP set (IPv4 addresses cannot be stored in the limitations of an IP set (IPv4 addresses cannot be stored in a
an IPv6 IP set and vice versa). n IPv6 IP set and vice versa).
Domains and subdomains are matched in the same way as --address. Domains and subdomains are matched in the same way as --addre
These IP sets must already ss. These IP sets must already
exist. See ipset(8) for more details. exist. See ipset(8) for more details.
-m, --mx-host=<mx name>[[,<hostname>],<preference>] -m, --mx-host=<mx name>[[,<hostname>],<preference>]
Return an MX record named <mx name> pointing to the given hostname (if given), or the host speci- Return an MX record named <mx name> pointing to the given hostname (if given), or the host speci-
fied in the --mx-target switch or, if that switch is not given, th e host on which dnsmasq is run- fied in the --mx-target switch or, if that switch is not given, th e host on which dnsmasq is run-
ning. The default is useful for directing mail from systems on ning. The default is useful for directing mail from systems on a L
a LAN to a central server. The AN to a central server. The
preference value is optional, and defaults to 1 if not given. More preference value is optional, and defaults to 1 if not given.
than one MX record may be More than one MX record may be
given for a host. given for a host.
-t, --mx-target=<hostname> -t, --mx-target=<hostname>
Specify the default target for the MX record returned by dnsmasq. Specify the default target for the MX record returned by dnsmasq.
See --mx-host. If --mx-target See --mx-host. If --mx-target
is given, but not --mx-host, then dnsmasq returns a MX record cont is given, but not --mx-host, then dnsmasq returns a MX record
aining the MX target for MX containing the MX target for MX
queries on the hostname of the machine on which dnsmasq is running . queries on the hostname of the machine on which dnsmasq is running .
-e, --selfmx -e, --selfmx
Return an MX record pointing to itself for each local machi ne. Local machines are those in Return an MX record pointing to itself for each local machine. Local machines are those in
/etc/hosts or with DHCP leases. /etc/hosts or with DHCP leases.
-L, --localmx -L, --localmx
Return an MX record pointing to the host given by --mx-target (or the machine on which dnsmasq is 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. running) for each local machine. Local machines are those in /etc/ hosts or with DHCP leases.
-W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<priority >[,<weight>]]]] -W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<priority >[,<weight>]]]]
Return a SRV DNS record. See RFC2782 for details. If not suppli Return a SRV DNS record. See RFC2782 for details. If not supplied,
ed, the domain defaults to that the domain defaults to that
given by --domain. The default for the target domain is empty, an given by --domain. The default for the target domain is empty,
d the default for port is one and the default for port is one
and the defaults for weight and priority are zero. Be careful if and the defaults for weight and priority are zero. Be careful if t
transposing data from BIND zone ransposing data from BIND zone
files: the port, weight and priority numbers are in a different or files: the port, weight and priority numbers are in a different
der. More than one SRV record order. More than one SRV record
for a given service/domain is allowed, all that match are returned . for a given service/domain is allowed, all that match are returned .
--host-record=<name>[,<name>....],[<IPv4-address>],[<IPv6-address>][,<TTL >] --host-record=<name>[,<name>....],[<IPv4-address>],[<IPv6-address>][,<TTL >]
Add A, AAAA and PTR records to the DNS. This adds one or more n Add A, AAAA and PTR records to the DNS. This adds one or more name
ames to the DNS with associated s to the DNS with associated
IPv4 (A) and IPv6 (AAAA) records. A name may appear in more than o IPv4 (A) and IPv6 (AAAA) records. A name may appear in more than
ne --host-record and therefore one --host-record and therefore
be assigned more than one address. Only the first address c be assigned more than one address. Only the first address create
reates a PTR record linking the s a PTR record linking the
address to the name. This is the same rule as is used reading host s-files. --host-record options address to the name. This is the same rule as is used reading host s-files. --host-record options
are considered to be read before host-files, so a name appearing are considered to be read before host-files, so a name appearing t
there inhibits PTR-record cre- here inhibits PTR-record cre-
ation if it appears in hosts-file also. Unlike hosts-files, names ation if it appears in hosts-file also. Unlike hosts-files, na
are not expanded, even when mes are not expanded, even when
--expand-hosts is in effect. Short and long names may appear --expand-hosts is in effect. Short and long names may appear in
in the same --host-record, eg. the same --host-record, eg.
--host-record=laptop,laptop.thekelleys.org,192.168.0.1,1234::100 --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 z ero or the value of --local- If the time-to-live is given, it overrides the default, which i s zero or the value of --local-
ttl. The value is a positive integer and gives the time-to-live in seconds. ttl. The value is a positive integer and gives the time-to-live in seconds.
-Y, --txt-record=<name>[[,<text>],<text>] -Y, --txt-record=<name>[[,<text>],<text>]
Return a TXT DNS record. The value of TXT record is a set of Return a TXT DNS record. The value of TXT record is a set of stri
strings, so any number may be ngs, so any number may be
included, delimited by commas; use quotes to put commas into a st included, delimited by commas; use quotes to put commas into
ring. Note that the maximum a string. Note that the maximum
length of a single string is 255 characters, longer strings are sp lit into 255 character chunks. length of a single string is 255 characters, longer strings are sp lit into 255 character chunks.
--ptr-record=<name>[,<target>] --ptr-record=<name>[,<target>]
Return a PTR DNS record. Return a PTR DNS record.
--naptr-record=<name>,<order>,<preference>,<flags>,<service>,<regexp>[,<r eplacement>] --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<regexp>[,<r eplacement>]
Return an NAPTR DNS record, as specified in RFC3403. Return an NAPTR DNS record, as specified in RFC3403.
--caa-record=<name>,<flags>,<tag>,<value> --caa-record=<name>,<flags>,<tag>,<value>
Return a CAA DNS record, as specified in RFC6844. Return a CAA DNS record, as specified in RFC6844.
--cname=<cname>,[<cname>,]<target>[,<TTL>] --cname=<cname>,[<cname>,]<target>[,<TTL>]
Return a CNAME record which indicates that <cname> is really <targ Return a CNAME record which indicates that <cname> is really <targ
et>. There are significant lim- et>. There is a significant
itations on the target; it must be a DNS name which is known to dn limitation on the target; it must be a DNS record which is known
smasq from /etc/hosts (or addi- to dnsmasq and NOT a DNS record
tional hosts files), from DHCP, from --interface-name or from which comes from an upstream server. The cname must be unique, but
another --cname. If the target it is permissible to have more
does not satisfy this criteria, the whole cname is ignored. The cn than one cname pointing to the same target. Indeed it's possible
ame must be unique, but it is to declare multiple cnames to a
permissible to have more than one cname pointing to the same target in a single line, like so: --cname=cname1,cname2,target
target. Indeed it's possible to
declare multiple cnames to a target in a single line, like so: --c
name=cname1,cname2,target
If the time-to-live is given, it overrides the default, which is z ero or the value of --local- If the time-to-live is given, it overrides the default, which is z ero or the value of --local-
ttl. The value is a positive integer and gives the time-to-live in seconds. ttl. The value is a positive integer and gives the time-to-live in seconds.
--dns-rr=<name>,<RR-number>,[<hex data>] --dns-rr=<name>,<RR-number>,[<hex data>]
Return an arbitrary DNS Resource Record. The number is the type of the record (which is always in 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 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. 01:23:45 or 01 23 45 or 012345 or any mixture of these.
--interface-name=<name>,<interface>[/4|/6] --interface-name=<name>,<interface>[/4|/6]
skipping to change at line 541 skipping to change at line 543
Add the MAC address of the requestor to DNS queries which are forwarded upstream. This may be 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 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 mec hanism used to achieve this (an is on the same subnet as the dnsmasq server. Note that the mec hanism used to achieve this (an
EDNS0 option) is not yet standardised, so this should be considere d experimental. Also note that EDNS0 option) is not yet standardised, so this should be considere d experimental. Also note that
exposing MAC addresses in this way may have security and privacy implications. The warning about 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 altern ative encoding of the MAC, as caching given for --add-subnet applies to --add-mac too. An altern ative encoding of the MAC, as
base64, is enabled by adding the "base64" parameter and a huma n-readable encoding of hex-and- base64, is enabled by adding the "base64" parameter and a huma n-readable encoding of hex-and-
colons is enabled by added the "text" parameter. colons is enabled by added the "text" parameter.
--add-cpe-id=<string> --add-cpe-id=<string>
Add an arbitrary identifying string to o DNS queries which are for warded upstream. Add an arbitrary identifying string to DNS queries which are forwa rded upstream.
--add-subnet[[=[<IPv4 address>/]<IPv4 prefix length>][,[<IPv6 address>/]< IPv6 prefix length>]] --add-subnet[[=[<IPv4 address>/]<IPv4 prefix length>][,[<IPv6 address>/]< IPv6 prefix length>]]
Add a subnet address to the DNS queries which are forwarded upstre am. If an address is specified Add a subnet address to the DNS queries which are forwarded upstre am. If an address is specified
in the flag, it will be used, otherwise, the address of the reques tor will be used. The amount of in the flag, it will be used, otherwise, the address of the reques tor will be used. The amount of
the address forwarded depends on the prefix length parameter: 32 (128 for IPv6) forwards the the address forwarded depends on the prefix length parameter: 32 (128 for IPv6) forwards the
whole address, zero forwards none of it but still marks the re quest so that no upstream name- whole address, zero forwards none of it but still marks the re quest so that no upstream name-
server will add client address information either. The default is zero for both IPv4 and IPv6. server will add client address information either. The default is zero for both IPv4 and IPv6.
Note that upstream nameservers may be configured to return differe nt results based on this infor- Note that upstream nameservers may be configured to return differe nt results based on this infor-
mation, but the dnsmasq cache does not take account. If a dnsmasq instance is configured such mation, but the dnsmasq cache does not take account. If a dnsmasq instance is configured such
that different results may be encountered, caching should be disab led. that different results may be encountered, caching should be disab led.
skipping to change at line 604 skipping to change at line 606
--dnssec-check-unsigned=no appears in the configuration, then such replies they are assumed to be --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 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. 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 unsign ed replies, and used --dnssec- Versions of dnsmasq prior to 2.80 defaulted to not checking unsign ed replies, and used --dnssec-
check-unsigned to switch this on. Such configurations will contin ue to work as before, but those check-unsigned to switch this on. Such configurations will contin ue to work as before, but those
which used the default of no checking will need to be altered to e xplicitly select no checking. which used the default of no checking will need to be altered to e xplicitly select no checking.
The new default is because switching off checking for unsigned r eplies is inherently dangerous. The new default is because switching off checking for unsigned r eplies is inherently dangerous.
Not only does it open the possiblity of forged replies, but it all ows everything to appear to be Not only does it open the possiblity of forged replies, but it all ows everything to appear to be
working even when the upstream namesevers do not support DNSSEC, a nd in this case no DNSSEC vali- working even when the upstream namesevers do not support DNSSEC, a nd in this case no DNSSEC vali-
dation at all is occuring. dation at all is occurring.
--dnssec-no-timecheck --dnssec-no-timecheck
DNSSEC signatures are only valid for specified time windows, and s hould be rejected outside those DNSSEC signatures are only valid for specified time windows, and s hould be rejected outside those
windows. This generates an interesting chicken-and-egg problem for machines which don't have a 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 corr ect time typically requires use hardware real time clock. For these machines to determine the corr ect time typically requires use
of NTP and therefore DNS, but validating DNS requires that the correct time is already known. 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 DN SSEC validation.) only until Setting this flag removes the time-window checks (but not other DN SSEC validation.) only until
the dnsmasq process receives SIGINT. The intention is that dnsm asq should be started with this the dnsmasq process receives SIGINT. The intention is that dnsm asq should be started with this
flag when the platform determines that reliable time is not curren tly available. As soon as reli- flag when the platform determines that reliable time is not curren tly available. As soon as reli-
able time is established, a SIGINT should be sent to dnsmasq, w hich enables time checking, and able time is established, a SIGINT should be sent to dnsmasq, w hich enables time checking, and
skipping to change at line 632 skipping to change at line 634
--dnssec-timestamp=<path> --dnssec-timestamp=<path>
Enables an alternative way of checking the validity of the system time for DNSSEC (see --dnssec- 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 v alid once it becomes later than no-timecheck). In this case, the system time is considered to be v alid once it becomes later than
the timestamp on the specified file. The file is created and its t imestamp set automatically by the timestamp on the specified file. The file is created and its t imestamp set automatically by
dnsmasq. The file must be stored on a persistent filesystem, so th at it and its mtime are carried dnsmasq. The file must be stored on a persistent filesystem, so th at it and its mtime are carried
over system restarts. The timestamp file is created after dnsmasq has dropped root, so it must be 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. in a location writable by the unprivileged user that dnsmasq runs as.
--proxy-dnssec --proxy-dnssec
Copy the DNSSEC Authenticated Data bit from upstream servers to d Copy the DNSSEC Authenticated Data bit from upstream servers to
ownstream clients and cache it. downstream clients. This is an
This is an alternative to having dnsmasq validate DNSSEC, but it d alternative to having dnsmasq validate DNSSEC, but it depends on
epends on the security of the the security of the network
network between dnsmasq and the upstream servers, and the between dnsmasq and the upstream servers, and the trustworthines
trustworthiness of the upstream s of the upstream servers. Note
servers. that caching the Authenticated Data bit correctly 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 d
nsmasq is a better option. See
--dnssec for details.
--dnssec-debug --dnssec-debug
Set debugging mode for the DNSSEC validation, set the Checking Dis abled bit on upstream queries, Set debugging mode for the DNSSEC validation, set the Checking Di sabled bit on upstream queries,
and don't convert replies which do not validate to responses with a return code of SERVFAIL. Note 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 no t an extra-logging flag and that setting this may affect DNS behaviour in bad ways, it i s not an extra-logging flag and
should not be set in production. should not be set in production.
--auth-zone=<domain>[,<subnet>[/<prefix length>][,<subnet>[/<prefix length>].....][,exclude:<sub- --auth-zone=<domain>[,<subnet>[/<prefix length>][,<subnet>[/<prefix length>].....][,exclude:<sub-
net>[/<prefix length>]].....] net>[/<prefix length>]].....]
Define a DNS zone for which dnsmasq acts as authoritative server. Locally defined DNS records Define a DNS zone for which dnsmasq acts as authoritative serv er. 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 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. of the specified subnets.
As alternative to directly specifying the subnets, it's possible t o give the name of an inter- As alternative to directly specifying the subnets, it's possibl e to give the name of an inter-
face, in which case the subnets implied by that interface's config ured addresses and netmask/pre- face, in which case the subnets implied by that interface's config ured addresses and netmask/pre-
fix-length are used; this is useful when using constructed DHCP ra fix-length are used; this is useful when using constructed DHCP
nges as the actual address is ranges as the actual address is
dynamic and not known when configuring dnsmasq. The interface ad dynamic and not known when configuring dnsmasq. The interface addr
dresses may be confined to only esses may be confined to only
IPv6 addresses using <interface>/6 or to only IPv4 using <interfac IPv6 addresses using <interface>/6 or to only IPv4 using <inter
e>/4. This is useful when an face>/4. This is useful when an
interface has dynamically determined global IPv6 addresses which interface has dynamically determined global IPv6 addresses which s
should appear in the zone, but hould appear in the zone, but
RFC1918 IPv4 addresses which should not. Interface-name and addr RFC1918 IPv4 addresses which should not. Interface-name and ad
ess-literal subnet specifica- dress-literal subnet specifica-
tions may be used freely in the same --auth-zone declaration. tions may be used freely in the same --auth-zone declaration.
It's possible to exclude certain IP addresses from responses. It It's possible to exclude certain IP addresses from responses. It c
can be used, to make sure that an be used, to make sure that
answers contain only global routeable IP addresses (by excludin answers contain only global routeable IP addresses (by excl
g loopback, RFC1918 and ULA uding loopback, RFC1918 and ULA
addresses). addresses).
The subnet(s) are also used to define in-addr.arpa and ip6.ar pa domains which are served for The subnet(s) are also used to define in-addr.arpa and ip6.arpa d omains which are served for
reverse-DNS queries. If not specified, the prefix length defaults to 24 for IPv4 and 64 for IPv6. 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, 1 For IPv4 subnets, the prefix length should be have the value 8, 16
6 or 24 unless you are familiar or 24 unless you are familiar
with RFC 2317 and have arranged the in-addr.arpa delegation accord with RFC 2317 and have arranged the in-addr.arpa delegation accor
ingly. Note that if no subnets dingly. Note that if no subnets
are specified, then no reverse queries are answered. are specified, then no reverse queries are answered.
--auth-soa=<serial>[,<hostmaster>[,<refresh>[,<retry>[,<expiry>]]]] --auth-soa=<serial>[,<hostmaster>[,<refresh>[,<retry>[,<expiry>]]]]
Specify fields in the SOA record associated with authoritative zon es. Note that this is optional, Specify fields in the SOA record associated with authoritative zon es. Note that this is optional,
all the values are set to sane defaults. all the values are set to sane defaults.
--auth-sec-servers=<domain>[,<domain>[,<domain>...]] --auth-sec-servers=<domain>[,<domain>[,<domain>...]]
Specify any secondary servers for a zone for which dnsmasq is auth Specify any secondary servers for a zone for which dnsmasq is au
oritative. These servers must thoritative. These servers must
be configured to get zone data from dnsmasq by zone transfer, be configured to get zone data from dnsmasq by zone transfer, and
and answer queries for the same answer queries for the same
authoritative zones as dnsmasq. authoritative zones as dnsmasq.
--auth-peer=<ip-address>[,<ip-address>[,<ip-address>...]] --auth-peer=<ip-address>[,<ip-address>[,<ip-address>...]]
Specify the addresses of secondary servers which are allowed to i Specify the addresses of secondary servers which are allowed t
nitiate zone transfer (AXFR) o initiate zone transfer (AXFR)
requests for zones for which dnsmasq is authoritative. If this requests for zones for which dnsmasq is authoritative. If this opt
option is not given but --auth- ion is not given but --auth-
sec-servers is, then AXFR requests will be accepted from any seco sec-servers is, then AXFR requests will be accepted from any se
ndary. Specifying --auth-peer condary. Specifying --auth-peer
without --auth-sec-servers enables zone transfer but does no without --auth-sec-servers enables zone transfer but does not ad
t advertise the secondary in NS vertise the secondary in NS
records returned by dnsmasq. records returned by dnsmasq.
--conntrack --conntrack
Read the Linux connection track mark associated with incoming DNS Read the Linux connection track mark associated with incoming DN
queries and set the same mark S queries and set the same mark
value on upstream traffic used to answer those queries. This allo value on upstream traffic used to answer those queries. This allow
ws traffic generated by dnsmasq s traffic generated by dnsmasq
to be associated with the queries which cause it, useful for ba to be associated with the queries which cause it, useful for
ndwidth accounting and fire- bandwidth accounting and fire-
walling. Dnsmasq must have conntrack support compiled in and the walling. Dnsmasq must have conntrack support compiled in and the k
kernel must have conntrack sup- ernel must have conntrack sup-
port included and configured. This option cannot be combined with --query-port. port included and configured. This option cannot be combined with --query-port.
-F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-a ddr>[,<end-addr>|<mode>][,<net- -F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-a ddr>[,<end-addr>|<mode>][,<net-
mask>[,<broadcast>]][,<lease time>] mask>[,<broadcast>]][,<lease time>]
-F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-IPv6 addr>[,<end-IPv6addr>|construc- -F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-IPv6 addr>[,<end-IPv6addr>|construc-
tor:<interface>][,<mode>][,<prefix-len>][,<lease time>] tor:<interface>][,<mode>][,<prefix-len>][,<lease time>]
Enable the DHCP server. Addresses will be given out from the range <start-addr> to <end-addr> and Enable the DHCP server. Addresses will be given out from the range <start-addr> to <end-addr> and
from statically defined addresses given in --dhcp-host options. I from statically defined addresses given in --dhcp-host options. If
f the lease time is given, then the lease time is given, then
leases will be given for that length of time. The lease time is in leases will be given for that length of time. The lease time is
seconds, or minutes (eg 45m) in seconds, or minutes (eg 45m)
or hours (eg 1h) or "infinite". If not given, the default leas or hours (eg 1h) or "infinite". If not given, the default lease ti
e time is one hour. The minimum me is one hour. The minimum
lease time is two minutes. For IPv6 ranges, the lease time maybe " deprecated"; this sets the pre- lease time is two minutes. For IPv6 ranges, the lease time maybe " deprecated"; this sets the pre-
ferred lifetime sent in a DHCP lease or router advertisement to ze ro, which causes clients to use ferred lifetime sent in a DHCP lease or router advertisement to ze ro, which causes clients to use
other addresses, if available, for new connections as a prelude to renumbering. other addresses, if available, for new connections as a prelude to renumbering.
This option may be repeated, with different addresses, to enable D This option may be repeated, with different addresses, to enabl
HCP service to more than one e DHCP service to more than one
network. For directly connected networks (ie, networks on which network. For directly connected networks (ie, networks on which th
the machine running dnsmasq has e machine running dnsmasq has
an interface) the netmask is optional: dnsmasq will determine it f an interface) the netmask is optional: dnsmasq will determine i
rom the interface configura- t from the interface configura-
tion. For networks which receive DHCP service via a relay agen tion. For networks which receive DHCP service via a relay agent,
t, dnsmasq cannot determine the dnsmasq cannot determine the
netmask itself, so it should be specified, otherwise dnsmasq will netmask itself, so it should be specified, otherwise dnsmasq w
have to guess, based on the ill have to guess, based on the
class (A, B or C) of the network address. The broadcast address i class (A, B or C) of the network address. The broadcast address is
s always optional. It is always always optional. It is always
allowed to have more than one --dhcp-range in a single subnet. allowed to have more than one --dhcp-range in a single subnet.
For IPv6, the parameters are slightly different: instead of netmas k and broadcast address, there For IPv6, the parameters are slightly different: instead of netma sk and broadcast address, there
is an optional prefix length which must be equal to or larger then the prefix length on the local 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 interface. If not given, this defaults to 64. Unlike the IPv4
, the prefix length is not case, the prefix length is not
automatically derived from the interface configuration. The minim automatically derived from the interface configuration. The minimu
um size of the prefix length is m size of the prefix length is
64. 64.
IPv6 (only) supports another type of range. In this, the start add IPv6 (only) supports another type of range. In this, the start a
ress and optional end address ddress and optional end address
contain only the network part (ie ::1) and they are followed by contain only the network part (ie ::1) and they are followed by
constructor:<interface>. This constructor:<interface>. This
forms a template which describes how to create ranges, based on th forms a template which describes how to create ranges, based o
e addresses assigned to the n the addresses assigned to the
interface. For instance interface. For instance
--dhcp-range=::1,::400,constructor:eth0 --dhcp-range=::1,::400,constructor:eth0
will look for addresses on eth0 and then create a range from <ne will look for addresses on eth0 and then create a range from <netw
twork>::1 to <network>::400. If ork>::1 to <network>::400. If
the interface is assigned more than one network, then the correspo the interface is assigned more than one network, then the corresp
nding ranges will be automati- onding ranges will be automati-
cally created, and then deprecated and finally removed again a cally created, and then deprecated and finally removed again as th
s the address is deprecated and e address is deprecated and
then deleted. The interface name may have a final "*" wildcard. No then deleted. The interface name may have a final "*" wildcard
te that just any address on . Note that just any address on
eth0 will not do: it must not be an autoconfigured or privacy addr ess, or be deprecated. eth0 will not do: it must not be an autoconfigured or privacy addr ess, or be deprecated.
If a --dhcp-range is only being used for stateless DHCP and/or SLAAC, then the address can be If a --dhcp-range is only being used for stateless DHCP and/or SLA AC, then the address can be
simply :: simply ::
--dhcp-range=::,constructor:eth0 --dhcp-range=::,constructor:eth0
The optional set:<tag> sets an alphanumeric label which marks this network so that dhcp options The optional set:<tag> sets an alphanumeric label which marks th is network so that DHCP options
may be specified on a per-network basis. When it is prefixed with 'tag:' instead, then its mean- may be specified on a per-network basis. When it is prefixed with 'tag:' instead, then its mean-
ing changes from setting a tag to matching it. Only one tag may be set, but more than one tag may ing changes from setting a tag to matching it. Only one tag may be set, but more than one tag may
be matched. be matched.
The optional <mode> keyword may be static which tells dnsmasq The optional <mode> keyword may be static which tells dnsmasq to
to enable DHCP for the network enable DHCP for the network
specified, but not to dynamically allocate IP addresses: only host specified, but not to dynamically allocate IP addresses: only ho
s which have static addresses sts which have static addresses
given via --dhcp-host or from /etc/ethers will be served. A stat given via --dhcp-host or from /etc/ethers will be served. A static
ic-only subnet with address all -only subnet with address all
zeros may be used as a "catch-all" address to enable replies to al zeros may be used as a "catch-all" address to enable replies to
l Information-request packets all Information-request packets
on a subnet which is provided with stateless DHCPv6, ie --dhcp-ran ge=::,static on a subnet which is provided with stateless DHCPv6, ie --dhcp-ran ge=::,static
For IPv4, the <mode> may be proxy in which case dnsmasq will prov ide proxy-DHCP on the specified For IPv4, the <mode> may be proxy in which case dnsmasq will provi de proxy-DHCP on the specified
subnet. (See --pxe-prompt and --pxe-service for details.) 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- For IPv6, the mode may be some combination of ra-only, sla ac, ra-names, ra-stateless, ra-
advrouter, off-link. advrouter, off-link.
ra-only tells dnsmasq to offer Router Advertisement only on this s ubnet, and not DHCP. ra-only tells dnsmasq to offer Router Advertisement only on this s ubnet, and not DHCP.
slaac tells dnsmasq to offer Router Advertisement on this sub net and to set the A bit in the slaac tells dnsmasq to offer Router Advertisement on this subnet a nd to set the A bit in the
router advertisement, so that the client will use SLAAC addresses. When used with a DHCP range or 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. 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 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 oth er configuration information. service. The client will use a SLAAC address, and use DHCP for oth er configuration information.
ra-names enables a mode which gives DNS names to dual-stack hosts ra-names enables a mode which gives DNS names to dual-stack host
which do SLAAC for IPv6. Dns- s which do SLAAC for IPv6. Dns-
masq uses the host's IPv4 lease to derive the name, network segm masq uses the host's IPv4 lease to derive the name, network segmen
ent and MAC address and assumes t and MAC address and assumes
that the host will also have an IPv6 address calculated using the that the host will also have an IPv6 address calculated using t
SLAAC algorithm, on the same he SLAAC algorithm, on the same
network segment. The address is pinged, and if a reply is recei network segment. The address is pinged, and if a reply is received
ved, an AAAA record is added to , an AAAA record is added to
the DNS for this IPv6 address. Note that this is only happens for the DNS for this IPv6 address. Note that this is only happens f
directly-connected networks, or directly-connected networks,
(not one doing DHCP via a relay) and it will not work if a host is using privacy extensions. ra- (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. names can be combined with ra-stateless and slaac.
ra-advrouter enables a mode where router address(es) rather than p ra-advrouter enables a mode where router address(es) rather than
refix(es) are included in the prefix(es) are included in the
advertisements. This is described in RFC-3775 section 7.2 and advertisements. This is described in RFC-3775 section 7.2 and is
is used in mobile IPv6. In this used in mobile IPv6. In this
mode the interval option is also included, as described in RFC-377 5 section 7.3. mode the interval option is also included, as described in RFC-377 5 section 7.3.
off-link tells dnsmasq to advertise the prefix without the on-link (aka L) bit set. off-link tells dnsmasq to advertise the prefix without the on-link (aka L) bit set.
-G, --dhcp-host=[<hwaddr>][,id:<client_id>|*] [,set:<tag>][,<ipaddr>][,<host- -G, --dhcp-host=[<hwaddr>][,id:<client_id>|*][,set:<tag> ][tag:<tag>][,<ipaddr>][,<host-
name>][,<lease_time>][,ignore] name>][,<lease_time>][,ignore]
Specify per host parameters for the DHCP server. This allows a mac hine with a particular hardware Specify per host parameters for the DHCP server. This allows a mac hine with a particular hardware
address to be always allocated the same hostname, IP address and l ease time. A hostname specified address to be always allocated the same hostname, IP address and l ease time. A hostname specified
like this overrides any supplied by the DHCP client on the machin like this overrides any supplied by the DHCP client on the machine
e. It is also allowable to omit . It is also allowable to omit
the hardware address and include the hostname, in which case the I the hardware address and include the hostname, in which case the
P address and lease times will IP address and lease times will
apply to any machine claiming that name. For example --dhcp-host apply to any machine claiming that name. For example --dhcp-host
=00:20:e0:3b:13:af,wap,infinite =00:20:e0:3b:13:af,wap,infinite
tells dnsmasq to give the machine with hardware address 00:20:e0:3 tells dnsmasq to give the machine with hardware address 00:20:e
b:13:af the name wap, and an 0:3b:13:af the name wap, and an
infinite DHCP lease. --dhcp-host=lap,192.168.0.199 tells dnsmasq infinite DHCP lease. --dhcp-host=lap,192.168.0.199 tells dnsmasq
to always allocate the machine to always allocate the machine
lap the IP address 192.168.0.199. lap the IP address 192.168.0.199.
Addresses allocated like this are not constrained to be in the ran Addresses allocated like this are not constrained to be in the
ge given by the --dhcp-range range given by the --dhcp-range
option, but they must be in the same subnet as some valid dhcp- option, but they must be in the same subnet as some valid dhcp-ran
range. For subnets which don't ge. For subnets which don't
need a pool of dynamically allocated addresses, use the "static" k eyword in the --dhcp-range dec- need a pool of dynamically allocated addresses, use the "static" k eyword in the --dhcp-range dec-
laration. laration.
It is allowed to use client identifiers (called client DUID in It is allowed to use client identifiers (called client DUID in IPv
IPv6-land) rather than hardware 6-land) rather than hardware
addresses to identify hosts by prefixing with 'id:'. Thus: - addresses to identify hosts by prefixing with 'id:'. Thus: -
-dhcp-host=id:01:02:03:04,..... -dhcp-host=id:01:02:03:04,.....
refers to the host with client identifier 01:02:03:04. It is als refers to the host with client identifier 01:02:03:04. It is also
o allowed to specify the client allowed to specify the client
ID as text, like this: --dhcp-host=id:clientidastext,..... ID as text, like this: --dhcp-host=id:clientidastext,.....
A single --dhcp-host may contain an IPv4 address or an IPv6 addres A single --dhcp-host may contain an IPv4 address or one or mor
s, or both. IPv6 addresses must e IPv6 addresses, or both. IPv6
be bracketed by square brackets thus: --dhcp-host=laptop,[1234: addresses must be bracketed by square brackets thus: --dhcp-host=l
:56] IPv6 addresses may contain aptop,[1234::56] IPv6 addresses
only the host-identifier part: --dhcp-host=laptop,[::56] in which may contain only the host-identifier part: --dhcp-host=laptop,[
case they act as wildcards in ::56] in which case they act as
constructed dhcp ranges, with the appropriate network part inserte wildcards in constructed DHCP ranges, with the appropriate network
d. Note that in IPv6 DHCP, the part inserted. For IPv6, an
hardware address may not be available, though it normally is for address may include a prefix length: --dhcp-host=laptop,[1234:50/1
direct-connected clients, or 26] which (in this case) speci-
clients using DHCP relays which support RFC 6939. fies 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 varying DUIDs, since it
allows dnsmasq to honour the static address allocation but assign
a different adddress for each
DUID. This typically occurs when chain netbooting, as each stage
of the chain gets in turn allo-
cates 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 suppo
rt RFC 6939.
For DHCPv4, the special option id:* means "ignore any client- id and use MAC addresses only." 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 no t others. This is useful when a client presents a client-id sometimes but no t others.
If a name appears in /etc/hosts, the associated address can be all ocated to a DHCP lease, but If a name appears in /etc/hosts, the associated address can be all ocated to a DHCP lease, but
only if a --dhcp-host option specifying the name also exists. Only one hostname can be given in a 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 ). --dhcp-host option, but aliases are possible by using CNAMEs. (See --cname ).
The special keyword "ignore" tells dnsmasq to never offer a DHCP l ease to a machine. The machine The special keyword "ignore" tells dnsmasq to never offer a DHCP l ease to a machine. The machine
can be specified by hardware address, client ID or ho stname, for instance --dhcp- can be specified by hardware address, client ID or ho stname, for instance --dhcp-
host=00:20:e0:3b:13:af,ignore This is useful when there is another DHCP server on the network 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. which should be used by some machines.
The set:<tag> construct sets the tag whenever this --dhcp-host d irective is in use. This can be The set:<tag> construct sets the tag whenever this --dhcp-host d irective is in use. This can be
used to selectively send DHCP options just for this host. More tha n one tag can be set in a used to selectively send DHCP options just for this host. More tha n one tag can be set in a
--dhcp-host directive (but not in other places where "set:<tag>" i s allowed). When a host matches --dhcp-host directive (but not in other places where "set:<tag>" i s allowed). When a host matches
any --dhcp-host directive (or one implied by /etc/ethers) then the special tag "known" is set. 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- 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 cannot be used because ignore=tag:!known If the host matches only a --dhcp-host directive which cannot be used because
it specifies an address on different subnet, the tag "known-othern it specifies an address on different subnet, the tag "known-othern
et" is set. Ethernet addresses et" is set.
(but not client-ids) may have wildcard bytes, so for example --dh
cp-host=00:20:e0:3b:13:*,ignore The tag:<tag> construct filters which dhcp-host directives are u
will cause dnsmasq to ignore a range of hardware addresses. No sed. Tagged directives are used
te that the "*" will need to be in preference to untagged ones.
escaped or quoted on a command line, but not in the configuration
file. Ethernet addresses (but not client-ids) may have wildcard by
tes, so for example --dhcp-
host=00:20:e0:3b:13:*,ignore will cause dnsmasq to ignore a ra
nge 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 i s possible to restrict them to 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 (i n HEX) and "-". so --dhcp- a single ARP type by preceding them with the ARP-type (i n HEX) and "-". so --dhcp-
host=06-00:20:e0:3b:13:af,1.2.3.4 will only match a Token-Ring har dware address, since the ARP- host=06-00:20:e0:3b:13:af,1.2.3.4 will only match a Token-Ring h ardware address, since the ARP-
address type for token ring is 6. address type for token ring is 6.
As a special case, in DHCPv4, it is possible to include more than one hardware address. eg: As a special case, in DHCPv4, it is possible to include more tha n one hardware address. eg:
--dhcp-host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2 This a llows an IP address to be asso- --dhcp-host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2 This a llows an IP address to be asso-
ciated with multiple hardware addresses, and gives dnsmasq permis ciated with multiple hardware addresses, and gives dnsmasq permiss
sion to abandon a DHCP lease to ion to abandon a DHCP lease to
one of the hardware addresses when another one asks for a lease. B one of the hardware addresses when another one asks for a lease.
eware that this is a dangerous Beware that this is a dangerous
thing to do, it will only work reliably if only one of the hard thing to do, it will only work reliably if only one of the hardwar
ware addresses is active at any e addresses is active at any
time and there is no way for dnsmasq to enforce this. It is, for i time and there is no way for dnsmasq to enforce this. It is, for
nstance, useful to allocate a instance, useful to allocate a
stable IP address to a laptop which has both wired and wireless in terfaces. stable IP address to a laptop which has both wired and wireless in terfaces.
--dhcp-hostsfile=<path> --dhcp-hostsfile=<path>
Read DHCP host information from the specified file. If a direct Read DHCP host information from the specified file. If a directory
ory is given, then read all the is given, then read all the
files contained in that directory. The file contains information a files contained in that directory. The file contains informati
bout one host per line. The on 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 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 with out re-starting dnsmasq: the DHCP host information in this file is that it can be changed w ithout re-starting dnsmasq: the
file will be re-read when dnsmasq receives SIGHUP. file will be re-read when dnsmasq receives SIGHUP.
--dhcp-optsfile=<path> --dhcp-optsfile=<path>
Read DHCP option information from the specified file. If a direct ory is given, then read all the Read DHCP option information from the specified file. If a direct ory is given, then read all the
files contained in that directory. The advantage of using this opt ion is the same as for --dhcp- files contained in that directory. The advantage of using this op tion is the same as for --dhcp-
hostsfile: the --dhcp-optsfile will be re-read when dnsmasq receiv es SIGHUP. Note that it is pos- hostsfile: the --dhcp-optsfile will be re-read when dnsmasq receiv es SIGHUP. Note that it is pos-
sible to encode the information in a --dhcp-boot flag as DHCP opti sible to encode the information in a --dhcp-boot flag as DHCP o
ons, using the options names ptions, using the options names
bootfile-name, server-ip-address and tftp-server. This allows th bootfile-name, server-ip-address and tftp-server. This allows thes
ese to be included in a --dhcp- e to be included in a --dhcp-
optsfile. optsfile.
--dhcp-hostsdir=<path> --dhcp-hostsdir=<path>
This is equivalent to --dhcp-hostsfile, except for the following. This is equivalent to --dhcp-hostsfile, except for the following
The path MUST be a directory, . The path MUST be a directory,
and not an individual file. Changed or new files within the di and not an individual file. Changed or new files within the direc
rectory are read automatically, tory are read automatically,
without the need to send SIGHUP. If a file is deleted or changed without the need to send SIGHUP. If a file is deleted or changed
after it has been read by dns- after it has been read by dns-
masq, then the host record it contained will remain until d masq, then the host record it contained will remain until dnsmas
nsmasq receives a SIGHUP, or is q receives a SIGHUP, or is
restarted; ie host records are only added dynamically. restarted; ie host records are only added dynamically.
--dhcp-optsdir=<path> --dhcp-optsdir=<path>
This is equivalent to --dhcp-optsfile, with the differences noted for --dhcp-hostsdir. This is equivalent to --dhcp-optsfile, with the differences noted for --dhcp-hostsdir.
-Z, --read-ethers -Z, --read-ethers
Read /etc/ethers for information about hosts for the DHCP server. Read /etc/ethers for information about hosts for the DHCP server.
The format of /etc/ethers is a The format of /etc/ethers is a
hardware address, followed by either a hostname or dotted-quad I hardware address, followed by either a hostname or dotted-quad IP
P address. When read by dnsmasq address. When read by dnsmasq
these lines have exactly the same effect as --dhcp-host options co these lines have exactly the same effect as --dhcp-host options c
ntaining the same information. ontaining the same information.
/etc/ethers is re-read when dnsmasq receives SIGHUP. IPv6 addresses are NOT read from /etc/ethers is re-read when dnsmasq receives SIGHUP. IPv6 addresses are NOT read from
/etc/ethers. /etc/ethers.
-O, --dhcp-option=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap: <enterprise>,][vendor:[<vendor- -O, --dhcp-option=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap: <enterprise>,][vendor:[<vendor-
class>],][<opt>|option:<opt-name>|option6:<opt>|option6:<opt-name>],[<val ue>[,<value>]] class>],][<opt>|option:<opt-name>|option6:<opt>|option6:<opt-name>],[<val ue>[,<value>]]
Specify different or extra options to DHCP clients. By defau Specify different or extra options to DHCP clients. By default,
lt, dnsmasq sends some standard dnsmasq sends some standard
options to DHCP clients, the netmask and broadcast address are set options to DHCP clients, the netmask and broadcast address are s
to the same as the host run- et to the same as the host run-
ning dnsmasq, and the DNS server and default route are set to the ning dnsmasq, and the DNS server and default route are set to the
address of the machine running address of the machine running
dnsmasq. (Equivalent rules apply for IPv6.) If the domain name opt ion has been set, that is sent. dnsmasq. (Equivalent rules apply for IPv6.) If the domain name opt ion has been set, that is sent.
This configuration allows these defaults to be overridden, This configuration allows these defaults to be overridden, or
or other options specified. The other options specified. The
option, to be sent may be given as a decimal number or as "option: option, to be sent may be given as a decimal number or as "option
<option-name>" The option num- :<option-name>" The option num-
bers are specified in RFC2132 and subsequent RFCs. The set of op bers are specified in RFC2132 and subsequent RFCs. The set of opti
tion-names known by dnsmasq can on-names known by dnsmasq can
be discovered by running "dnsmasq --help dhcp". For example, to s be discovered by running "dnsmasq --help dhcp". For example, to
et the default route option to set the default route option to
192.168.4.4, do --dhcp-option=3,192.168.4.4 or --dhcp-option = op 192.168.4.4, do --dhcp-option=3,192.168.4.4 or --dhcp-option = opt
tion:router, 192.168.4.4 and to ion:router, 192.168.4.4 and to
set the time-server address to 192.168.0.4, do --dhcp-option = 42, set the time-server address to 192.168.0.4, do --dhcp-option = 42
192.168.0.4 or --dhcp-option = ,192.168.0.4 or --dhcp-option =
option:ntp-server, 192.168.0.4 The special address 0.0.0.0 is ta option:ntp-server, 192.168.0.4 The special address 0.0.0.0 is take
ken to mean "the address of the n to mean "the address of the
machine running dnsmasq". machine running dnsmasq".
Data types allowed are comma separated dotted-quad IPv4 addresses, []-wrapped IPv6 addresses, a Data types allowed are comma separated dotted-quad IPv4 addresse s, []-wrapped IPv6 addresses, a
decimal number, colon-separated hex digits and a text string. If t he optional tags are given then decimal number, colon-separated hex digits and a text string. If t he optional tags are given then
this option is only sent when all the tags are matched. this option is only sent when all the tags are matched.
Special processing is done on a text argument for option 119, to c Special processing is done on a text argument for option 119, to
onform with RFC 3397. Text or conform with RFC 3397. Text or
dotted-quad IP addresses as arguments to option 120 are handled dotted-quad IP addresses as arguments to option 120 are handled as
as per RFC 3361. Dotted-quad IP per RFC 3361. Dotted-quad IP
addresses which are followed by a slash and then a netmask size ar addresses which are followed by a slash and then a netmask size
e encoded as described in RFC are encoded as described in RFC
3442. 3442.
IPv6 options are specified using the option6: keyword, followed IPv6 options are specified using the option6: keyword, followed by
by the option number or option the option number or option
name. The IPv6 option name space is disjoint from the IPv4 option name. The IPv6 option name space is disjoint from the IPv4 optio
name space. IPv6 addresses in n name space. IPv6 addresses in
options must be bracketed with square brackets, eg. --dhcp-optio options must be bracketed with square brackets, eg. --dhcp-optio
n=option6:ntp-server,[1234::56] n=option6:ntp-server,[1234::56]
For IPv6, [::] means "the global address of the machine running For IPv6, [::] means "the global address of the machine runni
dnsmasq", whilst [fd00::] is ng dnsmasq", whilst [fd00::] is
replaced with the ULA, if it exists, and [fe80::] with the link-lo cal address. replaced with the ULA, if it exists, and [fe80::] with the link-lo cal address.
Be careful: no checking is done that the correct type of data fo Be careful: no checking is done that the correct type of data for
r the option number is sent, it the option number is sent, it
is quite possible to persuade dnsmasq to generate illegal DHCP pac is quite possible to persuade dnsmasq to generate illegal DHCP
kets with injudicious use of packets with injudicious use of
this flag. When the value is a decimal number, dnsmasq must determ ine how large the data item is. this flag. When the value is a decimal number, dnsmasq must determ ine how large the data item is.
It does this by examining the option number and/or the value, but can be overridden by appending 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 use- a single letter flag as follows: b = one byte, s = two bytes, i = four bytes. This is mainly use-
ful with encapsulated vendor class options (see below) where dnsma ful with encapsulated vendor class options (see below) where dns
sq cannot determine data size masq cannot determine data size
from the option number. Option data which consists solely of pe from the option number. Option data which consists solely of peri
riods and digits will be inter- ods and digits will be inter-
preted by dnsmasq as an IP address, and inserted into an option a preted by dnsmasq as an IP address, and inserted into an opt
s such. To force a literal ion as such. To force a literal
string, use quotes. For instance when using option 66 to send a li teral IP address as TFTP server string, use quotes. For instance when using option 66 to send a li teral IP address as TFTP server
name, it is necessary to do --dhcp-option=66,"1.2.3.4" name, it is necessary to do --dhcp-option=66,"1.2.3.4"
Encapsulated Vendor-class options may also be specified (IPv4 on Encapsulated Vendor-class options may also be specified (IPv4
ly) using --dhcp-option: for only) using --dhcp-option: for
instance --dhcp-option=vendor:PXEClient,1,0.0.0.0 sends the enc instance --dhcp-option=vendor:PXEClient,1,0.0.0.0 sends the encap
apsulated vendor class-specific sulated vendor class-specific
option "mftp-address=0.0.0.0" to any client whose vendor-class mat option "mftp-address=0.0.0.0" to any client whose vendor-class m
ches "PXEClient". The vendor- atches "PXEClient". The vendor-
class matching is substring based (see --dhcp-vendorclass for det class matching is substring based (see --dhcp-vendorclass for deta
ails). If a vendor-class option ils). If a vendor-class option
(number 60) is sent by dnsmasq, then that is used for selecting en (number 60) is sent by dnsmasq, then that is used for selecting
capsulated options in prefer- encapsulated options in prefer-
ence to any sent by the client. It is possible to omit the ence to any sent by the client. It is possible to omit the ve
vendorclass completely; --dhcp- ndorclass completely; --dhcp-
option=vendor:,1,0.0.0.0 in which case the encapsulated option is always sent. option=vendor:,1,0.0.0.0 in which case the encapsulated option is always sent.
Options may be encapsulated (IPv4 only) within other opti Options may be encapsulated (IPv4 only) within other o
ons: for instance --dhcp- ptions: for instance --dhcp-
option=encap:175, 190, iscsi-client0 will send option 175, wit option=encap:175, 190, iscsi-client0 will send option 175, within
hin which is the option 190. If which is the option 190. If
multiple options are given which are encapsulated with the same op multiple options are given which are encapsulated with the same
tion number then they will be option number then they will be
correctly combined into one encapsulated option. encap: and ven correctly combined into one encapsulated option. encap: and vendo
dor: are may not both be set in r: are may not both be set in
the same --dhcp-option. the same --dhcp-option.
The final variant on encapsulated options is "Vendor-Identifying V The final variant on encapsulated options is "Vendor-Identifying
endor Options" as specified by Vendor Options" as specified by
RFC3925. These are denoted like this: --dhcp-option=vi-encap:2, RFC3925. These are denoted like this: --dhcp-option=vi-encap:2, 10
10, text The number in the vi- , text The number in the vi-
encap: section is the IANA enterprise number used to identify this encap: section is the IANA enterprise number used to identify thi
option. This form of encapsu- s option. This form of encapsu-
lation is supported in IPv6. lation is supported in IPv6.
The address 0.0.0.0 is not treated specially in encapsulated optio ns. The address 0.0.0.0 is not treated specially in encapsulated optio ns.
--dhcp-option-force=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<ente rprise>,][vendor:[<vendor- --dhcp-option-force=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<ente rprise>,][vendor:[<vendor-
class>],]<opt>,[<value>[,<value>]] class>],]<opt>,[<value>[,<value>]]
This works in exactly the same way as --dhcp-option except that th This works in exactly the same way as --dhcp-option except that
e option will always be sent, the option will always be sent,
even if the client does not ask for it in the parameter request even if the client does not ask for it in the parameter request li
list. This is sometimes needed, st. This is sometimes needed,
for example when sending options to PXELinux. for example when sending options to PXELinux.
--dhcp-no-override --dhcp-no-override
(IPv4 only) Disable re-use of the DHCP servername and filename fie (IPv4 only) Disable re-use of the DHCP servername and filename f
lds as extra option space. If ields as extra option space. If
it can, dnsmasq moves the boot server and filename information it can, dnsmasq moves the boot server and filename information (fr
(from --dhcp-boot) out of their om --dhcp-boot) out of their
dedicated fields into DHCP options. This make extra space availa dedicated fields into DHCP options. This make extra space a
ble in the DHCP packet for vailable in the DHCP packet for
options but can, rarely, confuse old or broken clients. This flag forces "simple and safe" behav- options but can, rarely, confuse old or broken clients. This flag forces "simple and safe" behav-
iour to avoid problems in such a case. iour to avoid problems in such a case.
--dhcp-relay=<local address>,<server address>[,<interface] --dhcp-relay=<local address>,<server address>[,<interface]
Configure dnsmasq to do DHCP relay. The local address is an addres Configure dnsmasq to do DHCP relay. The local address is an addre
s allocated to an interface on ss allocated to an interface on
the host running dnsmasq. All DHCP requests arriving on that the host running dnsmasq. All DHCP requests arriving on that inte
interface will we relayed to a rface will we relayed to a
remote DHCP server at the server address. It is possible to relay remote DHCP server at the server address. It is possible to relay
from a single local address to from a single local address to
multiple remote servers by using multiple --dhcp-relay configs multiple remote servers by using multiple --dhcp-relay configs wit
with the same local address and h the same local address and
different server addresses. A server address must be an IP literal address, not a domain name. In different server addresses. A server address must be an IP literal address, not a domain name. In
the case of DHCPv6, the server address may be the ALL_SERVERS m the case of DHCPv6, the server address may be the ALL_SERVERS mult
ulticast address, ff05::1:3. In icast address, ff05::1:3. In
this case the interface must be given, not be wildcard, and is use this case the interface must be given, not be wildcard, and is
d to direct the multicast to used to direct the multicast to
the correct interface to reach the DHCP server. the correct interface to reach the DHCP server.
Access control for DHCP clients has the same rules as for th Access control for DHCP clients has the same rules as for the D
e DHCP server, see --interface, HCP server, see --interface,
--except-interface, etc. The optional interface name in the --dhcp --except-interface, etc. The optional interface name in the --dh
-relay config has a different cp-relay config has a different
function: it controls on which interface DHCP replies from the s function: it controls on which interface DHCP replies from the ser
erver will be accepted. This is ver will be accepted. This is
intended for configurations which have three interfaces: one being intended for configurations which have three interfaces: one be
relayed from, a second con- ing relayed from, a second con-
necting the DHCP server, and a third untrusted network, typicall necting the DHCP server, and a third untrusted network, typically
y the wider internet. It avoids the wider internet. It avoids
the possibility of spoof replies arriving via this third interface . the possibility of spoof replies arriving via this third interface .
It is allowed to have dnsmasq act as a DHCP server on one set of i nterfaces and relay from a dis- It is allowed to have dnsmasq act as a DHCP server on one set of i nterfaces and relay from a dis-
joint set of interfaces. Note that whilst it is quite possibl joint set of interfaces. Note that whilst it is quite possible t
e to write configurations which o write configurations which
appear to act as a server and a relay on the same interface, this appear to act as a server and a relay on the same interface, t
is not supported: the relay his is not supported: the relay
function will take precedence. function will take precedence.
Both DHCPv4 and DHCPv6 relay is supported. It's not possible to relay DHCPv4 to a DHCPv6 server Both DHCPv4 and DHCPv6 relay is supported. It's not possible to re lay DHCPv4 to a DHCPv6 server
or vice-versa. or vice-versa.
-U, --dhcp-vendorclass=set:<tag>,[enterprise:<IANA-enterprise number>,]<v endor-class> -U, --dhcp-vendorclass=set:<tag>,[enterprise:<IANA-enterprise number>,]<v endor-class>
Map from a vendor-class string to a tag. Most DHCP clients provide Map from a vendor-class string to a tag. Most DHCP clients provid
a "vendor class" which repre- e a "vendor class" which repre-
sents, in some sense, the type of host. This option maps vendo sents, in some sense, the type of host. This option maps vendor cl
r classes to tags, so that DHCP asses to tags, so that DHCP
options may be selectively delivered to different classes of hosts options may be selectively delivered to different classes of ho
. For example --dhcp-vendor- sts. For example --dhcp-vendor-
class=set:printers,Hewlett-Packard JetDirect will allow options class=set:printers,Hewlett-Packard JetDirect will allow options to
to be set only for HP printers be set only for HP printers
like so: --dhcp-option=tag:printers,3,192.168.4.4 The vendor-class like so: --dhcp-option=tag:printers,3,192.168.4.4 The vendor-cl
string is substring matched ass string is substring matched
against the vendor-class supplied by the client, to allow fuz against the vendor-class supplied by the client, to allow fuzzy m
zy matching. The set: prefix is atching. The set: prefix is
optional but allowed for consistency. optional but allowed for consistency.
Note that in IPv6 only, vendorclasses are namespaced with an IANA Note that in IPv6 only, vendorclasses are namespaced with an IA
-allocated enterprise number. NA-allocated enterprise number.
This is given with enterprise: keyword and specifies that only ve This is given with enterprise: keyword and specifies that only ven
ndorclasses matching the speci- dorclasses matching the speci-
fied number should be searched. fied number should be searched.
-j, --dhcp-userclass=set:<tag>,<user-class> -j, --dhcp-userclass=set:<tag>,<user-class>
Map from a user-class string to a tag (with substring matching, li Map from a user-class string to a tag (with substring matching,
ke vendor classes). Most DHCP like vendor classes). Most DHCP
clients provide a "user class" which is configurable. This optio clients provide a "user class" which is configurable. This option
n maps user classes to tags, so maps user classes to tags, so
that DHCP options may be selectively delivered to different classe s of hosts. It is possible, for that DHCP options may be selectively delivered to different classe s of hosts. It is possible, for
instance to use this to set a different printer server for hosts i n the class "accounts" than for instance to use this to set a different printer server for hosts i n the class "accounts" than for
hosts in the class "engineering". hosts in the class "engineering".
-4, --dhcp-mac=set:<tag>,<MAC address> -4, --dhcp-mac=set:<tag>,<MAC address>
Map from a MAC address to a tag. The MAC address may include wi Map from a MAC address to a tag. The MAC address may include
ldcards. For example --dhcp- wildcards. For example --dhcp-
mac=set:3com,01:34:23:*:*:* will set the tag "3com" for any hos mac=set:3com,01:34:23:*:*:* will set the tag "3com" for any host w
t whose MAC address matches the hose MAC address matches the
pattern. pattern.
--dhcp-circuitid=set:<tag>,<circuit-id>, --dhcp-remoteid=set:<tag>,<remot e-id> --dhcp-circuitid=set:<tag>,<circuit-id>, --dhcp-remoteid=set:<tag>,<remot e-id>
Map from RFC3046 relay agent options to tags. This data may be pro vided by DHCP relay agents. The Map from RFC3046 relay agent options to tags. This data may be pro vided by DHCP relay agents. The
circuit-id or remote-id is normally given as colon-separated h circuit-id or remote-id is normally given as colon-separated hex,
ex, but is also allowed to be a but is also allowed to be a
simple string. If an exact match is achieved between the circuit o simple string. If an exact match is achieved between the circuit
r agent ID and one provided by or agent ID and one provided by
a relay agent, the tag is set. a relay agent, the tag is set.
--dhcp-remoteid (but not --dhcp-circuitid) is supported in IPv6. --dhcp-remoteid (but not --dhcp-circuitid) is supported in IPv6.
--dhcp-subscrid=set:<tag>,<subscriber-id> --dhcp-subscrid=set:<tag>,<subscriber-id>
(IPv4 and IPv6) Map from RFC3993 subscriber-id relay agent options to tags. (IPv4 and IPv6) Map from RFC3993 subscriber-id relay agent options to tags.
--dhcp-proxy[=<ip addr>]...... --dhcp-proxy[=<ip addr>]......
(IPv4 only) A normal DHCP relay agent is only used to forward the initial parts of a DHCP inter- (IPv4 only) A normal DHCP relay agent is only used to forward the initial parts of a DHCP inter-
action to the DHCP server. Once a client is configured, it communi cates directly with the server. action to the DHCP server. Once a client is configured, it communi cates directly with the server.
This is undesirable if the relay agent is adding extra informati This is undesirable if the relay agent is adding extra information
on to the DHCP packets, such as to the DHCP packets, such as
that used by --dhcp-circuitid and --dhcp-remoteid. A full relay i that used by --dhcp-circuitid and --dhcp-remoteid. A full relay
mplementation can use the RFC implementation can use the RFC
5107 serverid-override option to force the DHCP server to use the relay as a full proxy, with all 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 meth od of doing the same thing, for packets passing through it. This flag provides an alternative meth od of doing the same thing, for
relays which don't support RFC 5107. Given alone, it manipulates relays which don't support RFC 5107. Given alone, it manipulates t
the server-id for all interac- he server-id for all interac-
tions via relays. If a list of IP addresses is given, only inter tions via relays. If a list of IP addresses is given, only i
actions via relays at those nteractions via relays at those
addresses are affected. addresses are affected.
--dhcp-match=set:<tag>,<option number>|option:<option name>|vi-encap:<ent erprise>[,<value>] --dhcp-match=set:<tag>,<option number>|option:<option name>|vi-encap:<ent erprise>[,<value>]
Without a value, set the tag if the client sends a DHCP option of Without a value, set the tag if the client sends a DHCP option of
the given number or name. When the given number or name. When
a value is given, set the tag only if the option is sent and match a value is given, set the tag only if the option is sent and matc
es the value. The value may be hes the value. The value may be
of the form "01:ff:*:02" in which case the value must match (apart from wildcards) but the option of the form "01:ff:*:02" in which case the value must match (apart from wildcards) but the option
sent may have unmatched data past the end of the value. The value may also be of the same form as sent may have unmatched data past the end of the value. The value may also be of the same form as
in --dhcp-option in which case the option sent is treated as in --dhcp-option in which case the option sent is treated as an
an array, and one element must array, and one element must
match, so --dhcp-match=set:efi-ia32,option:client-arch,6 will set match, so --dhcp-match=set:efi-ia32,option:client-arch,6 will se
the tag "efi-ia32" if the the t the tag "efi-ia32" if the the
number 6 appears in the list of architectures sent by the client number 6 appears in the list of architectures sent by the client i
in option 93. (See RFC 4578 for n option 93. (See RFC 4578 for
details.) If the value is a string, substring matching is used. details.) If the value is a string, substring matching is used.
The special form with vi-encap:<enterprise number> matches agai The special form with vi-encap:<enterprise number> matches ag
nst vendor-identifying vendor ainst vendor-identifying vendor
classes for the specified enterprise. Please see RFC 3925 for classes for the specified enterprise. Please see RFC 3925 for more
more details of these rare and details of these rare and
interesting beasts. interesting beasts.
--dhcp-name-match=set:<tag>,<name>[*] --dhcp-name-match=set:<tag>,<name>[*]
Set the tag if the given name is supplied by a dhcp client. There Set the tag if the given name is supplied by a DHCP client. There
may be a single trailing wild- may be a single trailing wild-
card *, which has the usual meaning. Combined with dhcp-ignore card *, which has the usual meaning. Combined with dhcp-ignore or
or dhcp-ignore-names this gives dhcp-ignore-names this gives
the ability to ignore certain clients by name, or disallow certain the ability to ignore certain clients by name, or disallow certa
hostnames from being claimed in hostnames from being claimed
by a client. by a client.
--tag-if=set:<tag>[,set:<tag>[,tag:<tag>[,tag:<tag>]]] --tag-if=set:<tag>[,set:<tag>[,tag:<tag>[,tag:<tag>]]]
Perform boolean operations on tags. Any tag appearing as set:<ta g> is set if all the tags which Perform boolean operations on tags. Any tag appearing as set:<tag> is set if all the tags which
appear as tag:<tag> are set, (or unset when tag:!<tag> is used) If no tag:<tag> appears set:<tag> appear as tag:<tag> are set, (or unset when tag:!<tag> is used) If no tag:<tag> appears set:<tag>
tags are set unconditionally. Any number of set: and tag: tags are set unconditionally. Any number of set: and tag: forms
forms may appear, in any order. may appear, in any order.
--tag-if lines are executed in order, so if the tag in tag:<tag> i --tag-if lines are executed in order, so if the tag in tag:<tag>
s a tag set by another --tag- is a tag set by another --tag-
if, the line which sets the tag must precede the one which tests i t. if, the line which sets the tag must precede the one which tests i t.
-J, --dhcp-ignore=tag:<tag>[,tag:<tag>] -J, --dhcp-ignore=tag:<tag>[,tag:<tag>]
When all the given tags appear in the tag set ignore the hos t and do not allocate it a DHCP When all the given tags appear in the tag set ignore the host and do not allocate it a DHCP
lease. lease.
--dhcp-ignore-names[=tag:<tag>[,tag:<tag>]] --dhcp-ignore-names[=tag:<tag>[,tag:<tag>]]
When all the given tags appear in the tag set, ignore any hostname When all the given tags appear in the tag set, ignore any host
provided by the host. Note name provided by the host. Note
that, unlike --dhcp-ignore, it is permissible to supply no tags, that, unlike --dhcp-ignore, it is permissible to supply no tags, i
in which case DHCP-client sup- n which case DHCP-client sup-
plied hostnames are always ignored, and DHCP hosts are added to th plied hostnames are always ignored, and DHCP hosts are added to
e DNS using only --dhcp-host the DNS using only --dhcp-host
configuration in dnsmasq and the contents of /etc/hosts and /etc/e thers. configuration in dnsmasq and the contents of /etc/hosts and /etc/e thers.
--dhcp-generate-names=tag:<tag>[,tag:<tag>] --dhcp-generate-names=tag:<tag>[,tag:<tag>]
(IPv4 only) Generate a name for DHCP clients which do not ot (IPv4 only) Generate a name for DHCP clients which do not otherwi
herwise have one, using the MAC se have one, using the MAC
address expressed in hex, separated by dashes. Note that if a host address expressed in hex, separated by dashes. Note that if a h
provides a name, it will be ost provides a name, it will be
used by preference to this, unless --dhcp-ignore-names is set. used by preference to this, unless --dhcp-ignore-names is set.
--dhcp-broadcast[=tag:<tag>[,tag:<tag>]] --dhcp-broadcast[=tag:<tag>[,tag:<tag>]]
(IPv4 only) When all the given tags appear in the tag set, alwa ys use broadcast to communicate (IPv4 only) When all the given tags appear in the tag set, always use broadcast to communicate
with the host when it is unconfigured. It is permissible to supply no tags, in which case this is with the host when it is unconfigured. It is permissible to supply no tags, in which case this is
unconditional. Most DHCP clients which need broadcast replies set a flag in their requests so unconditional. Most DHCP clients which need broadcast replies set a flag in their requests so
that this happens automatically, some old BOOTP clients do not. that this happens automatically, some old BOOTP clients do not.
-M, --dhcp-boot=[tag:<tag>,]<filename>,[<servername>[,<server address>|<t ftp_servername>]] -M, --dhcp-boot=[tag:<tag>,]<filename>,[<servername>[,<server address>|<t ftp_servername>]]
(IPv4 only) Set BOOTP options to be returned by the DHCP server. (IPv4 only) Set BOOTP options to be returned by the DHCP serv
Server name and address are er. Server name and address are
optional: if not provided, the name is left empty, and the ad optional: if not provided, the name is left empty, and the address
dress set to the address of the set to the address of the
machine running dnsmasq. If dnsmasq is providing a TFTP service (s machine running dnsmasq. If dnsmasq is providing a TFTP service
ee --enable-tftp ) then only (see --enable-tftp ) then only
the filename is required here to enable network booting. If the the filename is required here to enable network booting. If the o
optional tag(s) are given, they ptional tag(s) are given, they
must match for this configuration to be sent. Instead of an IP ad must match for this configuration to be sent. Instead of an IP a
dress, the TFTP server address ddress, the TFTP server address
can be given as a domain name which is looked up in /etc/hosts. can be given as a domain name which is looked up in /etc/hosts. Th
This name can be associated in is name can be associated in
/etc/hosts with multiple IP addresses, which are used round-robin. /etc/hosts with multiple IP addresses, which are used round-robin
This facility can be used to . This facility can be used to
load balance the tftp load among a set of servers. load balance the tftp load among a set of servers.
--dhcp-sequential-ip --dhcp-sequential-ip
Dnsmasq is designed to choose IP addresses for DHCP clients u Dnsmasq is designed to choose IP addresses for DHCP clients using
sing a hash of the client's MAC a hash of the client's MAC
address. This normally allows a client's address to remain stable address. This normally allows a client's address to remain stabl
long-term, even if the client e long-term, even if the client
sometimes allows its DHCP lease to expire. In this default mo sometimes allows its DHCP lease to expire. In this default mode
de IP addresses are distributed IP addresses are distributed
pseudo-randomly over the entire available address range. There are sometimes circumstances (typi- pseudo-randomly over the entire available address range. There are sometimes circumstances (typi-
cally server deployment) where it is more convenient to have IP ad dresses allocated sequentially, cally server deployment) where it is more convenient to have IP ad dresses allocated sequentially,
starting from the lowest available address, and setting this flag enables this mode. Note that in starting from the lowest available address, and setting this flag enables this mode. Note that in
the sequential mode, clients which allow a lease to expire are much more likely to move IP the sequential mode, clients which allow a lease to expire are m uch more likely to move IP
address; for this reason it should not be generally used. address; for this reason it should not be generally used.
--dhcp-ignore-clid
Dnsmasq is reading 'client identifier' (RFC 2131) option sent by
clients (if available) to iden-
tify clients. This allow to serve same IP address for a host using
several interfaces. Use this
option to disable 'client identifier' reading, i.e. to alway
s identify a host using the MAC
address.
--pxe-service=[tag:<tag>,]<CSA>,<menu text>[,<basena me>|<bootservicetype>][,<server --pxe-service=[tag:<tag>,]<CSA>,<menu text>[,<basena me>|<bootservicetype>][,<server
address>|<server_name>] address>|<server_name>]
Most uses of PXE boot-ROMS simply allow the PXE system to obtain an IP address and then download Most uses of PXE boot-ROMS simply allow the PXE system to obtain an IP address and then download
the file specified by --dhcp-boot and execute it. However the PXE system is capable of more com- the file specified by --dhcp-boot and execute it. However the PXE system is capable of more com-
plex functions when supported by a suitable DHCP server. plex functions when supported by a suitable DHCP server.
This specifies a boot option which may appear in a PXE boot men u. <CSA> is client system type, This specifies a boot option which may appear in a PXE boot men u. <CSA> is client system type,
only services of the correct type will appear in a menu. The k nown types are x86PC, PC98, only services of the correct type will appear in a menu. The k nown types are x86PC, PC98,
IA64_EFI, Alpha, Arc_x86, Intel_Lean_Client, IA32_EFI, X86-64_EFI , Xscale_EFI, BC_EFI, ARM32_EFI IA64_EFI, Alpha, Arc_x86, Intel_Lean_Client, IA32_EFI, X86-64_EFI , Xscale_EFI, BC_EFI, ARM32_EFI
and ARM64_EFI; an integer may be used for other types. The paramet er after the menu text may be a and ARM64_EFI; an integer may be used for other types. The paramet er after the menu text may be a
skipping to change at line 1190 skipping to change at line 1213
cally created DUIDs or vice-versa, the lease database must be re-i nitialised. The enterprise-id cally created DUIDs or vice-versa, the lease database must be re-i nitialised. The enterprise-id
is assigned by IANA, and the uid is a string of hex octets unique to a particular device. is assigned by IANA, and the uid is a string of hex octets unique to a particular device.
-6 --dhcp-script=<path> -6 --dhcp-script=<path>
Whenever a new DHCP lease is created, or an old one destroyed, or a TFTP file transfer completes, Whenever a new DHCP lease is created, or an old one destroyed, or a TFTP file transfer completes,
the executable specified by this option is run. <path> must be an absolute pathname, no PATH the executable specified by this option is run. <path> must be an absolute pathname, no PATH
search occurs. The arguments to the process are "add", "old" o r "del", the MAC address of the search occurs. The arguments to the process are "add", "old" o r "del", the MAC address of the
host (or DUID for IPv6) , the IP address, and the hostname, if kno wn. "add" means a lease has host (or DUID for IPv6) , the IP address, and the hostname, if kno wn. "add" means a lease has
been created, "del" means it has been destroyed, "old" is a no tification of an existing lease been created, "del" means it has been destroyed, "old" is a no tification of an existing lease
when dnsmasq starts or a change to MAC address or hostname of an existing lease (also, lease when dnsmasq starts or a change to MAC address or hostname of an existing lease (also, lease
length or expiry and client-id, if --leasefile-ro is set). If th length or expiry and client-id, if --leasefile-ro is set and leas
e MAC address is from a network e expiry if --script-on-renewal
type other than ethernet, it will have the network type prepended, is set). If the MAC address is from a network type other than eth
eg "06-01:23:45:67:89:ab" for ernet, it will have the network
token ring. The process is run as root (assuming that dnsmasq was type prepended, eg "06-01:23:45:67:89:ab" for token ring. The p
originally run as root) even if rocess is run as root (assuming
dnsmasq is configured to change UID to an unprivileged user. that dnsmasq was originally run as root) even if dnsmasq is conf
igured to change UID to an
unprivileged user.
The environment is inherited from the invoker of dnsmasq, with som e or all of the following vari- The environment is inherited from the invoker of dnsmasq, with som e or all of the following vari-
ables added ables added
For both IPv4 and IPv6: For both IPv4 and IPv6:
DNSMASQ_DOMAIN if the fully-qualified domain name of the ho DNSMASQ_DOMAIN if the fully-qualified domain name of the host is
st is known, this is set to the known, this is set to the
domain part. (Note that the hostname passed to the script as an ar domain part. (Note that the hostname passed to the script as an
gument is never fully-quali- argument is never fully-quali-
fied.) fied.)
If the client provides a hostname, DNSMASQ_SUPPLIED_HOSTNAME If the client provides a hostname, DNSMASQ_SUPPLIED_HOSTNAME
If the client provides user-classes, DNSMASQ_USER_CLASS0..DNSMASQ_ USER_CLASSn If the client provides user-classes, DNSMASQ_USER_CLASS0..DNSMASQ_ USER_CLASSn
If dnsmasq was compiled with HAVE_BROKEN_RTC, then the length of t he lease (in seconds) is stored If dnsmasq was compiled with HAVE_BROKEN_RTC, then the length of t he lease (in seconds) is stored
in DNSMASQ_LEASE_LENGTH, otherwise the time of lease expiry is sto red in DNSMASQ_LEASE_EXPIRES. in DNSMASQ_LEASE_LENGTH, otherwise the time of lease expiry is s tored in DNSMASQ_LEASE_EXPIRES.
The number of seconds until lease expiry is always stored in DNSMA SQ_TIME_REMAINING. The number of seconds until lease expiry is always stored in DNSMA SQ_TIME_REMAINING.
If a lease used to have a hostname, which is removed, an "old" If a lease used to have a hostname, which is removed, an "old" eve
event is generated with the new nt is generated with the new
state of the lease, ie no name, and the former name is provided in state of the lease, ie no name, and the former name is provided i
the environment variable DNS- n the environment variable DNS-
MASQ_OLD_HOSTNAME. MASQ_OLD_HOSTNAME.
DNSMASQ_INTERFACE stores the name of the interface on which the r equest arrived; this is not set DNSMASQ_INTERFACE stores the name of the interface on which the re quest arrived; this is not set
for "old" actions when dnsmasq restarts. for "old" actions when dnsmasq restarts.
DNSMASQ_RELAY_ADDRESS is set if the client used a DHCP relay to contact dnsmasq and the IP DNSMASQ_RELAY_ADDRESS is set if the client used a DHCP rela y to contact dnsmasq and the IP
address of the relay is known. address of the relay is known.
DNSMASQ_TAGS contains all the tags set during the DHCP transaction , separated by spaces. DNSMASQ_TAGS contains all the tags set during the DHCP transaction , separated by spaces.
DNSMASQ_LOG_DHCP is set if --log-dhcp is in effect. DNSMASQ_LOG_DHCP is set if --log-dhcp is in effect.
For IPv4 only: For IPv4 only:
DNSMASQ_CLIENT_ID if the host provided a client-id. DNSMASQ_CLIENT_ID if the host provided a client-id.
DNSMASQ_CIRCUIT_ID, DNSMASQ_SUBSCRIBER_ID, DNSMASQ_REMOTE_ID if a DHCP relay-agent added any of DNSMASQ_CIRCUIT_ID, DNSMASQ_SUBSCRIBER_ID, DNSMASQ_REMOTE_ID if a DHCP relay-agent added any of
these options. these options.
If the client provides vendor-class, DNSMASQ_VENDOR_CLASS. If the client provides vendor-class, DNSMASQ_VENDOR_CLASS.
DNSMASQ_REQUESTED_OPTIONS a string containing the decimal values i n the Parameter Request List DNSMASQ_REQUESTED_OPTIONS a string containing the decimal value s in the Parameter Request List
option, comma separated, if the parameter request list option is p rovided by the client. option, comma separated, if the parameter request list option is p rovided by the client.
For IPv6 only: For IPv6 only:
If the client provides vendor-class, DNSMASQ_VENDOR_CLASS_ID, co ntaining the IANA enterprise id If the client provides vendor-class, DNSMASQ_VENDOR_CLASS_ID, cont aining the IANA enterprise id
for the class, and DNSMASQ_VENDOR_CLASS0..DNSMASQ_VENDOR_CLASSn fo r the data. for the class, and DNSMASQ_VENDOR_CLASS0..DNSMASQ_VENDOR_CLASSn fo r the data.
DNSMASQ_SERVER_DUID containing the DUID of the server: this is the same for every call to the DNSMASQ_SERVER_DUID containing the DUID of the server: this is the same for every call to the
script. script.
DNSMASQ_IAID containing the IAID for the lease. If the lease is a temporary allocation, this is DNSMASQ_IAID containing the IAID for the lease. If the lease is a temporary allocation, this is
prefixed to 'T'. prefixed to 'T'.
DNSMASQ_MAC containing the MAC address of the client, if known. DNSMASQ_MAC containing the MAC address of the client, if known.
Note that the supplied hostname, vendorclass and userclass data Note that the supplied hostname, vendorclass and userclass d
is only supplied for "add" ata is only supplied for "add"
actions or "old" actions when a host resumes an existing lease, s actions or "old" actions when a host resumes an existing lease, si
ince these data are not held in nce these data are not held in
dnsmasq's lease database. dnsmasq's lease database.
All file descriptors are closed except stdin, which is open to /de All file descriptors are closed except stdin, which is open to /
v/null, and stdout and stderr dev/null, and stdout and stderr
which capture output for logging by dnsmasq. (In debug mode, st which capture output for logging by dnsmasq. (In debug mode, stdi
dio, stdout and stderr file are o, stdout and stderr file are
left as those inherited from the invoker of dnsmasq). left as those inherited from the invoker of dnsmasq).
The script is not invoked concurrently: at most one instance of th e script is ever running (dns- The script is not invoked concurrently: at most one instance of t he script is ever running (dns-
masq waits for an instance of script to exit before running the ne xt). Changes to the lease data- masq waits for an instance of script to exit before running the ne xt). Changes to the lease data-
base are which require the script to be invoked are queued awaitin base are which require the script to be invoked are queued await
g exit of a running instance. ing exit of a running instance.
If this queueing allows multiple state changes occur to a single If this queueing allows multiple state changes occur to a single l
lease before the script can be ease before the script can be
run then earlier states are discarded and the current state of tha run then earlier states are discarded and the current state of t
t lease is reflected when the hat lease is reflected when the
script finally runs. script finally runs.
At dnsmasq startup, the script will be invoked for all existing l eases as they are read from the At dnsmasq startup, the script will be invoked for all existing le ases as they are read from the
lease file. Expired leases will be called with "del" and others wi th "old". When dnsmasq receives lease file. Expired leases will be called with "del" and others wi th "old". When dnsmasq receives
a HUP signal, the script will be invoked for existing leases with an "old" event. a HUP signal, the script will be invoked for existing leases with an "old" event.
There are four further actions which may appear as the first argument to the script, "init", There are four further actions which may appear as the first argu ment to the script, "init",
"arp-add", "arp-del" and "tftp". More may be added in the future, so scripts should be written to "arp-add", "arp-del" and "tftp". More may be added in the future, so scripts should be written to
ignore unknown actions. "init" is described below in --leasefile- ignore unknown actions. "init" is described below in --leasefile-r
ro The "tftp" action is invoked o The "tftp" action is invoked
when a TFTP file transfer completes: the arguments are the file si when a TFTP file transfer completes: the arguments are the fil
ze in bytes, the address to e size in bytes, the address to
which the file was sent, and the complete pathname of the file. which the file was sent, and the complete pathname of the file.
The "arp-add" and "arp-del" actions are only called if enabled with --script-arp They are are The "arp-add" and "arp-del" actions are only called if enabled wit h --script-arp They are are
supplied with a MAC address and IP address as arguments. "arp-add" indicates the arrival of a new supplied with a MAC address and IP address as arguments. "arp-add" indicates the arrival of a new
entry in the ARP or neighbour table, and "arp-del" indicates the d eletion of same. entry in the ARP or neighbour table, and "arp-del" indicates the d eletion of same.
--dhcp-luascript=<path> --dhcp-luascript=<path>
Specify a script written in Lua, to be run when leases are create Specify a script written in Lua, to be run when leases are created
d, destroyed or changed. To use , destroyed or changed. To use
this option, dnsmasq must be compiled with the correct support. this option, dnsmasq must be compiled with the correct suppo
The Lua interpreter is ini- rt. The Lua interpreter is ini-
tialised once, when dnsmasq starts, so that global variables pe tialised once, when dnsmasq starts, so that global variables persi
rsist between lease events. The st between lease events. The
Lua code must define a lease function, and may provide init and s Lua code must define a lease function, and may provide init an
hutdown functions, which are d shutdown functions, which are
called, without arguments when dnsmasq starts up and terminates. I t may also provide a tftp func- called, without arguments when dnsmasq starts up and terminates. I t may also provide a tftp func-
tion. tion.
The lease function receives the information detailed in --dhcp-scr The lease function receives the information detailed in --dhcp-
ipt. It gets two arguments, script. It gets two arguments,
firstly the action, which is a string containing, "add", "old" or firstly the action, which is a string containing, "add", "old" or
"del", and secondly a table of "del", and secondly a table of
tag value pairs. The tags mostly correspond to the environment v tag value pairs. The tags mostly correspond to the environmen
ariables detailed above, for t variables detailed above, for
instance the tag "domain" holds the same data as the environment instance the tag "domain" holds the same data as the environment v
variable DNSMASQ_DOMAIN. There ariable DNSMASQ_DOMAIN. There
are a few extra tags which hold the data supplied as arguments are a few extra tags which hold the data supplied as argumen
to --dhcp-script. These are ts to --dhcp-script. These are
mac_address, ip_address and hostname for IPv4, and client_duid, ip _address and hostname for IPv6. mac_address, ip_address and hostname for IPv4, and client_duid, ip _address and hostname for IPv6.
The tftp function is called in the same way as the lease functio n, and the table holds the tags The tftp function is called in the same way as the lease function, and the table holds the tags
destination_address, file_name and file_size. destination_address, file_name and file_size.
The arp and arp-old functions are called only when enabled with -- script-arp and have a table The arp and arp-old functions are called only when enabled wit h --script-arp and have a table
which holds the tags mac_address and client_address. which holds the tags mac_address and client_address.
--dhcp-scriptuser --dhcp-scriptuser
Specify the user as which to run the lease-change script or Lua script. This defaults to root, Specify the user as which to run the lease-change script or Lua sc ript. This defaults to root,
but can be changed to another user using this flag. but can be changed to another user using this flag.
--script-arp --script-arp
Enable the "arp" and "arp-old" functions in the --dhcp-script and --dhcp-luascript. Enable the "arp" and "arp-old" functions in the --dhcp-script and --dhcp-luascript.
-9, --leasefile-ro -9, --leasefile-ro
Completely suppress use of the lease database file. The file will Completely suppress use of the lease database file. The file will
not be created, read, or writ- not be created, read, or writ-
ten. Change the way the lease-change script (if one is provide ten. Change the way the lease-change script (if one is provided) i
d) is called, so that the lease s called, so that the lease
database may be maintained in external storage by the script. In database may be maintained in external storage by the script.
addition to the invocations In addition to the invocations
given in --dhcp-script the lease-change script is called once, at given in --dhcp-script the lease-change script is called once, at
dnsmasq startup, with the sin- dnsmasq startup, with the sin-
gle argument "init". When called like this the script should write gle argument "init". When called like this the script should wri
the saved state of the lease te the saved state of the lease
database, in dnsmasq leasefile format, to stdout and exit wi database, in dnsmasq leasefile format, to stdout and exit with z
th zero exit code. Setting this ero exit code. Setting this
option also forces the leasechange script to be called on changes option also forces the leasechange script to be called on cha
to the client-id and lease nges to the client-id and lease
length and expiry time. length and expiry time.
--script-on-renewal
Call the DHCP script when the lease expiry time changes, for insta
nce when the lease is renewed.
--bridge-interface=<interface>,<alias>[,<alias>] --bridge-interface=<interface>,<alias>[,<alias>]
Treat DHCP (v4 and v6) requests and IPv6 Router Solicit packets arriving at any of the <alias> Treat DHCP (v4 and v6) requests and IPv6 Router Solicit packets ar riving at any of the <alias>
interfaces as if they had arrived at <interface>. This option all ows dnsmasq to provide DHCP and interfaces as if they had arrived at <interface>. This option all ows dnsmasq to provide DHCP and
RA service over unaddressed and unbridged Ethernet interfaces, e. RA service over unaddressed and unbridged Ethernet interfaces, e.g
g. on an OpenStack compute host . on an OpenStack compute host
where each such interface is a TAP interface to a VM, or as in "ol where each such interface is a TAP interface to a VM, or as in "o
d style bridging" on BSD plat- ld style bridging" on BSD plat-
forms. A trailing '*' wildcard can be used in each <alias>. forms. A trailing '*' wildcard can be used in each <alias>.
It is permissible to add more than one alias using more than one It is permissible to add more than one alias using more than one -
--bridge-interface option since -bridge-interface option since
--bridge-interface=int1,alias1,alias2 is exactly equivalent to --bridge-interface=int1,alias1,alias2 is exactly equivalent to
--bridge-interface=int1,alias1 --bridge-interface=int1,alias1
--bridge-interface=int1,alias2 --bridge-interface=int1,alias2
--shared-network=<interface>,<addr>
--shared-network=<addr>,<addr>
The DHCP server determines which DHCP ranges are useable for alloc
ating an address to a DHCP
client based on the network from which the DHCP request arrives,
and the IP configuration of the
server's interface on that network. The shared-network option exte
nds the available subnets (and
therefore DHCP ranges) beyond the subnets configured on the arriva
l interface.
The first argument is either the name of an interface, or an
address that is configured on a
local interface, and the second argument is an address which defi
nes another subnet on which
addresses can be allocated.
To be useful, there must be a suitable dhcp-range which allows ad
dress allocation on this subnet
and this dhcp-range MUST include the netmask.
Using shared-network also needs extra consideration of routing. Dn
smasq does not have the usual
information that it uses to determine the default route, so the
default route option (or other
routing) MUST be configured manually. The client must have a route
to the server: if the two-
address form of shared-network is used, this needs to be to the
first specified address. If the
interface,address form is used, there must be a route to all of th
e addresses configured on the
interface.
The two-address form of shared-network is also usable with a DHCP
relay: the first address is the
address of the relay and the second, as before, specifies an extra
subnet which addresses may be
allocated from.
-s, --domain=<domain>[,<address range>[,local]] -s, --domain=<domain>[,<address range>[,local]]
Specifies DNS domains for the DHCP server. Domains may be be giv en unconditionally (without the Specifies DNS domains for the DHCP server. Domains may be be giv en unconditionally (without the
IP range) or for limited IP ranges. This has two effects; firstly it causes the DHCP server to IP range) or for limited IP ranges. This has two effects; firstly it causes the DHCP server to
return the domain to any hosts which request it, and secondly it sets the domain which it is return the domain to any hosts which request it, and secondly it sets the domain which it is
legal for DHCP-configured hosts to claim. The intention is to con strain hostnames so that an legal for DHCP-configured hosts to claim. The intention is to con strain hostnames so that an
untrusted host on the LAN cannot advertise its name via dhcp as e .g. "microsoft.com" and capture untrusted host on the LAN cannot advertise its name via DHCP as e .g. "microsoft.com" and capture
traffic not meant for it. If no domain suffix is specified, then a ny DHCP hostname with a domain traffic not meant for it. If no domain suffix is specified, then a ny DHCP hostname with a domain
part (ie with a period) will be disallowed and logged. If suff ix is specified, then hostnames part (ie with a period) will be disallowed and logged. If suff ix is specified, then hostnames
with a domain part are allowed, provided the domain part matches t he suffix. In addition, when a with a domain part are allowed, provided the domain part matches t he suffix. In addition, when a
suffix is set then hostnames without a domain part have the suf fix added as an optional domain suffix is set then hostnames without a domain part have the suf fix added as an optional domain
part. Eg on my network I can set --domain=thekelleys.org.uk and ha ve a machine whose DHCP host- part. Eg on my network I can set --domain=thekelleys.org.uk and ha ve a machine whose DHCP host-
name is "laptop". The IP address for that machine is available fr om dnsmasq both as "laptop" and name is "laptop". The IP address for that machine is available fr om dnsmasq both as "laptop" and
"laptop.thekelleys.org.uk". If the domain is given as "#" then the domain is read from the first "laptop.thekelleys.org.uk". If the domain is given as "#" then the domain is read from the first
"search" directive in /etc/resolv.conf (or equivalent). "search" directive in /etc/resolv.conf (or equivalent).
The address range can be of the form <ip address>,<ip address> or <ip address>/<netmask> or just The address range can be of the form <ip address>,<ip address> or <ip address>/<netmask> or just
skipping to change at line 1387 skipping to change at line 1439
subnets with the mode keywords described in --dhcp-range. RFC6106 DNS parameters are included in subnets with the mode keywords described in --dhcp-range. RFC6106 DNS parameters are included in
the advertisements. By default, the relevant link-local address of the machine running dnsmasq is the advertisements. By default, the relevant link-local address of the machine running dnsmasq is
sent as recursive DNS server. If provided, the DHCPv6 options d ns-server and domain-search are sent as recursive DNS server. If provided, the DHCPv6 options d ns-server and domain-search are
used for the DNS server (RDNSS) and the domain search list (DNSSL) . used for the DNS server (RDNSS) and the domain search list (DNSSL) .
--ra-param=<interface>,[mtu:<integer>|<interface>|off,][high,|low,]<ra-in terval>[,<router lifetime>] --ra-param=<interface>,[mtu:<integer>|<interface>|off,][high,|low,]<ra-in terval>[,<router lifetime>]
Set non-default values for router advertisements sent via an inter face. The priority field for Set non-default values for router advertisements sent via an inter face. The priority field for
the router may be altered from the default of medium with eg --ra -param=eth0,high. The interval the router may be altered from the default of medium with eg --ra -param=eth0,high. The interval
between router advertisements may be set (in seconds) with --ra-pa ram=eth0,60. The lifetime of between router advertisements may be set (in seconds) with --ra-pa ram=eth0,60. The lifetime of
the route may be changed or set to zero, which allows a router to advertise prefixes but not a the route may be changed or set to zero, which allows a router to advertise prefixes but not a
route via itself. --ra-parm=eth0,0,0 (A value of zero for the int route via itself. --ra-param=eth0,0,0 (A value of zero for the
erval means the default value.) interval means the default
All four parameters may be set at once. --ra-param=eth0,mtu:1280, value.) All four parameters may be set at once. --ra-param=eth0,m
low,60,1200 tu:1280,low,60,1200
The interface field may include a wildcard. The interface field may include a wildcard.
The mtu: parameter may be an arbitrary interface name, in wh ich case the MTU value for that The mtu: parameter may be an arbitrary interface name, in wh ich case the MTU value for that
interface is used. This is useful for (eg) advertising the MTU of a WAN interface on the other interface is used. This is useful for (eg) advertising the MTU of a WAN interface on the other
interfaces of a router. interfaces of a router.
--dhcp-reply-delay=[tag:<tag>,]<integer> --dhcp-reply-delay=[tag:<tag>,]<integer>
Delays sending DHCPOFFER and proxydhcp replies for at least t he specified number of seconds. Delays sending DHCPOFFER and PROXYDHCP replies for at least t he specified number of seconds.
This can be used as workaround for bugs in PXE boot firmware that does not function properly when This can be used as workaround for bugs in PXE boot firmware that does not function properly when
receiving an instant reply. This option takes into account the t ime already spent waiting (e.g. receiving an instant reply. This option takes into account the t ime already spent waiting (e.g.
performing ping check) if any. performing ping check) if any.
--enable-tftp[=<interface>[,<interface>]] --enable-tftp[=<interface>[,<interface>]]
Enable the TFTP server function. This is deliberately limited to that needed to net-boot a Enable the TFTP server function. This is deliberately limited to that needed to net-boot a
client. Only reading is allowed; the tsize and blksize extensio ns are supported (tsize is only client. Only reading is allowed; the tsize and blksize extensio ns are supported (tsize is only
supported in octet mode). Without an argument, the TFTP service is provided to the same set of supported in octet mode). Without an argument, the TFTP service is provided to the same set of
interfaces as DHCP service. If the list of interfaces is provided , that defines which interfaces interfaces as DHCP service. If the list of interfaces is provided , that defines which interfaces
receive TFTP service. receive TFTP service.
skipping to change at line 1466 skipping to change at line 1518
Stop the TFTP server from negotiating the "blocksize" option wi th a client. Some buggy clients Stop the TFTP server from negotiating the "blocksize" option wi th a client. Some buggy clients
request this option but then behave badly when it is granted. request this option but then behave badly when it is granted.
--tftp-port-range=<start>,<end> --tftp-port-range=<start>,<end>
A TFTP server listens on a well-known port (69) for connection ini tiation, but it also uses a A TFTP server listens on a well-known port (69) for connection ini tiation, but it also uses a
dynamically-allocated port for each connection. Normally these ar e allocated by the OS, but this dynamically-allocated port for each connection. Normally these ar e allocated by the OS, but this
option specifies a range of ports for use by TFTP transfers. This can be useful when TFTP has to option specifies a range of ports for use by TFTP transfers. This can be useful when TFTP has to
traverse a firewall. The start of the range cannot be lower than 1025 unless dnsmasq is running traverse a firewall. The start of the range cannot be lower than 1025 unless dnsmasq is running
as root. The number of concurrent TFTP connections is limited by t he size of the port range. as root. The number of concurrent TFTP connections is limited by t he size of the port range.
--tftp-single-port
Run in a mode where the TFTP server uses ONLY the well-known port
(69) for its end of the TFTP
transfer. This allows TFTP to work when there in NAT is the path
between client and server. Note
that this is not strictly compliant with the RFCs specifying the T
FTP protocol: use at your own
risk.
-C, --conf-file=<file> -C, --conf-file=<file>
Specify a different configuration file. The --conf-file option is Specify a configuration file. The presence of this option stops d
also allowed in configuration nsmasq from reading the default
files, to include multiple configuration files. A filename of "-" configuration file (normally /etc/dnsmasq.conf). Multiple files ma
causes dnsmasq to read configu- y be specified by repeating the
ration from stdin. option either on the command line or in configuration files. A fi
lename of "-" causes dnsmasq to
read configuration from stdin.
-7, --conf-dir=<directory>[,<file-extension>......], -7, --conf-dir=<directory>[,<file-extension>......],
Read all the files in the given directory as configuration files. If extension(s) are given, any Read all the files in the given directory as configuration files. If extension(s) are given, any
files which end in those extensions are skipped. Any files whose names end in ~ or start with . files which end in those extensions are skipped. Any files whose names end in ~ or start with .
or start and end with # are always skipped. If the extension start s with * then only files which or start and end with # are always skipped. If the extension start s with * then only files which
have that extension are loaded. So --conf-dir=/path/to/dir,*.conf loads all files with the suffix have that extension are loaded. So --conf-dir=/path/to/dir,*.conf loads all files with the suffix
.conf in /path/to/dir. This flag may be given on the command line or in a configuration file. If .conf in /path/to/dir. This flag may be given on the command line or in a configuration file. If
giving it on the command line, be sure to escape * characters. giving it on the command line, be sure to escape * characters. F
iles are loaded in alphabetical
order of filename.
--servers-file=<file> --servers-file=<file>
A special case of --conf-file which differs in two respects. Fi rstly, only --server and --rev- A special case of --conf-file which differs in two respects. First ly, only --server and --rev-
server are allowed in the configuration file included. Secondly, t he file is re-read and the con- server are allowed in the configuration file included. Secondly, t he file is re-read and the con-
figuration therein is updated when dnsmasq receives SIGHUP. figuration therein is updated when dnsmasq receives SIGHUP.
CONFIG FILE CONFIG FILE
At startup, dnsmasq reads /etc/dnsmasq.conf, if it exists. (On FreeBSD, At startup, dnsmasq reads /etc/dnsmasq.conf, if it exists. (On FreeBSD, t
the file is /usr/local/etc/dns- he file is /usr/local/etc/dns-
masq.conf ) (but see the --conf-file and --conf-dir options.) The format masq.conf ) (but see the --conf-file and --conf-dir options.) The form
of this file consists of one at of this file consists of one
option per line, exactly as the long options detailed in the OPTIONS option per line, exactly as the long options detailed in the OPTIONS sect
section but without the leading ion but without the leading
"--". Lines starting with # are comments and ignored. For options which m "--". Lines starting with # are comments and ignored. For options which
ay only be specified once, the may only be specified once, the
configuration file overrides the command line. Quoting is allowed in configuration file overrides the command line. Quoting is allowed in a c
a config file: between " quotes onfig file: between " quotes
the special meanings of ,:. and # are removed and the following escapes a the special meanings of ,:. and # are removed and the following escapes
re allowed: \\ \" \t \e \b \r are allowed: \\ \" \t \e \b \r
and \n. The later corresponding to tab, escape, backspace, return and new line. and \n. The later corresponding to tab, escape, backspace, return and new line.
NOTES NOTES
When it receives a SIGHUP, dnsmasq clears its cache and then re-loads /et c/hosts and /etc/ethers and any When it receives a SIGHUP, dnsmasq clears its cache and then re-loads /et c/hosts and /etc/ethers and any
file given by --dhcp-hostsfile, --dhcp-hostsdir, --dhcp-optsfile, -- file given by --dhcp-hostsfile, --dhcp-hostsdir, --dhcp-optsfile, -
dhcp-optsdir, --addn-hosts or -dhcp-optsdir, --addn-hosts or
--hostsdir. The dhcp lease change script is called for all existing D --hostsdir. The DHCP lease change script is called for all existing DHCP
HCP leases. If --no-poll is set leases. If --no-poll is set
SIGHUP also re-reads /etc/resolv.conf. SIGHUP does NOT re-read the confi guration file. SIGHUP also re-reads /etc/resolv.conf. SIGHUP does NOT re-read the confi guration file.
When it receives a SIGUSR1, dnsmasq writes statistics to the system log. When it receives a SIGUSR1, dnsmasq writes statistics to the system log
It writes the cache size, the . It writes the cache size, the
number of names which have had to removed from the cache before they ex number of names which have had to removed from the cache before they expi
pired in order to make room for red in order to make room for
new names and the total number of names that have been inserted into the cache. The number of cache hits new names and the total number of names that have been inserted into the cache. The number of cache hits
and misses and the number of authoritative queries answered are also giv en. For each upstream server it and misses and the number of authoritative queries answered are also give n. For each upstream server it
gives the number of queries sent, and the number which resulted in an err or. In --no-daemon mode or when gives the number of queries sent, and the number which resulted in an err or. In --no-daemon mode or when
full logging is enabled (--log-queries), a complete dump of the contents of the cache is made. full logging is enabled (--log-queries), a complete dump of the contents of the cache is made.
The cache statistics are also available in the DNS as answers to queries of class CHAOS and type TXT in The cache statistics are also available in the DNS as answers to queries of class CHAOS and type TXT in
domain bind. The domain names are cachesize.bind, insertions.bind, evictions.bind, misses.bind, domain bind. The domain names are cachesize.bind, insertions.bind, evictions.bind, misses.bind,
hits.bind, auth.bind and servers.bind. An example command to query this, using the dig utility would be hits.bind, auth.bind and servers.bind. An example command to query this, using the dig utility would be
dig +short chaos txt cachesize.bind dig +short chaos txt cachesize.bind
When it receives SIGUSR2 and it is logging direct to a file (see --log-fa cility ) dnsmasq will close and When it receives SIGUSR2 and it is logging direct to a file (see --log-fa cility ) dnsmasq will close and
reopen the log file. Note that during this operation, dnsmasq will not be running as root. When it first reopen the log file. Note that during this operation, dnsmasq will not be running as root. When it first
creates the logfile dnsmasq changes the ownership of the file to th creates the logfile dnsmasq changes the ownership of the file to the non
e non-root user it will run as. -root user it will run as.
Logrotate should be configured to create a new log file with the ownershi Logrotate should be configured to create a new log file with the owner
p which matches the existing ship which matches the existing
one before sending SIGUSR2. If TCP DNS queries are in progress, the one before sending SIGUSR2. If TCP DNS queries are in progress, the old
old logfile will remain open in logfile will remain open in
child processes which are handling TCP queries and may continue to be wri child processes which are handling TCP queries and may continue to be w
tten. There is a limit of 150 ritten. There is a limit of 150
seconds, after which all existing TCP processes will have expired: for seconds, after which all existing TCP processes will have expired: for th
this reason, it is not wise to is reason, it is not wise to
configure logfile compression for logfiles which have just been rotated. configure logfile compression for logfiles which have just been rotated
Using logrotate, the required . Using logrotate, the required
options are create and delaycompress. options are create and delaycompress.
Dnsmasq is a DNS query forwarder: it is not capable of recursively answe Dnsmasq is a DNS query forwarder: it is not capable of recursively answer
ring arbitrary queries starting ing arbitrary queries starting
from the root servers but forwards such queries to a fully recursive upst from the root servers but forwards such queries to a fully recursive ups
ream DNS server which is typi- tream DNS server which is typi-
cally provided by an ISP. By default, dnsmasq reads /etc/resolv.conf to d iscover the IP addresses of the cally provided by an ISP. By default, dnsmasq reads /etc/resolv.conf to d iscover the IP addresses of the
upstream nameservers it should use, since the information is typically st ored there. Unless --no-poll is upstream nameservers it should use, since the information is typically st ored there. Unless --no-poll is
used, dnsmasq checks the modification time of /etc/resolv.conf (or equiv used, dnsmasq checks the modification time of /etc/resolv.conf (or equiva
alent if --resolv-file is used) lent if --resolv-file is used)
and re-reads it if it changes. This allows the DNS servers to be set dyna and re-reads it if it changes. This allows the DNS servers to be set d
mically by PPP or DHCP since ynamically by PPP or DHCP since
both protocols provide the information. Absence of /etc/resolv.conf i both protocols provide the information. Absence of /etc/resolv.conf is n
s not an error since it may not ot an error since it may not
have been created before a PPP connection exists. Dnsmasq simply keeps ch ecking in case /etc/resolv.conf have been created before a PPP connection exists. Dnsmasq simply keeps ch ecking in case /etc/resolv.conf
is created at any time. Dnsmasq can be told to parse more than one resolv .conf file. This is useful on a is created at any time. Dnsmasq can be told to parse more than one resolv .conf file. This is useful on a
laptop, where both PPP and DHCP may be used: dnsmasq can be set to poll laptop, where both PPP and DHCP may be used: dnsmasq can be set to pol
both /etc/ppp/resolv.conf and l both /etc/ppp/resolv.conf and
/etc/dhcpc/resolv.conf and will use the contents of whichever changed l /etc/dhcpc/resolv.conf and will use the contents of whichever changed las
ast, giving automatic switching t, giving automatic switching
between DNS servers. between DNS servers.
Upstream servers may also be specified on the command line or in the conf Upstream servers may also be specified on the command line or in the c
iguration file. These server onfiguration file. These server
specifications optionally take a domain name which tells dnsmasq to use specifications optionally take a domain name which tells dnsmasq to use t
that server only to find names hat server only to find names
in that particular domain. in that particular domain.
In order to configure dnsmasq to act as cache for the host on which it In order to configure dnsmasq to act as cache for the host on which
is running, put "nameserver it is running, put "nameserver
127.0.0.1" in /etc/resolv.conf to force local processes to send queries 127.0.0.1" in /etc/resolv.conf to force local processes to send queries t
to dnsmasq. Then either specify o dnsmasq. Then either specify
the upstream servers directly to dnsmasq using --server options or put th the upstream servers directly to dnsmasq using --server options or put
eir addresses real in another their addresses real in another
file, say /etc/resolv.dnsmasq and run dnsmasq with the --resolv-file / file, say /etc/resolv.dnsmasq and run dnsmasq with the --resolv-file /et
etc/resolv.dnsmasq option. This c/resolv.dnsmasq option. This
second technique allows for dynamic update of the server addresses by PPP or DHCP. second technique allows for dynamic update of the server addresses by PPP or DHCP.
Addresses in /etc/hosts will "shadow" different addresses for the same na mes in the upstream DNS, so Addresses in /etc/hosts will "shadow" different addresses for the sam e names in the upstream DNS, so
"mycompany.com 1.2.3.4" in /etc/hosts will ensure that queries for "mycom pany.com" always return 1.2.3.4 "mycompany.com 1.2.3.4" in /etc/hosts will ensure that queries for "mycom pany.com" always return 1.2.3.4
even if queries in the upstream DNS would otherwise return a different ad dress. There is one exception even if queries in the upstream DNS would otherwise return a different address. There is one exception
to this: if the upstream DNS contains a CNAME which points to a shadowed name, then looking up the CNAME to this: if the upstream DNS contains a CNAME which points to a shadowed name, then looking up the CNAME
through dnsmasq will result in the unshadowed address associated with the target of the CNAME. To work through dnsmasq will result in the unshadowed address associated with t he target of the CNAME. To work
around this, add the CNAME to /etc/hosts so that the CNAME is shadowed to o. around this, add the CNAME to /etc/hosts so that the CNAME is shadowed to o.
The tag system works as follows: For each DHCP request, dnsmasq collects a set of valid tags from active The tag system works as follows: For each DHCP request, dnsmasq collects a set of valid tags from active
configuration lines which include set:<tag>, including one from the --dhc configuration lines which include set:<tag>, including one from the --
p-range used to allocate the dhcp-range used to allocate the
address, one from any matching --dhcp-host (and "known" or "known-othe address, one from any matching --dhcp-host (and "known" or "known-otherne
rnet" if a --dhcp-host matches) t" if a --dhcp-host matches)
The tag "bootp" is set for BOOTP requests, and a tag whose name is the na The tag "bootp" is set for BOOTP requests, and a tag whose name is the
me of the interface on which name of the interface on which
the request arrived is also set. the request arrived is also set.
Any configuration lines which include one or more tag:<tag> constructs Any configuration lines which include one or more tag:<tag> constructs wi
will only be valid if all that ll only be valid if all that
tags are matched in the set derived above. Typically this is --dhcp-opti tags are matched in the set derived above. Typically this is --dhcp-o
on. --dhcp-option which has ption. --dhcp-option which has
tags will be used in preference to an untagged --dhcp-option, provided tags will be used in preference to an untagged --dhcp-option, provided t
that _all_ the tags match some- hat _all_ the tags match some-
where in the set collected as described above. The prefix '!' on a where in the set collected as described above. The prefix '!'
tag means 'not' so --dhcp- on a tag means 'not' so --dhcp-
option=tag:!purple,3,1.2.3.4 sends the option when the tag purple is no option=tag:!purple,3,1.2.3.4 sends the option when the tag purple is not
t in the set of valid tags. (If in the set of valid tags. (If
using this in a command line rather than a configuration file, be sure to using this in a command line rather than a configuration file, be sur
escape !, which is a shell e to escape !, which is a shell
metacharacter) metacharacter)
When selecting --dhcp-options, a tag from --dhcp-range is second class When selecting --dhcp-options, a tag from --dhcp-range is second class re
relative to other tags, to make lative to other tags, to make
it easy to override options for individual hosts, so --dhcp-range= it easy to override options for individual hosts, so --dhcp-range
set:interface1,...... --dhcp- =set:interface1,...... --dhcp-
host=set:myhost,..... --dhcp-option=tag:interface1,option:nis-d host=set:myhost,..... --dhcp-option=tag:interface1,option:nis-do
omain,"domain1" --dhcp- main,"domain1" --dhcp-
option=tag:myhost,option:nis-domain,"domain2" will set the NIS-domain to domain1 for hosts in the range, option=tag:myhost,option:nis-domain,"domain2" will set the NIS-domain to domain1 for hosts in the range,
but override that to domain2 for a particular host. but override that to domain2 for a particular host.
Note that for --dhcp-range both tag:<tag> and set:<tag> are allowed, to both select the range in use Note that for --dhcp-range both tag:<tag> and set:<tag> are allowed, to b oth select the range in use
based on (eg) --dhcp-host, and to affect the options sent, based on the r ange selected. based on (eg) --dhcp-host, and to affect the options sent, based on the r ange selected.
This system evolved from an earlier, more limited one and for backward co mpatibility "net:" may be used This system evolved from an earlier, more limited one and for backward c ompatibility "net:" may be used
instead of "tag:" and "set:" may be omitted. (Except in --dhcp-host, wher e "net:" may be used instead of instead of "tag:" and "set:" may be omitted. (Except in --dhcp-host, wher e "net:" may be used instead of
"set:".) For the same reason, '#' may be used instead of '!' to indicate NOT. "set:".) For the same reason, '#' may be used instead of '!' to indicate NOT.
The DHCP server in dnsmasq will function as a BOOTP server also, provided that the MAC address and IP The DHCP server in dnsmasq will function as a BOOTP server also, provi ded that the MAC address and IP
address for clients are given, either using --dhcp-host configurations or in /etc/ethers , and a --dhcp- address for clients are given, either using --dhcp-host configurations or in /etc/ethers , and a --dhcp-
range configuration option is present to activate the DHCP server on a particular network. (Setting range configuration option is present to activate the DHCP server on a particular network. (Setting
--bootp-dynamic removes the need for static address mappings.) The filena me parameter in a BOOTP request --bootp-dynamic removes the need for static address mappings.) The filena me parameter in a BOOTP request
is used as a tag, as is the tag "bootp", allowing some control over the o ptions returned to different is used as a tag, as is the tag "bootp", allowing some control over th e options returned to different
classes of hosts. classes of hosts.
AUTHORITATIVE CONFIGURATION AUTHORITATIVE CONFIGURATION
Configuring dnsmasq to act as an authoritative DNS server is complicat Configuring dnsmasq to act as an authoritative DNS server is complicated
ed by the fact that it involves by the fact that it involves
configuration of external DNS servers to provide delegation. We will walk configuration of external DNS servers to provide delegation. We will
through three scenarios of walk through three scenarios of
increasing complexity. Prerequisites for all of these scenarios are a glo bally accessible IP address, an increasing complexity. Prerequisites for all of these scenarios are a glo bally accessible IP address, an
A or AAAA record pointing to that address, and an external DNS server cap able of doing delegation of the A or AAAA record pointing to that address, and an external DNS server cap able of doing delegation of the
zone in question. For the first part of this explanation, we will call zone in question. For the first part of this explanation, we will call th
the A (or AAAA) record for the e A (or AAAA) record for the
globally accessible address server.example.com, and the zone for wh globally accessible address server.example.com, and the zone for
ich dnsmasq is authoritative which dnsmasq is authoritative
our.zone.com. our.zone.com.
The simplest configuration consists of two lines of dnsmasq configuration ; something like The simplest configuration consists of two lines of dnsmasq configuration ; something like
--auth-server=server.example.com,eth0 --auth-server=server.example.com,eth0
--auth-zone=our.zone.com,1.2.3.0/24 --auth-zone=our.zone.com,1.2.3.0/24
and two records in the external DNS and two records in the external DNS
server.example.com A 192.0.43.10 server.example.com A 192.0.43.10
our.zone.com NS server.example.com our.zone.com NS server.example.com
eth0 is the external network interface on which dnsmasq is listening , and has (globally accessible) eth0 is the external network interface on which dnsmasq is listening, a nd has (globally accessible)
address 192.0.43.10. address 192.0.43.10.
Note that the external IP address may well be dynamic (ie assigned from a n ISP by DHCP or PPP) If so, Note that the external IP address may well be dynamic (ie assigned fro m an ISP by DHCP or PPP) If so,
the A record must be linked to this dynamic assignment by one of the usua l dynamic-DNS systems. the A record must be linked to this dynamic assignment by one of the usua l dynamic-DNS systems.
A more complex, but practically useful configuration has the address rec A more complex, but practically useful configuration has the address reco
ord for the globally accessible rd for the globally accessible
IP address residing in the authoritative zone which dnsmasq is serving, t IP address residing in the authoritative zone which dnsmasq is serving
ypically at the root. Now we , typically at the root. Now we
have have
--auth-server=our.zone.com,eth0 --auth-server=our.zone.com,eth0
--auth-zone=our.zone.com,1.2.3.0/24 --auth-zone=our.zone.com,1.2.3.0/24
our.zone.com A 1.2.3.4 our.zone.com A 1.2.3.4
our.zone.com NS our.zone.com our.zone.com NS our.zone.com
The A record for our.zone.com has now become a glue record, it solves The A record for our.zone.com has now become a glue record, it solves th
the chicken-and-egg problem of e chicken-and-egg problem of
finding the IP address of the nameserver for our.zone.com when the A reco finding the IP address of the nameserver for our.zone.com when the A r
rd is within that zone. Note ecord is within that zone. Note
that this is the only role of this record: as dnsmasq is now authoritativ e from our.zone.com it too must that this is the only role of this record: as dnsmasq is now authoritativ e from our.zone.com it too must
provide this record. If the external address is static, this can be done with an /etc/hosts entry or provide this record. If the external address is static, this can be d one with an /etc/hosts entry or
--host-record. --host-record.
--auth-server=our.zone.com,eth0 --auth-server=our.zone.com,eth0
--host-record=our.zone.com,1.2.3.4 --host-record=our.zone.com,1.2.3.4
--auth-zone=our.zone.com,1.2.3.0/24 --auth-zone=our.zone.com,1.2.3.0/24
If the external address is dynamic, the address associated with our.zo ne.com must be derived from the If the external address is dynamic, the address associated with our.zone. com must be derived from the
address of the relevant interface. This is done using --interface-name So mething like: address of the relevant interface. This is done using --interface-name So mething like:
--auth-server=our.zone.com,eth0 --auth-server=our.zone.com,eth0
--interface-name=our.zone.com,eth0 --interface-name=our.zone.com,eth0
--auth-zone=our.zone.com,1.2.3.0/24,eth0 --auth-zone=our.zone.com,1.2.3.0/24,eth0
(The "eth0" argument in --auth-zone adds the subnet containing eth0's dyn amic address to the zone, so (The "eth0" argument in --auth-zone adds the subnet containing eth0's dynamic address to the zone, so
that the --interface-name returns the address in outside queries.) that the --interface-name returns the address in outside queries.)
Our final configuration builds on that above, but also adds a secondary Our final configuration builds on that above, but also adds a secondary D
DNS server. This is another DNS NS server. This is another DNS
server which learns the DNS data for the zone by doing zones transfer, an server which learns the DNS data for the zone by doing zones transfer,
d acts as a backup should the and acts as a backup should the
primary server become inaccessible. The configuration of the secondary i primary server become inaccessible. The configuration of the secondary is
s beyond the scope of this man- beyond the scope of this man-
page, but the extra configuration of dnsmasq is simple: page, but the extra configuration of dnsmasq is simple:
--auth-sec-servers=secondary.myisp.com --auth-sec-servers=secondary.myisp.com
and and
our.zone.com NS secondary.myisp.com our.zone.com NS secondary.myisp.com
Adding auth-sec-servers enables zone transfer in dnsmasq, to allow the s econdary to collect the DNS Adding auth-sec-servers enables zone transfer in dnsmasq, to allow t he secondary to collect the DNS
data. If you wish to restrict this data to particular hosts then data. If you wish to restrict this data to particular hosts then
--auth-peer=<IP address of secondary> --auth-peer=<IP address of secondary>
will do so. will do so.
Dnsmasq acts as an authoritative server for in-addr.arpa and ip6.arpa d Dnsmasq acts as an authoritative server for in-addr.arpa and ip6.arpa do
omains associated with the sub- mains associated with the sub-
nets given in --auth-zone declarations, so reverse (address to name) look nets given in --auth-zone declarations, so reverse (address to name) l
ups can be simply configured ookups can be simply configured
with a suitable NS record, for instance in this example, where we allow 1 .2.3.0/24 addresses. with a suitable NS record, for instance in this example, where we allow 1 .2.3.0/24 addresses.
3.2.1.in-addr.arpa NS our.zone.com 3.2.1.in-addr.arpa NS our.zone.com
Note that at present, reverse (in-addr.arpa and ip6.arpa) zones are not available in zone transfers, so Note that at present, reverse (in-addr.arpa and ip6.arpa) zones are not a vailable in zone transfers, so
there is no point arranging secondary servers for reverse lookups. there is no point arranging secondary servers for reverse lookups.
When dnsmasq is configured to act as an authoritative server, the followi ng data is used to populate the When dnsmasq is configured to act as an authoritative server, the followi ng data is used to populate the
authoritative zone. authoritative zone.
--mx-host, --srv-host, --dns-rr, --txt-record, --naptr-record, --caa-reco rd, as long as the record names --mx-host, --srv-host, --dns-rr, --txt-record, --naptr-record, --caa-reco rd, as long as the record names
are in the authoritative domain. are in the authoritative domain.
--cname as long as the record name is in the authoritative domain. If --cname as long as the record name is in the authoritative domain
the target of the CNAME is . If the target of the CNAME is
unqualified, then it is qualified with the authoritative zone name. CN unqualified, then it is qualified with the authoritative zone name. CNAM
AME used in this way (only) may E used in this way (only) may
be wildcards, as in be wildcards, as in
--cname=*.example.com,default.example.com --cname=*.example.com,default.example.com
IPv4 and IPv6 addresses from /etc/hosts (and --addn-hosts ) and --host-re cord and --interface-name pro- IPv4 and IPv6 addresses from /etc/hosts (and --addn-hosts ) and --host-r ecord and --interface-name pro-
vided the address falls into one of the subnets specified in the --auth-z one. vided the address falls into one of the subnets specified in the --auth-z one.
Addresses of DHCP leases, provided the address falls into one of the s Addresses of DHCP leases, provided the address falls into one of the subn
ubnets specified in the --auth- ets specified in the --auth-
zone. (If constructed DHCP ranges are is use, which depend on the addres zone. (If constructed DHCP ranges are is use, which depend on the add
s dynamically assigned to an ress dynamically assigned to an
interface, then the form of --auth-zone which defines subnets by the interface, then the form of --auth-zone which defines subnets by the dyna
dynamic address of an interface mic address of an interface
should be used to ensure this condition is met.) should be used to ensure this condition is met.)
In the default mode, where a DHCP lease has an unqualified name, and pos sibly a qualified name con- In the default mode, where a DHCP lease has an unqualified name, and possibly a qualified name con-
structed using --domain then the name in the authoritative zone is constr ucted from the unqualified name structed using --domain then the name in the authoritative zone is constr ucted from the unqualified name
and the zone's domain. This may or may not equal that specified by --doma in. If --dhcp-fqdn is set, and the zone's domain. This may or may not equal that specified by -- domain. If --dhcp-fqdn is set,
then the fully qualified names associated with DHCP leases are used, and must match the zone's domain. then the fully qualified names associated with DHCP leases are used, and must match the zone's domain.
EXIT CODES EXIT CODES
0 - Dnsmasq successfully forked into the background, or terminated n ormally if backgrounding is not 0 - Dnsmasq successfully forked into the background, or terminated norma lly if backgrounding is not
enabled. enabled.
1 - A problem with configuration was detected. 1 - A problem with configuration was detected.
2 - A problem with network access occurred (address in use, attempt to us e privileged ports without per- 2 - A problem with network access occurred (address in use, attempt to us e privileged ports without per-
mission). mission).
3 - A problem occurred with a filesystem operation (missing file/director y, permissions). 3 - A problem occurred with a filesystem operation (missing file/director y, permissions).
4 - Memory allocation failure. 4 - Memory allocation failure.
5 - Other miscellaneous problem. 5 - Other miscellaneous problem.
11 or greater - a non zero return code was received from the lease-scrip t process "init" call. The exit 11 or greater - a non zero return code was received from the lease-script process "init" call. The exit
code from dnsmasq is the script's exit code with 10 added. code from dnsmasq is the script's exit code with 10 added.
LIMITS LIMITS
The default values for resource limits in dnsmasq are generally conservat ive, and appropriate for embed- The default values for resource limits in dnsmasq are generally conservat ive, and appropriate for embed-
ded router type devices with slow processors and limited memory. On more capable hardware, it is possi- ded router type devices with slow processors and limited memory. On more capable hardware, it is possi-
ble to increase the limits, and handle many more clients. The following a pplies to dnsmasq-2.37: earlier ble to increase the limits, and handle many more clients. The following a pplies to dnsmasq-2.37: earlier
versions did not scale as well. versions did not scale as well.
Dnsmasq is capable of handling DNS and DHCP for at least a thousand clien ts. The DHCP lease times should Dnsmasq is capable of handling DNS and DHCP for at least a thousand clien ts. The DHCP lease times should
not be very short (less than one hour). The value of --dns-forward-max ca not be very short (less than one hour). The value of --dns-forward-max
n be increased: start with it can be increased: start with it
equal to the number of clients and increase if DNS seems slow. Note that equal to the number of clients and increase if DNS seems slow. Note that
DNS performance depends too on DNS performance depends too on
the performance of the upstream nameservers. The size of the DNS cache ma the performance of the upstream nameservers. The size of the DNS cache m
y be increased: the hard limit ay be increased: the hard limit
is 10000 names and the default (150) is very low. Sending SIGUSR1 to d is 10000 names and the default (150) is very low. Sending SIGUSR1 to dnsm
nsmasq makes it log information asq makes it log information
which is useful for tuning the cache size. See the NOTES section for deta ils. which is useful for tuning the cache size. See the NOTES section for deta ils.
The built-in TFTP server is capable of many simultaneous file transfers: The built-in TFTP server is capable of many simultaneous file transfers
the absolute limit is related : the absolute limit is related
to the number of file-handles allowed to a process and the ability of t to the number of file-handles allowed to a process and the ability of the
he select() system call to cope select() system call to cope
with large numbers of file handles. If the limit is set too high using -- tftp-max it will be scaled down with large numbers of file handles. If the limit is set too high using -- tftp-max it will be scaled down
and the actual limit logged at start-up. Note that more transfers are possible when the same file is and the actual limit logged at start-up. Note that more transfers are pos sible when the same file is
being sent than when each transfer sends a different file. being sent than when each transfer sends a different file.
It is possible to use dnsmasq to block Web advertising by using a list of known banner-ad servers, all It is possible to use dnsmasq to block Web advertising by using a list of known banner-ad servers, all
resolving to 127.0.0.1 or 0.0.0.0, in /etc/hosts or an additional hosts f ile. The list can be very long, resolving to 127.0.0.1 or 0.0.0.0, in /etc/hosts or an additional hosts f ile. The list can be very long,
dnsmasq has been tested successfully with one million names. That size fi le needs a 1GHz processor and dnsmasq has been tested successfully with one million names. That size file needs a 1GHz processor and
about 60Mb of RAM. about 60Mb of RAM.
INTERNATIONALISATION INTERNATIONALISATION
Dnsmasq can be compiled to support internationalisation. To do this, Dnsmasq can be compiled to support internationalisation. To do this, the
the make targets "all-i18n" and make targets "all-i18n" and
"install-i18n" should be used instead of the standard targets "all" and " "install-i18n" should be used instead of the standard targets "all" and
install". When internationali- "install". When internationali-
sation is compiled in, dnsmasq will produce log messages in the local la sation is compiled in, dnsmasq will produce log messages in the local lan
nguage and support internation- guage and support internation-
alised domain names (IDN). Domain names in /etc/hosts, /etc/ethers and /e alised domain names (IDN). Domain names in /etc/hosts, /etc/ethers and
tc/dnsmasq.conf which contain /etc/dnsmasq.conf which contain
non-ASCII characters will be translated to the DNS-internal punycode re non-ASCII characters will be translated to the DNS-internal punycode repr
presentation. Note that dnsmasq esentation. Note that dnsmasq
determines both the language for messages and the assumed charset for con determines both the language for messages and the assumed charset for co
figuration files from the LANG nfiguration files from the LANG
environment variable. This should be set to the system default value by environment variable. This should be set to the system default value by t
the script which is responsible he script which is responsible
for starting dnsmasq. When editing the configuration files, be careful to for starting dnsmasq. When editing the configuration files, be careful
do so using only the system- to do so using only the system-
default locale and not user-specific one, since dnsmasq has no direct wa default locale and not user-specific one, since dnsmasq has no direct way
y of determining the charset in of determining the charset in
use, and must assume that it is the system default. use, and must assume that it is the system default.
FILES FILES
/etc/dnsmasq.conf /etc/dnsmasq.conf
/usr/local/etc/dnsmasq.conf /usr/local/etc/dnsmasq.conf
/etc/resolv.conf /var/run/dnsmasq/resolv.conf /etc/ppp/resolv.conf /etc/d hcpc/resolv.conf /etc/resolv.conf /var/run/dnsmasq/resolv.conf /etc/ppp/resolv.conf /etc/d hcpc/resolv.conf
/etc/hosts /etc/hosts
skipping to change at line 1770 skipping to change at line 1830
/var/db/dnsmasq.leases /var/db/dnsmasq.leases
/var/run/dnsmasq.pid /var/run/dnsmasq.pid
SEE ALSO SEE ALSO
hosts(5), resolver(5) hosts(5), resolver(5)
AUTHOR AUTHOR
This manual page was written by Simon Kelley <simon@thekelleys.org.uk>. This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.
DNSMASQ(8) 2020-04-05 DNSMASQ(8)
 End of changes. 204 change blocks. 
810 lines changed or deleted 904 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)