1DNSMASQ(8) System Manager's Manual DNSMASQ(8)
2
6 dnsmasq - A lightweight DHCP and caching DNS server.
7
9 dnsmasq [OPTION]...
10
12 dnsmasq is a lightweight DNS, TFTP, PXE, router advertisement and DHCP
13 server. It is intended to provide coupled DNS and DHCP service to a
14 LAN.
15 Dnsmasq accepts DNS queries and either answers them from a small, lo‐
17 cal, cache or forwards them to a real, recursive, DNS server. It loads
18 the contents of /etc/hosts so that local hostnames which do not appear
19 in the global DNS can be resolved and also answers DNS queries for DHCP
20 configured hosts. It can also act as the authoritative DNS server for
21 one or more domains, allowing local names to appear in the global DNS.
22 It can be configured to do DNSSEC validation.
23 The dnsmasq DHCP server supports static address assignments and multi‐
25 ple networks. It automatically sends a sensible default set of DHCP op‐
26 tions, and can be configured to send any desired set of DHCP options,
27 including vendor-encapsulated options. It includes a secure, read-only,
28 TFTP server to allow net/PXE boot of DHCP hosts and also supports
29 BOOTP. The PXE support is full featured, and includes a proxy mode
30 which supplies PXE information to clients whilst DHCP address alloca‐
31 tion is done by another server.
32 The dnsmasq DHCPv6 server provides the same set of features as the
34 DHCPv4 server, and in addition, it includes router advertisements and a
35 neat feature which allows naming for clients which use DHCPv4 and
36 stateless autoconfiguration only for IPv6 configuration. There is sup‐
37 port for doing address allocation (both DHCPv6 and RA) from subnets
38 which are dynamically delegated via DHCPv6 prefix delegation.
39 Dnsmasq is coded with small embedded systems in mind. It aims for the
41 smallest possible memory footprint compatible with the supported func‐
42 tions, and allows unneeded functions to be omitted from the compiled
43 binary.
44
46 Note that in general missing parameters are allowed and switch off
47 functions, for instance "--pid-file" disables writing a PID file. On
48 BSD, unless the GNU getopt library is linked, the long form of the op‐
49 tions does not work on the command line; it is still recognised in the
50 configuration file.
51 --test Read and syntax check configuration file(s). Exit with code 0 if
53 all is OK, or a non-zero code otherwise. Do not start up dns‐
54 masq.
55 -w, --help
57 Display all command-line options. --help dhcp will display
58 known DHCPv4 configuration options, and --help dhcp6 will dis‐
59 play DHCPv6 options.
60 -h, --no-hosts
62 Don't read the hostnames in /etc/hosts.
63 -H, --addn-hosts=<file>
65 Additional hosts file. Read the specified file as well as
66 /etc/hosts. If --no-hosts is given, read only the specified
67 file. This option may be repeated for more than one additional
68 hosts file. If a directory is given, then read all the files
69 contained in that directory in alphabetical order.
70 --hostsdir=<path>
72 Read all the hosts files contained in the directory. New or
73 changed files are read automatically. See --dhcp-hostsdir for
74 details.
75 -E, --expand-hosts
77 Add the domain to simple names (without a period) in /etc/hosts
78 in the same way as for DHCP-derived names. Note that this does
79 not apply to domain names in cnames, PTR records, TXT records
80 etc.
81 -T, --local-ttl=<time>
83 When replying with information from /etc/hosts or configuration
84 or the DHCP leases file dnsmasq by default sets the time-to-live
85 field to zero, meaning that the requester should not itself
86 cache the information. This is the correct thing to do in almost
87 all situations. This option allows a time-to-live (in seconds)
88 to be given for these replies. This will reduce the load on the
89 server at the expense of clients using stale data under some
90 circumstances.
91 --dhcp-ttl=<time>
93 As for --local-ttl, but affects only replies with information
94 from DHCP leases. If both are given, --dhcp-ttl applies for DHCP
95 information, and --local-ttl for others. Setting this to zero
96 eliminates the effect of --local-ttl for DHCP.
97 --neg-ttl=<time>
99 Negative replies from upstream servers normally contain time-to-
100 live information in SOA records which dnsmasq uses for caching.
101 If the replies from upstream servers omit this information, dns‐
102 masq does not cache the reply. This option gives a default value
103 for time-to-live (in seconds) which dnsmasq uses to cache nega‐
104 tive replies even in the absence of an SOA record.
105 --max-ttl=<time>
107 Set a maximum TTL value that will be handed out to clients. The
108 specified maximum TTL will be given to clients instead of the
109 true TTL value if it is lower. The true TTL value is however
110 kept in the cache to avoid flooding the upstream DNS servers.
111 --max-cache-ttl=<time>
113 Set a maximum TTL value for entries in the cache.
114 --min-cache-ttl=<time>
116 Extend short TTL values to the time given when caching them.
117 Note that artificially extending TTL values is in general a bad
118 idea, do not do it unless you have a good reason, and understand
119 what you are doing. Dnsmasq limits the value of this option to
120 one hour, unless recompiled.
121 --auth-ttl=<time>
123 Set the TTL value returned in answers from the authoritative
124 server.
125 -k, --keep-in-foreground
127 Do not go into the background at startup but otherwise run as
128 normal. This is intended for use when dnsmasq is run under dae‐
129 montools or launchd.
130 -d, --no-daemon
132 Debug mode: don't fork to the background, don't write a pid
133 file, don't change user id, generate a complete cache dump on
134 receipt on SIGUSR1, log to stderr as well as syslog, don't fork
135 new processes to handle TCP queries. Note that this option is
136 for use in debugging only, to stop dnsmasq daemonising in pro‐
137 duction, use --keep-in-foreground.
138 -q, --log-queries
140 Log the results of DNS queries handled by dnsmasq. Enable a full
141 cache dump on receipt of SIGUSR1. If the argument "extra" is
142 supplied, ie --log-queries=extra then the log has extra informa‐
143 tion at the start of each line. This consists of a serial num‐
144 ber which ties together the log lines associated with an indi‐
145 vidual query, and the IP address of the requestor.
146 -8, --log-facility=<facility>
148 Set the facility to which dnsmasq will send syslog entries, this
149 defaults to DAEMON, and to LOCAL0 when debug mode is in opera‐
150 tion. If the facility given contains at least one '/' character,
151 it is taken to be a filename, and dnsmasq logs to the given
152 file, instead of syslog. If the facility is '-' then dnsmasq
153 logs to stderr. (Errors whilst reading configuration will still
154 go to syslog, but all output from a successful startup, and all
155 output whilst running, will go exclusively to the file.) When
156 logging to a file, dnsmasq will close and reopen the file when
157 it receives SIGUSR2. This allows the log file to be rotated
158 without stopping dnsmasq.
159 --log-debug
161 Enable extra logging intended for debugging rather than informa‐
162 tion.
163 --log-async[=<lines>]
165 Enable asynchronous logging and optionally set the limit on the
166 number of lines which will be queued by dnsmasq when writing to
167 the syslog is slow. Dnsmasq can log asynchronously: this allows
168 it to continue functioning without being blocked by syslog, and
169 allows syslog to use dnsmasq for DNS queries without risking
170 deadlock. If the queue of log-lines becomes full, dnsmasq will
171 log the overflow, and the number of messages lost. The default
172 queue length is 5, a sane value would be 5-25, and a maximum
173 limit of 100 is imposed.
174 -x, --pid-file=<path>
176 Specify an alternate path for dnsmasq to record its process-id
177 in. Normally /var/run/dnsmasq.pid.
178 -u, --user=<username>
180 Specify the userid to which dnsmasq will change after startup.
181 Dnsmasq must normally be started as root, but it will drop root
182 privileges after startup by changing id to another user. Nor‐
183 mally this user is "nobody" but that can be over-ridden with
184 this switch.
185 -g, --group=<groupname>
187 Specify the group which dnsmasq will run as. The default is
188 "dip", if available, to facilitate access to /etc/ppp/re‐
189 solv.conf which is not normally world readable.
190 -v, --version
192 Print the version number.
193 -p, --port=<port>
195 Listen on <port> instead of the standard DNS port (53). Setting
196 this to zero completely disables DNS function, leaving only DHCP
197 and/or TFTP.
198 -P, --edns-packet-max=<size>
200 Specify the largest EDNS.0 UDP packet which is supported by the
201 DNS forwarder. Defaults to 4096, which is the RFC5625-recom‐
202 mended size.
203 -Q, --query-port=<query_port>
205 Send outbound DNS queries from, and listen for their replies on,
206 the specific UDP port <query_port> instead of using random
207 ports. NOTE that using this option will make dnsmasq less secure
208 against DNS spoofing attacks but it may be faster and use less
209 resources. Setting this option to zero makes dnsmasq use a sin‐
210 gle port allocated to it by the OS: this was the default behav‐
211 iour in versions prior to 2.43.
212 --min-port=<port>
214 Do not use ports less than that given as source for outbound DNS
215 queries. Dnsmasq picks random ports as source for outbound
216 queries: when this option is given, the ports used will always
217 be larger than that specified. Useful for systems behind fire‐
218 walls. If not specified, defaults to 1024.
219 --max-port=<port>
221 Use ports lower than that given as source for outbound DNS
222 queries. Dnsmasq picks random ports as source for outbound
223 queries: when this option is given, the ports used will always
224 be lower than that specified. Useful for systems behind fire‐
225 walls.
226 -i, --interface=<interface name>
228 Listen only on the specified interface(s). Dnsmasq automatically
229 adds the loopback (local) interface to the list of interfaces to
230 use when the --interface option is used. If no --interface or
231 --listen-address options are given dnsmasq listens on all avail‐
232 able interfaces except any given in --except-interface options.
233 On Linux, when --bind-interfaces or --bind-dynamic are in ef‐
234 fect, IP alias interface labels (eg "eth1:0") are checked,
235 rather than interface names. In the degenerate case when an in‐
236 terface has one address, this amounts to the same thing but when
237 an interface has multiple addresses it allows control over which
238 of those addresses are accepted. The same effect is achievable
239 in default mode by using --listen-address. A simple wildcard,
240 consisting of a trailing '*', can be used in --interface and
241 --except-interface options.
242 -I, --except-interface=<interface name>
244 Do not listen on the specified interface. Note that the order of
245 --listen-address --interface and --except-interface options does
246 not matter and that --except-interface options always override
247 the others. The comments about interface labels for --listen-ad‐
248 dress apply here.
249 --auth-server=<domain>,[<interface>|<ip-address>...]
251 Enable DNS authoritative mode for queries arriving at an inter‐
252 face or address. Note that the interface or address need not be
253 mentioned in --interface or --listen-address configuration, in‐
254 deed --auth-server will override these and provide a different
255 DNS service on the specified interface. The <domain> is the
256 "glue record". It should resolve in the global DNS to an A
257 and/or AAAA record which points to the address dnsmasq is lis‐
258 tening on. When an interface is specified, it may be qualified
259 with "/4" or "/6" to specify only the IPv4 or IPv6 addresses as‐
260 sociated with the interface. Since any defined authoritative
261 zones are also available as part of the normal recusive DNS ser‐
262 vice supplied by dnsmasq, it can make sense to have an --auth-
263 server declaration with no interfaces or address, but simply
264 specifying the primary external nameserver.
265 --local-service
267 Accept DNS queries only from hosts whose address is on a local
268 subnet, ie a subnet for which an interface exists on the server.
269 This option only has effect if there are no --interface, --ex‐
270 cept-interface, --listen-address or --auth-server options. It is
271 intended to be set as a default on installation, to allow uncon‐
272 figured installations to be useful but also safe from being used
273 for DNS amplification attacks.
274 -2, --no-dhcp-interface=<interface name>
276 Do not provide DHCP or TFTP on the specified interface, but do
277 provide DNS service.
278 -a, --listen-address=<ipaddr>
280 Listen on the given IP address(es). Both --interface and --lis‐
281 ten-address options may be given, in which case the set of both
282 interfaces and addresses is used. Note that if no --interface
283 option is given, but --listen-address is, dnsmasq will not auto‐
284 matically listen on the loopback interface. To achieve this, its
285 IP address, 127.0.0.1, must be explicitly given as a --listen-
286 address option.
287 -z, --bind-interfaces
289 On systems which support it, dnsmasq binds the wildcard address,
290 even when it is listening on only some interfaces. It then dis‐
291 cards requests that it shouldn't reply to. This has the advan‐
292 tage of working even when interfaces come and go and change ad‐
293 dress. This option forces dnsmasq to really bind only the inter‐
294 faces it is listening on. About the only time when this is use‐
295 ful is when running another nameserver (or another instance of
296 dnsmasq) on the same machine. Setting this option also enables
297 multiple instances of dnsmasq which provide DHCP service to run
298 in the same machine.
299 --bind-dynamic
301 Enable a network mode which is a hybrid between --bind-inter‐
302 faces and the default. Dnsmasq binds the address of individual
303 interfaces, allowing multiple dnsmasq instances, but if new in‐
304 terfaces or addresses appear, it automatically listens on those
305 (subject to any access-control configuration). This makes dynam‐
306 ically created interfaces work in the same way as the default.
307 Implementing this option requires non-standard networking APIs
308 and it is only available under Linux. On other platforms it
309 falls-back to --bind-interfaces mode.
310 -y, --localise-queries
312 Return answers to DNS queries from /etc/hosts and --interface-
313 name and --dynamic-host which depend on the interface over which
314 the query was received. If a name has more than one address as‐
315 sociated with it, and at least one of those addresses is on the
316 same subnet as the interface to which the query was sent, then
317 return only the address(es) on that subnet. This allows for a
318 server to have multiple addresses in /etc/hosts corresponding
319 to each of its interfaces, and hosts will get the correct ad‐
320 dress based on which network they are attached to. Currently
321 this facility is limited to IPv4.
322 -b, --bogus-priv
324 Bogus private reverse lookups. All reverse lookups for private
325 IP ranges (ie 192.168.x.x, etc) which are not found in
326 /etc/hosts or the DHCP leases file are answered with "no such
327 domain" rather than being forwarded upstream. The set of pre‐
328 fixes affected is the list given in RFC6303, for IPv4 and IPv6.
329 -V, --alias=[<old-ip>]|[<start-ip>-<end-ip>],<new-ip>[,<mask>]
331 Modify IPv4 addresses returned from upstream nameservers; old-ip
332 is replaced by new-ip. If the optional mask is given then any
333 address which matches the masked old-ip will be re-written. So,
334 for instance --alias=1.2.3.0,6.7.8.0,255.255.255.0 will map
335 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. This is what
336 Cisco PIX routers call "DNS doctoring". If the old IP is given
337 as range, then only addresses in the range, rather than a whole
338 subnet, are re-written. So
339 --alias=192.168.0.10-192.168.0.40,10.0.0.0,255.255.255.0 maps
340 192.168.0.10->192.168.0.40 to 10.0.0.10->10.0.0.40
341 -B, --bogus-nxdomain=<ipaddr>[/prefix]
343 Transform replies which contain the specified address or subnet
344 into "No such domain" replies. IPv4 and IPv6 are supported. This
345 is intended to counteract a devious move made by Verisign in
346 September 2003 when they started returning the address of an ad‐
347 vertising web page in response to queries for unregistered
348 names, instead of the correct NXDOMAIN response. This option
349 tells dnsmasq to fake the correct response when it sees this be‐
350 haviour. As at Sept 2003 the IP address being returned by
351 Verisign is 64.94.110.11
352 --ignore-address=<ipaddr>[/prefix]
354 Ignore replies to A or AAAA queries which include the specified
355 address or subnet. No error is generated, dnsmasq simply con‐
356 tinues to listen for another reply. This is useful to defeat
357 blocking strategies which rely on quickly supplying a forged an‐
358 swer to a DNS request for certain domain, before the correct an‐
359 swer can arrive.
360 -f, --filterwin2k
362 Later versions of windows make periodic DNS requests which don't
363 get sensible answers from the public DNS and can cause problems
364 by triggering dial-on-demand links. This flag turns on an option
365 to filter such requests. The requests blocked are for records of
366 types SOA and SRV, and type ANY where the requested name has un‐
367 derscores, to catch LDAP requests.
368 -r, --resolv-file=<file>
370 Read the IP addresses of the upstream nameservers from <file>,
371 instead of /etc/resolv.conf. For the format of this file see re‐
372 solv.conf(5). The only lines relevant to dnsmasq are nameserver
373 ones. Dnsmasq can be told to poll more than one resolv.conf
374 file, the first file name specified overrides the default, sub‐
375 sequent ones add to the list. This is only allowed when polling;
376 the file with the currently latest modification time is the one
377 used.
378 -R, --no-resolv
380 Don't read /etc/resolv.conf. Get upstream servers only from the
381 command line or the dnsmasq configuration file.
382 -1, --enable-dbus[=<service-name>]
384 Allow dnsmasq configuration to be updated via DBus method calls.
385 The configuration which can be changed is upstream DNS servers
386 (and corresponding domains) and cache clear. Requires that dns‐
387 masq has been built with DBus support. If the service name is
388 given, dnsmasq provides service at that name, rather than the
389 default which is uk.org.thekelleys.dnsmasq
390 --enable-ubus[=<service-name>]
392 Enable dnsmasq UBus interface. It sends notifications via UBus
393 on DHCPACK and DHCPRELEASE events. Furthermore it offers metrics
394 and allows configuration of Linux connection track mark based
395 filtering. When DNS query filtering based on Linux connection
396 track marks is enabled UBus notifications are generated for each
397 resolved or filtered DNS query. Requires that dnsmasq has been
398 built with UBus support. If the service name is given, dnsmasq
399 provides service at that namespace, rather than the default
400 which is dnsmasq
401 -o, --strict-order
403 By default, dnsmasq will send queries to any of the upstream
404 servers it knows about and tries to favour servers that are
405 known to be up. Setting this flag forces dnsmasq to try each
406 query with each server strictly in the order they appear in
407 /etc/resolv.conf
408 --all-servers
410 By default, when dnsmasq has more than one upstream server
411 available, it will send queries to just one server. Setting this
412 flag forces dnsmasq to send all queries to all available
413 servers. The reply from the server which answers first will be
414 returned to the original requester.
415 --dns-loop-detect
417 Enable code to detect DNS forwarding loops; ie the situation
418 where a query sent to one of the upstream server eventually re‐
419 turns as a new query to the dnsmasq instance. The process works
420 by generating TXT queries of the form <hex>.test and sending
421 them to each upstream server. The hex is a UID which encodes the
422 instance of dnsmasq sending the query and the upstream server to
423 which it was sent. If the query returns to the server which sent
424 it, then the upstream server through which it was sent is dis‐
425 abled and this event is logged. Each time the set of upstream
426 servers changes, the test is re-run on all of them, including
427 ones which were previously disabled.
428 --stop-dns-rebind
430 Reject (and log) addresses from upstream nameservers which are
431 in the private ranges. This blocks an attack where a browser be‐
432 hind a firewall is used to probe machines on the local network.
433 For IPv6, the private range covers the IPv4-mapped addresses in
434 private space plus all link-local (LL) and site-local (ULA) ad‐
435 dresses.
436 --rebind-localhost-ok
438 Exempt 127.0.0.0/8 and ::1 from rebinding checks. This address
439 range is returned by realtime black hole servers, so blocking it
440 may disable these services.
441 --rebind-domain-ok=[<domain>]|[[/<domain>/[<domain>/]
443 Do not detect and block dns-rebind on queries to these domains.
444 The argument may be either a single domain, or multiple domains
445 surrounded by '/', like the --server syntax, eg. --rebind-do‐
446 main-ok=/domain1/domain2/domain3/
447 -n, --no-poll
449 Don't poll /etc/resolv.conf for changes.
450 --clear-on-reload
452 Whenever /etc/resolv.conf is re-read or the upstream servers are
453 set via DBus, clear the DNS cache. This is useful when new
454 nameservers may have different data than that held in cache.
455 -D, --domain-needed
457 Tells dnsmasq to never forward A or AAAA queries for plain
458 names, without dots or domain parts, to upstream nameservers. If
459 the name is not known from /etc/hosts or DHCP then a "not found"
460 answer is returned.
461 -S, --local, --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>]][@<in‐
463 terface>][@<source-ip>[#<port>]]
464 Specify IP address of upstream servers directly. Setting this
465 flag does not suppress reading of /etc/resolv.conf, use --no-re‐
466 solv to do that. If one or more optional domains are given, that
467 server is used only for those domains and they are queried only
468 using the specified server. This is intended for private name‐
469 servers: if you have a nameserver on your network which deals
470 with names of the form xxx.internal.thekelleys.org.uk at
471 192.168.1.1 then giving the flag --server=/internal.thekel‐
472 leys.org.uk/192.168.1.1 will send all queries for internal ma‐
473 chines to that nameserver, everything else will go to the
474 servers in /etc/resolv.conf. DNSSEC validation is turned off for
475 such private nameservers, UNLESS a --trust-anchor is specified
476 for the domain in question. An empty domain specification, //
477 has the special meaning of "unqualified names only" ie names
478 without any dots in them. A non-standard port may be specified
479 as part of the IP address using a # character. More than one
480 --server flag is allowed, with repeated domain or ipaddr parts
481 as required.
482 More specific domains take precedence over less specific do‐
484 mains, so: --server=/google.com/1.2.3.4
485 --server=/www.google.com/2.3.4.5 will send queries for
486 google.com and gmail.google.com to 1.2.3.4, but www.google.com
487 will go to 2.3.4.5
488 Matching of domains is normally done on complete labels, so
490 /google.com/ matches google.com and www.google.com but NOT su‐
491 pergoogle.com. This can be overridden with a * at the start of a
492 pattern only: /*google.com/ will match google.com and
493 www.google.com AND supergoogle.com. The non-wildcard form has
494 priority, so if /google.com/ and /*google.com/ are both speci‐
495 fied then google.com and www.google.com will match /google.com/
496 and /*google.com/ will only match supergoogle.com.
497 For historical reasons, the pattern /.google.com/ is equivalent
499 to /google.com/ if you wish to match any subdomain of google.com
500 but NOT google.com itself, use /*.google.com/
501 The special server address '#' means, "use the standard
503 servers", so --server=/google.com/1.2.3.4
504 --server=/www.google.com/# will send queries for google.com and
505 its subdomains to 1.2.3.4, except www.google.com (and its subdo‐
506 mains) which will be forwarded as usual.
507 Also permitted is a -S flag which gives a domain but no IP ad‐
509 dress; this tells dnsmasq that a domain is local and it may an‐
510 swer queries from /etc/hosts or DHCP but should never forward
511 queries on that domain to any upstream servers. --local is a
512 synonym for --server to make configuration files clearer in this
513 case.
514 IPv6 addresses may include an %interface scope-id, eg
516 fe80::202:a412:4512:7bbf%eth0.
517 The optional string after the @ character tells dnsmasq how to
519 set the source of the queries to this nameserver. It can either
520 be an ip-address, an interface name or both. The ip-address
521 should belong to the machine on which dnsmasq is running, other‐
522 wise this server line will be logged and then ignored. If an in‐
523 terface name is given, then queries to the server will be forced
524 via that interface; if an ip-address is given then the source
525 address of the queries will be set to that address; and if both
526 are given then a combination of ip-address and interface name
527 will be used to steer requests to the server. The query-port
528 flag is ignored for any servers which have a source address
529 specified but the port may be specified directly as part of the
530 source address. Forcing queries to an interface is not imple‐
531 mented on all platforms supported by dnsmasq.
532 --rev-server=<ip-address>/<prefix-len>[,<ipaddr>][#<port>][@<inter‐
534 face>][@<source-ip>[#<port>]]
535 This is functionally the same as --server, but provides some
536 syntactic sugar to make specifying address-to-name queries eas‐
537 ier. For example --rev-server=1.2.3.0/24,192.168.0.1 is exactly
538 equivalent to --server=/3.2.1.in-addr.arpa/192.168.0.1
539 -A, --address=/<domain>[/<domain>...]/[<ipaddr>]
541 Specify an IP address to return for any host in the given do‐
542 mains. Queries in the domains are never forwarded and always
543 replied to with the specified IP address which may be IPv4 or
544 IPv6. To give both IPv4 and IPv6 addresses for a domain, use re‐
545 peated --address flags. To include multiple IP addresses for a
546 single query, use --addn-hosts=<path> instead. Note that
547 /etc/hosts and DHCP leases override this for individual names. A
548 common use of this is to redirect the entire doubleclick.net do‐
549 main to some friendly local web server to avoid banner ads. The
550 domain specification works in the same way as for --server, with
551 the additional facility that /#/ matches any domain. Thus --ad‐
552 dress=/#/1.2.3.4 will always return 1.2.3.4 for any query not
553 answered from /etc/hosts or DHCP and not sent to an upstream
554 nameserver by a more specific --server directive. As for
555 --server, one or more domains with no address returns a no-such-
556 domain answer, so --address=/example.com/ is equivalent to
557 --server=/example.com/ and returns NXDOMAIN for example.com and
558 all its subdomains. An address specified as '#' translates to
559 the NULL address of 0.0.0.0 and its IPv6 equivalent of :: so
560 --address=/example.com/# will return NULL addresses for exam‐
561 ple.com and its subdomains. This is partly syntactic sugar for
562 --address=/example.com/0.0.0.0 and --address=/example.com/:: but
563 is also more efficient than including both as separate configu‐
564 ration lines. Note that NULL addresses normally work in the same
565 way as localhost, so beware that clients looking up these names
566 are likely to end up talking to themselves.
567 --ipset=/<domain>[/<domain>...]/<ipset>[,<ipset>...]
569 Places the resolved IP addresses of queries for one or more do‐
570 mains in the specified Netfilter IP set. If multiple setnames
571 are given, then the addresses are placed in each of them, sub‐
572 ject to the limitations of an IP set (IPv4 addresses cannot be
573 stored in an IPv6 IP set and vice versa). Domains and subdo‐
574 mains are matched in the same way as --address. These IP sets
575 must already exist. See ipset(8) for more details.
576 --connmark-allowlist-enable[=<mask>]
578 Enables filtering of incoming DNS queries with associated Linux
579 connection track marks according to individual allowlists con‐
580 figured via a series of --connmark-allowlist options. Disallowed
581 queries are not forwarded; they are rejected with a REFUSED er‐
582 ror code. DNS queries are only allowed if they do not have an
583 associated Linux connection track mark, or if the queried do‐
584 mains match the configured DNS patterns for the associated Linux
585 connection track mark. If no allowlist is configured for a Linux
586 connection track mark, all DNS queries associated with that mark
587 are rejected. If a mask is specified, Linux connection track
588 marks are first bitwise ANDed with the given mask before being
589 processed.
590 --connmark-allowlist=<connmark>[/<mask>][,<pattern>[/<pattern>...]]
592 Configures the DNS patterns that are allowed in DNS queries as‐
593 sociated with the given Linux connection track mark. If a mask
594 is specified, Linux connection track marks are first bitwise
595 ANDed with the given mask before they are compared to the given
596 connection track mark. Patterns follow the syntax of DNS names,
597 but additionally allow the wildcard character "*" to be used up
598 to twice per label to match 0 or more characters within that la‐
599 bel. Note that the wildcard never matches a dot (e.g., "*.exam‐
600 ple.com" matches "api.example.com" but not "api.us.exam‐
601 ple.com"). Patterns must be fully qualified, i.e., consist of at
602 least two labels. The final label must not be fully numeric, and
603 must not be the "local" pseudo-TLD. A pattern must end with at
604 least two literal (non-wildcard) labels. Instead of a pattern,
605 "*" can be specified to disable allowlist filtering for a given
606 Linux connection track mark entirely.
607 -m, --mx-host=<mx name>[[,<hostname>],<preference>]
609 Return an MX record named <mx name> pointing to the given host‐
610 name (if given), or the host specified in the --mx-target switch
611 or, if that switch is not given, the host on which dnsmasq is
612 running. The default is useful for directing mail from systems
613 on a LAN to a central server. The preference value is optional,
614 and defaults to 1 if not given. More than one MX record may be
615 given for a host.
616 -t, --mx-target=<hostname>
618 Specify the default target for the MX record returned by dns‐
619 masq. See --mx-host. If --mx-target is given, but not --mx-
620 host, then dnsmasq returns a MX record containing the MX target
621 for MX queries on the hostname of the machine on which dnsmasq
622 is running.
623 -e, --selfmx
625 Return an MX record pointing to itself for each local machine.
626 Local machines are those in /etc/hosts or with DHCP leases.
627 -L, --localmx
629 Return an MX record pointing to the host given by --mx-target
630 (or the machine on which dnsmasq is running) for each local ma‐
631 chine. Local machines are those in /etc/hosts or with DHCP
632 leases.
633 -W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<prior‐
635 ity>[,<weight>]]]]
636 Return a SRV DNS record. See RFC2782 for details. If not sup‐
637 plied, the domain defaults to that given by --domain. The de‐
638 fault for the target domain is empty, and the default for port
639 is one and the defaults for weight and priority are zero. Be
640 careful if transposing data from BIND zone files: the port,
641 weight and priority numbers are in a different order. More than
642 one SRV record for a given service/domain is allowed, all that
643 match are returned.
644 --host-record=<name>[,<name>....],[<IPv4-address>],[<IPv6-ad‐
646 dress>][,<TTL>]
647 Add A, AAAA and PTR records to the DNS. This adds one or more
648 names to the DNS with associated IPv4 (A) and IPv6 (AAAA)
649 records. A name may appear in more than one --host-record and
650 therefore be assigned more than one address. Only the first ad‐
651 dress creates a PTR record linking the address to the name. This
652 is the same rule as is used reading hosts-files. --host-record
653 options are considered to be read before host-files, so a name
654 appearing there inhibits PTR-record creation if it appears in
655 hosts-file also. Unlike hosts-files, names are not expanded,
656 even when --expand-hosts is in effect. Short and long names may
657 appear in the same --host-record, eg. --host-record=laptop,lap‐
658 top.thekelleys.org,192.168.0.1,1234::100
659 If the time-to-live is given, it overrides the default, which is
661 zero or the value of --local-ttl. The value is a positive inte‐
662 ger and gives the time-to-live in seconds.
663 --dynamic-host=<name>,[IPv4-address],[IPv6-address],<interface>
665 Add A, AAAA and PTR records to the DNS in the same subnet as the
666 specified interface. The address is derived from the network
667 part of each address associated with the interface, and the host
668 part from the specified address. For example --dynamic-host=ex‐
669 ample.com,0.0.0.8,eth0 will, when eth0 has the address
670 192.168.78.x and netmask 255.255.255.0 give the name example.com
671 an A record for 192.168.78.8. The same principle applies to IPv6
672 addresses. Note that if an interface has more than one address,
673 more than one A or AAAA record will be created. The TTL of the
674 records is always zero, and any changes to interface addresses
675 will be immediately reflected in them.
676 -Y, --txt-record=<name>[[,<text>],<text>]
678 Return a TXT DNS record. The value of TXT record is a set of
679 strings, so any number may be included, delimited by commas;
680 use quotes to put commas into a string. Note that the maximum
681 length of a single string is 255 characters, longer strings are
682 split into 255 character chunks.
683 --ptr-record=<name>[,<target>]
685 Return a PTR DNS record.
686 --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<reg‐
688 exp>[,<replacement>]
689 Return an NAPTR DNS record, as specified in RFC3403.
690 --caa-record=<name>,<flags>,<tag>,<value>
692 Return a CAA DNS record, as specified in RFC6844.
693 --cname=<cname>,[<cname>,]<target>[,<TTL>]
695 Return a CNAME record which indicates that <cname> is really
696 <target>. There is a significant limitation on the target; it
697 must be a DNS record which is known to dnsmasq and NOT a DNS
698 record which comes from an upstream server. The cname must be
699 unique, but it is permissible to have more than one cname point‐
700 ing to the same target. Indeed it's possible to declare multiple
701 cnames to a target in a single line, like so:
702 --cname=cname1,cname2,target
703 If the time-to-live is given, it overrides the default, which is
705 zero or the value of --local-ttl. The value is a positive inte‐
706 ger and gives the time-to-live in seconds.
707 --dns-rr=<name>,<RR-number>,[<hex data>]
709 Return an arbitrary DNS Resource Record. The number is the type
710 of the record (which is always in the C_IN class). The value of
711 the record is given by the hex data, which may be of the form
712 01:23:45 or 01 23 45 or 012345 or any mixture of these.
713 --interface-name=<name>,<interface>[/4|/6]
715 Return DNS records associating the name with the address(es) of
716 the given interface. This flag specifies an A or AAAA record for
717 the given name in the same way as an /etc/hosts line, except
718 that the address is not constant, but taken from the given in‐
719 terface. The interface may be followed by "/4" or "/6" to spec‐
720 ify that only IPv4 or IPv6 addresses of the interface should be
721 used. If the interface is down, not configured or non-existent,
722 an empty record is returned. The matching PTR record is also
723 created, mapping the interface address to the name. More than
724 one name may be associated with an interface address by repeat‐
725 ing the flag; in that case the first instance is used for the
726 reverse address-to-name mapping. Note that a name used in --in‐
727 terface-name may not appear in /etc/hosts.
728 --synth-domain=<domain>,<address range>[,<prefix>[*]]
730 Create artificial A/AAAA and PTR records for an address range.
731 The records either seqential numbers or the address, with peri‐
732 ods (or colons for IPv6) replaced with dashes.
733 An examples should make this clearer. First sequential numbers.
735 --synth-domain=thekelleys.org.uk,192.168.0.50,192.168.0.70,in‐
736 ternal-* results in the name internal-0.thekelleys.org.uk. re‐
737 turning 192.168.0.50, internal-1.thekelleys.org.uk returning
738 192.168.0.51 and so on. (note the *) The same principle applies
739 to IPv6 addresses (where the numbers may be very large). Reverse
740 lookups from address to name behave as expected.
741 Second, --synth-domain=thekelleys.org.uk,192.168.0.0/24,inter‐
743 nal- (no *) will result in a query for inter‐
744 nal-192-168-0-56.thekelleys.org.uk returning 192.168.0.56 and a
745 reverse query vice versa. The same applies to IPv6, but IPv6 ad‐
746 dresses may start with '::' but DNS labels may not start with
747 '-' so in this case if no prefix is configured a zero is added
748 in front of the label. ::1 becomes 0--1.
749 V4 mapped IPv6 addresses, which have a representation like
751 ::ffff:1.2.3.4 are handled specially, and become like
752 0--ffff-1-2-3-4
753 The address range can be of the form <start address>,<end ad‐
755 dress> or <ip address>/<prefix-length> in both forms of the op‐
756 tion. For IPv6 the start and end addresses must fall in the same
757 /64 network, or prefix-length must be greater than or equal to
758 64 except that shorter prefix lengths than 64 are allowed only
759 if non-sequential names are in use.
760 --dumpfile=<path/to/file>
762 Specify the location of a pcap-format file which dnsmasq uses to
763 dump copies of network packets for debugging purposes. If the
764 file exists when dnsmasq starts, it is not deleted; new packets
765 are added to the end.
766 --dumpmask=<mask>
768 Specify which types of packets should be added to the dumpfile.
769 The argument should be the OR of the bitmasks for each type of
770 packet to be dumped: it can be specified in hex by preceding the
771 number with 0x in the normal way. Each time a packet is written
772 to the dumpfile, dnsmasq logs the packet sequence and the mask
773 representing its type. The current types are: 0x0001 - DNS
774 queries from clients 0x0002 DNS replies to clients 0x0004 - DNS
775 queries to upstream 0x0008 - DNS replies from upstream 0x0010 -
776 queries send upstream for DNSSEC validation 0x0020 - replies to
777 queries for DNSSEC validation 0x0040 - replies to client queries
778 which fail DNSSEC validation 0x0080 replies to queries for
779 DNSSEC validation which fail validation.
780 --add-mac[=base64|text]
782 Add the MAC address of the requestor to DNS queries which are
783 forwarded upstream. This may be used to DNS filtering by the up‐
784 stream server. The MAC address can only be added if the re‐
785 questor is on the same subnet as the dnsmasq server. Note that
786 the mechanism used to achieve this (an EDNS0 option) is not yet
787 standardised, so this should be considered experimental. Also
788 note that exposing MAC addresses in this way may have security
789 and privacy implications. The warning about caching given for
790 --add-subnet applies to --add-mac too. An alternative encoding
791 of the MAC, as base64, is enabled by adding the "base64" parame‐
792 ter and a human-readable encoding of hex-and-colons is enabled
793 by added the "text" parameter.
794 --add-cpe-id=<string>
796 Add an arbitrary identifying string to DNS queries which are
797 forwarded upstream.
798 --add-subnet[[=[<IPv4 address>/]<IPv4 prefix length>][,[<IPv6 ad‐
800 dress>/]<IPv6 prefix length>]]
801 Add a subnet address to the DNS queries which are forwarded up‐
802 stream. If an address is specified in the flag, it will be used,
803 otherwise, the address of the requestor will be used. The amount
804 of the address forwarded depends on the prefix length parameter:
805 32 (128 for IPv6) forwards the whole address, zero forwards none
806 of it but still marks the request so that no upstream nameserver
807 will add client address information either. The default is zero
808 for both IPv4 and IPv6. Note that upstream nameservers may be
809 configured to return different results based on this informa‐
810 tion, but the dnsmasq cache does not take account. Caching is
811 therefore disabled for such replies, unless the subnet address
812 being added is constant.
813 For example, --add-subnet=24,96 will add the /24 and /96 subnets
815 of the requestor for IPv4 and IPv6 requestors, respectively.
816 --add-subnet=1.2.3.4/24 will add 1.2.3.0/24 for IPv4 requestors
817 and ::/0 for IPv6 requestors. --add-sub‐
818 net=1.2.3.4/24,1.2.3.4/24 will add 1.2.3.0/24 for both IPv4 and
819 IPv6 requestors.
820 --umbrella[=deviceid:<deviceid>[,orgid:<orgid>]]
822 Embeds the requestor's IP address in DNS queries forwarded up‐
823 stream. If device id or organization id are specified, the in‐
824 formation is included in the forwarded queries and may be able
825 to be used in filtering policies and reporting. The order of the
826 deviceid and orgid attributes is irrelevant, but must be sepa‐
827 rated by a comma.
828 -c, --cache-size=<cachesize>
830 Set the size of dnsmasq's cache. The default is 150 names. Set‐
831 ting the cache size to zero disables caching. Note: huge cache
832 size impacts performance.
833 -N, --no-negcache
835 Disable negative caching. Negative caching allows dnsmasq to re‐
836 member "no such domain" answers from upstream nameservers and
837 answer identical queries without forwarding them again.
838 -0, --dns-forward-max=<queries>
840 Set the maximum number of concurrent DNS queries. The default
841 value is 150, which should be fine for most setups. The only
842 known situation where this needs to be increased is when using
843 web-server log file resolvers, which can generate large numbers
844 of concurrent queries. This parameter actually controls the num‐
845 ber of concurrent queries per server group, where a server group
846 is the set of server(s) associated with a single domain. So if a
847 domain has it's own server via --server=/example.com/1.2.3.4 and
848 1.2.3.4 is not responding, but queries for *.example.com cannot
849 go elsewhere, then other queries will not be affected. On con‐
850 figurations with many such server groups and tight resources,
851 this value may need to be reduced.
852 --dnssec
854 Validate DNS replies and cache DNSSEC data. When forwarding DNS
855 queries, dnsmasq requests the DNSSEC records needed to validate
856 the replies. The replies are validated and the result returned
857 as the Authenticated Data bit in the DNS packet. In addition the
858 DNSSEC records are stored in the cache, making validation by
859 clients more efficient. Note that validation by clients is the
860 most secure DNSSEC mode, but for clients unable to do valida‐
861 tion, use of the AD bit set by dnsmasq is useful, provided that
862 the network between the dnsmasq server and the client is
863 trusted. Dnsmasq must be compiled with HAVE_DNSSEC enabled, and
864 DNSSEC trust anchors provided, see --trust-anchor. Because the
865 DNSSEC validation process uses the cache, it is not permitted to
866 reduce the cache size below the default when DNSSEC is enabled.
867 The nameservers upstream of dnsmasq must be DNSSEC-capable, ie
868 capable of returning DNSSEC records with data. If they are not,
869 then dnsmasq will not be able to determine the trusted status of
870 answers and this means that DNS service will be entirely broken.
871 --trust-anchor=[<class>],<domain>,<key-tag>,<algorithm>,<digest-
873 type>,<digest>
874 Provide DS records to act a trust anchors for DNSSEC validation.
875 Typically these will be the DS record(s) for Key Signing key(s)
876 (KSK) of the root zone, but trust anchors for limited domains
877 are also possible. The current root-zone trust anchors may be
878 downloaded from https://data.iana.org/root-anchors/root-an‐
879 chors.xml
880 --dnssec-check-unsigned[=no]
882 As a default, dnsmasq checks that unsigned DNS replies are le‐
883 gitimate: this entails possible extra queries even for the ma‐
884 jority of DNS zones which are not, at the moment, signed. If
885 --dnssec-check-unsigned=no appears in the configuration, then
886 such replies they are assumed to be valid and passed on (without
887 the "authentic data" bit set, of course). This does not protect
888 against an attacker forging unsigned replies for signed DNS
889 zones, but it is fast.
890 Versions of dnsmasq prior to 2.80 defaulted to not checking un‐
892 signed replies, and used --dnssec-check-unsigned to switch this
893 on. Such configurations will continue to work as before, but
894 those which used the default of no checking will need to be al‐
895 tered to explicitly select no checking. The new default is be‐
896 cause switching off checking for unsigned replies is inherently
897 dangerous. Not only does it open the possiblity of forged
898 replies, but it allows everything to appear to be working even
899 when the upstream namesevers do not support DNSSEC, and in this
900 case no DNSSEC validation at all is occurring.
901 --dnssec-no-timecheck
903 DNSSEC signatures are only valid for specified time windows, and
904 should be rejected outside those windows. This generates an in‐
905 teresting chicken-and-egg problem for machines which don't have
906 a hardware real time clock. For these machines to determine the
907 correct time typically requires use of NTP and therefore DNS,
908 but validating DNS requires that the correct time is already
909 known. Setting this flag removes the time-window checks (but not
910 other DNSSEC validation.) only until the dnsmasq process re‐
911 ceives SIGINT. The intention is that dnsmasq should be started
912 with this flag when the platform determines that reliable time
913 is not currently available. As soon as reliable time is estab‐
914 lished, a SIGINT should be sent to dnsmasq, which enables time
915 checking, and purges the cache of DNS records which have not
916 been thoroughly checked.
917 Earlier versions of dnsmasq overloaded SIGHUP (which re-reads
919 much configuration) to also enable time validation.
920 If dnsmasq is run in debug mode (--no-daemon flag) then SIGINT
922 retains its usual meaning of terminating the dnsmasq process.
923 --dnssec-timestamp=<path>
925 Enables an alternative way of checking the validity of the sys‐
926 tem time for DNSSEC (see --dnssec-no-timecheck). In this case,
927 the system time is considered to be valid once it becomes later
928 than the timestamp on the specified file. The file is created
929 and its timestamp set automatically by dnsmasq. The file must be
930 stored on a persistent filesystem, so that it and its mtime are
931 carried over system restarts. The timestamp file is created af‐
932 ter dnsmasq has dropped root, so it must be in a location
933 writable by the unprivileged user that dnsmasq runs as.
934 --proxy-dnssec
936 Copy the DNSSEC Authenticated Data bit from upstream servers to
937 downstream clients. This is an alternative to having dnsmasq
938 validate DNSSEC, but it depends on the security of the network
939 between dnsmasq and the upstream servers, and the trustworthi‐
940 ness of the upstream servers. Note that caching the Authenti‐
941 cated Data bit correctly in all cases is not technically possi‐
942 ble. If the AD bit is to be relied upon when using this option,
943 then the cache should be disabled using --cache-size=0. In most
944 cases, enabling DNSSEC validation within dnsmasq is a better op‐
945 tion. See --dnssec for details.
946 --dnssec-debug
948 Set debugging mode for the DNSSEC validation, set the Checking
949 Disabled bit on upstream queries, and don't convert replies
950 which do not validate to responses with a return code of SERV‐
951 FAIL. Note that setting this may affect DNS behaviour in bad
952 ways, it is not an extra-logging flag and should not be set in
953 production.
954 --auth-zone=<domain>[,<subnet>[/<prefix length>][,<subnet>[/<prefix
956 length>].....][,exclude:<subnet>[/<prefix length>]].....]
957 Define a DNS zone for which dnsmasq acts as authoritative
958 server. Locally defined DNS records which are in the domain will
959 be served. If subnet(s) are given, A and AAAA records must be in
960 one of the specified subnets.
961 As alternative to directly specifying the subnets, it's possible
963 to give the name of an interface, in which case the subnets im‐
964 plied by that interface's configured addresses and netmask/pre‐
965 fix-length are used; this is useful when using constructed DHCP
966 ranges as the actual address is dynamic and not known when con‐
967 figuring dnsmasq. The interface addresses may be confined to
968 only IPv6 addresses using <interface>/6 or to only IPv4 using
969 <interface>/4. This is useful when an interface has dynamically
970 determined global IPv6 addresses which should appear in the
971 zone, but RFC1918 IPv4 addresses which should not. Interface-
972 name and address-literal subnet specifications may be used
973 freely in the same --auth-zone declaration.
974 It's possible to exclude certain IP addresses from responses. It
976 can be used, to make sure that answers contain only global
977 routeable IP addresses (by excluding loopback, RFC1918 and ULA
978 addresses).
979 The subnet(s) are also used to define in-addr.arpa and ip6.arpa
981 domains which are served for reverse-DNS queries. If not speci‐
982 fied, the prefix length defaults to 24 for IPv4 and 64 for IPv6.
983 For IPv4 subnets, the prefix length should be have the value 8,
984 16 or 24 unless you are familiar with RFC 2317 and have arranged
985 the in-addr.arpa delegation accordingly. Note that if no subnets
986 are specified, then no reverse queries are answered.
987 --auth-soa=<serial>[,<hostmaster>[,<refresh>[,<retry>[,<expiry>]]]]
989 Specify fields in the SOA record associated with authoritative
990 zones. Note that this is optional, all the values are set to
991 sane defaults.
992 --auth-sec-servers=<domain>[,<domain>[,<domain>...]]
994 Specify any secondary servers for a zone for which dnsmasq is
995 authoritative. These servers must be configured to get zone data
996 from dnsmasq by zone transfer, and answer queries for the same
997 authoritative zones as dnsmasq.
998 --auth-peer=<ip-address>[,<ip-address>[,<ip-address>...]]
1000 Specify the addresses of secondary servers which are allowed to
1001 initiate zone transfer (AXFR) requests for zones for which dns‐
1002 masq is authoritative. If this option is not given but --auth-
1003 sec-servers is, then AXFR requests will be accepted from any
1004 secondary. Specifying --auth-peer without --auth-sec-servers en‐
1005 ables zone transfer but does not advertise the secondary in NS
1006 records returned by dnsmasq.
1007 --conntrack
1009 Read the Linux connection track mark associated with incoming
1010 DNS queries and set the same mark value on upstream traffic used
1011 to answer those queries. This allows traffic generated by dns‐
1012 masq to be associated with the queries which cause it, useful
1013 for bandwidth accounting and firewalling. Dnsmasq must have con‐
1014 ntrack support compiled in and the kernel must have conntrack
1015 support included and configured. This option cannot be combined
1016 with --query-port.
1017 -F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-
1019 addr>[,<end-addr>|<mode>[,<netmask>[,<broadcast>]]][,<lease time>]
1020 -F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-
1022 IPv6addr>[,<end-IPv6addr>|constructor:<interface>][,<mode>][,<prefix-
1023 len>][,<lease time>]
1024 Enable the DHCP server. Addresses will be given out from the
1026 range <start-addr> to <end-addr> and from statically defined ad‐
1027 dresses given in --dhcp-host options. If the lease time is
1028 given, then leases will be given for that length of time. The
1029 lease time is in seconds, or minutes (eg 45m) or hours (eg 1h)
1030 or days (2d) or weeks (1w) or "infinite". If not given, the de‐
1031 fault lease time is one hour for IPv4 and one day for IPv6. The
1032 minimum lease time is two minutes. For IPv6 ranges, the lease
1033 time maybe "deprecated"; this sets the preferred lifetime sent
1034 in a DHCP lease or router advertisement to zero, which causes
1035 clients to use other addresses, if available, for new connec‐
1036 tions as a prelude to renumbering.
1037 This option may be repeated, with different addresses, to enable
1039 DHCP service to more than one network. For directly connected
1040 networks (ie, networks on which the machine running dnsmasq has
1041 an interface) the netmask is optional: dnsmasq will determine it
1042 from the interface configuration. For networks which receive
1043 DHCP service via a relay agent, dnsmasq cannot determine the
1044 netmask itself, so it should be specified, otherwise dnsmasq
1045 will have to guess, based on the class (A, B or C) of the net‐
1046 work address. The broadcast address is always optional. It is
1047 always allowed to have more than one --dhcp-range in a single
1048 subnet.
1049 For IPv6, the parameters are slightly different: instead of net‐
1051 mask and broadcast address, there is an optional prefix length
1052 which must be equal to or larger then the prefix length on the
1053 local interface. If not given, this defaults to 64. Unlike the
1054 IPv4 case, the prefix length is not automatically derived from
1055 the interface configuration. The minimum size of the prefix
1056 length is 64.
1057 IPv6 (only) supports another type of range. In this, the start
1059 address and optional end address contain only the network part
1060 (ie ::1) and they are followed by constructor:<interface>. This
1061 forms a template which describes how to create ranges, based on
1062 the addresses assigned to the interface. For instance
1063 --dhcp-range=::1,::400,constructor:eth0
1065 will look for addresses on eth0 and then create a range from
1067 <network>::1 to <network>::400. If the interface is assigned
1068 more than one network, then the corresponding ranges will be au‐
1069 tomatically created, and then deprecated and finally removed
1070 again as the address is deprecated and then deleted. The inter‐
1071 face name may have a final "*" wildcard. Note that just any ad‐
1072 dress on eth0 will not do: it must not be an autoconfigured or
1073 privacy address, or be deprecated.
1074 If a --dhcp-range is only being used for stateless DHCP and/or
1076 SLAAC, then the address can be simply ::
1077 --dhcp-range=::,constructor:eth0
1079 The optional set:<tag> sets an alphanumeric label which marks
1082 this network so that DHCP options may be specified on a per-net‐
1083 work basis. When it is prefixed with 'tag:' instead, then its
1084 meaning changes from setting a tag to matching it. Only one tag
1085 may be set, but more than one tag may be matched.
1086 The optional <mode> keyword may be static which tells dnsmasq to
1088 enable DHCP for the network specified, but not to dynamically
1089 allocate IP addresses: only hosts which have static addresses
1090 given via --dhcp-host or from /etc/ethers will be served. A
1091 static-only subnet with address all zeros may be used as a
1092 "catch-all" address to enable replies to all Information-request
1093 packets on a subnet which is provided with stateless DHCPv6, ie
1094 --dhcp-range=::,static
1095 For IPv4, the <mode> may be proxy in which case dnsmasq will
1097 provide proxy-DHCP on the specified subnet. (See --pxe-prompt
1098 and --pxe-service for details.)
1099 For IPv6, the mode may be some combination of ra-only, slaac,
1101 ra-names, ra-stateless, ra-advrouter, off-link.
1102 ra-only tells dnsmasq to offer Router Advertisement only on this
1104 subnet, and not DHCP.
1105 slaac tells dnsmasq to offer Router Advertisement on this subnet
1107 and to set the A bit in the router advertisement, so that the
1108 client will use SLAAC addresses. When used with a DHCP range or
1109 static DHCP address this results in the client having both a
1110 DHCP-assigned and a SLAAC address.
1111 ra-stateless sends router advertisements with the O and A bits
1113 set, and provides a stateless DHCP service. The client will use
1114 a SLAAC address, and use DHCP for other configuration informa‐
1115 tion.
1116 ra-names enables a mode which gives DNS names to dual-stack
1118 hosts which do SLAAC for IPv6. Dnsmasq uses the host's IPv4
1119 lease to derive the name, network segment and MAC address and
1120 assumes that the host will also have an IPv6 address calculated
1121 using the SLAAC algorithm, on the same network segment. The ad‐
1122 dress is pinged, and if a reply is received, an AAAA record is
1123 added to the DNS for this IPv6 address. Note that this is only
1124 happens for directly-connected networks, (not one doing DHCP via
1125 a relay) and it will not work if a host is using privacy exten‐
1126 sions. ra-names can be combined with ra-stateless and slaac.
1127 ra-advrouter enables a mode where router address(es) rather than
1129 prefix(es) are included in the advertisements. This is de‐
1130 scribed in RFC-3775 section 7.2 and is used in mobile IPv6. In
1131 this mode the interval option is also included, as described in
1132 RFC-3775 section 7.3.
1133 off-link tells dnsmasq to advertise the prefix without the on-
1135 link (aka L) bit set.
1136 -G, --dhcp-
1139 host=[<hwaddr>][,id:<client_id>|*][,set:<tag>][tag:<tag>][,<ipaddr>][,<host‐
1140 name>][,<lease_time>][,ignore]
1141 Specify per host parameters for the DHCP server. This allows a
1142 machine with a particular hardware address to be always allo‐
1143 cated the same hostname, IP address and lease time. A hostname
1144 specified like this overrides any supplied by the DHCP client on
1145 the machine. It is also allowable to omit the hardware address
1146 and include the hostname, in which case the IP address and lease
1147 times will apply to any machine claiming that name. For example
1148 --dhcp-host=00:20:e0:3b:13:af,wap,infinite tells dnsmasq to give
1149 the machine with hardware address 00:20:e0:3b:13:af the name
1150 wap, and an infinite DHCP lease. --dhcp-host=lap,192.168.0.199
1151 tells dnsmasq to always allocate the machine lap the IP address
1152 192.168.0.199.
1153 Addresses allocated like this are not constrained to be in the
1155 range given by the --dhcp-range option, but they must be in the
1156 same subnet as some valid dhcp-range. For subnets which don't
1157 need a pool of dynamically allocated addresses, use the "static"
1158 keyword in the --dhcp-range declaration.
1159 It is allowed to use client identifiers (called client DUID in
1161 IPv6-land) rather than hardware addresses to identify hosts by
1162 prefixing with 'id:'. Thus: --dhcp-host=id:01:02:03:04,.....
1163 refers to the host with client identifier 01:02:03:04. It is
1164 also allowed to specify the client ID as text, like this:
1165 --dhcp-host=id:clientidastext,.....
1166 A single --dhcp-host may contain an IPv4 address or one or more
1168 IPv6 addresses, or both. IPv6 addresses must be bracketed by
1169 square brackets thus: --dhcp-host=laptop,[1234::56] IPv6 ad‐
1170 dresses may contain only the host-identifier part: --dhcp-
1171 host=laptop,[::56] in which case they act as wildcards in con‐
1172 structed DHCP ranges, with the appropriate network part in‐
1173 serted. For IPv6, an address may include a prefix length:
1174 --dhcp-host=laptop,[1234:50/126] which (in this case) specifies
1175 four addresses, 1234::50 to 1234::53. This (an the ability to
1176 specify multiple addresses) is useful when a host presents ei‐
1177 ther a consistent name or hardware-ID, but varying DUIDs, since
1178 it allows dnsmasq to honour the static address allocation but
1179 assign a different adddress for each DUID. This typically occurs
1180 when chain netbooting, as each stage of the chain gets in turn
1181 allocates an address.
1182 Note that in IPv6 DHCP, the hardware address may not be avail‐
1184 able, though it normally is for direct-connected clients, or
1185 clients using DHCP relays which support RFC 6939.
1186 For DHCPv4, the special option id:* means "ignore any client-id
1189 and use MAC addresses only." This is useful when a client
1190 presents a client-id sometimes but not others.
1191 If a name appears in /etc/hosts, the associated address can be
1193 allocated to a DHCP lease, but only if a --dhcp-host option
1194 specifying the name also exists. Only one hostname can be given
1195 in a --dhcp-host option, but aliases are possible by using
1196 CNAMEs. (See --cname ).
1197 More than one --dhcp-host can be associated (by name, hardware
1199 address or UID) with a host. Which one is used (and therefore
1200 which address is allocated by DHCP and appears in the DNS) de‐
1201 pends on the subnet on which the host last obtained a DHCP
1202 lease: the --dhcp-host with an address within the subnet is
1203 used. If more than one address is within the subnet, the result
1204 is undefined. A corollary to this is that the name associated
1205 with a host using --dhcp-host does not appear in the DNS until
1206 the host obtains a DHCP lease.
1207 The special keyword "ignore" tells dnsmasq to never offer a DHCP
1210 lease to a machine. The machine can be specified by hardware ad‐
1211 dress, client ID or hostname, for instance --dhcp-
1212 host=00:20:e0:3b:13:af,ignore This is useful when there is an‐
1213 other DHCP server on the network which should be used by some
1214 machines.
1215 The set:<tag> construct sets the tag whenever this --dhcp-host
1217 directive is in use. This can be used to selectively send DHCP
1218 options just for this host. More than one tag can be set in a
1219 --dhcp-host directive (but not in other places where "set:<tag>"
1220 is allowed). When a host matches any --dhcp-host directive (or
1221 one implied by /etc/ethers) then the special tag "known" is set.
1222 This allows dnsmasq to be configured to ignore requests from un‐
1223 known machines using --dhcp-ignore=tag:!known If the host
1224 matches only a --dhcp-host directive which cannot be used be‐
1225 cause it specifies an address on different subnet, the tag
1226 "known-othernet" is set.
1227 The tag:<tag> construct filters which dhcp-host directives are
1229 used. Tagged directives are used in preference to untagged ones.
1230 Ethernet addresses (but not client-ids) may have wildcard bytes,
1232 so for example --dhcp-host=00:20:e0:3b:13:*,ignore will cause
1233 dnsmasq to ignore a range of hardware addresses. Note that the
1234 "*" will need to be escaped or quoted on a command line, but not
1235 in the configuration file.
1236 Hardware addresses normally match any network (ARP) type, but it
1238 is possible to restrict them to a single ARP type by preceding
1239 them with the ARP-type (in HEX) and "-". so --dhcp-
1240 host=06-00:20:e0:3b:13:af,1.2.3.4 will only match a Token-Ring
1241 hardware address, since the ARP-address type for token ring is
1242 6.
1243 As a special case, in DHCPv4, it is possible to include more
1245 than one hardware address. eg: --dhcp-
1246 host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2 This allows
1247 an IP address to be associated with multiple hardware addresses,
1248 and gives dnsmasq permission to abandon a DHCP lease to one of
1249 the hardware addresses when another one asks for a lease. Beware
1250 that this is a dangerous thing to do, it will only work reliably
1251 if only one of the hardware addresses is active at any time and
1252 there is no way for dnsmasq to enforce this. It is, for in‐
1253 stance, useful to allocate a stable IP address to a laptop which
1254 has both wired and wireless interfaces.
1255 --dhcp-hostsfile=<path>
1257 Read DHCP host information from the specified file. If a direc‐
1258 tory is given, then read all the files contained in that direc‐
1259 tory in alphabetical order. The file contains information about
1260 one host per line. The format of a line is the same as text to
1261 the right of '=' in --dhcp-host. The advantage of storing DHCP
1262 host information in this file is that it can be changed without
1263 re-starting dnsmasq: the file will be re-read when dnsmasq re‐
1264 ceives SIGHUP.
1265 --dhcp-optsfile=<path>
1267 Read DHCP option information from the specified file. If a di‐
1268 rectory is given, then read all the files contained in that di‐
1269 rectory in alphabetical order. The advantage of using this op‐
1270 tion is the same as for --dhcp-hostsfile: the --dhcp-optsfile
1271 will be re-read when dnsmasq receives SIGHUP. Note that it is
1272 possible to encode the information in a --dhcp-boot flag as DHCP
1273 options, using the options names bootfile-name, server-ip-ad‐
1274 dress and tftp-server. This allows these to be included in a
1275 --dhcp-optsfile.
1276 --dhcp-hostsdir=<path>
1278 This is equivalent to --dhcp-hostsfile, except for the follow‐
1279 ing. The path MUST be a directory, and not an individual file.
1280 Changed or new files within the directory are read automati‐
1281 cally, without the need to send SIGHUP. If a file is deleted or
1282 changed after it has been read by dnsmasq, then the host record
1283 it contained will remain until dnsmasq receives a SIGHUP, or is
1284 restarted; ie host records are only added dynamically. The order
1285 in which the files in a directory are read is not defined.
1286 --dhcp-optsdir=<path>
1288 This is equivalent to --dhcp-optsfile, with the differences
1289 noted for --dhcp-hostsdir.
1290 -Z, --read-ethers
1292 Read /etc/ethers for information about hosts for the DHCP
1293 server. The format of /etc/ethers is a hardware address, fol‐
1294 lowed by either a hostname or dotted-quad IP address. When read
1295 by dnsmasq these lines have exactly the same effect as --dhcp-
1296 host options containing the same information. /etc/ethers is re-
1297 read when dnsmasq receives SIGHUP. IPv6 addresses are NOT read
1298 from /etc/ethers.
1299 -O, --dhcp-option=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<en‐
1301 terprise>,][vendor:[<vendor-class>],][<opt>|option:<opt-name>|op‐
1302 tion6:<opt>|option6:<opt-name>],[<value>[,<value>]]
1303 Specify different or extra options to DHCP clients. By default,
1304 dnsmasq sends some standard options to DHCP clients, the netmask
1305 and broadcast address are set to the same as the host running
1306 dnsmasq, and the DNS server and default route are set to the ad‐
1307 dress of the machine running dnsmasq. (Equivalent rules apply
1308 for IPv6.) If the domain name option has been set, that is sent.
1309 This configuration allows these defaults to be overridden, or
1310 other options specified. The option, to be sent may be given as
1311 a decimal number or as "option:<option-name>" The option numbers
1312 are specified in RFC2132 and subsequent RFCs. The set of option-
1313 names known by dnsmasq can be discovered by running "dnsmasq
1314 --help dhcp". For example, to set the default route option to
1315 192.168.4.4, do --dhcp-option=3,192.168.4.4 or --dhcp-option =
1316 option:router, 192.168.4.4 and to set the time-server address to
1317 192.168.0.4, do --dhcp-option = 42,192.168.0.4 or --dhcp-option
1318 = option:ntp-server, 192.168.0.4 The special address 0.0.0.0 is
1319 taken to mean "the address of the machine running dnsmasq".
1320 Data types allowed are comma separated dotted-quad IPv4 ad‐
1322 dresses, []-wrapped IPv6 addresses, a decimal number, colon-sep‐
1323 arated hex digits and a text string. If the optional tags are
1324 given then this option is only sent when all the tags are
1325 matched.
1326 Special processing is done on a text argument for option 119, to
1328 conform with RFC 3397. Text or dotted-quad IP addresses as argu‐
1329 ments to option 120 are handled as per RFC 3361. Dotted-quad IP
1330 addresses which are followed by a slash and then a netmask size
1331 are encoded as described in RFC 3442.
1332 IPv6 options are specified using the option6: keyword, followed
1334 by the option number or option name. The IPv6 option name space
1335 is disjoint from the IPv4 option name space. IPv6 addresses in
1336 options must be bracketed with square brackets, eg. --dhcp-op‐
1337 tion=option6:ntp-server,[1234::56] For IPv6, [::] means "the
1338 global address of the machine running dnsmasq", whilst [fd00::]
1339 is replaced with the ULA, if it exists, and [fe80::] with the
1340 link-local address.
1341 Be careful: no checking is done that the correct type of data
1343 for the option number is sent, it is quite possible to persuade
1344 dnsmasq to generate illegal DHCP packets with injudicious use of
1345 this flag. When the value is a decimal number, dnsmasq must de‐
1346 termine how large the data item is. It does this by examining
1347 the option number and/or the value, but can be overridden by ap‐
1348 pending a single letter flag as follows: b = one byte, s = two
1349 bytes, i = four bytes. This is mainly useful with encapsulated
1350 vendor class options (see below) where dnsmasq cannot determine
1351 data size from the option number. Option data which consists
1352 solely of periods and digits will be interpreted by dnsmasq as
1353 an IP address, and inserted into an option as such. To force a
1354 literal string, use quotes. For instance when using option 66 to
1355 send a literal IP address as TFTP server name, it is necessary
1356 to do --dhcp-option=66,"1.2.3.4"
1357 Encapsulated Vendor-class options may also be specified (IPv4
1359 only) using --dhcp-option: for instance --dhcp-option=vendor:PX‐
1360 EClient,1,0.0.0.0 sends the encapsulated vendor class-specific
1361 option "mftp-address=0.0.0.0" to any client whose vendor-class
1362 matches "PXEClient". The vendor-class matching is substring
1363 based (see --dhcp-vendorclass for details). If a vendor-class
1364 option (number 60) is sent by dnsmasq, then that is used for se‐
1365 lecting encapsulated options in preference to any sent by the
1366 client. It is possible to omit the vendorclass completely;
1367 --dhcp-option=vendor:,1,0.0.0.0 in which case the encapsulated
1368 option is always sent.
1369 Options may be encapsulated (IPv4 only) within other options:
1371 for instance --dhcp-option=encap:175, 190, iscsi-client0 will
1372 send option 175, within which is the option 190. If multiple op‐
1373 tions are given which are encapsulated with the same option num‐
1374 ber then they will be correctly combined into one encapsulated
1375 option. encap: and vendor: are may not both be set in the same
1376 --dhcp-option.
1377 The final variant on encapsulated options is "Vendor-Identifying
1379 Vendor Options" as specified by RFC3925. These are denoted like
1380 this: --dhcp-option=vi-encap:2, 10, text The number in the vi-
1381 encap: section is the IANA enterprise number used to identify
1382 this option. This form of encapsulation is supported in IPv6.
1383 The address 0.0.0.0 is not treated specially in encapsulated op‐
1385 tions.
1386 --dhcp-option-force=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-en‐
1388 cap:<enterprise>,][vendor:[<vendor-class>],]<opt>,[<value>[,<value>]]
1389 This works in exactly the same way as --dhcp-option except that
1390 the option will always be sent, even if the client does not ask
1391 for it in the parameter request list. This is sometimes needed,
1392 for example when sending options to PXELinux.
1393 --dhcp-no-override
1395 (IPv4 only) Disable re-use of the DHCP servername and filename
1396 fields as extra option space. If it can, dnsmasq moves the boot
1397 server and filename information (from --dhcp-boot) out of their
1398 dedicated fields into DHCP options. This make extra space avail‐
1399 able in the DHCP packet for options but can, rarely, confuse old
1400 or broken clients. This flag forces "simple and safe" behaviour
1401 to avoid problems in such a case.
1402 --dhcp-relay=<local address>,<server address>[,<interface]
1404 Configure dnsmasq to do DHCP relay. The local address is an ad‐
1405 dress allocated to an interface on the host running dnsmasq. All
1406 DHCP requests arriving on that interface will we relayed to a
1407 remote DHCP server at the server address. It is possible to re‐
1408 lay from a single local address to multiple remote servers by
1409 using multiple --dhcp-relay configs with the same local address
1410 and different server addresses. A server address must be an IP
1411 literal address, not a domain name. In the case of DHCPv6, the
1412 server address may be the ALL_SERVERS multicast address,
1413 ff05::1:3. In this case the interface must be given, not be
1414 wildcard, and is used to direct the multicast to the correct in‐
1415 terface to reach the DHCP server.
1416 Access control for DHCP clients has the same rules as for the
1418 DHCP server, see --interface, --except-interface, etc. The op‐
1419 tional interface name in the --dhcp-relay config has a different
1420 function: it controls on which interface DHCP replies from the
1421 server will be accepted. This is intended for configurations
1422 which have three interfaces: one being relayed from, a second
1423 connecting the DHCP server, and a third untrusted network, typi‐
1424 cally the wider internet. It avoids the possibility of spoof
1425 replies arriving via this third interface.
1426 It is allowed to have dnsmasq act as a DHCP server on one set of
1428 interfaces and relay from a disjoint set of interfaces. Note
1429 that whilst it is quite possible to write configurations which
1430 appear to act as a server and a relay on the same interface,
1431 this is not supported: the relay function will take precedence.
1432 Both DHCPv4 and DHCPv6 relay is supported. It's not possible to
1434 relay DHCPv4 to a DHCPv6 server or vice-versa.
1435 -U, --dhcp-vendorclass=set:<tag>,[enterprise:<IANA-enterprise num‐
1437 ber>,]<vendor-class>
1438 Map from a vendor-class string to a tag. Most DHCP clients pro‐
1439 vide a "vendor class" which represents, in some sense, the type
1440 of host. This option maps vendor classes to tags, so that DHCP
1441 options may be selectively delivered to different classes of
1442 hosts. For example --dhcp-vendorclass=set:printers,Hewlett-
1443 Packard JetDirect will allow options to be set only for HP
1444 printers like so: --dhcp-option=tag:printers,3,192.168.4.4 The
1445 vendor-class string is substring matched against the vendor-
1446 class supplied by the client, to allow fuzzy matching. The set:
1447 prefix is optional but allowed for consistency.
1448 Note that in IPv6 only, vendorclasses are namespaced with an
1450 IANA-allocated enterprise number. This is given with enterprise:
1451 keyword and specifies that only vendorclasses matching the spec‐
1452 ified number should be searched.
1453 -j, --dhcp-userclass=set:<tag>,<user-class>
1455 Map from a user-class string to a tag (with substring matching,
1456 like vendor classes). Most DHCP clients provide a "user class"
1457 which is configurable. This option maps user classes to tags, so
1458 that DHCP options may be selectively delivered to different
1459 classes of hosts. It is possible, for instance to use this to
1460 set a different printer server for hosts in the class "accounts"
1461 than for hosts in the class "engineering".
1462 -4, --dhcp-mac=set:<tag>,<MAC address>
1464 Map from a MAC address to a tag. The MAC address may include
1465 wildcards. For example --dhcp-mac=set:3com,01:34:23:*:*:* will
1466 set the tag "3com" for any host whose MAC address matches the
1467 pattern.
1468 --dhcp-circuitid=set:<tag>,<circuit-id>, --dhcp-remoteid=set:<tag>,<re‐
1470 mote-id>
1471 Map from RFC3046 relay agent options to tags. This data may be
1472 provided by DHCP relay agents. The circuit-id or remote-id is
1473 normally given as colon-separated hex, but is also allowed to be
1474 a simple string. If an exact match is achieved between the cir‐
1475 cuit or agent ID and one provided by a relay agent, the tag is
1476 set.
1477 --dhcp-remoteid (but not --dhcp-circuitid) is supported in IPv6.
1479 --dhcp-subscrid=set:<tag>,<subscriber-id>
1481 (IPv4 and IPv6) Map from RFC3993 subscriber-id relay agent op‐
1482 tions to tags.
1483 --dhcp-proxy[=<ip addr>]......
1485 (IPv4 only) A normal DHCP relay agent is only used to forward
1486 the initial parts of a DHCP interaction to the DHCP server. Once
1487 a client is configured, it communicates directly with the
1488 server. This is undesirable if the relay agent is adding extra
1489 information to the DHCP packets, such as that used by --dhcp-
1490 circuitid and --dhcp-remoteid. A full relay implementation can
1491 use the RFC 5107 serverid-override option to force the DHCP
1492 server to use the relay as a full proxy, with all packets pass‐
1493 ing through it. This flag provides an alternative method of do‐
1494 ing the same thing, for relays which don't support RFC 5107.
1495 Given alone, it manipulates the server-id for all interactions
1496 via relays. If a list of IP addresses is given, only interac‐
1497 tions via relays at those addresses are affected.
1498 --dhcp-match=set:<tag>,<option number>|option:<option name>|vi-en‐
1500 cap:<enterprise>[,<value>]
1501 Without a value, set the tag if the client sends a DHCP option
1502 of the given number or name. When a value is given, set the tag
1503 only if the option is sent and matches the value. The value may
1504 be of the form "01:ff:*:02" in which case the value must match
1505 (apart from wildcards) but the option sent may have unmatched
1506 data past the end of the value. The value may also be of the
1507 same form as in --dhcp-option in which case the option sent is
1508 treated as an array, and one element must match, so --dhcp-
1509 match=set:efi-ia32,option:client-arch,6 will set the tag "efi-
1510 ia32" if the the number 6 appears in the list of architectures
1511 sent by the client in option 93. (See RFC 4578 for details.) If
1512 the value is a string, substring matching is used.
1513 The special form with vi-encap:<enterprise number> matches
1515 against vendor-identifying vendor classes for the specified en‐
1516 terprise. Please see RFC 3925 for more details of these rare and
1517 interesting beasts.
1518 --dhcp-name-match=set:<tag>,<name>[*]
1520 Set the tag if the given name is supplied by a DHCP client.
1521 There may be a single trailing wildcard *, which has the usual
1522 meaning. Combined with dhcp-ignore or dhcp-ignore-names this
1523 gives the ability to ignore certain clients by name, or disallow
1524 certain hostnames from being claimed by a client.
1525 --tag-if=set:<tag>[,set:<tag>[,tag:<tag>[,tag:<tag>]]]
1527 Perform boolean operations on tags. Any tag appearing as
1528 set:<tag> is set if all the tags which appear as tag:<tag> are
1529 set, (or unset when tag:!<tag> is used) If no tag:<tag> appears
1530 set:<tag> tags are set unconditionally. Any number of set: and
1531 tag: forms may appear, in any order. --tag-if lines are exe‐
1532 cuted in order, so if the tag in tag:<tag> is a tag set by an‐
1533 other --tag-if, the line which sets the tag must precede the one
1534 which tests it.
1535 As an extension, the tag:<tag> clauses support limited wildcard
1537 matching, similar to the matching in the --interface directive.
1538 This allows, for example, using --tag-if=set:ppp,tag:ppp* to set
1539 the tag 'ppp' for all requests received on any matching inter‐
1540 face (ppp0, ppp1, etc). This can be used in conjunction with
1541 the tag:!<tag> format meaning that no tag matching the wildcard
1542 may be set.
1543 -J, --dhcp-ignore=tag:<tag>[,tag:<tag>]
1545 When all the given tags appear in the tag set ignore the host
1546 and do not allocate it a DHCP lease.
1547 --dhcp-ignore-names[=tag:<tag>[,tag:<tag>]]
1549 When all the given tags appear in the tag set, ignore any host‐
1550 name provided by the host. Note that, unlike --dhcp-ignore, it
1551 is permissible to supply no tags, in which case DHCP-client sup‐
1552 plied hostnames are always ignored, and DHCP hosts are added to
1553 the DNS using only --dhcp-host configuration in dnsmasq and the
1554 contents of /etc/hosts and /etc/ethers.
1555 --dhcp-generate-names=tag:<tag>[,tag:<tag>]
1557 (IPv4 only) Generate a name for DHCP clients which do not other‐
1558 wise have one, using the MAC address expressed in hex, separated
1559 by dashes. Note that if a host provides a name, it will be used
1560 by preference to this, unless --dhcp-ignore-names is set.
1561 --dhcp-broadcast[=tag:<tag>[,tag:<tag>]]
1563 (IPv4 only) When all the given tags appear in the tag set, al‐
1564 ways use broadcast to communicate with the host when it is un‐
1565 configured. It is permissible to supply no tags, in which case
1566 this is unconditional. Most DHCP clients which need broadcast
1567 replies set a flag in their requests so that this happens auto‐
1568 matically, some old BOOTP clients do not.
1569 -M, --dhcp-boot=[tag:<tag>,]<filename>,[<servername>[,<server ad‐
1571 dress>|<tftp_servername>]]
1572 (IPv4 only) Set BOOTP options to be returned by the DHCP server.
1573 Server name and address are optional: if not provided, the name
1574 is left empty, and the address set to the address of the machine
1575 running dnsmasq. If dnsmasq is providing a TFTP service (see
1576 --enable-tftp ) then only the filename is required here to en‐
1577 able network booting. If the optional tag(s) are given, they
1578 must match for this configuration to be sent. Instead of an IP
1579 address, the TFTP server address can be given as a domain name
1580 which is looked up in /etc/hosts. This name can be associated in
1581 /etc/hosts with multiple IP addresses, which are used round-
1582 robin. This facility can be used to load balance the tftp load
1583 among a set of servers.
1584 --dhcp-sequential-ip
1586 Dnsmasq is designed to choose IP addresses for DHCP clients us‐
1587 ing a hash of the client's MAC address. This normally allows a
1588 client's address to remain stable long-term, even if the client
1589 sometimes allows its DHCP lease to expire. In this default mode
1590 IP addresses are distributed pseudo-randomly over the entire
1591 available address range. There are sometimes circumstances (typ‐
1592 ically server deployment) where it is more convenient to have IP
1593 addresses allocated sequentially, starting from the lowest
1594 available address, and setting this flag enables this mode. Note
1595 that in the sequential mode, clients which allow a lease to ex‐
1596 pire are much more likely to move IP address; for this reason it
1597 should not be generally used.
1598 --dhcp-ignore-clid
1600 Dnsmasq is reading 'client identifier' (RFC 2131) option sent by
1601 clients (if available) to identify clients. This allow to serve
1602 same IP address for a host using several interfaces. Use this
1603 option to disable 'client identifier' reading, i.e. to always
1604 identify a host using the MAC address.
1605 --pxe-service=[tag:<tag>,]<CSA>,<menu text>[,<basename>|<bootservice‐
1607 type>][,<server address>|<server_name>]
1608 Most uses of PXE boot-ROMS simply allow the PXE system to obtain
1609 an IP address and then download the file specified by --dhcp-
1610 boot and execute it. However the PXE system is capable of more
1611 complex functions when supported by a suitable DHCP server.
1612 This specifies a boot option which may appear in a PXE boot
1614 menu. <CSA> is client system type, only services of the correct
1615 type will appear in a menu. The known types are x86PC, PC98,
1616 IA64_EFI, Alpha, Arc_x86, Intel_Lean_Client, IA32_EFI,
1617 x86-64_EFI, Xscale_EFI, BC_EFI, ARM32_EFI and ARM64_EFI; an in‐
1618 teger may be used for other types. The parameter after the menu
1619 text may be a file name, in which case dnsmasq acts as a boot
1620 server and directs the PXE client to download the file by TFTP,
1621 either from itself ( --enable-tftp must be set for this to work)
1622 or another TFTP server if the final server address/name is
1623 given. Note that the "layer" suffix (normally ".0") is supplied
1624 by PXE, and need not be added to the basename. Alternatively,
1625 the basename may be a filename, complete with suffix, in which
1626 case no layer suffix is added. If an integer boot service type,
1627 rather than a basename is given, then the PXE client will search
1628 for a suitable boot service for that type on the network. This
1629 search may be done by broadcast, or direct to a server if its IP
1630 address/name is provided. If no boot service type or filename
1631 is provided (or a boot service type of 0 is specified) then the
1632 menu entry will abort the net boot procedure and continue boot‐
1633 ing from local media. The server address can be given as a do‐
1634 main name which is looked up in /etc/hosts. This name can be as‐
1635 sociated in /etc/hosts with multiple IP addresses, which are
1636 used round-robin.
1637 --pxe-prompt=[tag:<tag>,]<prompt>[,<timeout>]
1639 Setting this provides a prompt to be displayed after PXE boot.
1640 If the timeout is given then after the timeout has elapsed with
1641 no keyboard input, the first available menu option will be auto‐
1642 matically executed. If the timeout is zero then the first avail‐
1643 able menu item will be executed immediately. If --pxe-prompt is
1644 omitted the system will wait for user input if there are multi‐
1645 ple items in the menu, but boot immediately if there is only
1646 one. See --pxe-service for details of menu items.
1647 Dnsmasq supports PXE "proxy-DHCP", in this case another DHCP
1649 server on the network is responsible for allocating IP ad‐
1650 dresses, and dnsmasq simply provides the information given in
1651 --pxe-prompt and --pxe-service to allow netbooting. This mode is
1652 enabled using the proxy keyword in --dhcp-range.
1653 --dhcp-pxe-vendor=<vendor>[,...]
1655 According to UEFI and PXE specifications, DHCP packets between
1656 PXE clients and proxy PXE servers should have PXEClient in their
1657 vendor-class field. However, the firmware of computers from a
1658 few vendors is customized to carry a different identifier in
1659 that field. This option is used to consider such identifiers
1660 valid for identifying PXE clients. For instance
1661 --dhcp-pxe-vendor=PXEClient,HW-Client
1663 will enable dnsmasq to also provide proxy PXE service to those
1665 PXE clients with HW-Client in as their identifier.
1666 -X, --dhcp-lease-max=<number>
1668 Limits dnsmasq to the specified maximum number of DHCP leases.
1669 The default is 1000. This limit is to prevent DoS attacks from
1670 hosts which create thousands of leases and use lots of memory in
1671 the dnsmasq process.
1672 -K, --dhcp-authoritative
1674 Should be set when dnsmasq is definitely the only DHCP server on
1675 a network. For DHCPv4, it changes the behaviour from strict RFC
1676 compliance so that DHCP requests on unknown leases from unknown
1677 hosts are not ignored. This allows new hosts to get a lease
1678 without a tedious timeout under all circumstances. It also al‐
1679 lows dnsmasq to rebuild its lease database without each client
1680 needing to reacquire a lease, if the database is lost. For
1681 DHCPv6 it sets the priority in replies to 255 (the maximum) in‐
1682 stead of 0 (the minimum).
1683 --dhcp-rapid-commit
1685 Enable DHCPv4 Rapid Commit Option specified in RFC 4039. When
1686 enabled, dnsmasq will respond to a DHCPDISCOVER message includ‐
1687 ing a Rapid Commit option with a DHCPACK including a Rapid Com‐
1688 mit option and fully committed address and configuration infor‐
1689 mation. Should only be enabled if either the server is the only
1690 server for the subnet, or multiple servers are present and they
1691 each commit a binding for all clients.
1692 --dhcp-alternate-port[=<server port>[,<client port>]]
1694 (IPv4 only) Change the ports used for DHCP from the default. If
1695 this option is given alone, without arguments, it changes the
1696 ports used for DHCP from 67 and 68 to 1067 and 1068. If a single
1697 argument is given, that port number is used for the server and
1698 the port number plus one used for the client. Finally, two port
1699 numbers allows arbitrary specification of both server and client
1700 ports for DHCP.
1701 -3, --bootp-dynamic[=<network-id>[,<network-id>]]
1703 (IPv4 only) Enable dynamic allocation of IP addresses to BOOTP
1704 clients. Use this with care, since each address allocated to a
1705 BOOTP client is leased forever, and therefore becomes perma‐
1706 nently unavailable for re-use by other hosts. if this is given
1707 without tags, then it unconditionally enables dynamic alloca‐
1708 tion. With tags, only when the tags are all set. It may be re‐
1709 peated with different tag sets.
1710 -5, --no-ping
1712 (IPv4 only) By default, the DHCP server will attempt to ensure
1713 that an address is not in use before allocating it to a host. It
1714 does this by sending an ICMP echo request (aka "ping") to the
1715 address in question. If it gets a reply, then the address must
1716 already be in use, and another is tried. This flag disables this
1717 check. Use with caution.
1718 --log-dhcp
1720 Extra logging for DHCP: log all the options sent to DHCP clients
1721 and the tags used to determine them.
1722 --quiet-dhcp, --quiet-dhcp6, --quiet-ra, --quiet-tftp
1724 Suppress logging of the routine operation of these protocols.
1725 Errors and problems will still be logged. --quiet-tftp does not
1726 consider file not found to be an error. --quiet-dhcp and quiet-
1727 dhcp6 are over-ridden by --log-dhcp.
1728 -l, --dhcp-leasefile=<path>
1730 Use the specified file to store DHCP lease information.
1731 --dhcp-duid=<enterprise-id>,<uid>
1733 (IPv6 only) Specify the server persistent UID which the DHCPv6
1734 server will use. This option is not normally required as dnsmasq
1735 creates a DUID automatically when it is first needed. When
1736 given, this option provides dnsmasq the data required to create
1737 a DUID-EN type DUID. Note that once set, the DUID is stored in
1738 the lease database, so to change between DUID-EN and automati‐
1739 cally created DUIDs or vice-versa, the lease database must be
1740 re-initialised. The enterprise-id is assigned by IANA, and the
1741 uid is a string of hex octets unique to a particular device.
1742 -6 --dhcp-script=<path>
1744 Whenever a new DHCP lease is created, or an old one destroyed,
1745 or a TFTP file transfer completes, the executable specified by
1746 this option is run. <path> must be an absolute pathname, no
1747 PATH search occurs. The arguments to the process are "add",
1748 "old" or "del", the MAC address of the host (or DUID for IPv6) ,
1749 the IP address, and the hostname, if known. "add" means a lease
1750 has been created, "del" means it has been destroyed, "old" is a
1751 notification of an existing lease when dnsmasq starts or a
1752 change to MAC address or hostname of an existing lease (also,
1753 lease length or expiry and client-id, if --leasefile-ro is set
1754 and lease expiry if --script-on-renewal is set). If the MAC ad‐
1755 dress is from a network type other than ethernet, it will have
1756 the network type prepended, eg "06-01:23:45:67:89:ab" for token
1757 ring. The process is run as root (assuming that dnsmasq was
1758 originally run as root) even if dnsmasq is configured to change
1759 UID to an unprivileged user.
1760 The environment is inherited from the invoker of dnsmasq, with
1762 some or all of the following variables added
1763 For both IPv4 and IPv6:
1765 DNSMASQ_DOMAIN if the fully-qualified domain name of the host is
1767 known, this is set to the domain part. (Note that the hostname
1768 passed to the script as an argument is never fully-qualified.)
1769 If the client provides a hostname, DNSMASQ_SUPPLIED_HOSTNAME
1771 If the client provides user-classes, DNSMASQ_USER_CLASS0..DNS‐
1773 MASQ_USER_CLASSn
1774 If dnsmasq was compiled with HAVE_BROKEN_RTC, then the length of
1776 the lease (in seconds) is stored in DNSMASQ_LEASE_LENGTH, other‐
1777 wise the time of lease expiry is stored in DNSMASQ_LEASE_EX‐
1778 PIRES. The number of seconds until lease expiry is always stored
1779 in DNSMASQ_TIME_REMAINING.
1780 If a lease used to have a hostname, which is removed, an "old"
1782 event is generated with the new state of the lease, ie no name,
1783 and the former name is provided in the environment variable DNS‐
1784 MASQ_OLD_HOSTNAME.
1785 DNSMASQ_INTERFACE stores the name of the interface on which the
1787 request arrived; this is not set for "old" actions when dnsmasq
1788 restarts.
1789 DNSMASQ_RELAY_ADDRESS is set if the client used a DHCP relay to
1791 contact dnsmasq and the IP address of the relay is known.
1792 DNSMASQ_TAGS contains all the tags set during the DHCP transac‐
1794 tion, separated by spaces.
1795 DNSMASQ_LOG_DHCP is set if --log-dhcp is in effect.
1797 For IPv4 only:
1799 DNSMASQ_CLIENT_ID if the host provided a client-id.
1801 DNSMASQ_CIRCUIT_ID, DNSMASQ_SUBSCRIBER_ID, DNSMASQ_REMOTE_ID if
1803 a DHCP relay-agent added any of these options.
1804 If the client provides vendor-class, DNSMASQ_VENDOR_CLASS.
1806 DNSMASQ_REQUESTED_OPTIONS a string containing the decimal values
1808 in the Parameter Request List option, comma separated, if the
1809 parameter request list option is provided by the client.
1810 For IPv6 only:
1812 If the client provides vendor-class, DNSMASQ_VENDOR_CLASS_ID,
1814 containing the IANA enterprise id for the class, and DNS‐
1815 MASQ_VENDOR_CLASS0..DNSMASQ_VENDOR_CLASSn for the data.
1816 DNSMASQ_SERVER_DUID containing the DUID of the server: this is
1818 the same for every call to the script.
1819 DNSMASQ_IAID containing the IAID for the lease. If the lease is
1821 a temporary allocation, this is prefixed to 'T'.
1822 DNSMASQ_MAC containing the MAC address of the client, if known.
1824 Note that the supplied hostname, vendorclass and userclass data
1826 is only supplied for "add" actions or "old" actions when a host
1827 resumes an existing lease, since these data are not held in dns‐
1828 masq's lease database.
1829 All file descriptors are closed except stdin, which is open to
1833 /dev/null, and stdout and stderr which capture output for log‐
1834 ging by dnsmasq. (In debug mode, stdio, stdout and stderr file
1835 are left as those inherited from the invoker of dnsmasq).
1836 The script is not invoked concurrently: at most one instance of
1838 the script is ever running (dnsmasq waits for an instance of
1839 script to exit before running the next). Changes to the lease
1840 database are which require the script to be invoked are queued
1841 awaiting exit of a running instance. If this queueing allows
1842 multiple state changes occur to a single lease before the script
1843 can be run then earlier states are discarded and the current
1844 state of that lease is reflected when the script finally runs.
1845 At dnsmasq startup, the script will be invoked for all existing
1847 leases as they are read from the lease file. Expired leases will
1848 be called with "del" and others with "old". When dnsmasq re‐
1849 ceives a HUP signal, the script will be invoked for existing
1850 leases with an "old" event.
1851 There are four further actions which may appear as the first ar‐
1854 gument to the script, "init", "arp-add", "arp-del" and "tftp".
1855 More may be added in the future, so scripts should be written to
1856 ignore unknown actions. "init" is described below in --lease‐
1857 file-ro The "tftp" action is invoked when a TFTP file transfer
1858 completes: the arguments are the file size in bytes, the address
1859 to which the file was sent, and the complete pathname of the
1860 file.
1861 The "arp-add" and "arp-del" actions are only called if enabled
1863 with --script-arp They are are supplied with a MAC address and
1864 IP address as arguments. "arp-add" indicates the arrival of a
1865 new entry in the ARP or neighbour table, and "arp-del" indicates
1866 the deletion of same.
1867 --dhcp-luascript=<path>
1870 Specify a script written in Lua, to be run when leases are cre‐
1871 ated, destroyed or changed. To use this option, dnsmasq must be
1872 compiled with the correct support. The Lua interpreter is ini‐
1873 tialised once, when dnsmasq starts, so that global variables
1874 persist between lease events. The Lua code must define a lease
1875 function, and may provide init and shutdown functions, which are
1876 called, without arguments when dnsmasq starts up and terminates.
1877 It may also provide a tftp function.
1878 The lease function receives the information detailed in --dhcp-
1880 script. It gets two arguments, firstly the action, which is a
1881 string containing, "add", "old" or "del", and secondly a table
1882 of tag value pairs. The tags mostly correspond to the environ‐
1883 ment variables detailed above, for instance the tag "domain"
1884 holds the same data as the environment variable DNSMASQ_DOMAIN.
1885 There are a few extra tags which hold the data supplied as argu‐
1886 ments to --dhcp-script. These are mac_address, ip_address and
1887 hostname for IPv4, and client_duid, ip_address and hostname for
1888 IPv6.
1889 The tftp function is called in the same way as the lease func‐
1891 tion, and the table holds the tags destination_address,
1892 file_name and file_size.
1893 The arp and arp-old functions are called only when enabled with
1895 --script-arp and have a table which holds the tags mac_address
1896 and client_address.
1897 --dhcp-scriptuser
1899 Specify the user as which to run the lease-change script or Lua
1900 script. This defaults to root, but can be changed to another
1901 user using this flag.
1902 --script-arp
1904 Enable the "arp" and "arp-old" functions in the --dhcp-script
1905 and --dhcp-luascript.
1906 -9, --leasefile-ro
1908 Completely suppress use of the lease database file. The file
1909 will not be created, read, or written. Change the way the lease-
1910 change script (if one is provided) is called, so that the lease
1911 database may be maintained in external storage by the script. In
1912 addition to the invocations given in --dhcp-script the lease-
1913 change script is called once, at dnsmasq startup, with the sin‐
1914 gle argument "init". When called like this the script should
1915 write the saved state of the lease database, in dnsmasq lease‐
1916 file format, to stdout and exit with zero exit code. Setting
1917 this option also forces the leasechange script to be called on
1918 changes to the client-id and lease length and expiry time.
1919 --script-on-renewal
1921 Call the DHCP script when the lease expiry time changes, for in‐
1922 stance when the lease is renewed.
1923 --bridge-interface=<interface>,<alias>[,<alias>]
1925 Treat DHCP (v4 and v6) requests and IPv6 Router Solicit packets
1926 arriving at any of the <alias> interfaces as if they had arrived
1927 at <interface>. This option allows dnsmasq to provide DHCP and
1928 RA service over unaddressed and unbridged Ethernet interfaces,
1929 e.g. on an OpenStack compute host where each such interface is a
1930 TAP interface to a VM, or as in "old style bridging" on BSD
1931 platforms. A trailing '*' wildcard can be used in each <alias>.
1932 It is permissible to add more than one alias using more than one
1934 --bridge-interface option since --bridge-inter‐
1935 face=int1,alias1,alias2 is exactly equivalent to --bridge-inter‐
1936 face=int1,alias1 --bridge-interface=int1,alias2
1937 --shared-network=<interface>,<addr>
1939 --shared-network=<addr>,<addr>
1940 The DHCP server determines which DHCP ranges are useable for al‐
1941 locating an address to a DHCP client based on the network from
1942 which the DHCP request arrives, and the IP configuration of the
1943 server's interface on that network. The shared-network option
1944 extends the available subnets (and therefore DHCP ranges) beyond
1945 the subnets configured on the arrival interface.
1946 The first argument is either the name of an interface, or an ad‐
1948 dress that is configured on a local interface, and the second
1949 argument is an address which defines another subnet on which ad‐
1950 dresses can be allocated.
1951 To be useful, there must be a suitable dhcp-range which allows
1953 address allocation on this subnet and this dhcp-range MUST in‐
1954 clude the netmask.
1955 Using shared-network also needs extra consideration of routing.
1957 Dnsmasq does not have the usual information that it uses to de‐
1958 termine the default route, so the default route option (or other
1959 routing) MUST be configured manually. The client must have a
1960 route to the server: if the two-address form of shared-network
1961 is used, this needs to be to the first specified address. If the
1962 interface,address form is used, there must be a route to all of
1963 the addresses configured on the interface.
1964 The two-address form of shared-network is also usable with a
1966 DHCP relay: the first address is the address of the relay and
1967 the second, as before, specifies an extra subnet which addresses
1968 may be allocated from.
1969 -s, --domain=<domain>[,<address range>[,local]]
1972 Specifies DNS domains for the DHCP server. Domains may be be
1973 given unconditionally (without the IP range) or for limited IP
1974 ranges. This has two effects; firstly it causes the DHCP server
1975 to return the domain to any hosts which request it, and secondly
1976 it sets the domain which it is legal for DHCP-configured hosts
1977 to claim. The intention is to constrain hostnames so that an un‐
1978 trusted host on the LAN cannot advertise its name via DHCP as
1979 e.g. "microsoft.com" and capture traffic not meant for it. If no
1980 domain suffix is specified, then any DHCP hostname with a domain
1981 part (ie with a period) will be disallowed and logged. If suffix
1982 is specified, then hostnames with a domain part are allowed,
1983 provided the domain part matches the suffix. In addition, when a
1984 suffix is set then hostnames without a domain part have the suf‐
1985 fix added as an optional domain part. Eg on my network I can set
1986 --domain=thekelleys.org.uk and have a machine whose DHCP host‐
1987 name is "laptop". The IP address for that machine is available
1988 from dnsmasq both as "laptop" and "laptop.thekelleys.org.uk". If
1989 the domain is given as "#" then the domain is read from the
1990 first "search" directive in /etc/resolv.conf (or equivalent).
1991 The address range can be of the form <ip address>,<ip address>
1993 or <ip address>/<netmask> or just a single <ip address>. See
1994 --dhcp-fqdn which can change the behaviour of dnsmasq with do‐
1995 mains.
1996 If the address range is given as ip-address/network-size, then a
1998 additional flag "local" may be supplied which has the effect of
1999 adding --local declarations for forward and reverse DNS queries.
2000 Eg. --domain=thekelleys.org.uk,192.168.0.0/24,local is identi‐
2001 cal to --domain=thekelleys.org.uk,192.168.0.0/24 --lo‐
2002 cal=/thekelleys.org.uk/ --local=/0.168.192.in-addr.arpa/ The
2003 network size must be 8, 16 or 24 for this to be legal.
2004 --dhcp-fqdn
2006 In the default mode, dnsmasq inserts the unqualified names of
2007 DHCP clients into the DNS. For this reason, the names must be
2008 unique, even if two clients which have the same name are in dif‐
2009 ferent domains. If a second DHCP client appears which has the
2010 same name as an existing client, the name is transferred to the
2011 new client. If --dhcp-fqdn is set, this behaviour changes: the
2012 unqualified name is no longer put in the DNS, only the qualified
2013 name. Two DHCP clients with the same name may both keep the
2014 name, provided that the domain part is different (ie the fully
2015 qualified names differ.) To ensure that all names have a domain
2016 part, there must be at least --domain without an address speci‐
2017 fied when --dhcp-fqdn is set.
2018 --dhcp-client-update
2020 Normally, when giving a DHCP lease, dnsmasq sets flags in the
2021 FQDN option to tell the client not to attempt a DDNS update with
2022 its name and IP address. This is because the name-IP pair is au‐
2023 tomatically added into dnsmasq's DNS view. This flag suppresses
2024 that behaviour, this is useful, for instance, to allow Windows
2025 clients to update Active Directory servers. See RFC 4702 for de‐
2026 tails.
2027 --enable-ra
2029 Enable dnsmasq's IPv6 Router Advertisement feature. DHCPv6
2030 doesn't handle complete network configuration in the same way as
2031 DHCPv4. Router discovery and (possibly) prefix discovery for au‐
2032 tonomous address creation are handled by a different protocol.
2033 When DHCP is in use, only a subset of this is needed, and dns‐
2034 masq can handle it, using existing DHCP configuration to provide
2035 most data. When RA is enabled, dnsmasq will advertise a prefix
2036 for each --dhcp-range, with default router as the relevant
2037 link-local address on the machine running dnsmasq. By default,
2038 the "managed address" bits are set, and the "use SLAAC" bit is
2039 reset. This can be changed for individual subnets with the mode
2040 keywords described in --dhcp-range. RFC6106 DNS parameters are
2041 included in the advertisements. By default, the relevant link-
2042 local address of the machine running dnsmasq is sent as recur‐
2043 sive DNS server. If provided, the DHCPv6 options dns-server and
2044 domain-search are used for the DNS server (RDNSS) and the domain
2045 search list (DNSSL).
2046 --ra-param=<interface>,[mtu:<integer>|<interface>|off,][high,|low,]<ra-
2048 interval>[,<router lifetime>]
2049 Set non-default values for router advertisements sent via an in‐
2050 terface. The priority field for the router may be altered from
2051 the default of medium with eg --ra-param=eth0,high. The inter‐
2052 val between router advertisements may be set (in seconds) with
2053 --ra-param=eth0,60. The lifetime of the route may be changed or
2054 set to zero, which allows a router to advertise prefixes but not
2055 a route via itself. --ra-param=eth0,0,0 (A value of zero for
2056 the interval means the default value.) All four parameters may
2057 be set at once. --ra-param=eth0,mtu:1280,low,60,1200
2058 The interface field may include a wildcard.
2060 The mtu: parameter may be an arbitrary interface name, in which
2062 case the MTU value for that interface is used. This is useful
2063 for (eg) advertising the MTU of a WAN interface on the other in‐
2064 terfaces of a router.
2065 --dhcp-reply-delay=[tag:<tag>,]<integer>
2067 Delays sending DHCPOFFER and PROXYDHCP replies for at least the
2068 specified number of seconds. This can be used as workaround for
2069 bugs in PXE boot firmware that does not function properly when
2070 receiving an instant reply. This option takes into account the
2071 time already spent waiting (e.g. performing ping check) if any.
2072 --enable-tftp[=<interface>[,<interface>]]
2074 Enable the TFTP server function. This is deliberately limited to
2075 that needed to net-boot a client. Only reading is allowed; the
2076 tsize and blksize extensions are supported (tsize is only sup‐
2077 ported in octet mode). Without an argument, the TFTP service is
2078 provided to the same set of interfaces as DHCP service. If the
2079 list of interfaces is provided, that defines which interfaces
2080 receive TFTP service.
2081 --tftp-root=<directory>[,<interface>]
2083 Look for files to transfer using TFTP relative to the given di‐
2084 rectory. When this is set, TFTP paths which include ".." are re‐
2085 jected, to stop clients getting outside the specified root. Ab‐
2086 solute paths (starting with /) are allowed, but they must be
2087 within the tftp-root. If the optional interface argument is
2088 given, the directory is only used for TFTP requests via that in‐
2089 terface.
2090 --tftp-no-fail
2092 Do not abort startup if specified tftp root directories are in‐
2093 accessible.
2094 --tftp-unique-root[=ip|mac]
2096 Add the IP or hardware address of the TFTP client as a path com‐
2097 ponent on the end of the TFTP-root. Only valid if a --tftp-root
2098 is set and the directory exists. Defaults to adding IP address
2099 (in standard dotted-quad format). For instance, if --tftp-root
2100 is "/tftp" and client 1.2.3.4 requests file "myfile" then the
2101 effective path will be "/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4
2102 exists or /tftp/myfile otherwise. When "=mac" is specified it
2103 will append the MAC address instead, using lowercase zero padded
2104 digits separated by dashes, e.g.: 01-02-03-04-aa-bb Note that
2105 resolving MAC addresses is only possible if the client is in the
2106 local network or obtained a DHCP lease from us.
2107 --tftp-secure
2109 Enable TFTP secure mode: without this, any file which is read‐
2110 able by the dnsmasq process under normal unix access-control
2111 rules is available via TFTP. When the --tftp-secure flag is
2112 given, only files owned by the user running the dnsmasq process
2113 are accessible. If dnsmasq is being run as root, different rules
2114 apply: --tftp-secure has no effect, but only files which have
2115 the world-readable bit set are accessible. It is not recommended
2116 to run dnsmasq as root with TFTP enabled, and certainly not
2117 without specifying --tftp-root. Doing so can expose any world-
2118 readable file on the server to any host on the net.
2119 --tftp-lowercase
2121 Convert filenames in TFTP requests to all lowercase. This is
2122 useful for requests from Windows machines, which have case-in‐
2123 sensitive filesystems and tend to play fast-and-loose with case
2124 in filenames. Note that dnsmasq's tftp server always converts
2125 "\" to "/" in filenames.
2126 --tftp-max=<connections>
2128 Set the maximum number of concurrent TFTP connections allowed.
2129 This defaults to 50. When serving a large number of TFTP connec‐
2130 tions, per-process file descriptor limits may be encountered.
2131 Dnsmasq needs one file descriptor for each concurrent TFTP con‐
2132 nection and one file descriptor per unique file (plus a few oth‐
2133 ers). So serving the same file simultaneously to n clients will
2134 use require about n + 10 file descriptors, serving different
2135 files simultaneously to n clients will require about (2*n) + 10
2136 descriptors. If --tftp-port-range is given, that can affect the
2137 number of concurrent connections.
2138 --tftp-mtu=<mtu size>
2140 Use size as the ceiling of the MTU supported by the intervening
2141 network when negotiating TFTP blocksize, overriding the MTU set‐
2142 ting of the local interface if it is larger.
2143 --tftp-no-blocksize
2145 Stop the TFTP server from negotiating the "blocksize" option
2146 with a client. Some buggy clients request this option but then
2147 behave badly when it is granted.
2148 --tftp-port-range=<start>,<end>
2150 A TFTP server listens on a well-known port (69) for connection
2151 initiation, but it also uses a dynamically-allocated port for
2152 each connection. Normally these are allocated by the OS, but
2153 this option specifies a range of ports for use by TFTP trans‐
2154 fers. This can be useful when TFTP has to traverse a firewall.
2155 The start of the range cannot be lower than 1025 unless dnsmasq
2156 is running as root. The number of concurrent TFTP connections is
2157 limited by the size of the port range.
2158 --tftp-single-port
2160 Run in a mode where the TFTP server uses ONLY the well-known
2161 port (69) for its end of the TFTP transfer. This allows TFTP to
2162 work when there in NAT is the path between client and server.
2163 Note that this is not strictly compliant with the RFCs specify‐
2164 ing the TFTP protocol: use at your own risk.
2165 -C, --conf-file=<file>
2167 Specify a configuration file. The presence of this option stops
2168 dnsmasq from reading the default configuration file (normally
2169 /etc/dnsmasq.conf). Multiple files may be specified by repeating
2170 the option either on the command line or in configuration files.
2171 A filename of "-" causes dnsmasq to read configuration from
2172 stdin.
2173 -7, --conf-dir=<directory>[,<file-extension>......],
2175 Read all the files in the given directory as configuration
2176 files. If extension(s) are given, any files which end in those
2177 extensions are skipped. Any files whose names end in ~ or start
2178 with . or start and end with # are always skipped. If the exten‐
2179 sion starts with * then only files which have that extension are
2180 loaded. So --conf-dir=/path/to/dir,*.conf loads all files with
2181 the suffix .conf in /path/to/dir. This flag may be given on the
2182 command line or in a configuration file. If giving it on the
2183 command line, be sure to escape * characters. Files are loaded
2184 in alphabetical order of filename.
2185 --servers-file=<file>
2187 A special case of --conf-file which differs in two respects.
2188 Firstly, only --server and --rev-server are allowed in the con‐
2189 figuration file included. Secondly, the file is re-read and the
2190 configuration therein is updated when dnsmasq receives SIGHUP.
2191
2193 At startup, dnsmasq reads /etc/dnsmasq.conf, if it exists. (On FreeBSD,
2194 the file is /usr/local/etc/dnsmasq.conf ) (but see the --conf-file and
2195 --conf-dir options.) The format of this file consists of one option per
2196 line, exactly as the long options detailed in the OPTIONS section but
2197 without the leading "--". Lines starting with # are comments and ig‐
2198 nored. For options which may only be specified once, the configuration
2199 file overrides the command line. Quoting is allowed in a config file:
2200 between " quotes the special meanings of ,:. and # are removed and the
2201 following escapes are allowed: \\ \" \t \e \b \r and \n. The later cor‐
2202 responding to tab, escape, backspace, return and newline.
2203
2205 When it receives a SIGHUP, dnsmasq clears its cache and then re-loads
2206 /etc/hosts and /etc/ethers and any file given by --dhcp-hostsfile,
2207 --dhcp-hostsdir, --dhcp-optsfile, --dhcp-optsdir, --addn-hosts or
2208 --hostsdir. The DHCP lease change script is called for all existing
2209 DHCP leases. If --no-poll is set SIGHUP also re-reads /etc/resolv.conf.
2210 SIGHUP does NOT re-read the configuration file.
2211 When it receives a SIGUSR1, dnsmasq writes statistics to the system
2213 log. It writes the cache size, the number of names which have had to
2214 removed from the cache before they expired in order to make room for
2215 new names and the total number of names that have been inserted into
2216 the cache. The number of cache hits and misses and the number of au‐
2217 thoritative queries answered are also given. For each upstream server
2218 it gives the number of queries sent, and the number which resulted in
2219 an error. In --no-daemon mode or when full logging is enabled (--log-
2220 queries), a complete dump of the contents of the cache is made.
2221 The cache statistics are also available in the DNS as answers to
2223 queries of class CHAOS and type TXT in domain bind. The domain names
2224 are cachesize.bind, insertions.bind, evictions.bind, misses.bind,
2225 hits.bind, auth.bind and servers.bind. An example command to query
2226 this, using the dig utility would be
2227 dig +short chaos txt cachesize.bind
2229 When it receives SIGUSR2 and it is logging direct to a file (see --log-
2232 facility ) dnsmasq will close and reopen the log file. Note that during
2233 this operation, dnsmasq will not be running as root. When it first cre‐
2234 ates the logfile dnsmasq changes the ownership of the file to the non-
2235 root user it will run as. Logrotate should be configured to create a
2236 new log file with the ownership which matches the existing one before
2237 sending SIGUSR2. If TCP DNS queries are in progress, the old logfile
2238 will remain open in child processes which are handling TCP queries and
2239 may continue to be written. There is a limit of 150 seconds, after
2240 which all existing TCP processes will have expired: for this reason, it
2241 is not wise to configure logfile compression for logfiles which have
2242 just been rotated. Using logrotate, the required options are create and
2243 delaycompress.
2244 Dnsmasq is a DNS query forwarder: it is not capable of recursively an‐
2248 swering arbitrary queries starting from the root servers but forwards
2249 such queries to a fully recursive upstream DNS server which is typi‐
2250 cally provided by an ISP. By default, dnsmasq reads /etc/resolv.conf to
2251 discover the IP addresses of the upstream nameservers it should use,
2252 since the information is typically stored there. Unless --no-poll is
2253 used, dnsmasq checks the modification time of /etc/resolv.conf (or
2254 equivalent if --resolv-file is used) and re-reads it if it changes.
2255 This allows the DNS servers to be set dynamically by PPP or DHCP since
2256 both protocols provide the information. Absence of /etc/resolv.conf is
2257 not an error since it may not have been created before a PPP connection
2258 exists. Dnsmasq simply keeps checking in case /etc/resolv.conf is cre‐
2259 ated at any time. Dnsmasq can be told to parse more than one re‐
2260 solv.conf file. This is useful on a laptop, where both PPP and DHCP may
2261 be used: dnsmasq can be set to poll both /etc/ppp/resolv.conf and
2262 /etc/dhcpc/resolv.conf and will use the contents of whichever changed
2263 last, giving automatic switching between DNS servers.
2264 Upstream servers may also be specified on the command line or in the
2266 configuration file. These server specifications optionally take a do‐
2267 main name which tells dnsmasq to use that server only to find names in
2268 that particular domain.
2269 In order to configure dnsmasq to act as cache for the host on which it
2271 is running, put "nameserver 127.0.0.1" in /etc/resolv.conf to force lo‐
2272 cal processes to send queries to dnsmasq. Then either specify the up‐
2273 stream servers directly to dnsmasq using --server options or put their
2274 addresses real in another file, say /etc/resolv.dnsmasq and run dnsmasq
2275 with the --resolv-file /etc/resolv.dnsmasq option. This second tech‐
2276 nique allows for dynamic update of the server addresses by PPP or DHCP.
2277 Addresses in /etc/hosts will "shadow" different addresses for the same
2279 names in the upstream DNS, so "mycompany.com 1.2.3.4" in /etc/hosts
2280 will ensure that queries for "mycompany.com" always return 1.2.3.4 even
2281 if queries in the upstream DNS would otherwise return a different ad‐
2282 dress. There is one exception to this: if the upstream DNS contains a
2283 CNAME which points to a shadowed name, then looking up the CNAME
2284 through dnsmasq will result in the unshadowed address associated with
2285 the target of the CNAME. To work around this, add the CNAME to
2286 /etc/hosts so that the CNAME is shadowed too.
2287 The tag system works as follows: For each DHCP request, dnsmasq col‐
2290 lects a set of valid tags from active configuration lines which include
2291 set:<tag>, including one from the --dhcp-range used to allocate the ad‐
2292 dress, one from any matching --dhcp-host (and "known" or "known-other‐
2293 net" if a --dhcp-host matches) The tag "bootp" is set for BOOTP re‐
2294 quests, and a tag whose name is the name of the interface on which the
2295 request arrived is also set.
2296 Any configuration lines which include one or more tag:<tag> constructs
2298 will only be valid if all that tags are matched in the set derived
2299 above. Typically this is --dhcp-option. --dhcp-option which has tags
2300 will be used in preference to an untagged --dhcp-option, provided that
2301 _all_ the tags match somewhere in the set collected as described above.
2302 The prefix '!' on a tag means 'not' so --dhcp-option=tag:!pur‐
2303 ple,3,1.2.3.4 sends the option when the tag purple is not in the set of
2304 valid tags. (If using this in a command line rather than a configura‐
2305 tion file, be sure to escape !, which is a shell metacharacter)
2306 When selecting --dhcp-options, a tag from --dhcp-range is second class
2308 relative to other tags, to make it easy to override options for indi‐
2309 vidual hosts, so --dhcp-range=set:interface1,...... --dhcp-
2310 host=set:myhost,..... --dhcp-option=tag:interface1,option:nis-do‐
2311 main,"domain1" --dhcp-option=tag:myhost,option:nis-domain,"domain2"
2312 will set the NIS-domain to domain1 for hosts in the range, but override
2313 that to domain2 for a particular host.
2314 Note that for --dhcp-range both tag:<tag> and set:<tag> are allowed, to
2317 both select the range in use based on (eg) --dhcp-host, and to affect
2318 the options sent, based on the range selected.
2319 This system evolved from an earlier, more limited one and for backward
2321 compatibility "net:" may be used instead of "tag:" and "set:" may be
2322 omitted. (Except in --dhcp-host, where "net:" may be used instead of
2323 "set:".) For the same reason, '#' may be used instead of '!' to indi‐
2324 cate NOT.
2325 The DHCP server in dnsmasq will function as a BOOTP server also, pro‐
2327 vided that the MAC address and IP address for clients are given, either
2328 using --dhcp-host configurations or in /etc/ethers , and a --dhcp-range
2329 configuration option is present to activate the DHCP server on a par‐
2330 ticular network. (Setting --bootp-dynamic removes the need for static
2331 address mappings.) The filename parameter in a BOOTP request is used as
2332 a tag, as is the tag "bootp", allowing some control over the options
2333 returned to different classes of hosts.
2334
2337 Configuring dnsmasq to act as an authoritative DNS server is compli‐
2338 cated by the fact that it involves configuration of external DNS
2339 servers to provide delegation. We will walk through three scenarios of
2340 increasing complexity. Prerequisites for all of these scenarios are a
2341 globally accessible IP address, an A or AAAA record pointing to that
2342 address, and an external DNS server capable of doing delegation of the
2343 zone in question. For the first part of this explanation, we will call
2344 the A (or AAAA) record for the globally accessible address server.exam‐
2345 ple.com, and the zone for which dnsmasq is authoritative our.zone.com.
2346 The simplest configuration consists of two lines of dnsmasq configura‐
2348 tion; something like
2349 --auth-server=server.example.com,eth0
2351 --auth-zone=our.zone.com,1.2.3.0/24
2352 and two records in the external DNS
2354 server.example.com A 192.0.43.10
2356 our.zone.com NS server.example.com
2357 eth0 is the external network interface on which dnsmasq is listening,
2359 and has (globally accessible) address 192.0.43.10.
2360 Note that the external IP address may well be dynamic (ie assigned from
2362 an ISP by DHCP or PPP) If so, the A record must be linked to this dy‐
2363 namic assignment by one of the usual dynamic-DNS systems.
2364 A more complex, but practically useful configuration has the address
2366 record for the globally accessible IP address residing in the authori‐
2367 tative zone which dnsmasq is serving, typically at the root. Now we
2368 have
2369 --auth-server=our.zone.com,eth0
2371 --auth-zone=our.zone.com,1.2.3.0/24
2372 our.zone.com A 1.2.3.4
2374 our.zone.com NS our.zone.com
2375 The A record for our.zone.com has now become a glue record, it solves
2377 the chicken-and-egg problem of finding the IP address of the nameserver
2378 for our.zone.com when the A record is within that zone. Note that this
2379 is the only role of this record: as dnsmasq is now authoritative from
2380 our.zone.com it too must provide this record. If the external address
2381 is static, this can be done with an /etc/hosts entry or --host-record.
2382 --auth-server=our.zone.com,eth0
2384 --host-record=our.zone.com,1.2.3.4
2385 --auth-zone=our.zone.com,1.2.3.0/24
2386 If the external address is dynamic, the address associated with
2388 our.zone.com must be derived from the address of the relevant inter‐
2389 face. This is done using --interface-name Something like:
2390 --auth-server=our.zone.com,eth0
2392 --interface-name=our.zone.com,eth0
2393 --auth-zone=our.zone.com,1.2.3.0/24,eth0
2394 (The "eth0" argument in --auth-zone adds the subnet containing eth0's
2396 dynamic address to the zone, so that the --interface-name returns the
2397 address in outside queries.)
2398 Our final configuration builds on that above, but also adds a secondary
2400 DNS server. This is another DNS server which learns the DNS data for
2401 the zone by doing zones transfer, and acts as a backup should the pri‐
2402 mary server become inaccessible. The configuration of the secondary is
2403 beyond the scope of this man-page, but the extra configuration of dns‐
2404 masq is simple:
2405 --auth-sec-servers=secondary.myisp.com
2407 and
2409 our.zone.com NS secondary.myisp.com
2411 Adding auth-sec-servers enables zone transfer in dnsmasq, to allow the
2413 secondary to collect the DNS data. If you wish to restrict this data to
2414 particular hosts then
2415 --auth-peer=<IP address of secondary>
2417 will do so.
2419 Dnsmasq acts as an authoritative server for in-addr.arpa and ip6.arpa
2421 domains associated with the subnets given in --auth-zone declarations,
2422 so reverse (address to name) lookups can be simply configured with a
2423 suitable NS record, for instance in this example, where we allow
2424 1.2.3.0/24 addresses.
2425 3.2.1.in-addr.arpa NS our.zone.com
2427 Note that at present, reverse (in-addr.arpa and ip6.arpa) zones are not
2429 available in zone transfers, so there is no point arranging secondary
2430 servers for reverse lookups.
2431 When dnsmasq is configured to act as an authoritative server, the fol‐
2434 lowing data is used to populate the authoritative zone.
2435 --mx-host, --srv-host, --dns-rr, --txt-record, --naptr-record, --caa-
2437 record, as long as the record names are in the authoritative domain.
2438 --synth-domain as long as the domain is in the authoritative zone and,
2440 for reverse (PTR) queries, the address is in the relevant subnet.
2441 --cname as long as the record name is in the authoritative domain. If
2443 the target of the CNAME is unqualified, then it is qualified with the
2444 authoritative zone name. CNAME used in this way (only) may be wild‐
2445 cards, as in
2446 --cname=*.example.com,default.example.com
2448 IPv4 and IPv6 addresses from /etc/hosts (and --addn-hosts ) and --host-
2451 record and --interface-name and ---dynamic-host provided the address
2452 falls into one of the subnets specified in the --auth-zone.
2453 Addresses of DHCP leases, provided the address falls into one of the
2455 subnets specified in the --auth-zone. (If constructed DHCP ranges are
2456 is use, which depend on the address dynamically assigned to an inter‐
2457 face, then the form of --auth-zone which defines subnets by the dynamic
2458 address of an interface should be used to ensure this condition is
2459 met.)
2460 In the default mode, where a DHCP lease has an unqualified name, and
2462 possibly a qualified name constructed using --domain then the name in
2463 the authoritative zone is constructed from the unqualified name and the
2464 zone's domain. This may or may not equal that specified by --domain.
2465 If --dhcp-fqdn is set, then the fully qualified names associated with
2466 DHCP leases are used, and must match the zone's domain.
2467
2472 0 - Dnsmasq successfully forked into the background, or terminated nor‐
2473 mally if backgrounding is not enabled.
2474 1 - A problem with configuration was detected.
2476 2 - A problem with network access occurred (address in use, attempt to
2478 use privileged ports without permission).
2479 3 - A problem occurred with a filesystem operation (missing file/direc‐
2481 tory, permissions).
2482 4 - Memory allocation failure.
2484 5 - Other miscellaneous problem.
2486 11 or greater - a non zero return code was received from the lease-
2488 script process "init" call. The exit code from dnsmasq is the script's
2489 exit code with 10 added.
2490
2493 The default values for resource limits in dnsmasq are generally conser‐
2494 vative, and appropriate for embedded router type devices with slow pro‐
2495 cessors and limited memory. On more capable hardware, it is possible to
2496 increase the limits, and handle many more clients. The following ap‐
2497 plies to dnsmasq-2.37: earlier versions did not scale as well.
2498 Dnsmasq is capable of handling DNS and DHCP for at least a thousand
2501 clients. The DHCP lease times should not be very short (less than one
2502 hour). The value of --dns-forward-max can be increased: start with it
2503 equal to the number of clients and increase if DNS seems slow. Note
2504 that DNS performance depends too on the performance of the upstream
2505 nameservers. The size of the DNS cache may be increased: the hard limit
2506 is 10000 names and the default (150) is very low. Sending SIGUSR1 to
2507 dnsmasq makes it log information which is useful for tuning the cache
2508 size. See the NOTES section for details.
2509 The built-in TFTP server is capable of many simultaneous file trans‐
2512 fers: the absolute limit is related to the number of file-handles al‐
2513 lowed to a process and the ability of the select() system call to cope
2514 with large numbers of file handles. If the limit is set too high using
2515 --tftp-max it will be scaled down and the actual limit logged at start-
2516 up. Note that more transfers are possible when the same file is being
2517 sent than when each transfer sends a different file.
2518 It is possible to use dnsmasq to block Web advertising by using a list
2521 of known banner-ad servers, all resolving to 127.0.0.1 or 0.0.0.0, in
2522 /etc/hosts or an additional hosts file. The list can be very long, dns‐
2523 masq has been tested successfully with one million names. That size
2524 file needs a 1GHz processor and about 60Mb of RAM.
2525
2528 Dnsmasq can be compiled to support internationalisation. To do this,
2529 the make targets "all-i18n" and "install-i18n" should be used instead
2530 of the standard targets "all" and "install". When internationalisation
2531 is compiled in, dnsmasq will produce log messages in the local language
2532 and support internationalised domain names (IDN). Domain names in
2533 /etc/hosts, /etc/ethers and /etc/dnsmasq.conf which contain non-ASCII
2534 characters will be translated to the DNS-internal punycode representa‐
2535 tion. Note that dnsmasq determines both the language for messages and
2536 the assumed charset for configuration files from the LANG environment
2537 variable. This should be set to the system default value by the script
2538 which is responsible for starting dnsmasq. When editing the configura‐
2539 tion files, be careful to do so using only the system-default locale
2540 and not user-specific one, since dnsmasq has no direct way of determin‐
2541 ing the charset in use, and must assume that it is the system default.
2542
2545 /etc/dnsmasq.conf
2546 /usr/local/etc/dnsmasq.conf
2548 /etc/resolv.conf /var/run/dnsmasq/resolv.conf /etc/ppp/resolv.conf
2550 /etc/dhcpc/resolv.conf
2551 /etc/hosts
2553 /etc/ethers
2555 /var/lib/dnsmasq/dnsmasq.leases
2557 /var/db/dnsmasq.leases
2559 /var/run/dnsmasq.pid
2561
2563 hosts(5), resolver(5)
2564
2566 This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.
2567 2021-08-16 DNSMASQ(8)