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