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-ip>|<inter‐
455 face>[#<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. If a dnsmasq instance is configured such that different
744 results may be encountered, caching should be disabled.
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 The minimum lease time is two minutes. For IPv6 ranges, the
950 lease time maybe "deprecated"; this sets the preferred lifetime
951 sent in a DHCP lease or router advertisement to zero, which
952 causes clients to use other addresses, if available, for new
953 connections as a prelude to renumbering.
954 This option may be repeated, with different addresses, to enable
956 DHCP service to more than one network. For directly connected
957 networks (ie, networks on which the machine running dnsmasq has
958 an interface) the netmask is optional: dnsmasq will determine it
959 from the interface configuration. For networks which receive
960 DHCP service via a relay agent, dnsmasq cannot determine the
961 netmask itself, so it should be specified, otherwise dnsmasq
962 will have to guess, based on the class (A, B or C) of the net‐
963 work address. The broadcast address is always optional. It is
964 always allowed to have more than one --dhcp-range in a single
965 subnet.
966 For IPv6, the parameters are slightly different: instead of net‐
968 mask and broadcast address, there is an optional prefix length
969 which must be equal to or larger then the prefix length on the
970 local interface. If not given, this defaults to 64. Unlike the
971 IPv4 case, the prefix length is not automatically derived from
972 the interface configuration. The minimum size of the prefix
973 length is 64.
974 IPv6 (only) supports another type of range. In this, the start
976 address and optional end address contain only the network part
977 (ie ::1) and they are followed by constructor:<interface>. This
978 forms a template which describes how to create ranges, based on
979 the addresses assigned to the interface. For instance
980 --dhcp-range=::1,::400,constructor:eth0
982 will look for addresses on eth0 and then create a range from
984 <network>::1 to <network>::400. If the interface is assigned
985 more than one network, then the corresponding ranges will be
986 automatically created, and then deprecated and finally removed
987 again as the address is deprecated and then deleted. The inter‐
988 face name may have a final "*" wildcard. Note that just any
989 address on eth0 will not do: it must not be an autoconfigured or
990 privacy address, or be deprecated.
991 If a --dhcp-range is only being used for stateless DHCP and/or
993 SLAAC, then the address can be simply ::
994 --dhcp-range=::,constructor:eth0
996 The optional set:<tag> sets an alphanumeric label which marks
999 this network so that DHCP options may be specified on a per-net‐
1000 work basis. When it is prefixed with 'tag:' instead, then its
1001 meaning changes from setting a tag to matching it. Only one tag
1002 may be set, but more than one tag may be matched.
1003 The optional <mode> keyword may be static which tells dnsmasq to
1005 enable DHCP for the network specified, but not to dynamically
1006 allocate IP addresses: only hosts which have static addresses
1007 given via --dhcp-host or from /etc/ethers will be served. A
1008 static-only subnet with address all zeros may be used as a
1009 "catch-all" address to enable replies to all Information-request
1010 packets on a subnet which is provided with stateless DHCPv6, ie
1011 --dhcp-range=::,static
1012 For IPv4, the <mode> may be proxy in which case dnsmasq will
1014 provide proxy-DHCP on the specified subnet. (See --pxe-prompt
1015 and --pxe-service for details.)
1016 For IPv6, the mode may be some combination of ra-only, slaac,
1018 ra-names, ra-stateless, ra-advrouter, off-link.
1019 ra-only tells dnsmasq to offer Router Advertisement only on this
1021 subnet, and not DHCP.
1022 slaac tells dnsmasq to offer Router Advertisement on this subnet
1024 and to set the A bit in the router advertisement, so that the
1025 client will use SLAAC addresses. When used with a DHCP range or
1026 static DHCP address this results in the client having both a
1027 DHCP-assigned and a SLAAC address.
1028 ra-stateless sends router advertisements with the O and A bits
1030 set, and provides a stateless DHCP service. The client will use
1031 a SLAAC address, and use DHCP for other configuration informa‐
1032 tion.
1033 ra-names enables a mode which gives DNS names to dual-stack
1035 hosts which do SLAAC for IPv6. Dnsmasq uses the host's IPv4
1036 lease to derive the name, network segment and MAC address and
1037 assumes that the host will also have an IPv6 address calculated
1038 using the SLAAC algorithm, on the same network segment. The
1039 address is pinged, and if a reply is received, an AAAA record is
1040 added to the DNS for this IPv6 address. Note that this is only
1041 happens for directly-connected networks, (not one doing DHCP via
1042 a relay) and it will not work if a host is using privacy exten‐
1043 sions. ra-names can be combined with ra-stateless and slaac.
1044 ra-advrouter enables a mode where router address(es) rather than
1046 prefix(es) are included in the advertisements. This is
1047 described in RFC-3775 section 7.2 and is used in mobile IPv6. In
1048 this mode the interval option is also included, as described in
1049 RFC-3775 section 7.3.
1050 off-link tells dnsmasq to advertise the prefix without the on-
1052 link (aka L) bit set.
1053 -G, --dhcp-
1056 host=[<hwaddr>][,id:<client_id>|*][,set:<tag>][tag:<tag>][,<ipaddr>][,<host‐
1057 name>][,<lease_time>][,ignore]
1058 Specify per host parameters for the DHCP server. This allows a
1059 machine with a particular hardware address to be always allo‐
1060 cated the same hostname, IP address and lease time. A hostname
1061 specified like this overrides any supplied by the DHCP client on
1062 the machine. It is also allowable to omit the hardware address
1063 and include the hostname, in which case the IP address and lease
1064 times will apply to any machine claiming that name. For example
1065 --dhcp-host=00:20:e0:3b:13:af,wap,infinite tells dnsmasq to give
1066 the machine with hardware address 00:20:e0:3b:13:af the name
1067 wap, and an infinite DHCP lease. --dhcp-host=lap,192.168.0.199
1068 tells dnsmasq to always allocate the machine lap the IP address
1069 192.168.0.199.
1070 Addresses allocated like this are not constrained to be in the
1072 range given by the --dhcp-range option, but they must be in the
1073 same subnet as some valid dhcp-range. For subnets which don't
1074 need a pool of dynamically allocated addresses, use the "static"
1075 keyword in the --dhcp-range declaration.
1076 It is allowed to use client identifiers (called client DUID in
1078 IPv6-land) rather than hardware addresses to identify hosts by
1079 prefixing with 'id:'. Thus: --dhcp-host=id:01:02:03:04,.....
1080 refers to the host with client identifier 01:02:03:04. It is
1081 also allowed to specify the client ID as text, like this:
1082 --dhcp-host=id:clientidastext,.....
1083 A single --dhcp-host may contain an IPv4 address or one or more
1085 IPv6 addresses, or both. IPv6 addresses must be bracketed by
1086 square brackets thus: --dhcp-host=laptop,[1234::56] IPv6
1087 addresses may contain only the host-identifier part: --dhcp-
1088 host=laptop,[::56] in which case they act as wildcards in con‐
1089 structed DHCP ranges, with the appropriate network part
1090 inserted. For IPv6, an address may include a prefix length:
1091 --dhcp-host=laptop,[1234:50/126] which (in this case) specifies
1092 four addresses, 1234::50 to 1234::53. This (an the ability to
1093 specify multiple addresses) is useful when a host presents
1094 either a consistent name or hardware-ID, but varying DUIDs,
1095 since it allows dnsmasq to honour the static address allocation
1096 but assign a different adddress for each DUID. This typically
1097 occurs when chain netbooting, as each stage of the chain gets in
1098 turn allocates an address.
1099 Note that in IPv6 DHCP, the hardware address may not be avail‐
1101 able, though it normally is for direct-connected clients, or
1102 clients using DHCP relays which support RFC 6939.
1103 For DHCPv4, the special option id:* means "ignore any client-id
1106 and use MAC addresses only." This is useful when a client
1107 presents a client-id sometimes but not others.
1108 If a name appears in /etc/hosts, the associated address can be
1110 allocated to a DHCP lease, but only if a --dhcp-host option
1111 specifying the name also exists. Only one hostname can be given
1112 in a --dhcp-host option, but aliases are possible by using
1113 CNAMEs. (See --cname ).
1114 The special keyword "ignore" tells dnsmasq to never offer a DHCP
1116 lease to a machine. The machine can be specified by hardware
1117 address, client ID or hostname, for instance --dhcp-
1118 host=00:20:e0:3b:13:af,ignore This is useful when there is
1119 another DHCP server on the network which should be used by some
1120 machines.
1121 The set:<tag> construct sets the tag whenever this --dhcp-host
1123 directive is in use. This can be used to selectively send DHCP
1124 options just for this host. More than one tag can be set in a
1125 --dhcp-host directive (but not in other places where "set:<tag>"
1126 is allowed). When a host matches any --dhcp-host directive (or
1127 one implied by /etc/ethers) then the special tag "known" is set.
1128 This allows dnsmasq to be configured to ignore requests from
1129 unknown machines using --dhcp-ignore=tag:!known If the host
1130 matches only a --dhcp-host directive which cannot be used
1131 because it specifies an address on different subnet, the tag
1132 "known-othernet" is set.
1133 The tag:<tag> construct filters which dhcp-host directives are
1135 used. Tagged directives are used in preference to untagged ones.
1136 Ethernet addresses (but not client-ids) may have wildcard bytes,
1138 so for example --dhcp-host=00:20:e0:3b:13:*,ignore will cause
1139 dnsmasq to ignore a range of hardware addresses. Note that the
1140 "*" will need to be escaped or quoted on a command line, but not
1141 in the configuration file.
1142 Hardware addresses normally match any network (ARP) type, but it
1144 is possible to restrict them to a single ARP type by preceding
1145 them with the ARP-type (in HEX) and "-". so --dhcp-
1146 host=06-00:20:e0:3b:13:af,1.2.3.4 will only match a Token-Ring
1147 hardware address, since the ARP-address type for token ring is
1148 6.
1149 As a special case, in DHCPv4, it is possible to include more
1151 than one hardware address. eg: --dhcp-
1152 host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2 This allows
1153 an IP address to be associated with multiple hardware addresses,
1154 and gives dnsmasq permission to abandon a DHCP lease to one of
1155 the hardware addresses when another one asks for a lease. Beware
1156 that this is a dangerous thing to do, it will only work reliably
1157 if only one of the hardware addresses is active at any time and
1158 there is no way for dnsmasq to enforce this. It is, for
1159 instance, useful to allocate a stable IP address to a laptop
1160 which has both wired and wireless interfaces.
1161 --dhcp-hostsfile=<path>
1163 Read DHCP host information from the specified file. If a direc‐
1164 tory is given, then read all the files contained in that direc‐
1165 tory. The file contains information about one host per line. The
1166 format of a line is the same as text to the right of '=' in
1167 --dhcp-host. The advantage of storing DHCP host information in
1168 this file is that it can be changed without re-starting dnsmasq:
1169 the file will be re-read when dnsmasq receives SIGHUP.
1170 --dhcp-optsfile=<path>
1172 Read DHCP option information from the specified file. If a
1173 directory is given, then read all the files contained in that
1174 directory. The advantage of using this option is the same as for
1175 --dhcp-hostsfile: the --dhcp-optsfile will be re-read when dns‐
1176 masq receives SIGHUP. Note that it is possible to encode the
1177 information in a --dhcp-boot flag as DHCP options, using the
1178 options names bootfile-name, server-ip-address and tftp-server.
1179 This allows these to be included in a --dhcp-optsfile.
1180 --dhcp-hostsdir=<path>
1182 This is equivalent to --dhcp-hostsfile, except for the follow‐
1183 ing. The path MUST be a directory, and not an individual file.
1184 Changed or new files within the directory are read automati‐
1185 cally, without the need to send SIGHUP. If a file is deleted or
1186 changed after it has been read by dnsmasq, then the host record
1187 it contained will remain until dnsmasq receives a SIGHUP, or is
1188 restarted; ie host records are only added dynamically.
1189 --dhcp-optsdir=<path>
1191 This is equivalent to --dhcp-optsfile, with the differences
1192 noted for --dhcp-hostsdir.
1193 -Z, --read-ethers
1195 Read /etc/ethers for information about hosts for the DHCP
1196 server. The format of /etc/ethers is a hardware address, fol‐
1197 lowed by either a hostname or dotted-quad IP address. When read
1198 by dnsmasq these lines have exactly the same effect as --dhcp-
1199 host options containing the same information. /etc/ethers is re-
1200 read when dnsmasq receives SIGHUP. IPv6 addresses are NOT read
1201 from /etc/ethers.
1202 -O, --dhcp-option=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-
1204 encap:<enterprise>,][vendor:[<vendor-class>],][<opt>|option:<opt-
1205 name>|option6:<opt>|option6:<opt-name>],[<value>[,<value>]]
1206 Specify different or extra options to DHCP clients. By default,
1207 dnsmasq sends some standard options to DHCP clients, the netmask
1208 and broadcast address are set to the same as the host running
1209 dnsmasq, and the DNS server and default route are set to the
1210 address of the machine running dnsmasq. (Equivalent rules apply
1211 for IPv6.) If the domain name option has been set, that is sent.
1212 This configuration allows these defaults to be overridden, or
1213 other options specified. The option, to be sent may be given as
1214 a decimal number or as "option:<option-name>" The option numbers
1215 are specified in RFC2132 and subsequent RFCs. The set of option-
1216 names known by dnsmasq can be discovered by running "dnsmasq
1217 --help dhcp". For example, to set the default route option to
1218 192.168.4.4, do --dhcp-option=3,192.168.4.4 or --dhcp-option =
1219 option:router, 192.168.4.4 and to set the time-server address to
1220 192.168.0.4, do --dhcp-option = 42,192.168.0.4 or --dhcp-option
1221 = option:ntp-server, 192.168.0.4 The special address 0.0.0.0 is
1222 taken to mean "the address of the machine running dnsmasq".
1223 Data types allowed are comma separated dotted-quad IPv4
1225 addresses, []-wrapped IPv6 addresses, a decimal number, colon-
1226 separated hex digits and a text string. If the optional tags are
1227 given then this option is only sent when all the tags are
1228 matched.
1229 Special processing is done on a text argument for option 119, to
1231 conform with RFC 3397. Text or dotted-quad IP addresses as argu‐
1232 ments to option 120 are handled as per RFC 3361. Dotted-quad IP
1233 addresses which are followed by a slash and then a netmask size
1234 are encoded as described in RFC 3442.
1235 IPv6 options are specified using the option6: keyword, followed
1237 by the option number or option name. The IPv6 option name space
1238 is disjoint from the IPv4 option name space. IPv6 addresses in
1239 options must be bracketed with square brackets, eg. --dhcp-
1240 option=option6:ntp-server,[1234::56] For IPv6, [::] means "the
1241 global address of the machine running dnsmasq", whilst [fd00::]
1242 is replaced with the ULA, if it exists, and [fe80::] with the
1243 link-local address.
1244 Be careful: no checking is done that the correct type of data
1246 for the option number is sent, it is quite possible to persuade
1247 dnsmasq to generate illegal DHCP packets with injudicious use of
1248 this flag. When the value is a decimal number, dnsmasq must
1249 determine how large the data item is. It does this by examining
1250 the option number and/or the value, but can be overridden by
1251 appending a single letter flag as follows: b = one byte, s = two
1252 bytes, i = four bytes. This is mainly useful with encapsulated
1253 vendor class options (see below) where dnsmasq cannot determine
1254 data size from the option number. Option data which consists
1255 solely of periods and digits will be interpreted by dnsmasq as
1256 an IP address, and inserted into an option as such. To force a
1257 literal string, use quotes. For instance when using option 66 to
1258 send a literal IP address as TFTP server name, it is necessary
1259 to do --dhcp-option=66,"1.2.3.4"
1260 Encapsulated Vendor-class options may also be specified (IPv4
1262 only) using --dhcp-option: for instance --dhcp-option=ven‐
1263 dor:PXEClient,1,0.0.0.0 sends the encapsulated vendor class-spe‐
1264 cific option "mftp-address=0.0.0.0" to any client whose vendor-
1265 class matches "PXEClient". The vendor-class matching is sub‐
1266 string based (see --dhcp-vendorclass for details). If a vendor-
1267 class option (number 60) is sent by dnsmasq, then that is used
1268 for selecting encapsulated options in preference to any sent by
1269 the client. It is possible to omit the vendorclass completely;
1270 --dhcp-option=vendor:,1,0.0.0.0 in which case the encapsulated
1271 option is always sent.
1272 Options may be encapsulated (IPv4 only) within other options:
1274 for instance --dhcp-option=encap:175, 190, iscsi-client0 will
1275 send option 175, within which is the option 190. If multiple
1276 options are given which are encapsulated with the same option
1277 number then they will be correctly combined into one encapsu‐
1278 lated option. encap: and vendor: are may not both be set in the
1279 same --dhcp-option.
1280 The final variant on encapsulated options is "Vendor-Identifying
1282 Vendor Options" as specified by RFC3925. These are denoted like
1283 this: --dhcp-option=vi-encap:2, 10, text The number in the vi-
1284 encap: section is the IANA enterprise number used to identify
1285 this option. This form of encapsulation is supported in IPv6.
1286 The address 0.0.0.0 is not treated specially in encapsulated
1288 options.
1289 --dhcp-option-force=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-
1291 encap:<enterprise>,][vendor:[<vendor-class>],]<opt>,[<value>[,<value>]]
1292 This works in exactly the same way as --dhcp-option except that
1293 the option will always be sent, even if the client does not ask
1294 for it in the parameter request list. This is sometimes needed,
1295 for example when sending options to PXELinux.
1296 --dhcp-no-override
1298 (IPv4 only) Disable re-use of the DHCP servername and filename
1299 fields as extra option space. If it can, dnsmasq moves the boot
1300 server and filename information (from --dhcp-boot) out of their
1301 dedicated fields into DHCP options. This make extra space avail‐
1302 able in the DHCP packet for options but can, rarely, confuse old
1303 or broken clients. This flag forces "simple and safe" behaviour
1304 to avoid problems in such a case.
1305 --dhcp-relay=<local address>,<server address>[,<interface]
1307 Configure dnsmasq to do DHCP relay. The local address is an
1308 address allocated to an interface on the host running dnsmasq.
1309 All DHCP requests arriving on that interface will we relayed to
1310 a remote DHCP server at the server address. It is possible to
1311 relay from a single local address to multiple remote servers by
1312 using multiple --dhcp-relay configs with the same local address
1313 and different server addresses. A server address must be an IP
1314 literal address, not a domain name. In the case of DHCPv6, the
1315 server address may be the ALL_SERVERS multicast address,
1316 ff05::1:3. In this case the interface must be given, not be
1317 wildcard, and is used to direct the multicast to the correct
1318 interface to reach the DHCP server.
1319 Access control for DHCP clients has the same rules as for the
1321 DHCP server, see --interface, --except-interface, etc. The
1322 optional interface name in the --dhcp-relay config has a differ‐
1323 ent function: it controls on which interface DHCP replies from
1324 the server will be accepted. This is intended for configurations
1325 which have three interfaces: one being relayed from, a second
1326 connecting the DHCP server, and a third untrusted network, typi‐
1327 cally the wider internet. It avoids the possibility of spoof
1328 replies arriving via this third interface.
1329 It is allowed to have dnsmasq act as a DHCP server on one set of
1331 interfaces and relay from a disjoint set of interfaces. Note
1332 that whilst it is quite possible to write configurations which
1333 appear to act as a server and a relay on the same interface,
1334 this is not supported: the relay function will take precedence.
1335 Both DHCPv4 and DHCPv6 relay is supported. It's not possible to
1337 relay DHCPv4 to a DHCPv6 server or vice-versa.
1338 -U, --dhcp-vendorclass=set:<tag>,[enterprise:<IANA-enterprise num‐
1340 ber>,]<vendor-class>
1341 Map from a vendor-class string to a tag. Most DHCP clients pro‐
1342 vide a "vendor class" which represents, in some sense, the type
1343 of host. This option maps vendor classes to tags, so that DHCP
1344 options may be selectively delivered to different classes of
1345 hosts. For example --dhcp-vendorclass=set:printers,Hewlett-
1346 Packard JetDirect will allow options to be set only for HP
1347 printers like so: --dhcp-option=tag:printers,3,192.168.4.4 The
1348 vendor-class string is substring matched against the vendor-
1349 class supplied by the client, to allow fuzzy matching. The set:
1350 prefix is optional but allowed for consistency.
1351 Note that in IPv6 only, vendorclasses are namespaced with an
1353 IANA-allocated enterprise number. This is given with enterprise:
1354 keyword and specifies that only vendorclasses matching the spec‐
1355 ified number should be searched.
1356 -j, --dhcp-userclass=set:<tag>,<user-class>
1358 Map from a user-class string to a tag (with substring matching,
1359 like vendor classes). Most DHCP clients provide a "user class"
1360 which is configurable. This option maps user classes to tags, so
1361 that DHCP options may be selectively delivered to different
1362 classes of hosts. It is possible, for instance to use this to
1363 set a different printer server for hosts in the class "accounts"
1364 than for hosts in the class "engineering".
1365 -4, --dhcp-mac=set:<tag>,<MAC address>
1367 Map from a MAC address to a tag. The MAC address may include
1368 wildcards. For example --dhcp-mac=set:3com,01:34:23:*:*:* will
1369 set the tag "3com" for any host whose MAC address matches the
1370 pattern.
1371 --dhcp-circuitid=set:<tag>,<circuit-id>, --dhcp-
1373 remoteid=set:<tag>,<remote-id>
1374 Map from RFC3046 relay agent options to tags. This data may be
1375 provided by DHCP relay agents. The circuit-id or remote-id is
1376 normally given as colon-separated hex, but is also allowed to be
1377 a simple string. If an exact match is achieved between the cir‐
1378 cuit or agent ID and one provided by a relay agent, the tag is
1379 set.
1380 --dhcp-remoteid (but not --dhcp-circuitid) is supported in IPv6.
1382 --dhcp-subscrid=set:<tag>,<subscriber-id>
1384 (IPv4 and IPv6) Map from RFC3993 subscriber-id relay agent
1385 options to tags.
1386 --dhcp-proxy[=<ip addr>]......
1388 (IPv4 only) A normal DHCP relay agent is only used to forward
1389 the initial parts of a DHCP interaction to the DHCP server. Once
1390 a client is configured, it communicates directly with the
1391 server. This is undesirable if the relay agent is adding extra
1392 information to the DHCP packets, such as that used by --dhcp-
1393 circuitid and --dhcp-remoteid. A full relay implementation can
1394 use the RFC 5107 serverid-override option to force the DHCP
1395 server to use the relay as a full proxy, with all packets pass‐
1396 ing through it. This flag provides an alternative method of
1397 doing the same thing, for relays which don't support RFC 5107.
1398 Given alone, it manipulates the server-id for all interactions
1399 via relays. If a list of IP addresses is given, only interac‐
1400 tions via relays at those addresses are affected.
1401 --dhcp-match=set:<tag>,<option number>|option:<option name>|vi-
1403 encap:<enterprise>[,<value>]
1404 Without a value, set the tag if the client sends a DHCP option
1405 of the given number or name. When a value is given, set the tag
1406 only if the option is sent and matches the value. The value may
1407 be of the form "01:ff:*:02" in which case the value must match
1408 (apart from wildcards) but the option sent may have unmatched
1409 data past the end of the value. The value may also be of the
1410 same form as in --dhcp-option in which case the option sent is
1411 treated as an array, and one element must match, so --dhcp-
1412 match=set:efi-ia32,option:client-arch,6 will set the tag "efi-
1413 ia32" if the the number 6 appears in the list of architectures
1414 sent by the client in option 93. (See RFC 4578 for details.) If
1415 the value is a string, substring matching is used.
1416 The special form with vi-encap:<enterprise number> matches
1418 against vendor-identifying vendor classes for the specified
1419 enterprise. Please see RFC 3925 for more details of these rare
1420 and interesting beasts.
1421 --dhcp-name-match=set:<tag>,<name>[*]
1423 Set the tag if the given name is supplied by a DHCP client.
1424 There may be a single trailing wildcard *, which has the usual
1425 meaning. Combined with dhcp-ignore or dhcp-ignore-names this
1426 gives the ability to ignore certain clients by name, or disallow
1427 certain hostnames from being claimed by a client.
1428 --tag-if=set:<tag>[,set:<tag>[,tag:<tag>[,tag:<tag>]]]
1430 Perform boolean operations on tags. Any tag appearing as
1431 set:<tag> is set if all the tags which appear as tag:<tag> are
1432 set, (or unset when tag:!<tag> is used) If no tag:<tag> appears
1433 set:<tag> tags are set unconditionally. Any number of set: and
1434 tag: forms may appear, in any order. --tag-if lines are exe‐
1435 cuted in order, so if the tag in tag:<tag> is a tag set by
1436 another --tag-if, the line which sets the tag must precede the
1437 one which tests it.
1438 -J, --dhcp-ignore=tag:<tag>[,tag:<tag>]
1440 When all the given tags appear in the tag set ignore the host
1441 and do not allocate it a DHCP lease.
1442 --dhcp-ignore-names[=tag:<tag>[,tag:<tag>]]
1444 When all the given tags appear in the tag set, ignore any host‐
1445 name provided by the host. Note that, unlike --dhcp-ignore, it
1446 is permissible to supply no tags, in which case DHCP-client sup‐
1447 plied hostnames are always ignored, and DHCP hosts are added to
1448 the DNS using only --dhcp-host configuration in dnsmasq and the
1449 contents of /etc/hosts and /etc/ethers.
1450 --dhcp-generate-names=tag:<tag>[,tag:<tag>]
1452 (IPv4 only) Generate a name for DHCP clients which do not other‐
1453 wise have one, using the MAC address expressed in hex, separated
1454 by dashes. Note that if a host provides a name, it will be used
1455 by preference to this, unless --dhcp-ignore-names is set.
1456 --dhcp-broadcast[=tag:<tag>[,tag:<tag>]]
1458 (IPv4 only) When all the given tags appear in the tag set,
1459 always use broadcast to communicate with the host when it is
1460 unconfigured. It is permissible to supply no tags, in which case
1461 this is unconditional. Most DHCP clients which need broadcast
1462 replies set a flag in their requests so that this happens auto‐
1463 matically, some old BOOTP clients do not.
1464 -M, --dhcp-boot=[tag:<tag>,]<filename>,[<servername>[,<server
1466 address>|<tftp_servername>]]
1467 (IPv4 only) Set BOOTP options to be returned by the DHCP server.
1468 Server name and address are optional: if not provided, the name
1469 is left empty, and the address set to the address of the machine
1470 running dnsmasq. If dnsmasq is providing a TFTP service (see
1471 --enable-tftp ) then only the filename is required here to
1472 enable network booting. If the optional tag(s) are given, they
1473 must match for this configuration to be sent. Instead of an IP
1474 address, the TFTP server address can be given as a domain name
1475 which is looked up in /etc/hosts. This name can be associated in
1476 /etc/hosts with multiple IP addresses, which are used round-
1477 robin. This facility can be used to load balance the tftp load
1478 among a set of servers.
1479 --dhcp-sequential-ip
1481 Dnsmasq is designed to choose IP addresses for DHCP clients
1482 using a hash of the client's MAC address. This normally allows a
1483 client's address to remain stable long-term, even if the client
1484 sometimes allows its DHCP lease to expire. In this default mode
1485 IP addresses are distributed pseudo-randomly over the entire
1486 available address range. There are sometimes circumstances (typ‐
1487 ically server deployment) where it is more convenient to have IP
1488 addresses allocated sequentially, starting from the lowest
1489 available address, and setting this flag enables this mode. Note
1490 that in the sequential mode, clients which allow a lease to
1491 expire are much more likely to move IP address; for this reason
1492 it should not be generally used.
1493 --dhcp-ignore-clid
1495 Dnsmasq is reading 'client identifier' (RFC 2131) option sent by
1496 clients (if available) to identify clients. This allow to serve
1497 same IP address for a host using several interfaces. Use this
1498 option to disable 'client identifier' reading, i.e. to always
1499 identify a host using the MAC address.
1500 --pxe-service=[tag:<tag>,]<CSA>,<menu text>[,<basename>|<bootservice‐
1502 type>][,<server address>|<server_name>]
1503 Most uses of PXE boot-ROMS simply allow the PXE system to obtain
1504 an IP address and then download the file specified by --dhcp-
1505 boot and execute it. However the PXE system is capable of more
1506 complex functions when supported by a suitable DHCP server.
1507 This specifies a boot option which may appear in a PXE boot
1509 menu. <CSA> is client system type, only services of the correct
1510 type will appear in a menu. The known types are x86PC, PC98,
1511 IA64_EFI, Alpha, Arc_x86, Intel_Lean_Client, IA32_EFI,
1512 X86-64_EFI, Xscale_EFI, BC_EFI, ARM32_EFI and ARM64_EFI; an
1513 integer may be used for other types. The parameter after the
1514 menu text may be a file name, in which case dnsmasq acts as a
1515 boot server and directs the PXE client to download the file by
1516 TFTP, either from itself ( --enable-tftp must be set for this to
1517 work) or another TFTP server if the final server address/name is
1518 given. Note that the "layer" suffix (normally ".0") is supplied
1519 by PXE, and need not be added to the basename. Alternatively,
1520 the basename may be a filename, complete with suffix, in which
1521 case no layer suffix is added. If an integer boot service type,
1522 rather than a basename is given, then the PXE client will search
1523 for a suitable boot service for that type on the network. This
1524 search may be done by broadcast, or direct to a server if its IP
1525 address/name is provided. If no boot service type or filename
1526 is provided (or a boot service type of 0 is specified) then the
1527 menu entry will abort the net boot procedure and continue boot‐
1528 ing from local media. The server address can be given as a
1529 domain name which is looked up in /etc/hosts. This name can be
1530 associated in /etc/hosts with multiple IP addresses, which are
1531 used round-robin.
1532 --pxe-prompt=[tag:<tag>,]<prompt>[,<timeout>]
1534 Setting this provides a prompt to be displayed after PXE boot.
1535 If the timeout is given then after the timeout has elapsed with
1536 no keyboard input, the first available menu option will be auto‐
1537 matically executed. If the timeout is zero then the first avail‐
1538 able menu item will be executed immediately. If --pxe-prompt is
1539 omitted the system will wait for user input if there are multi‐
1540 ple items in the menu, but boot immediately if there is only
1541 one. See --pxe-service for details of menu items.
1542 Dnsmasq supports PXE "proxy-DHCP", in this case another DHCP
1544 server on the network is responsible for allocating IP
1545 addresses, and dnsmasq simply provides the information given in
1546 --pxe-prompt and --pxe-service to allow netbooting. This mode is
1547 enabled using the proxy keyword in --dhcp-range.
1548 -X, --dhcp-lease-max=<number>
1550 Limits dnsmasq to the specified maximum number of DHCP leases.
1551 The default is 1000. This limit is to prevent DoS attacks from
1552 hosts which create thousands of leases and use lots of memory in
1553 the dnsmasq process.
1554 -K, --dhcp-authoritative
1556 Should be set when dnsmasq is definitely the only DHCP server on
1557 a network. For DHCPv4, it changes the behaviour from strict RFC
1558 compliance so that DHCP requests on unknown leases from unknown
1559 hosts are not ignored. This allows new hosts to get a lease
1560 without a tedious timeout under all circumstances. It also
1561 allows dnsmasq to rebuild its lease database without each client
1562 needing to reacquire a lease, if the database is lost. For
1563 DHCPv6 it sets the priority in replies to 255 (the maximum)
1564 instead of 0 (the minimum).
1565 --dhcp-rapid-commit
1567 Enable DHCPv4 Rapid Commit Option specified in RFC 4039. When
1568 enabled, dnsmasq will respond to a DHCPDISCOVER message includ‐
1569 ing a Rapid Commit option with a DHCPACK including a Rapid Com‐
1570 mit option and fully committed address and configuration infor‐
1571 mation. Should only be enabled if either the server is the only
1572 server for the subnet, or multiple servers are present and they
1573 each commit a binding for all clients.
1574 --dhcp-alternate-port[=<server port>[,<client port>]]
1576 (IPv4 only) Change the ports used for DHCP from the default. If
1577 this option is given alone, without arguments, it changes the
1578 ports used for DHCP from 67 and 68 to 1067 and 1068. If a single
1579 argument is given, that port number is used for the server and
1580 the port number plus one used for the client. Finally, two port
1581 numbers allows arbitrary specification of both server and client
1582 ports for DHCP.
1583 -3, --bootp-dynamic[=<network-id>[,<network-id>]]
1585 (IPv4 only) Enable dynamic allocation of IP addresses to BOOTP
1586 clients. Use this with care, since each address allocated to a
1587 BOOTP client is leased forever, and therefore becomes perma‐
1588 nently unavailable for re-use by other hosts. if this is given
1589 without tags, then it unconditionally enables dynamic alloca‐
1590 tion. With tags, only when the tags are all set. It may be
1591 repeated with different tag sets.
1592 -5, --no-ping
1594 (IPv4 only) By default, the DHCP server will attempt to ensure
1595 that an address is not in use before allocating it to a host. It
1596 does this by sending an ICMP echo request (aka "ping") to the
1597 address in question. If it gets a reply, then the address must
1598 already be in use, and another is tried. This flag disables this
1599 check. Use with caution.
1600 --log-dhcp
1602 Extra logging for DHCP: log all the options sent to DHCP clients
1603 and the tags used to determine them.
1604 --quiet-dhcp, --quiet-dhcp6, --quiet-ra
1606 Suppress logging of the routine operation of these protocols.
1607 Errors and problems will still be logged. --quiet-dhcp and
1608 quiet-dhcp6 are over-ridden by --log-dhcp.
1609 -l, --dhcp-leasefile=<path>
1611 Use the specified file to store DHCP lease information.
1612 --dhcp-duid=<enterprise-id>,<uid>
1614 (IPv6 only) Specify the server persistent UID which the DHCPv6
1615 server will use. This option is not normally required as dnsmasq
1616 creates a DUID automatically when it is first needed. When
1617 given, this option provides dnsmasq the data required to create
1618 a DUID-EN type DUID. Note that once set, the DUID is stored in
1619 the lease database, so to change between DUID-EN and automati‐
1620 cally created DUIDs or vice-versa, the lease database must be
1621 re-initialised. The enterprise-id is assigned by IANA, and the
1622 uid is a string of hex octets unique to a particular device.
1623 -6 --dhcp-script=<path>
1625 Whenever a new DHCP lease is created, or an old one destroyed,
1626 or a TFTP file transfer completes, the executable specified by
1627 this option is run. <path> must be an absolute pathname, no
1628 PATH search occurs. The arguments to the process are "add",
1629 "old" or "del", the MAC address of the host (or DUID for IPv6) ,
1630 the IP address, and the hostname, if known. "add" means a lease
1631 has been created, "del" means it has been destroyed, "old" is a
1632 notification of an existing lease when dnsmasq starts or a
1633 change to MAC address or hostname of an existing lease (also,
1634 lease length or expiry and client-id, if --leasefile-ro is set
1635 and lease expiry if --script-on-renewal is set). If the MAC
1636 address is from a network type other than ethernet, it will have
1637 the network type prepended, eg "06-01:23:45:67:89:ab" for token
1638 ring. The process is run as root (assuming that dnsmasq was
1639 originally run as root) even if dnsmasq is configured to change
1640 UID to an unprivileged user.
1641 The environment is inherited from the invoker of dnsmasq, with
1643 some or all of the following variables added
1644 For both IPv4 and IPv6:
1646 DNSMASQ_DOMAIN if the fully-qualified domain name of the host is
1648 known, this is set to the domain part. (Note that the hostname
1649 passed to the script as an argument is never fully-qualified.)
1650 If the client provides a hostname, DNSMASQ_SUPPLIED_HOSTNAME
1652 If the client provides user-classes, DNSMASQ_USER_CLASS0..DNS‐
1654 MASQ_USER_CLASSn
1655 If dnsmasq was compiled with HAVE_BROKEN_RTC, then the length of
1657 the lease (in seconds) is stored in DNSMASQ_LEASE_LENGTH, other‐
1658 wise the time of lease expiry is stored in DNS‐
1659 MASQ_LEASE_EXPIRES. The number of seconds until lease expiry is
1660 always stored in DNSMASQ_TIME_REMAINING.
1661 If a lease used to have a hostname, which is removed, an "old"
1663 event is generated with the new state of the lease, ie no name,
1664 and the former name is provided in the environment variable DNS‐
1665 MASQ_OLD_HOSTNAME.
1666 DNSMASQ_INTERFACE stores the name of the interface on which the
1668 request arrived; this is not set for "old" actions when dnsmasq
1669 restarts.
1670 DNSMASQ_RELAY_ADDRESS is set if the client used a DHCP relay to
1672 contact dnsmasq and the IP address of the relay is known.
1673 DNSMASQ_TAGS contains all the tags set during the DHCP transac‐
1675 tion, separated by spaces.
1676 DNSMASQ_LOG_DHCP is set if --log-dhcp is in effect.
1678 For IPv4 only:
1680 DNSMASQ_CLIENT_ID if the host provided a client-id.
1682 DNSMASQ_CIRCUIT_ID, DNSMASQ_SUBSCRIBER_ID, DNSMASQ_REMOTE_ID if
1684 a DHCP relay-agent added any of these options.
1685 If the client provides vendor-class, DNSMASQ_VENDOR_CLASS.
1687 DNSMASQ_REQUESTED_OPTIONS a string containing the decimal values
1689 in the Parameter Request List option, comma separated, if the
1690 parameter request list option is provided by the client.
1691 For IPv6 only:
1693 If the client provides vendor-class, DNSMASQ_VENDOR_CLASS_ID,
1695 containing the IANA enterprise id for the class, and DNS‐
1696 MASQ_VENDOR_CLASS0..DNSMASQ_VENDOR_CLASSn for the data.
1697 DNSMASQ_SERVER_DUID containing the DUID of the server: this is
1699 the same for every call to the script.
1700 DNSMASQ_IAID containing the IAID for the lease. If the lease is
1702 a temporary allocation, this is prefixed to 'T'.
1703 DNSMASQ_MAC containing the MAC address of the client, if known.
1705 Note that the supplied hostname, vendorclass and userclass data
1707 is only supplied for "add" actions or "old" actions when a host
1708 resumes an existing lease, since these data are not held in dns‐
1709 masq's lease database.
1710 All file descriptors are closed except stdin, which is open to
1714 /dev/null, and stdout and stderr which capture output for log‐
1715 ging by dnsmasq. (In debug mode, stdio, stdout and stderr file
1716 are left as those inherited from the invoker of dnsmasq).
1717 The script is not invoked concurrently: at most one instance of
1719 the script is ever running (dnsmasq waits for an instance of
1720 script to exit before running the next). Changes to the lease
1721 database are which require the script to be invoked are queued
1722 awaiting exit of a running instance. If this queueing allows
1723 multiple state changes occur to a single lease before the script
1724 can be run then earlier states are discarded and the current
1725 state of that lease is reflected when the script finally runs.
1726 At dnsmasq startup, the script will be invoked for all existing
1728 leases as they are read from the lease file. Expired leases will
1729 be called with "del" and others with "old". When dnsmasq
1730 receives a HUP signal, the script will be invoked for existing
1731 leases with an "old" event.
1732 There are four further actions which may appear as the first
1735 argument to the script, "init", "arp-add", "arp-del" and "tftp".
1736 More may be added in the future, so scripts should be written to
1737 ignore unknown actions. "init" is described below in --lease‐
1738 file-ro The "tftp" action is invoked when a TFTP file transfer
1739 completes: the arguments are the file size in bytes, the address
1740 to which the file was sent, and the complete pathname of the
1741 file.
1742 The "arp-add" and "arp-del" actions are only called if enabled
1744 with --script-arp They are are supplied with a MAC address and
1745 IP address as arguments. "arp-add" indicates the arrival of a
1746 new entry in the ARP or neighbour table, and "arp-del" indicates
1747 the deletion of same.
1748 --dhcp-luascript=<path>
1751 Specify a script written in Lua, to be run when leases are cre‐
1752 ated, destroyed or changed. To use this option, dnsmasq must be
1753 compiled with the correct support. The Lua interpreter is ini‐
1754 tialised once, when dnsmasq starts, so that global variables
1755 persist between lease events. The Lua code must define a lease
1756 function, and may provide init and shutdown functions, which are
1757 called, without arguments when dnsmasq starts up and terminates.
1758 It may also provide a tftp function.
1759 The lease function receives the information detailed in --dhcp-
1761 script. It gets two arguments, firstly the action, which is a
1762 string containing, "add", "old" or "del", and secondly a table
1763 of tag value pairs. The tags mostly correspond to the environ‐
1764 ment variables detailed above, for instance the tag "domain"
1765 holds the same data as the environment variable DNSMASQ_DOMAIN.
1766 There are a few extra tags which hold the data supplied as argu‐
1767 ments to --dhcp-script. These are mac_address, ip_address and
1768 hostname for IPv4, and client_duid, ip_address and hostname for
1769 IPv6.
1770 The tftp function is called in the same way as the lease func‐
1772 tion, and the table holds the tags destination_address,
1773 file_name and file_size.
1774 The arp and arp-old functions are called only when enabled with
1776 --script-arp and have a table which holds the tags mac_address
1777 and client_address.
1778 --dhcp-scriptuser
1780 Specify the user as which to run the lease-change script or Lua
1781 script. This defaults to root, but can be changed to another
1782 user using this flag.
1783 --script-arp
1785 Enable the "arp" and "arp-old" functions in the --dhcp-script
1786 and --dhcp-luascript.
1787 -9, --leasefile-ro
1789 Completely suppress use of the lease database file. The file
1790 will not be created, read, or written. Change the way the lease-
1791 change script (if one is provided) is called, so that the lease
1792 database may be maintained in external storage by the script. In
1793 addition to the invocations given in --dhcp-script the lease-
1794 change script is called once, at dnsmasq startup, with the sin‐
1795 gle argument "init". When called like this the script should
1796 write the saved state of the lease database, in dnsmasq lease‐
1797 file format, to stdout and exit with zero exit code. Setting
1798 this option also forces the leasechange script to be called on
1799 changes to the client-id and lease length and expiry time.
1800 --script-on-renewal
1802 Call the DHCP script when the lease expiry time changes, for
1803 instance when the lease is renewed.
1804 --bridge-interface=<interface>,<alias>[,<alias>]
1806 Treat DHCP (v4 and v6) requests and IPv6 Router Solicit packets
1807 arriving at any of the <alias> interfaces as if they had arrived
1808 at <interface>. This option allows dnsmasq to provide DHCP and
1809 RA service over unaddressed and unbridged Ethernet interfaces,
1810 e.g. on an OpenStack compute host where each such interface is a
1811 TAP interface to a VM, or as in "old style bridging" on BSD
1812 platforms. A trailing '*' wildcard can be used in each <alias>.
1813 It is permissible to add more than one alias using more than one
1815 --bridge-interface option since --bridge-inter‐
1816 face=int1,alias1,alias2 is exactly equivalent to --bridge-inter‐
1817 face=int1,alias1 --bridge-interface=int1,alias2
1818 --shared-network=<interface>,<addr>
1820 --shared-network=<addr>,<addr>
1821 The DHCP server determines which DHCP ranges are useable for
1822 allocating an address to a DHCP client based on the network from
1823 which the DHCP request arrives, and the IP configuration of the
1824 server's interface on that network. The shared-network option
1825 extends the available subnets (and therefore DHCP ranges) beyond
1826 the subnets configured on the arrival interface.
1827 The first argument is either the name of an interface, or an
1829 address that is configured on a local interface, and the second
1830 argument is an address which defines another subnet on which
1831 addresses can be allocated.
1832 To be useful, there must be a suitable dhcp-range which allows
1834 address allocation on this subnet and this dhcp-range MUST
1835 include the netmask.
1836 Using shared-network also needs extra consideration of routing.
1838 Dnsmasq does not have the usual information that it uses to
1839 determine the default route, so the default route option (or
1840 other routing) MUST be configured manually. The client must have
1841 a route to the server: if the two-address form of shared-network
1842 is used, this needs to be to the first specified address. If the
1843 interface,address form is used, there must be a route to all of
1844 the addresses configured on the interface.
1845 The two-address form of shared-network is also usable with a
1847 DHCP relay: the first address is the address of the relay and
1848 the second, as before, specifies an extra subnet which addresses
1849 may be allocated from.
1850 -s, --domain=<domain>[,<address range>[,local]]
1853 Specifies DNS domains for the DHCP server. Domains may be be
1854 given unconditionally (without the IP range) or for limited IP
1855 ranges. This has two effects; firstly it causes the DHCP server
1856 to return the domain to any hosts which request it, and secondly
1857 it sets the domain which it is legal for DHCP-configured hosts
1858 to claim. The intention is to constrain hostnames so that an
1859 untrusted host on the LAN cannot advertise its name via DHCP as
1860 e.g. "microsoft.com" and capture traffic not meant for it. If no
1861 domain suffix is specified, then any DHCP hostname with a domain
1862 part (ie with a period) will be disallowed and logged. If suffix
1863 is specified, then hostnames with a domain part are allowed,
1864 provided the domain part matches the suffix. In addition, when a
1865 suffix is set then hostnames without a domain part have the suf‐
1866 fix added as an optional domain part. Eg on my network I can set
1867 --domain=thekelleys.org.uk and have a machine whose DHCP host‐
1868 name is "laptop". The IP address for that machine is available
1869 from dnsmasq both as "laptop" and "laptop.thekelleys.org.uk". If
1870 the domain is given as "#" then the domain is read from the
1871 first "search" directive in /etc/resolv.conf (or equivalent).
1872 The address range can be of the form <ip address>,<ip address>
1874 or <ip address>/<netmask> or just a single <ip address>. See
1875 --dhcp-fqdn which can change the behaviour of dnsmasq with
1876 domains.
1877 If the address range is given as ip-address/network-size, then a
1879 additional flag "local" may be supplied which has the effect of
1880 adding --local declarations for forward and reverse DNS queries.
1881 Eg. --domain=thekelleys.org.uk,192.168.0.0/24,local is identi‐
1882 cal to --domain=thekelleys.org.uk,192.168.0.0/24
1883 --local=/thekelleys.org.uk/ --local=/0.168.192.in-addr.arpa/ The
1884 network size must be 8, 16 or 24 for this to be legal.
1885 --dhcp-fqdn
1887 In the default mode, dnsmasq inserts the unqualified names of
1888 DHCP clients into the DNS. For this reason, the names must be
1889 unique, even if two clients which have the same name are in dif‐
1890 ferent domains. If a second DHCP client appears which has the
1891 same name as an existing client, the name is transferred to the
1892 new client. If --dhcp-fqdn is set, this behaviour changes: the
1893 unqualified name is no longer put in the DNS, only the qualified
1894 name. Two DHCP clients with the same name may both keep the
1895 name, provided that the domain part is different (ie the fully
1896 qualified names differ.) To ensure that all names have a domain
1897 part, there must be at least --domain without an address speci‐
1898 fied when --dhcp-fqdn is set.
1899 --dhcp-client-update
1901 Normally, when giving a DHCP lease, dnsmasq sets flags in the
1902 FQDN option to tell the client not to attempt a DDNS update with
1903 its name and IP address. This is because the name-IP pair is
1904 automatically added into dnsmasq's DNS view. This flag sup‐
1905 presses that behaviour, this is useful, for instance, to allow
1906 Windows clients to update Active Directory servers. See RFC 4702
1907 for details.
1908 --enable-ra
1910 Enable dnsmasq's IPv6 Router Advertisement feature. DHCPv6
1911 doesn't handle complete network configuration in the same way as
1912 DHCPv4. Router discovery and (possibly) prefix discovery for au‐
1913 tonomous address creation are handled by a different protocol.
1914 When DHCP is in use, only a subset of this is needed, and dns‐
1915 masq can handle it, using existing DHCP configuration to provide
1916 most data. When RA is enabled, dnsmasq will advertise a prefix
1917 for each --dhcp-range, with default router as the relevant
1918 link-local address on the machine running dnsmasq. By default,
1919 the "managed address" bits are set, and the "use SLAAC" bit is
1920 reset. This can be changed for individual subnets with the mode
1921 keywords described in --dhcp-range. RFC6106 DNS parameters are
1922 included in the advertisements. By default, the relevant link-
1923 local address of the machine running dnsmasq is sent as recur‐
1924 sive DNS server. If provided, the DHCPv6 options dns-server and
1925 domain-search are used for the DNS server (RDNSS) and the domain
1926 search list (DNSSL).
1927 --ra-param=<interface>,[mtu:<integer>|<interface>|off,][high,|low,]<ra-
1929 interval>[,<router lifetime>]
1930 Set non-default values for router advertisements sent via an
1931 interface. The priority field for the router may be altered from
1932 the default of medium with eg --ra-param=eth0,high. The inter‐
1933 val between router advertisements may be set (in seconds) with
1934 --ra-param=eth0,60. The lifetime of the route may be changed or
1935 set to zero, which allows a router to advertise prefixes but not
1936 a route via itself. --ra-param=eth0,0,0 (A value of zero for
1937 the interval means the default value.) All four parameters may
1938 be set at once. --ra-param=eth0,mtu:1280,low,60,1200
1939 The interface field may include a wildcard.
1941 The mtu: parameter may be an arbitrary interface name, in which
1943 case the MTU value for that interface is used. This is useful
1944 for (eg) advertising the MTU of a WAN interface on the other
1945 interfaces of a router.
1946 --dhcp-reply-delay=[tag:<tag>,]<integer>
1948 Delays sending DHCPOFFER and PROXYDHCP replies for at least the
1949 specified number of seconds. This can be used as workaround for
1950 bugs in PXE boot firmware that does not function properly when
1951 receiving an instant reply. This option takes into account the
1952 time already spent waiting (e.g. performing ping check) if any.
1953 --enable-tftp[=<interface>[,<interface>]]
1955 Enable the TFTP server function. This is deliberately limited to
1956 that needed to net-boot a client. Only reading is allowed; the
1957 tsize and blksize extensions are supported (tsize is only sup‐
1958 ported in octet mode). Without an argument, the TFTP service is
1959 provided to the same set of interfaces as DHCP service. If the
1960 list of interfaces is provided, that defines which interfaces
1961 receive TFTP service.
1962 --tftp-root=<directory>[,<interface>]
1964 Look for files to transfer using TFTP relative to the given
1965 directory. When this is set, TFTP paths which include ".." are
1966 rejected, to stop clients getting outside the specified root.
1967 Absolute paths (starting with /) are allowed, but they must be
1968 within the tftp-root. If the optional interface argument is
1969 given, the directory is only used for TFTP requests via that
1970 interface.
1971 --tftp-no-fail
1973 Do not abort startup if specified tftp root directories are
1974 inaccessible.
1975 --tftp-unique-root[=ip|mac]
1977 Add the IP or hardware address of the TFTP client as a path com‐
1978 ponent on the end of the TFTP-root. Only valid if a --tftp-root
1979 is set and the directory exists. Defaults to adding IP address
1980 (in standard dotted-quad format). For instance, if --tftp-root
1981 is "/tftp" and client 1.2.3.4 requests file "myfile" then the
1982 effective path will be "/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4
1983 exists or /tftp/myfile otherwise. When "=mac" is specified it
1984 will append the MAC address instead, using lowercase zero padded
1985 digits separated by dashes, e.g.: 01-02-03-04-aa-bb Note that
1986 resolving MAC addresses is only possible if the client is in the
1987 local network or obtained a DHCP lease from us.
1988 --tftp-secure
1990 Enable TFTP secure mode: without this, any file which is read‐
1991 able by the dnsmasq process under normal unix access-control
1992 rules is available via TFTP. When the --tftp-secure flag is
1993 given, only files owned by the user running the dnsmasq process
1994 are accessible. If dnsmasq is being run as root, different rules
1995 apply: --tftp-secure has no effect, but only files which have
1996 the world-readable bit set are accessible. It is not recommended
1997 to run dnsmasq as root with TFTP enabled, and certainly not
1998 without specifying --tftp-root. Doing so can expose any world-
1999 readable file on the server to any host on the net.
2000 --tftp-lowercase
2002 Convert filenames in TFTP requests to all lowercase. This is
2003 useful for requests from Windows machines, which have case-
2004 insensitive filesystems and tend to play fast-and-loose with
2005 case in filenames. Note that dnsmasq's tftp server always con‐
2006 verts "\" to "/" in filenames.
2007 --tftp-max=<connections>
2009 Set the maximum number of concurrent TFTP connections allowed.
2010 This defaults to 50. When serving a large number of TFTP connec‐
2011 tions, per-process file descriptor limits may be encountered.
2012 Dnsmasq needs one file descriptor for each concurrent TFTP con‐
2013 nection and one file descriptor per unique file (plus a few oth‐
2014 ers). So serving the same file simultaneously to n clients will
2015 use require about n + 10 file descriptors, serving different
2016 files simultaneously to n clients will require about (2*n) + 10
2017 descriptors. If --tftp-port-range is given, that can affect the
2018 number of concurrent connections.
2019 --tftp-mtu=<mtu size>
2021 Use size as the ceiling of the MTU supported by the intervening
2022 network when negotiating TFTP blocksize, overriding the MTU set‐
2023 ting of the local interface if it is larger.
2024 --tftp-no-blocksize
2026 Stop the TFTP server from negotiating the "blocksize" option
2027 with a client. Some buggy clients request this option but then
2028 behave badly when it is granted.
2029 --tftp-port-range=<start>,<end>
2031 A TFTP server listens on a well-known port (69) for connection
2032 initiation, but it also uses a dynamically-allocated port for
2033 each connection. Normally these are allocated by the OS, but
2034 this option specifies a range of ports for use by TFTP trans‐
2035 fers. This can be useful when TFTP has to traverse a firewall.
2036 The start of the range cannot be lower than 1025 unless dnsmasq
2037 is running as root. The number of concurrent TFTP connections is
2038 limited by the size of the port range.
2039 --tftp-single-port
2041 Run in a mode where the TFTP server uses ONLY the well-known
2042 port (69) for its end of the TFTP transfer. This allows TFTP to
2043 work when there in NAT is the path between client and server.
2044 Note that this is not strictly compliant with the RFCs specify‐
2045 ing the TFTP protocol: use at your own risk.
2046 -C, --conf-file=<file>
2048 Specify a configuration file. The presence of this option stops
2049 dnsmasq from reading the default configuration file (normally
2050 /etc/dnsmasq.conf). Multiple files may be specified by repeating
2051 the option either on the command line or in configuration files.
2052 A filename of "-" causes dnsmasq to read configuration from
2053 stdin.
2054 -7, --conf-dir=<directory>[,<file-extension>......],
2056 Read all the files in the given directory as configuration
2057 files. If extension(s) are given, any files which end in those
2058 extensions are skipped. Any files whose names end in ~ or start
2059 with . or start and end with # are always skipped. If the exten‐
2060 sion starts with * then only files which have that extension are
2061 loaded. So --conf-dir=/path/to/dir,*.conf loads all files with
2062 the suffix .conf in /path/to/dir. This flag may be given on the
2063 command line or in a configuration file. If giving it on the
2064 command line, be sure to escape * characters. Files are loaded
2065 in alphabetical order of filename.
2066 --servers-file=<file>
2068 A special case of --conf-file which differs in two respects.
2069 Firstly, only --server and --rev-server are allowed in the con‐
2070 figuration file included. Secondly, the file is re-read and the
2071 configuration therein is updated when dnsmasq receives SIGHUP.
2072
2074 At startup, dnsmasq reads /etc/dnsmasq.conf, if it exists. (On FreeBSD,
2075 the file is /usr/local/etc/dnsmasq.conf ) (but see the --conf-file and
2076 --conf-dir options.) The format of this file consists of one option per
2077 line, exactly as the long options detailed in the OPTIONS section but
2078 without the leading "--". Lines starting with # are comments and
2079 ignored. For options which may only be specified once, the configura‐
2080 tion file overrides the command line. Quoting is allowed in a config
2081 file: between " quotes the special meanings of ,:. and # are removed
2082 and the following escapes are allowed: \\ \" \t \e \b \r and \n. The
2083 later corresponding to tab, escape, backspace, return and newline.
2084
2086 When it receives a SIGHUP, dnsmasq clears its cache and then re-loads
2087 /etc/hosts and /etc/ethers and any file given by --dhcp-hostsfile,
2088 --dhcp-hostsdir, --dhcp-optsfile, --dhcp-optsdir, --addn-hosts or
2089 --hostsdir. The DHCP lease change script is called for all existing
2090 DHCP leases. If --no-poll is set SIGHUP also re-reads /etc/resolv.conf.
2091 SIGHUP does NOT re-read the configuration file.
2092 When it receives a SIGUSR1, dnsmasq writes statistics to the system
2094 log. It writes the cache size, the number of names which have had to
2095 removed from the cache before they expired in order to make room for
2096 new names and the total number of names that have been inserted into
2097 the cache. The number of cache hits and misses and the number of
2098 authoritative queries answered are also given. For each upstream server
2099 it gives the number of queries sent, and the number which resulted in
2100 an error. In --no-daemon mode or when full logging is enabled (--log-
2101 queries), a complete dump of the contents of the cache is made.
2102 The cache statistics are also available in the DNS as answers to
2104 queries of class CHAOS and type TXT in domain bind. The domain names
2105 are cachesize.bind, insertions.bind, evictions.bind, misses.bind,
2106 hits.bind, auth.bind and servers.bind. An example command to query
2107 this, using the dig utility would be
2108 dig +short chaos txt cachesize.bind
2110 When it receives SIGUSR2 and it is logging direct to a file (see --log-
2113 facility ) dnsmasq will close and reopen the log file. Note that during
2114 this operation, dnsmasq will not be running as root. When it first cre‐
2115 ates the logfile dnsmasq changes the ownership of the file to the non-
2116 root user it will run as. Logrotate should be configured to create a
2117 new log file with the ownership which matches the existing one before
2118 sending SIGUSR2. If TCP DNS queries are in progress, the old logfile
2119 will remain open in child processes which are handling TCP queries and
2120 may continue to be written. There is a limit of 150 seconds, after
2121 which all existing TCP processes will have expired: for this reason, it
2122 is not wise to configure logfile compression for logfiles which have
2123 just been rotated. Using logrotate, the required options are create and
2124 delaycompress.
2125 Dnsmasq is a DNS query forwarder: it is not capable of recursively
2129 answering arbitrary queries starting from the root servers but forwards
2130 such queries to a fully recursive upstream DNS server which is typi‐
2131 cally provided by an ISP. By default, dnsmasq reads /etc/resolv.conf to
2132 discover the IP addresses of the upstream nameservers it should use,
2133 since the information is typically stored there. Unless --no-poll is
2134 used, dnsmasq checks the modification time of /etc/resolv.conf (or
2135 equivalent if --resolv-file is used) and re-reads it if it changes.
2136 This allows the DNS servers to be set dynamically by PPP or DHCP since
2137 both protocols provide the information. Absence of /etc/resolv.conf is
2138 not an error since it may not have been created before a PPP connection
2139 exists. Dnsmasq simply keeps checking in case /etc/resolv.conf is cre‐
2140 ated at any time. Dnsmasq can be told to parse more than one
2141 resolv.conf file. This is useful on a laptop, where both PPP and DHCP
2142 may be used: dnsmasq can be set to poll both /etc/ppp/resolv.conf and
2143 /etc/dhcpc/resolv.conf and will use the contents of whichever changed
2144 last, giving automatic switching between DNS servers.
2145 Upstream servers may also be specified on the command line or in the
2147 configuration file. These server specifications optionally take a
2148 domain name which tells dnsmasq to use that server only to find names
2149 in that particular domain.
2150 In order to configure dnsmasq to act as cache for the host on which it
2152 is running, put "nameserver 127.0.0.1" in /etc/resolv.conf to force
2153 local processes to send queries to dnsmasq. Then either specify the
2154 upstream servers directly to dnsmasq using --server options or put
2155 their addresses real in another file, say /etc/resolv.dnsmasq and run
2156 dnsmasq with the --resolv-file /etc/resolv.dnsmasq option. This second
2157 technique allows for dynamic update of the server addresses by PPP or
2158 DHCP.
2159 Addresses in /etc/hosts will "shadow" different addresses for the same
2161 names in the upstream DNS, so "mycompany.com 1.2.3.4" in /etc/hosts
2162 will ensure that queries for "mycompany.com" always return 1.2.3.4 even
2163 if queries in the upstream DNS would otherwise return a different
2164 address. There is one exception to this: if the upstream DNS contains a
2165 CNAME which points to a shadowed name, then looking up the CNAME
2166 through dnsmasq will result in the unshadowed address associated with
2167 the target of the CNAME. To work around this, add the CNAME to
2168 /etc/hosts so that the CNAME is shadowed too.
2169 The tag system works as follows: For each DHCP request, dnsmasq col‐
2172 lects a set of valid tags from active configuration lines which include
2173 set:<tag>, including one from the --dhcp-range used to allocate the
2174 address, one from any matching --dhcp-host (and "known" or "known-oth‐
2175 ernet" if a --dhcp-host matches) The tag "bootp" is set for BOOTP
2176 requests, and a tag whose name is the name of the interface on which
2177 the request arrived is also set.
2178 Any configuration lines which include one or more tag:<tag> constructs
2180 will only be valid if all that tags are matched in the set derived
2181 above. Typically this is --dhcp-option. --dhcp-option which has tags
2182 will be used in preference to an untagged --dhcp-option, provided that
2183 _all_ the tags match somewhere in the set collected as described above.
2184 The prefix '!' on a tag means 'not' so --dhcp-option=tag:!pur‐
2185 ple,3,1.2.3.4 sends the option when the tag purple is not in the set of
2186 valid tags. (If using this in a command line rather than a configura‐
2187 tion file, be sure to escape !, which is a shell metacharacter)
2188 When selecting --dhcp-options, a tag from --dhcp-range is second class
2190 relative to other tags, to make it easy to override options for indi‐
2191 vidual hosts, so --dhcp-range=set:interface1,...... --dhcp-
2192 host=set:myhost,..... --dhcp-option=tag:interface1,option:nis-
2193 domain,"domain1" --dhcp-option=tag:myhost,option:nis-domain,"domain2"
2194 will set the NIS-domain to domain1 for hosts in the range, but override
2195 that to domain2 for a particular host.
2196 Note that for --dhcp-range both tag:<tag> and set:<tag> are allowed, to
2199 both select the range in use based on (eg) --dhcp-host, and to affect
2200 the options sent, based on the range selected.
2201 This system evolved from an earlier, more limited one and for backward
2203 compatibility "net:" may be used instead of "tag:" and "set:" may be
2204 omitted. (Except in --dhcp-host, where "net:" may be used instead of
2205 "set:".) For the same reason, '#' may be used instead of '!' to indi‐
2206 cate NOT.
2207 The DHCP server in dnsmasq will function as a BOOTP server also, pro‐
2209 vided that the MAC address and IP address for clients are given, either
2210 using --dhcp-host configurations or in /etc/ethers , and a --dhcp-range
2211 configuration option is present to activate the DHCP server on a par‐
2212 ticular network. (Setting --bootp-dynamic removes the need for static
2213 address mappings.) The filename parameter in a BOOTP request is used as
2214 a tag, as is the tag "bootp", allowing some control over the options
2215 returned to different classes of hosts.
2216
2219 Configuring dnsmasq to act as an authoritative DNS server is compli‐
2220 cated by the fact that it involves configuration of external DNS
2221 servers to provide delegation. We will walk through three scenarios of
2222 increasing complexity. Prerequisites for all of these scenarios are a
2223 globally accessible IP address, an A or AAAA record pointing to that
2224 address, and an external DNS server capable of doing delegation of the
2225 zone in question. For the first part of this explanation, we will call
2226 the A (or AAAA) record for the globally accessible address server.exam‐
2227 ple.com, and the zone for which dnsmasq is authoritative our.zone.com.
2228 The simplest configuration consists of two lines of dnsmasq configura‐
2230 tion; something like
2231 --auth-server=server.example.com,eth0
2233 --auth-zone=our.zone.com,1.2.3.0/24
2234 and two records in the external DNS
2236 server.example.com A 192.0.43.10
2238 our.zone.com NS server.example.com
2239 eth0 is the external network interface on which dnsmasq is listening,
2241 and has (globally accessible) address 192.0.43.10.
2242 Note that the external IP address may well be dynamic (ie assigned from
2244 an ISP by DHCP or PPP) If so, the A record must be linked to this
2245 dynamic assignment by one of the usual dynamic-DNS systems.
2246 A more complex, but practically useful configuration has the address
2248 record for the globally accessible IP address residing in the authori‐
2249 tative zone which dnsmasq is serving, typically at the root. Now we
2250 have
2251 --auth-server=our.zone.com,eth0
2253 --auth-zone=our.zone.com,1.2.3.0/24
2254 our.zone.com A 1.2.3.4
2256 our.zone.com NS our.zone.com
2257 The A record for our.zone.com has now become a glue record, it solves
2259 the chicken-and-egg problem of finding the IP address of the nameserver
2260 for our.zone.com when the A record is within that zone. Note that this
2261 is the only role of this record: as dnsmasq is now authoritative from
2262 our.zone.com it too must provide this record. If the external address
2263 is static, this can be done with an /etc/hosts entry or --host-record.
2264 --auth-server=our.zone.com,eth0
2266 --host-record=our.zone.com,1.2.3.4
2267 --auth-zone=our.zone.com,1.2.3.0/24
2268 If the external address is dynamic, the address associated with
2270 our.zone.com must be derived from the address of the relevant inter‐
2271 face. This is done using --interface-name Something like:
2272 --auth-server=our.zone.com,eth0
2274 --interface-name=our.zone.com,eth0
2275 --auth-zone=our.zone.com,1.2.3.0/24,eth0
2276 (The "eth0" argument in --auth-zone adds the subnet containing eth0's
2278 dynamic address to the zone, so that the --interface-name returns the
2279 address in outside queries.)
2280 Our final configuration builds on that above, but also adds a secondary
2282 DNS server. This is another DNS server which learns the DNS data for
2283 the zone by doing zones transfer, and acts as a backup should the pri‐
2284 mary server become inaccessible. The configuration of the secondary is
2285 beyond the scope of this man-page, but the extra configuration of dns‐
2286 masq is simple:
2287 --auth-sec-servers=secondary.myisp.com
2289 and
2291 our.zone.com NS secondary.myisp.com
2293 Adding auth-sec-servers enables zone transfer in dnsmasq, to allow the
2295 secondary to collect the DNS data. If you wish to restrict this data to
2296 particular hosts then
2297 --auth-peer=<IP address of secondary>
2299 will do so.
2301 Dnsmasq acts as an authoritative server for in-addr.arpa and ip6.arpa
2303 domains associated with the subnets given in --auth-zone declarations,
2304 so reverse (address to name) lookups can be simply configured with a
2305 suitable NS record, for instance in this example, where we allow
2306 1.2.3.0/24 addresses.
2307 3.2.1.in-addr.arpa NS our.zone.com
2309 Note that at present, reverse (in-addr.arpa and ip6.arpa) zones are not
2311 available in zone transfers, so there is no point arranging secondary
2312 servers for reverse lookups.
2313 When dnsmasq is configured to act as an authoritative server, the fol‐
2316 lowing data is used to populate the authoritative zone.
2317 --mx-host, --srv-host, --dns-rr, --txt-record, --naptr-record, --caa-
2319 record, as long as the record names are in the authoritative domain.
2320 --cname as long as the record name is in the authoritative domain. If
2322 the target of the CNAME is unqualified, then it is qualified with the
2323 authoritative zone name. CNAME used in this way (only) may be wild‐
2324 cards, as in
2325 --cname=*.example.com,default.example.com
2327 IPv4 and IPv6 addresses from /etc/hosts (and --addn-hosts ) and --host-
2330 record and --interface-name provided the address falls into one of the
2331 subnets specified in the --auth-zone.
2332 Addresses of DHCP leases, provided the address falls into one of the
2334 subnets specified in the --auth-zone. (If constructed DHCP ranges are
2335 is use, which depend on the address dynamically assigned to an inter‐
2336 face, then the form of --auth-zone which defines subnets by the dynamic
2337 address of an interface should be used to ensure this condition is
2338 met.)
2339 In the default mode, where a DHCP lease has an unqualified name, and
2341 possibly a qualified name constructed using --domain then the name in
2342 the authoritative zone is constructed from the unqualified name and the
2343 zone's domain. This may or may not equal that specified by --domain.
2344 If --dhcp-fqdn is set, then the fully qualified names associated with
2345 DHCP leases are used, and must match the zone's domain.
2346
2351 0 - Dnsmasq successfully forked into the background, or terminated nor‐
2352 mally if backgrounding is not enabled.
2353 1 - A problem with configuration was detected.
2355 2 - A problem with network access occurred (address in use, attempt to
2357 use privileged ports without permission).
2358 3 - A problem occurred with a filesystem operation (missing file/direc‐
2360 tory, permissions).
2361 4 - Memory allocation failure.
2363 5 - Other miscellaneous problem.
2365 11 or greater - a non zero return code was received from the lease-
2367 script process "init" call. The exit code from dnsmasq is the script's
2368 exit code with 10 added.
2369
2372 The default values for resource limits in dnsmasq are generally conser‐
2373 vative, and appropriate for embedded router type devices with slow pro‐
2374 cessors and limited memory. On more capable hardware, it is possible to
2375 increase the limits, and handle many more clients. The following
2376 applies to dnsmasq-2.37: earlier versions did not scale as well.
2377 Dnsmasq is capable of handling DNS and DHCP for at least a thousand
2380 clients. The DHCP lease times should not be very short (less than one
2381 hour). The value of --dns-forward-max can be increased: start with it
2382 equal to the number of clients and increase if DNS seems slow. Note
2383 that DNS performance depends too on the performance of the upstream
2384 nameservers. The size of the DNS cache may be increased: the hard limit
2385 is 10000 names and the default (150) is very low. Sending SIGUSR1 to
2386 dnsmasq makes it log information which is useful for tuning the cache
2387 size. See the NOTES section for details.
2388 The built-in TFTP server is capable of many simultaneous file trans‐
2391 fers: the absolute limit is related to the number of file-handles
2392 allowed to a process and the ability of the select() system call to
2393 cope with large numbers of file handles. If the limit is set too high
2394 using --tftp-max it will be scaled down and the actual limit logged at
2395 start-up. Note that more transfers are possible when the same file is
2396 being sent than when each transfer sends a different file.
2397 It is possible to use dnsmasq to block Web advertising by using a list
2400 of known banner-ad servers, all resolving to 127.0.0.1 or 0.0.0.0, in
2401 /etc/hosts or an additional hosts file. The list can be very long, dns‐
2402 masq has been tested successfully with one million names. That size
2403 file needs a 1GHz processor and about 60Mb of RAM.
2404
2407 Dnsmasq can be compiled to support internationalisation. To do this,
2408 the make targets "all-i18n" and "install-i18n" should be used instead
2409 of the standard targets "all" and "install". When internationalisation
2410 is compiled in, dnsmasq will produce log messages in the local language
2411 and support internationalised domain names (IDN). Domain names in
2412 /etc/hosts, /etc/ethers and /etc/dnsmasq.conf which contain non-ASCII
2413 characters will be translated to the DNS-internal punycode representa‐
2414 tion. Note that dnsmasq determines both the language for messages and
2415 the assumed charset for configuration files from the LANG environment
2416 variable. This should be set to the system default value by the script
2417 which is responsible for starting dnsmasq. When editing the configura‐
2418 tion files, be careful to do so using only the system-default locale
2419 and not user-specific one, since dnsmasq has no direct way of determin‐
2420 ing the charset in use, and must assume that it is the system default.
2421
2424 /etc/dnsmasq.conf
2425 /usr/local/etc/dnsmasq.conf
2427 /etc/resolv.conf /var/run/dnsmasq/resolv.conf /etc/ppp/resolv.conf
2429 /etc/dhcpc/resolv.conf
2430 /etc/hosts
2432 /etc/ethers
2434 /var/lib/dnsmasq/dnsmasq.leases
2436 /var/db/dnsmasq.leases
2438 /var/run/dnsmasq.pid
2440
2442 hosts(5), resolver(5)
2443
2445 This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.
2446 2020-04-05 DNSMASQ(8)