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 glue record.
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
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 -o, --strict-order
392 By default, dnsmasq will send queries to any of the upstream
393 servers it knows about and tries to favour servers that are
394 known to be up. Setting this flag forces dnsmasq to try each
395 query with each server strictly in the order they appear in
396 /etc/resolv.conf
397 --all-servers
399 By default, when dnsmasq has more than one upstream server
400 available, it will send queries to just one server. Setting this
401 flag forces dnsmasq to send all queries to all available
402 servers. The reply from the server which answers first will be
403 returned to the original requester.
404 --dns-loop-detect
406 Enable code to detect DNS forwarding loops; ie the situation
407 where a query sent to one of the upstream server eventually
408 returns as a new query to the dnsmasq instance. The process
409 works by generating TXT queries of the form <hex>.test and send‐
410 ing them to each upstream server. The hex is a UID which encodes
411 the instance of dnsmasq sending the query and the upstream
412 server to which it was sent. If the query returns to the server
413 which sent it, then the upstream server through which it was
414 sent is disabled and this event is logged. Each time the set of
415 upstream servers changes, the test is re-run on all of them,
416 including ones which were previously disabled.
417 --stop-dns-rebind
419 Reject (and log) addresses from upstream nameservers which are
420 in the private IP ranges. This blocks an attack where a browser
421 behind a firewall is used to probe machines on the local net‐
422 work.
423 --rebind-localhost-ok
425 Exempt 127.0.0.0/8 from rebinding checks. This address range is
426 returned by realtime black hole servers, so blocking it may dis‐
427 able these services.
428 --rebind-domain-ok=[<domain>]|[[/<domain>/[<domain>/]
430 Do not detect and block dns-rebind on queries to these domains.
431 The argument may be either a single domain, or multiple domains
432 surrounded by '/', like the --server syntax, eg. --rebind-
433 domain-ok=/domain1/domain2/domain3/
434 -n, --no-poll
436 Don't poll /etc/resolv.conf for changes.
437 --clear-on-reload
439 Whenever /etc/resolv.conf is re-read or the upstream servers are
440 set via DBus, clear the DNS cache. This is useful when new
441 nameservers may have different data than that held in cache.
442 -D, --domain-needed
444 Tells dnsmasq to never forward A or AAAA queries for plain
445 names, without dots or domain parts, to upstream nameservers. If
446 the name is not known from /etc/hosts or DHCP then a "not found"
447 answer is returned.
448 -S, --local,
450 --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>][@<source-ip>|<inter‐
451 face>[#<port>]]
452 Specify IP address of upstream servers directly. Setting this
453 flag does not suppress reading of /etc/resolv.conf, use --no-
454 resolv to do that. If one or more optional domains are given,
455 that server is used only for those domains and they are queried
456 only using the specified server. This is intended for private
457 nameservers: if you have a nameserver on your network which
458 deals with names of the form xxx.internal.thekelleys.org.uk at
459 192.168.1.1 then giving the flag --server=/internal.thekel‐
460 leys.org.uk/192.168.1.1 will send all queries for internal
461 machines to that nameserver, everything else will go to the
462 servers in /etc/resolv.conf. DNSSEC validation is turned off for
463 such private nameservers, UNLESS a --trust-anchor is specified
464 for the domain in question. An empty domain specification, //
465 has the special meaning of "unqualified names only" ie names
466 without any dots in them. A non-standard port may be specified
467 as part of the IP address using a # character. More than one
468 --server flag is allowed, with repeated domain or ipaddr parts
469 as required.
470 More specific domains take precedence over less specific
472 domains, so: --server=/google.com/1.2.3.4
473 --server=/www.google.com/2.3.4.5 will send queries for
474 *.google.com to 1.2.3.4, except *www.google.com, which will go
475 to 2.3.4.5
476 The special server address '#' means, "use the standard
478 servers", so --server=/google.com/1.2.3.4
479 --server=/www.google.com/# will send queries for *.google.com to
480 1.2.3.4, except *www.google.com which will be forwarded as
481 usual.
482 Also permitted is a -S flag which gives a domain but no IP
484 address; this tells dnsmasq that a domain is local and it may
485 answer queries from /etc/hosts or DHCP but should never forward
486 queries on that domain to any upstream servers. --local is a
487 synonym for --server to make configuration files clearer in this
488 case.
489 IPv6 addresses may include an %interface scope-id, eg
491 fe80::202:a412:4512:7bbf%eth0.
492 The optional string after the @ character tells dnsmasq how to
494 set the source of the queries to this nameserver. It can either
495 be an ip-address, an interface name or both. The ip-address
496 should belong to the machine on which dnsmasq is running, other‐
497 wise this server line will be logged and then ignored. If an
498 interface name is given, then queries to the server will be
499 forced via that interface; if an ip-address is given then the
500 source address of the queries will be set to that address; and
501 if both are given then a combination of ip-address and interface
502 name will be used to steer requests to the server. The query-
503 port flag is ignored for any servers which have a source address
504 specified but the port may be specified directly as part of the
505 source address. Forcing queries to an interface is not imple‐
506 mented on all platforms supported by dnsmasq.
507 --rev-server=<ip-address>/<prefix-len>,<ipaddr>[#<port>][@<source-
509 ip>|<interface>[#<port>]]
510 This is functionally the same as --server, but provides some
511 syntactic sugar to make specifying address-to-name queries eas‐
512 ier. For example --rev-server=1.2.3.0/24,192.168.0.1 is exactly
513 equivalent to --server=/3.2.1.in-addr.arpa/192.168.0.1
514 -A, --address=/<domain>[/<domain>...]/[<ipaddr>]
516 Specify an IP address to return for any host in the given
517 domains. Queries in the domains are never forwarded and always
518 replied to with the specified IP address which may be IPv4 or
519 IPv6. To give both IPv4 and IPv6 addresses for a domain, use
520 repeated --address flags. To include multiple IP addresses for
521 a single query, use --addn-hosts=<path> instead. Note that
522 /etc/hosts and DHCP leases override this for individual names. A
523 common use of this is to redirect the entire doubleclick.net
524 domain to some friendly local web server to avoid banner ads.
525 The domain specification works in the same was as for --server,
526 with the additional facility that /#/ matches any domain. Thus
527 --address=/#/1.2.3.4 will always return 1.2.3.4 for any query
528 not answered from /etc/hosts or DHCP and not sent to an upstream
529 nameserver by a more specific --server directive. As for
530 --server, one or more domains with no address returns a no-such-
531 domain answer, so --address=/example.com/ is equivalent to
532 --server=/example.com/ and returns NXDOMAIN for example.com and
533 all its subdomains. An address specified as '#' translates to
534 the NULL address of 0.0.0.0 and its IPv6 equivalent of :: so
535 --address=/example.com/# will return NULL addresses for exam‐
536 ple.com and its subdomains. This is partly syntactic sugar for
537 --address=/example.com/0.0.0.0 and --address=/example.com/:: but
538 is also more efficient than including both as seperate configu‐
539 ration lines. Note that NULL addresses normally work in the same
540 way as localhost, so beware that clients looking up these names
541 are likely to end up talking to themselves.
542 --ipset=/<domain>[/<domain>...]/<ipset>[,<ipset>...]
544 Places the resolved IP addresses of queries for one or more
545 domains in the specified Netfilter IP set. If multiple setnames
546 are given, then the addresses are placed in each of them, sub‐
547 ject to the limitations of an IP set (IPv4 addresses cannot be
548 stored in an IPv6 IP set and vice versa). Domains and subdo‐
549 mains are matched in the same way as --address. These IP sets
550 must already exist. See ipset(8) for more details.
551 -m, --mx-host=<mx name>[[,<hostname>],<preference>]
553 Return an MX record named <mx name> pointing to the given host‐
554 name (if given), or the host specified in the --mx-target switch
555 or, if that switch is not given, the host on which dnsmasq is
556 running. The default is useful for directing mail from systems
557 on a LAN to a central server. The preference value is optional,
558 and defaults to 1 if not given. More than one MX record may be
559 given for a host.
560 -t, --mx-target=<hostname>
562 Specify the default target for the MX record returned by dns‐
563 masq. See --mx-host. If --mx-target is given, but not --mx-
564 host, then dnsmasq returns a MX record containing the MX target
565 for MX queries on the hostname of the machine on which dnsmasq
566 is running.
567 -e, --selfmx
569 Return an MX record pointing to itself for each local machine.
570 Local machines are those in /etc/hosts or with DHCP leases.
571 -L, --localmx
573 Return an MX record pointing to the host given by --mx-target
574 (or the machine on which dnsmasq is running) for each local
575 machine. Local machines are those in /etc/hosts or with DHCP
576 leases.
577 -W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<prior‐
579 ity>[,<weight>]]]]
580 Return a SRV DNS record. See RFC2782 for details. If not sup‐
581 plied, the domain defaults to that given by --domain. The
582 default for the target domain is empty, and the default for port
583 is one and the defaults for weight and priority are zero. Be
584 careful if transposing data from BIND zone files: the port,
585 weight and priority numbers are in a different order. More than
586 one SRV record for a given service/domain is allowed, all that
587 match are returned.
588 --host-
590 record=<name>[,<name>....],[<IPv4-address>],[<IPv6-address>][,<TTL>]
591 Add A, AAAA and PTR records to the DNS. This adds one or more
592 names to the DNS with associated IPv4 (A) and IPv6 (AAAA)
593 records. A name may appear in more than one --host-record and
594 therefore be assigned more than one address. Only the first
595 address creates a PTR record linking the address to the name.
596 This is the same rule as is used reading hosts-files. --host-
597 record options are considered to be read before host-files, so a
598 name appearing there inhibits PTR-record creation if it appears
599 in hosts-file also. Unlike hosts-files, names are not expanded,
600 even when --expand-hosts is in effect. Short and long names may
601 appear in the same --host-record, eg. --host-record=laptop,lap‐
602 top.thekelleys.org,192.168.0.1,1234::100
603 If the time-to-live is given, it overrides the default, which is
605 zero or the value of --local-ttl. The value is a positive inte‐
606 ger and gives the time-to-live in seconds.
607 -Y, --txt-record=<name>[[,<text>],<text>]
609 Return a TXT DNS record. The value of TXT record is a set of
610 strings, so any number may be included, delimited by commas;
611 use quotes to put commas into a string. Note that the maximum
612 length of a single string is 255 characters, longer strings are
613 split into 255 character chunks.
614 --ptr-record=<name>[,<target>]
616 Return a PTR DNS record.
617 --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<reg‐
619 exp>[,<replacement>]
620 Return an NAPTR DNS record, as specified in RFC3403.
621 --caa-record=<name>,<flags>,<tag>,<value>
623 Return a CAA DNS record, as specified in RFC6844.
624 --cname=<cname>,[<cname>,]<target>[,<TTL>]
626 Return a CNAME record which indicates that <cname> is really
627 <target>. There are significant limitations on the target; it
628 must be a DNS name which is known to dnsmasq from /etc/hosts (or
629 additional hosts files), from DHCP, from --interface-name or
630 from another --cname. If the target does not satisfy this cri‐
631 teria, the whole cname is ignored. The cname must be unique, but
632 it is permissible to have more than one cname pointing to the
633 same target. Indeed it's possible to declare multiple cnames to
634 a target in a single line, like so: --cname=cname1,cname2,target
635 If the time-to-live is given, it overrides the default, which is
637 zero or the value of --local-ttl. The value is a positive inte‐
638 ger and gives the time-to-live in seconds.
639 --dns-rr=<name>,<RR-number>,[<hex data>]
641 Return an arbitrary DNS Resource Record. The number is the type
642 of the record (which is always in the C_IN class). The value of
643 the record is given by the hex data, which may be of the form
644 01:23:45 or 01 23 45 or 012345 or any mixture of these.
645 --interface-name=<name>,<interface>[/4|/6]
647 Return DNS records associating the name with the address(es) of
648 the given interface. This flag specifies an A or AAAA record for
649 the given name in the same way as an /etc/hosts line, except
650 that the address is not constant, but taken from the given
651 interface. The interface may be followed by "/4" or "/6" to
652 specify that only IPv4 or IPv6 addresses of the interface should
653 be used. If the interface is down, not configured or non-exis‐
654 tent, an empty record is returned. The matching PTR record is
655 also created, mapping the interface address to the name. More
656 than one name may be associated with an interface address by
657 repeating the flag; in that case the first instance is used for
658 the reverse address-to-name mapping. Note that a name used in
659 --interface-name may not appear in /etc/hosts.
660 --synth-domain=<domain>,<address range>[,<prefix>[*]]
662 Create artificial A/AAAA and PTR records for an address range.
663 The records either seqential numbers or the address, with peri‐
664 ods (or colons for IPv6) replaced with dashes.
665 An examples should make this clearer. First sequential numbers.
667 --synth-domain=thekel‐
668 leys.org.uk,192.168.0.50,192.168.0.70,internal-* results in the
669 name internal-0.thekelleys.org.uk. returning 192.168.0.50,
670 internal-1.thekelleys.org.uk returning 192.168.0.51 and so on.
671 (note the *) The same principle applies to IPv6 addresses (where
672 the numbers may be very large). Reverse lookups from address to
673 name behave as expected.
674 Second, --synth-domain=thekelleys.org.uk,192.168.0.0/24,inter‐
676 nal- (no *) will result in a query for inter‐
677 nal-192-168-0-56.thekelleys.org.uk returning 192.168.0.56 and a
678 reverse query vice versa. The same applies to IPv6, but IPv6
679 addresses may start with '::' but DNS labels may not start with
680 '-' so in this case if no prefix is configured a zero is added
681 in front of the label. ::1 becomes 0--1.
682 V4 mapped IPv6 addresses, which have a representation like
684 ::ffff:1.2.3.4 are handled specially, and become like
685 0--ffff-1-2-3-4
686 The address range can be of the form <ip address>,<ip address>
688 or <ip address>/<netmask> in both forms of the option.
689 --dumpfile=<path/to/file>
691 Specify the location of a pcap-format file which dnsmasq uses to
692 dump copies of network packets for debugging purposes. If the
693 file exists when dnsmasq starts, it is not deleted; new packets
694 are added to the end.
695 --dumpmask=<mask>
697 Specify which types of packets should be added to the dumpfile.
698 The argument should be the OR of the bitmasks for each type of
699 packet to be dumped: it can be specified in hex by preceding the
700 number with 0x in the normal way. Each time a packet is written
701 to the dumpfile, dnsmasq logs the packet sequence and the mask
702 representing its type. The current types are: 0x0001 - DNS
703 queries from clients 0x0002 DNS replies to clients 0x0004 - DNS
704 queries to upstream 0x0008 - DNS replies from upstream 0x0010 -
705 queries send upstream for DNSSEC validation 0x0020 - replies to
706 queries for DNSSEC validation 0x0040 - replies to client queries
707 which fail DNSSEC validation 0x0080 replies to queries for
708 DNSSEC validation which fail validation.
709 --add-mac[=base64|text]
711 Add the MAC address of the requestor to DNS queries which are
712 forwarded upstream. This may be used to DNS filtering by the
713 upstream server. The MAC address can only be added if the
714 requestor is on the same subnet as the dnsmasq server. Note that
715 the mechanism used to achieve this (an EDNS0 option) is not yet
716 standardised, so this should be considered experimental. Also
717 note that exposing MAC addresses in this way may have security
718 and privacy implications. The warning about caching given for
719 --add-subnet applies to --add-mac too. An alternative encoding
720 of the MAC, as base64, is enabled by adding the "base64" parame‐
721 ter and a human-readable encoding of hex-and-colons is enabled
722 by added the "text" parameter.
723 --add-cpe-id=<string>
725 Add an arbitrary identifying string to o DNS queries which are
726 forwarded upstream.
727 --add-subnet[[=[<IPv4 address>/]<IPv4 prefix length>][,[<IPv6
729 address>/]<IPv6 prefix length>]]
730 Add a subnet address to the DNS queries which are forwarded
731 upstream. If an address is specified in the flag, it will be
732 used, otherwise, the address of the requestor will be used. The
733 amount of the address forwarded depends on the prefix length
734 parameter: 32 (128 for IPv6) forwards the whole address, zero
735 forwards none of it but still marks the request so that no
736 upstream nameserver will add client address information either.
737 The default is zero for both IPv4 and IPv6. Note that upstream
738 nameservers may be configured to return different results based
739 on this information, but the dnsmasq cache does not take
740 account. If a dnsmasq instance is configured such that different
741 results may be encountered, caching should be disabled.
742 For example, --add-subnet=24,96 will add the /24 and /96 subnets
744 of the requestor for IPv4 and IPv6 requestors, respectively.
745 --add-subnet=1.2.3.4/24 will add 1.2.3.0/24 for IPv4 requestors
746 and ::/0 for IPv6 requestors. --add-sub‐
747 net=1.2.3.4/24,1.2.3.4/24 will add 1.2.3.0/24 for both IPv4 and
748 IPv6 requestors.
749 -c, --cache-size=<cachesize>
752 Set the size of dnsmasq's cache. The default is 150 names. Set‐
753 ting the cache size to zero disables caching. Note: huge cache
754 size impacts performance.
755 -N, --no-negcache
757 Disable negative caching. Negative caching allows dnsmasq to
758 remember "no such domain" answers from upstream nameservers and
759 answer identical queries without forwarding them again.
760 -0, --dns-forward-max=<queries>
762 Set the maximum number of concurrent DNS queries. The default
763 value is 150, which should be fine for most setups. The only
764 known situation where this needs to be increased is when using
765 web-server log file resolvers, which can generate large numbers
766 of concurrent queries.
767 --dnssec
769 Validate DNS replies and cache DNSSEC data. When forwarding DNS
770 queries, dnsmasq requests the DNSSEC records needed to validate
771 the replies. The replies are validated and the result returned
772 as the Authenticated Data bit in the DNS packet. In addition the
773 DNSSEC records are stored in the cache, making validation by
774 clients more efficient. Note that validation by clients is the
775 most secure DNSSEC mode, but for clients unable to do valida‐
776 tion, use of the AD bit set by dnsmasq is useful, provided that
777 the network between the dnsmasq server and the client is
778 trusted. Dnsmasq must be compiled with HAVE_DNSSEC enabled, and
779 DNSSEC trust anchors provided, see --trust-anchor. Because the
780 DNSSEC validation process uses the cache, it is not permitted to
781 reduce the cache size below the default when DNSSEC is enabled.
782 The nameservers upstream of dnsmasq must be DNSSEC-capable, ie
783 capable of returning DNSSEC records with data. If they are not,
784 then dnsmasq will not be able to determine the trusted status of
785 answers and this means that DNS service will be entirely broken.
786 --trust-anchor=[<class>],<domain>,<key-tag>,<algorithm>,<digest-
788 type>,<digest>
789 Provide DS records to act a trust anchors for DNSSEC validation.
790 Typically these will be the DS record(s) for Key Signing key(s)
791 (KSK) of the root zone, but trust anchors for limited domains
792 are also possible. The current root-zone trust anchors may be
793 downloaded from https://data.iana.org/root-anchors/root-
794 anchors.xml
795 --dnssec-check-unsigned[=no]
797 As a default, dnsmasq checks that unsigned DNS replies are
798 legitimate: this entails possible extra queries even for the
799 majority of DNS zones which are not, at the moment, signed. If
800 --dnssec-check-unsigned=no appears in the configuration, then
801 such replies they are assumed to be valid and passed on (without
802 the "authentic data" bit set, of course). This does not protect
803 against an attacker forging unsigned replies for signed DNS
804 zones, but it is fast.
805 Versions of dnsmasq prior to 2.80 defaulted to not checking
807 unsigned replies, and used --dnssec-check-unsigned to switch
808 this on. Such configurations will continue to work as before,
809 but those which used the default of no checking will need to be
810 altered to explicitly select no checking. The new default is
811 because switching off checking for unsigned replies is inher‐
812 ently dangerous. Not only does it open the possiblity of forged
813 replies, but it allows everything to appear to be working even
814 when the upstream namesevers do not support DNSSEC, and in this
815 case no DNSSEC validation at all is occuring.
816 --dnssec-no-timecheck
818 DNSSEC signatures are only valid for specified time windows, and
819 should be rejected outside those windows. This generates an
820 interesting chicken-and-egg problem for machines which don't
821 have a hardware real time clock. For these machines to determine
822 the correct time typically requires use of NTP and therefore
823 DNS, but validating DNS requires that the correct time is
824 already known. Setting this flag removes the time-window checks
825 (but not other DNSSEC validation.) only until the dnsmasq
826 process receives SIGINT. The intention is that dnsmasq should be
827 started with this flag when the platform determines that reli‐
828 able time is not currently available. As soon as reliable time
829 is established, a SIGINT should be sent to dnsmasq, which
830 enables time checking, and purges the cache of DNS records which
831 have not been thoroughly checked.
832 Earlier versions of dnsmasq overloaded SIGHUP (which re-reads
834 much configuration) to also enable time validation.
835 If dnsmasq is run in debug mode (--no-daemon flag) then SIGINT
837 retains its usual meaning of terminating the dnsmasq process.
838 --dnssec-timestamp=<path>
840 Enables an alternative way of checking the validity of the sys‐
841 tem time for DNSSEC (see --dnssec-no-timecheck). In this case,
842 the system time is considered to be valid once it becomes later
843 than the timestamp on the specified file. The file is created
844 and its timestamp set automatically by dnsmasq. The file must be
845 stored on a persistent filesystem, so that it and its mtime are
846 carried over system restarts. The timestamp file is created
847 after dnsmasq has dropped root, so it must be in a location
848 writable by the unprivileged user that dnsmasq runs as.
849 --proxy-dnssec
851 Copy the DNSSEC Authenticated Data bit from upstream servers to
852 downstream clients and cache it. This is an alternative to hav‐
853 ing dnsmasq validate DNSSEC, but it depends on the security of
854 the network between dnsmasq and the upstream servers, and the
855 trustworthiness of the upstream servers.
856 --dnssec-debug
858 Set debugging mode for the DNSSEC validation, set the Checking
859 Disabled bit on upstream queries, and don't convert replies
860 which do not validate to responses with a return code of SERV‐
861 FAIL. Note that setting this may affect DNS behaviour in bad
862 ways, it is not an extra-logging flag and should not be set in
863 production.
864 --auth-zone=<domain>[,<subnet>[/<prefix length>][,<subnet>[/<prefix
866 length>].....][,exclude:<subnet>[/<prefix length>]].....]
867 Define a DNS zone for which dnsmasq acts as authoritative
868 server. Locally defined DNS records which are in the domain will
869 be served. If subnet(s) are given, A and AAAA records must be in
870 one of the specified subnets.
871 As alternative to directly specifying the subnets, it's possible
873 to give the name of an interface, in which case the subnets
874 implied by that interface's configured addresses and net‐
875 mask/prefix-length are used; this is useful when using con‐
876 structed DHCP ranges as the actual address is dynamic and not
877 known when configuring dnsmasq. The interface addresses may be
878 confined to only IPv6 addresses using <interface>/6 or to only
879 IPv4 using <interface>/4. This is useful when an interface has
880 dynamically determined global IPv6 addresses which should appear
881 in the zone, but RFC1918 IPv4 addresses which should not.
882 Interface-name and address-literal subnet specifications may be
883 used freely in the same --auth-zone declaration.
884 It's possible to exclude certain IP addresses from responses. It
886 can be used, to make sure that answers contain only global
887 routeable IP addresses (by excluding loopback, RFC1918 and ULA
888 addresses).
889 The subnet(s) are also used to define in-addr.arpa and ip6.arpa
891 domains which are served for reverse-DNS queries. If not speci‐
892 fied, the prefix length defaults to 24 for IPv4 and 64 for IPv6.
893 For IPv4 subnets, the prefix length should be have the value 8,
894 16 or 24 unless you are familiar with RFC 2317 and have arranged
895 the in-addr.arpa delegation accordingly. Note that if no subnets
896 are specified, then no reverse queries are answered.
897 --auth-soa=<serial>[,<hostmaster>[,<refresh>[,<retry>[,<expiry>]]]]
899 Specify fields in the SOA record associated with authoritative
900 zones. Note that this is optional, all the values are set to
901 sane defaults.
902 --auth-sec-servers=<domain>[,<domain>[,<domain>...]]
904 Specify any secondary servers for a zone for which dnsmasq is
905 authoritative. These servers must be configured to get zone data
906 from dnsmasq by zone transfer, and answer queries for the same
907 authoritative zones as dnsmasq.
908 --auth-peer=<ip-address>[,<ip-address>[,<ip-address>...]]
910 Specify the addresses of secondary servers which are allowed to
911 initiate zone transfer (AXFR) requests for zones for which dns‐
912 masq is authoritative. If this option is not given but --auth-
913 sec-servers is, then AXFR requests will be accepted from any
914 secondary. Specifying --auth-peer without --auth-sec-servers
915 enables zone transfer but does not advertise the secondary in NS
916 records returned by dnsmasq.
917 --conntrack
919 Read the Linux connection track mark associated with incoming
920 DNS queries and set the same mark value on upstream traffic used
921 to answer those queries. This allows traffic generated by dns‐
922 masq to be associated with the queries which cause it, useful
923 for bandwidth accounting and firewalling. Dnsmasq must have con‐
924 ntrack support compiled in and the kernel must have conntrack
925 support included and configured. This option cannot be combined
926 with --query-port.
927 -F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-
929 addr>[,<end-addr>|<mode>][,<netmask>[,<broadcast>]][,<lease time>]
930 -F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-
932 IPv6addr>[,<end-IPv6addr>|constructor:<interface>][,<mode>][,<prefix-
933 len>][,<lease time>]
934 Enable the DHCP server. Addresses will be given out from the
936 range <start-addr> to <end-addr> and from statically defined
937 addresses given in --dhcp-host options. If the lease time is
938 given, then leases will be given for that length of time. The
939 lease time is in seconds, or minutes (eg 45m) or hours (eg 1h)
940 or "infinite". If not given, the default lease time is one hour.
941 The minimum lease time is two minutes. For IPv6 ranges, the
942 lease time maybe "deprecated"; this sets the preferred lifetime
943 sent in a DHCP lease or router advertisement to zero, which
944 causes clients to use other addresses, if available, for new
945 connections as a prelude to renumbering.
946 This option may be repeated, with different addresses, to enable
948 DHCP service to more than one network. For directly connected
949 networks (ie, networks on which the machine running dnsmasq has
950 an interface) the netmask is optional: dnsmasq will determine it
951 from the interface configuration. For networks which receive
952 DHCP service via a relay agent, dnsmasq cannot determine the
953 netmask itself, so it should be specified, otherwise dnsmasq
954 will have to guess, based on the class (A, B or C) of the net‐
955 work address. The broadcast address is always optional. It is
956 always allowed to have more than one --dhcp-range in a single
957 subnet.
958 For IPv6, the parameters are slightly different: instead of net‐
960 mask and broadcast address, there is an optional prefix length
961 which must be equal to or larger then the prefix length on the
962 local interface. If not given, this defaults to 64. Unlike the
963 IPv4 case, the prefix length is not automatically derived from
964 the interface configuration. The minimum size of the prefix
965 length is 64.
966 IPv6 (only) supports another type of range. In this, the start
968 address and optional end address contain only the network part
969 (ie ::1) and they are followed by constructor:<interface>. This
970 forms a template which describes how to create ranges, based on
971 the addresses assigned to the interface. For instance
972 --dhcp-range=::1,::400,constructor:eth0
974 will look for addresses on eth0 and then create a range from
976 <network>::1 to <network>::400. If the interface is assigned
977 more than one network, then the corresponding ranges will be
978 automatically created, and then deprecated and finally removed
979 again as the address is deprecated and then deleted. The inter‐
980 face name may have a final "*" wildcard. Note that just any
981 address on eth0 will not do: it must not be an autoconfigured or
982 privacy address, or be deprecated.
983 If a --dhcp-range is only being used for stateless DHCP and/or
985 SLAAC, then the address can be simply ::
986 --dhcp-range=::,constructor:eth0
988 The optional set:<tag> sets an alphanumeric label which marks
991 this network so that dhcp options may be specified on a per-net‐
992 work basis. When it is prefixed with 'tag:' instead, then its
993 meaning changes from setting a tag to matching it. Only one tag
994 may be set, but more than one tag may be matched.
995 The optional <mode> keyword may be static which tells dnsmasq to
997 enable DHCP for the network specified, but not to dynamically
998 allocate IP addresses: only hosts which have static addresses
999 given via --dhcp-host or from /etc/ethers will be served. A
1000 static-only subnet with address all zeros may be used as a
1001 "catch-all" address to enable replies to all Information-request
1002 packets on a subnet which is provided with stateless DHCPv6, ie
1003 --dhcp-range=::,static
1004 For IPv4, the <mode> may be proxy in which case dnsmasq will
1006 provide proxy-DHCP on the specified subnet. (See --pxe-prompt
1007 and --pxe-service for details.)
1008 For IPv6, the mode may be some combination of ra-only, slaac,
1010 ra-names, ra-stateless, ra-advrouter, off-link.
1011 ra-only tells dnsmasq to offer Router Advertisement only on this
1013 subnet, and not DHCP.
1014 slaac tells dnsmasq to offer Router Advertisement on this subnet
1016 and to set the A bit in the router advertisement, so that the
1017 client will use SLAAC addresses. When used with a DHCP range or
1018 static DHCP address this results in the client having both a
1019 DHCP-assigned and a SLAAC address.
1020 ra-stateless sends router advertisements with the O and A bits
1022 set, and provides a stateless DHCP service. The client will use
1023 a SLAAC address, and use DHCP for other configuration informa‐
1024 tion.
1025 ra-names enables a mode which gives DNS names to dual-stack
1027 hosts which do SLAAC for IPv6. Dnsmasq uses the host's IPv4
1028 lease to derive the name, network segment and MAC address and
1029 assumes that the host will also have an IPv6 address calculated
1030 using the SLAAC algorithm, on the same network segment. The
1031 address is pinged, and if a reply is received, an AAAA record is
1032 added to the DNS for this IPv6 address. Note that this is only
1033 happens for directly-connected networks, (not one doing DHCP via
1034 a relay) and it will not work if a host is using privacy exten‐
1035 sions. ra-names can be combined with ra-stateless and slaac.
1036 ra-advrouter enables a mode where router address(es) rather than
1038 prefix(es) are included in the advertisements. This is
1039 described in RFC-3775 section 7.2 and is used in mobile IPv6. In
1040 this mode the interval option is also included, as described in
1041 RFC-3775 section 7.3.
1042 off-link tells dnsmasq to advertise the prefix without the on-
1044 link (aka L) bit set.
1045 -G, --dhcp-
1048 host=[<hwaddr>][,id:<client_id>|*][,set:<tag>][,<ipaddr>][,<host‐
1049 name>][,<lease_time>][,ignore]
1050 Specify per host parameters for the DHCP server. This allows a
1051 machine with a particular hardware address to be always allo‐
1052 cated the same hostname, IP address and lease time. A hostname
1053 specified like this overrides any supplied by the DHCP client on
1054 the machine. It is also allowable to omit the hardware address
1055 and include the hostname, in which case the IP address and lease
1056 times will apply to any machine claiming that name. For example
1057 --dhcp-host=00:20:e0:3b:13:af,wap,infinite tells dnsmasq to give
1058 the machine with hardware address 00:20:e0:3b:13:af the name
1059 wap, and an infinite DHCP lease. --dhcp-host=lap,192.168.0.199
1060 tells dnsmasq to always allocate the machine lap the IP address
1061 192.168.0.199.
1062 Addresses allocated like this are not constrained to be in the
1064 range given by the --dhcp-range option, but they must be in the
1065 same subnet as some valid dhcp-range. For subnets which don't
1066 need a pool of dynamically allocated addresses, use the "static"
1067 keyword in the --dhcp-range declaration.
1068 It is allowed to use client identifiers (called client DUID in
1070 IPv6-land) rather than hardware addresses to identify hosts by
1071 prefixing with 'id:'. Thus: --dhcp-host=id:01:02:03:04,.....
1072 refers to the host with client identifier 01:02:03:04. It is
1073 also allowed to specify the client ID as text, like this:
1074 --dhcp-host=id:clientidastext,.....
1075 A single --dhcp-host may contain an IPv4 address or an IPv6
1077 address, or both. IPv6 addresses must be bracketed by square
1078 brackets thus: --dhcp-host=laptop,[1234::56] IPv6 addresses may
1079 contain only the host-identifier part: --dhcp-host=laptop,[::56]
1080 in which case they act as wildcards in constructed dhcp ranges,
1081 with the appropriate network part inserted. Note that in IPv6
1082 DHCP, the hardware address may not be available, though it nor‐
1083 mally is for direct-connected clients, or clients using DHCP
1084 relays which support RFC 6939.
1085 For DHCPv4, the special option id:* means "ignore any client-id
1088 and use MAC addresses only." This is useful when a client
1089 presents a client-id sometimes but not others.
1090 If a name appears in /etc/hosts, the associated address can be
1092 allocated to a DHCP lease, but only if a --dhcp-host option
1093 specifying the name also exists. Only one hostname can be given
1094 in a --dhcp-host option, but aliases are possible by using
1095 CNAMEs. (See --cname ).
1096 The special keyword "ignore" tells dnsmasq to never offer a DHCP
1098 lease to a machine. The machine can be specified by hardware
1099 address, client ID or hostname, for instance --dhcp-
1100 host=00:20:e0:3b:13:af,ignore This is useful when there is
1101 another DHCP server on the network which should be used by some
1102 machines.
1103 The set:<tag> construct sets the tag whenever this --dhcp-host
1105 directive is in use. This can be used to selectively send DHCP
1106 options just for this host. More than one tag can be set in a
1107 --dhcp-host directive (but not in other places where "set:<tag>"
1108 is allowed). When a host matches any --dhcp-host directive (or
1109 one implied by /etc/ethers) then the special tag "known" is set.
1110 This allows dnsmasq to be configured to ignore requests from
1111 unknown machines using --dhcp-ignore=tag:!known If the host
1112 matches only a --dhcp-host directive which cannot be used
1113 because it specifies an address on different subnet, the tag
1114 "known-othernet" is set. Ethernet addresses (but not client-
1115 ids) may have wildcard bytes, so for example --dhcp-
1116 host=00:20:e0:3b:13:*,ignore will cause dnsmasq to ignore a
1117 range of hardware addresses. Note that the "*" will need to be
1118 escaped or quoted on a command line, but not in the configura‐
1119 tion file.
1120 Hardware addresses normally match any network (ARP) type, but it
1122 is possible to restrict them to a single ARP type by preceding
1123 them with the ARP-type (in HEX) and "-". so --dhcp-
1124 host=06-00:20:e0:3b:13:af,1.2.3.4 will only match a Token-Ring
1125 hardware address, since the ARP-address type for token ring is
1126 6.
1127 As a special case, in DHCPv4, it is possible to include more
1129 than one hardware address. eg: --dhcp-
1130 host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2 This allows
1131 an IP address to be associated with multiple hardware addresses,
1132 and gives dnsmasq permission to abandon a DHCP lease to one of
1133 the hardware addresses when another one asks for a lease. Beware
1134 that this is a dangerous thing to do, it will only work reliably
1135 if only one of the hardware addresses is active at any time and
1136 there is no way for dnsmasq to enforce this. It is, for
1137 instance, useful to allocate a stable IP address to a laptop
1138 which has both wired and wireless interfaces.
1139 --dhcp-hostsfile=<path>
1141 Read DHCP host information from the specified file. If a direc‐
1142 tory is given, then read all the files contained in that direc‐
1143 tory. The file contains information about one host per line. The
1144 format of a line is the same as text to the right of '=' in
1145 --dhcp-host. The advantage of storing DHCP host information in
1146 this file is that it can be changed without re-starting dnsmasq:
1147 the file will be re-read when dnsmasq receives SIGHUP.
1148 --dhcp-optsfile=<path>
1150 Read DHCP option information from the specified file. If a
1151 directory is given, then read all the files contained in that
1152 directory. The advantage of using this option is the same as for
1153 --dhcp-hostsfile: the --dhcp-optsfile will be re-read when dns‐
1154 masq receives SIGHUP. Note that it is possible to encode the
1155 information in a --dhcp-boot flag as DHCP options, using the
1156 options names bootfile-name, server-ip-address and tftp-server.
1157 This allows these to be included in a --dhcp-optsfile.
1158 --dhcp-hostsdir=<path>
1160 This is equivalent to --dhcp-hostsfile, except for the follow‐
1161 ing. The path MUST be a directory, and not an individual file.
1162 Changed or new files within the directory are read automati‐
1163 cally, without the need to send SIGHUP. If a file is deleted or
1164 changed after it has been read by dnsmasq, then the host record
1165 it contained will remain until dnsmasq receives a SIGHUP, or is
1166 restarted; ie host records are only added dynamically.
1167 --dhcp-optsdir=<path>
1169 This is equivalent to --dhcp-optsfile, with the differences
1170 noted for --dhcp-hostsdir.
1171 -Z, --read-ethers
1173 Read /etc/ethers for information about hosts for the DHCP
1174 server. The format of /etc/ethers is a hardware address, fol‐
1175 lowed by either a hostname or dotted-quad IP address. When read
1176 by dnsmasq these lines have exactly the same effect as --dhcp-
1177 host options containing the same information. /etc/ethers is re-
1178 read when dnsmasq receives SIGHUP. IPv6 addresses are NOT read
1179 from /etc/ethers.
1180 -O, --dhcp-option=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-
1182 encap:<enterprise>,][vendor:[<vendor-class>],][<opt>|option:<opt-
1183 name>|option6:<opt>|option6:<opt-name>],[<value>[,<value>]]
1184 Specify different or extra options to DHCP clients. By default,
1185 dnsmasq sends some standard options to DHCP clients, the netmask
1186 and broadcast address are set to the same as the host running
1187 dnsmasq, and the DNS server and default route are set to the
1188 address of the machine running dnsmasq. (Equivalent rules apply
1189 for IPv6.) If the domain name option has been set, that is sent.
1190 This configuration allows these defaults to be overridden, or
1191 other options specified. The option, to be sent may be given as
1192 a decimal number or as "option:<option-name>" The option numbers
1193 are specified in RFC2132 and subsequent RFCs. The set of option-
1194 names known by dnsmasq can be discovered by running "dnsmasq
1195 --help dhcp". For example, to set the default route option to
1196 192.168.4.4, do --dhcp-option=3,192.168.4.4 or --dhcp-option =
1197 option:router, 192.168.4.4 and to set the time-server address to
1198 192.168.0.4, do --dhcp-option = 42,192.168.0.4 or --dhcp-option
1199 = option:ntp-server, 192.168.0.4 The special address 0.0.0.0 is
1200 taken to mean "the address of the machine running dnsmasq".
1201 Data types allowed are comma separated dotted-quad IPv4
1203 addresses, []-wrapped IPv6 addresses, a decimal number, colon-
1204 separated hex digits and a text string. If the optional tags are
1205 given then this option is only sent when all the tags are
1206 matched.
1207 Special processing is done on a text argument for option 119, to
1209 conform with RFC 3397. Text or dotted-quad IP addresses as argu‐
1210 ments to option 120 are handled as per RFC 3361. Dotted-quad IP
1211 addresses which are followed by a slash and then a netmask size
1212 are encoded as described in RFC 3442.
1213 IPv6 options are specified using the option6: keyword, followed
1215 by the option number or option name. The IPv6 option name space
1216 is disjoint from the IPv4 option name space. IPv6 addresses in
1217 options must be bracketed with square brackets, eg. --dhcp-
1218 option=option6:ntp-server,[1234::56] For IPv6, [::] means "the
1219 global address of the machine running dnsmasq", whilst [fd00::]
1220 is replaced with the ULA, if it exists, and [fe80::] with the
1221 link-local address.
1222 Be careful: no checking is done that the correct type of data
1224 for the option number is sent, it is quite possible to persuade
1225 dnsmasq to generate illegal DHCP packets with injudicious use of
1226 this flag. When the value is a decimal number, dnsmasq must
1227 determine how large the data item is. It does this by examining
1228 the option number and/or the value, but can be overridden by
1229 appending a single letter flag as follows: b = one byte, s = two
1230 bytes, i = four bytes. This is mainly useful with encapsulated
1231 vendor class options (see below) where dnsmasq cannot determine
1232 data size from the option number. Option data which consists
1233 solely of periods and digits will be interpreted by dnsmasq as
1234 an IP address, and inserted into an option as such. To force a
1235 literal string, use quotes. For instance when using option 66 to
1236 send a literal IP address as TFTP server name, it is necessary
1237 to do --dhcp-option=66,"1.2.3.4"
1238 Encapsulated Vendor-class options may also be specified (IPv4
1240 only) using --dhcp-option: for instance --dhcp-option=ven‐
1241 dor:PXEClient,1,0.0.0.0 sends the encapsulated vendor class-spe‐
1242 cific option "mftp-address=0.0.0.0" to any client whose vendor-
1243 class matches "PXEClient". The vendor-class matching is sub‐
1244 string based (see --dhcp-vendorclass for details). If a vendor-
1245 class option (number 60) is sent by dnsmasq, then that is used
1246 for selecting encapsulated options in preference to any sent by
1247 the client. It is possible to omit the vendorclass completely;
1248 --dhcp-option=vendor:,1,0.0.0.0 in which case the encapsulated
1249 option is always sent.
1250 Options may be encapsulated (IPv4 only) within other options:
1252 for instance --dhcp-option=encap:175, 190, iscsi-client0 will
1253 send option 175, within which is the option 190. If multiple
1254 options are given which are encapsulated with the same option
1255 number then they will be correctly combined into one encapsu‐
1256 lated option. encap: and vendor: are may not both be set in the
1257 same --dhcp-option.
1258 The final variant on encapsulated options is "Vendor-Identifying
1260 Vendor Options" as specified by RFC3925. These are denoted like
1261 this: --dhcp-option=vi-encap:2, 10, text The number in the vi-
1262 encap: section is the IANA enterprise number used to identify
1263 this option. This form of encapsulation is supported in IPv6.
1264 The address 0.0.0.0 is not treated specially in encapsulated
1266 options.
1267 --dhcp-option-force=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-
1269 encap:<enterprise>,][vendor:[<vendor-class>],]<opt>,[<value>[,<value>]]
1270 This works in exactly the same way as --dhcp-option except that
1271 the option will always be sent, even if the client does not ask
1272 for it in the parameter request list. This is sometimes needed,
1273 for example when sending options to PXELinux.
1274 --dhcp-no-override
1276 (IPv4 only) Disable re-use of the DHCP servername and filename
1277 fields as extra option space. If it can, dnsmasq moves the boot
1278 server and filename information (from --dhcp-boot) out of their
1279 dedicated fields into DHCP options. This make extra space avail‐
1280 able in the DHCP packet for options but can, rarely, confuse old
1281 or broken clients. This flag forces "simple and safe" behaviour
1282 to avoid problems in such a case.
1283 --dhcp-relay=<local address>,<server address>[,<interface]
1285 Configure dnsmasq to do DHCP relay. The local address is an
1286 address allocated to an interface on the host running dnsmasq.
1287 All DHCP requests arriving on that interface will we relayed to
1288 a remote DHCP server at the server address. It is possible to
1289 relay from a single local address to multiple remote servers by
1290 using multiple --dhcp-relay configs with the same local address
1291 and different server addresses. A server address must be an IP
1292 literal address, not a domain name. In the case of DHCPv6, the
1293 server address may be the ALL_SERVERS multicast address,
1294 ff05::1:3. In this case the interface must be given, not be
1295 wildcard, and is used to direct the multicast to the correct
1296 interface to reach the DHCP server.
1297 Access control for DHCP clients has the same rules as for the
1299 DHCP server, see --interface, --except-interface, etc. The
1300 optional interface name in the --dhcp-relay config has a differ‐
1301 ent function: it controls on which interface DHCP replies from
1302 the server will be accepted. This is intended for configurations
1303 which have three interfaces: one being relayed from, a second
1304 connecting the DHCP server, and a third untrusted network, typi‐
1305 cally the wider internet. It avoids the possibility of spoof
1306 replies arriving via this third interface.
1307 It is allowed to have dnsmasq act as a DHCP server on one set of
1309 interfaces and relay from a disjoint set of interfaces. Note
1310 that whilst it is quite possible to write configurations which
1311 appear to act as a server and a relay on the same interface,
1312 this is not supported: the relay function will take precedence.
1313 Both DHCPv4 and DHCPv6 relay is supported. It's not possible to
1315 relay DHCPv4 to a DHCPv6 server or vice-versa.
1316 -U, --dhcp-vendorclass=set:<tag>,[enterprise:<IANA-enterprise num‐
1318 ber>,]<vendor-class>
1319 Map from a vendor-class string to a tag. Most DHCP clients pro‐
1320 vide a "vendor class" which represents, in some sense, the type
1321 of host. This option maps vendor classes to tags, so that DHCP
1322 options may be selectively delivered to different classes of
1323 hosts. For example --dhcp-vendorclass=set:printers,Hewlett-
1324 Packard JetDirect will allow options to be set only for HP
1325 printers like so: --dhcp-option=tag:printers,3,192.168.4.4 The
1326 vendor-class string is substring matched against the vendor-
1327 class supplied by the client, to allow fuzzy matching. The set:
1328 prefix is optional but allowed for consistency.
1329 Note that in IPv6 only, vendorclasses are namespaced with an
1331 IANA-allocated enterprise number. This is given with enterprise:
1332 keyword and specifies that only vendorclasses matching the spec‐
1333 ified number should be searched.
1334 -j, --dhcp-userclass=set:<tag>,<user-class>
1336 Map from a user-class string to a tag (with substring matching,
1337 like vendor classes). Most DHCP clients provide a "user class"
1338 which is configurable. This option maps user classes to tags, so
1339 that DHCP options may be selectively delivered to different
1340 classes of hosts. It is possible, for instance to use this to
1341 set a different printer server for hosts in the class "accounts"
1342 than for hosts in the class "engineering".
1343 -4, --dhcp-mac=set:<tag>,<MAC address>
1345 Map from a MAC address to a tag. The MAC address may include
1346 wildcards. For example --dhcp-mac=set:3com,01:34:23:*:*:* will
1347 set the tag "3com" for any host whose MAC address matches the
1348 pattern.
1349 --dhcp-circuitid=set:<tag>,<circuit-id>, --dhcp-
1351 remoteid=set:<tag>,<remote-id>
1352 Map from RFC3046 relay agent options to tags. This data may be
1353 provided by DHCP relay agents. The circuit-id or remote-id is
1354 normally given as colon-separated hex, but is also allowed to be
1355 a simple string. If an exact match is achieved between the cir‐
1356 cuit or agent ID and one provided by a relay agent, the tag is
1357 set.
1358 --dhcp-remoteid (but not --dhcp-circuitid) is supported in IPv6.
1360 --dhcp-subscrid=set:<tag>,<subscriber-id>
1362 (IPv4 and IPv6) Map from RFC3993 subscriber-id relay agent
1363 options to tags.
1364 --dhcp-proxy[=<ip addr>]......
1366 (IPv4 only) A normal DHCP relay agent is only used to forward
1367 the initial parts of a DHCP interaction to the DHCP server. Once
1368 a client is configured, it communicates directly with the
1369 server. This is undesirable if the relay agent is adding extra
1370 information to the DHCP packets, such as that used by --dhcp-
1371 circuitid and --dhcp-remoteid. A full relay implementation can
1372 use the RFC 5107 serverid-override option to force the DHCP
1373 server to use the relay as a full proxy, with all packets pass‐
1374 ing through it. This flag provides an alternative method of
1375 doing the same thing, for relays which don't support RFC 5107.
1376 Given alone, it manipulates the server-id for all interactions
1377 via relays. If a list of IP addresses is given, only interac‐
1378 tions via relays at those addresses are affected.
1379 --dhcp-match=set:<tag>,<option number>|option:<option name>|vi-
1381 encap:<enterprise>[,<value>]
1382 Without a value, set the tag if the client sends a DHCP option
1383 of the given number or name. When a value is given, set the tag
1384 only if the option is sent and matches the value. The value may
1385 be of the form "01:ff:*:02" in which case the value must match
1386 (apart from wildcards) but the option sent may have unmatched
1387 data past the end of the value. The value may also be of the
1388 same form as in --dhcp-option in which case the option sent is
1389 treated as an array, and one element must match, so --dhcp-
1390 match=set:efi-ia32,option:client-arch,6 will set the tag "efi-
1391 ia32" if the the number 6 appears in the list of architectures
1392 sent by the client in option 93. (See RFC 4578 for details.) If
1393 the value is a string, substring matching is used.
1394 The special form with vi-encap:<enterprise number> matches
1396 against vendor-identifying vendor classes for the specified
1397 enterprise. Please see RFC 3925 for more details of these rare
1398 and interesting beasts.
1399 --dhcp-name-match=set:<tag>,<name>[*]
1401 Set the tag if the given name is supplied by a dhcp client.
1402 There may be a single trailing wildcard *, which has the usual
1403 meaning. Combined with dhcp-ignore or dhcp-ignore-names this
1404 gives the ability to ignore certain clients by name, or disallow
1405 certain hostnames from being claimed by a client.
1406 --tag-if=set:<tag>[,set:<tag>[,tag:<tag>[,tag:<tag>]]]
1408 Perform boolean operations on tags. Any tag appearing as
1409 set:<tag> is set if all the tags which appear as tag:<tag> are
1410 set, (or unset when tag:!<tag> is used) If no tag:<tag> appears
1411 set:<tag> tags are set unconditionally. Any number of set: and
1412 tag: forms may appear, in any order. --tag-if lines are exe‐
1413 cuted in order, so if the tag in tag:<tag> is a tag set by
1414 another --tag-if, the line which sets the tag must precede the
1415 one which tests it.
1416 -J, --dhcp-ignore=tag:<tag>[,tag:<tag>]
1418 When all the given tags appear in the tag set ignore the host
1419 and do not allocate it a DHCP lease.
1420 --dhcp-ignore-names[=tag:<tag>[,tag:<tag>]]
1422 When all the given tags appear in the tag set, ignore any host‐
1423 name provided by the host. Note that, unlike --dhcp-ignore, it
1424 is permissible to supply no tags, in which case DHCP-client sup‐
1425 plied hostnames are always ignored, and DHCP hosts are added to
1426 the DNS using only --dhcp-host configuration in dnsmasq and the
1427 contents of /etc/hosts and /etc/ethers.
1428 --dhcp-generate-names=tag:<tag>[,tag:<tag>]
1430 (IPv4 only) Generate a name for DHCP clients which do not other‐
1431 wise have one, using the MAC address expressed in hex, separated
1432 by dashes. Note that if a host provides a name, it will be used
1433 by preference to this, unless --dhcp-ignore-names is set.
1434 --dhcp-broadcast[=tag:<tag>[,tag:<tag>]]
1436 (IPv4 only) When all the given tags appear in the tag set,
1437 always use broadcast to communicate with the host when it is
1438 unconfigured. It is permissible to supply no tags, in which case
1439 this is unconditional. Most DHCP clients which need broadcast
1440 replies set a flag in their requests so that this happens auto‐
1441 matically, some old BOOTP clients do not.
1442 -M, --dhcp-boot=[tag:<tag>,]<filename>,[<servername>[,<server
1444 address>|<tftp_servername>]]
1445 (IPv4 only) Set BOOTP options to be returned by the DHCP server.
1446 Server name and address are optional: if not provided, the name
1447 is left empty, and the address set to the address of the machine
1448 running dnsmasq. If dnsmasq is providing a TFTP service (see
1449 --enable-tftp ) then only the filename is required here to
1450 enable network booting. If the optional tag(s) are given, they
1451 must match for this configuration to be sent. Instead of an IP
1452 address, the TFTP server address can be given as a domain name
1453 which is looked up in /etc/hosts. This name can be associated in
1454 /etc/hosts with multiple IP addresses, which are used round-
1455 robin. This facility can be used to load balance the tftp load
1456 among a set of servers.
1457 --dhcp-sequential-ip
1459 Dnsmasq is designed to choose IP addresses for DHCP clients
1460 using a hash of the client's MAC address. This normally allows a
1461 client's address to remain stable long-term, even if the client
1462 sometimes allows its DHCP lease to expire. In this default mode
1463 IP addresses are distributed pseudo-randomly over the entire
1464 available address range. There are sometimes circumstances (typ‐
1465 ically server deployment) where it is more convenient to have IP
1466 addresses allocated sequentially, starting from the lowest
1467 available address, and setting this flag enables this mode. Note
1468 that in the sequential mode, clients which allow a lease to
1469 expire are much more likely to move IP address; for this reason
1470 it should not be generally used.
1471 --pxe-service=[tag:<tag>,]<CSA>,<menu text>[,<basename>|<bootservice‐
1473 type>][,<server address>|<server_name>]
1474 Most uses of PXE boot-ROMS simply allow the PXE system to obtain
1475 an IP address and then download the file specified by --dhcp-
1476 boot and execute it. However the PXE system is capable of more
1477 complex functions when supported by a suitable DHCP server.
1478 This specifies a boot option which may appear in a PXE boot
1480 menu. <CSA> is client system type, only services of the correct
1481 type will appear in a menu. The known types are x86PC, PC98,
1482 IA64_EFI, Alpha, Arc_x86, Intel_Lean_Client, IA32_EFI,
1483 X86-64_EFI, Xscale_EFI, BC_EFI, ARM32_EFI and ARM64_EFI; an
1484 integer may be used for other types. The parameter after the
1485 menu text may be a file name, in which case dnsmasq acts as a
1486 boot server and directs the PXE client to download the file by
1487 TFTP, either from itself ( --enable-tftp must be set for this to
1488 work) or another TFTP server if the final server address/name is
1489 given. Note that the "layer" suffix (normally ".0") is supplied
1490 by PXE, and need not be added to the basename. Alternatively,
1491 the basename may be a filename, complete with suffix, in which
1492 case no layer suffix is added. If an integer boot service type,
1493 rather than a basename is given, then the PXE client will search
1494 for a suitable boot service for that type on the network. This
1495 search may be done by broadcast, or direct to a server if its IP
1496 address/name is provided. If no boot service type or filename
1497 is provided (or a boot service type of 0 is specified) then the
1498 menu entry will abort the net boot procedure and continue boot‐
1499 ing from local media. The server address can be given as a
1500 domain name which is looked up in /etc/hosts. This name can be
1501 associated in /etc/hosts with multiple IP addresses, which are
1502 used round-robin.
1503 --pxe-prompt=[tag:<tag>,]<prompt>[,<timeout>]
1505 Setting this provides a prompt to be displayed after PXE boot.
1506 If the timeout is given then after the timeout has elapsed with
1507 no keyboard input, the first available menu option will be auto‐
1508 matically executed. If the timeout is zero then the first avail‐
1509 able menu item will be executed immediately. If --pxe-prompt is
1510 omitted the system will wait for user input if there are multi‐
1511 ple items in the menu, but boot immediately if there is only
1512 one. See --pxe-service for details of menu items.
1513 Dnsmasq supports PXE "proxy-DHCP", in this case another DHCP
1515 server on the network is responsible for allocating IP
1516 addresses, and dnsmasq simply provides the information given in
1517 --pxe-prompt and --pxe-service to allow netbooting. This mode is
1518 enabled using the proxy keyword in --dhcp-range.
1519 -X, --dhcp-lease-max=<number>
1521 Limits dnsmasq to the specified maximum number of DHCP leases.
1522 The default is 1000. This limit is to prevent DoS attacks from
1523 hosts which create thousands of leases and use lots of memory in
1524 the dnsmasq process.
1525 -K, --dhcp-authoritative
1527 Should be set when dnsmasq is definitely the only DHCP server on
1528 a network. For DHCPv4, it changes the behaviour from strict RFC
1529 compliance so that DHCP requests on unknown leases from unknown
1530 hosts are not ignored. This allows new hosts to get a lease
1531 without a tedious timeout under all circumstances. It also
1532 allows dnsmasq to rebuild its lease database without each client
1533 needing to reacquire a lease, if the database is lost. For
1534 DHCPv6 it sets the priority in replies to 255 (the maximum)
1535 instead of 0 (the minimum).
1536 --dhcp-rapid-commit
1538 Enable DHCPv4 Rapid Commit Option specified in RFC 4039. When
1539 enabled, dnsmasq will respond to a DHCPDISCOVER message includ‐
1540 ing a Rapid Commit option with a DHCPACK including a Rapid Com‐
1541 mit option and fully committed address and configuration infor‐
1542 mation. Should only be enabled if either the server is the only
1543 server for the subnet, or multiple servers are present and they
1544 each commit a binding for all clients.
1545 --dhcp-alternate-port[=<server port>[,<client port>]]
1547 (IPv4 only) Change the ports used for DHCP from the default. If
1548 this option is given alone, without arguments, it changes the
1549 ports used for DHCP from 67 and 68 to 1067 and 1068. If a single
1550 argument is given, that port number is used for the server and
1551 the port number plus one used for the client. Finally, two port
1552 numbers allows arbitrary specification of both server and client
1553 ports for DHCP.
1554 -3, --bootp-dynamic[=<network-id>[,<network-id>]]
1556 (IPv4 only) Enable dynamic allocation of IP addresses to BOOTP
1557 clients. Use this with care, since each address allocated to a
1558 BOOTP client is leased forever, and therefore becomes perma‐
1559 nently unavailable for re-use by other hosts. if this is given
1560 without tags, then it unconditionally enables dynamic alloca‐
1561 tion. With tags, only when the tags are all set. It may be
1562 repeated with different tag sets.
1563 -5, --no-ping
1565 (IPv4 only) By default, the DHCP server will attempt to ensure
1566 that an address is not in use before allocating it to a host. It
1567 does this by sending an ICMP echo request (aka "ping") to the
1568 address in question. If it gets a reply, then the address must
1569 already be in use, and another is tried. This flag disables this
1570 check. Use with caution.
1571 --log-dhcp
1573 Extra logging for DHCP: log all the options sent to DHCP clients
1574 and the tags used to determine them.
1575 --quiet-dhcp, --quiet-dhcp6, --quiet-ra
1577 Suppress logging of the routine operation of these protocols.
1578 Errors and problems will still be logged. --quiet-dhcp and
1579 quiet-dhcp6 are over-ridden by --log-dhcp.
1580 -l, --dhcp-leasefile=<path>
1582 Use the specified file to store DHCP lease information.
1583 --dhcp-duid=<enterprise-id>,<uid>
1585 (IPv6 only) Specify the server persistent UID which the DHCPv6
1586 server will use. This option is not normally required as dnsmasq
1587 creates a DUID automatically when it is first needed. When
1588 given, this option provides dnsmasq the data required to create
1589 a DUID-EN type DUID. Note that once set, the DUID is stored in
1590 the lease database, so to change between DUID-EN and automati‐
1591 cally created DUIDs or vice-versa, the lease database must be
1592 re-initialised. The enterprise-id is assigned by IANA, and the
1593 uid is a string of hex octets unique to a particular device.
1594 -6 --dhcp-script=<path>
1596 Whenever a new DHCP lease is created, or an old one destroyed,
1597 or a TFTP file transfer completes, the executable specified by
1598 this option is run. <path> must be an absolute pathname, no
1599 PATH search occurs. The arguments to the process are "add",
1600 "old" or "del", the MAC address of the host (or DUID for IPv6) ,
1601 the IP address, and the hostname, if known. "add" means a lease
1602 has been created, "del" means it has been destroyed, "old" is a
1603 notification of an existing lease when dnsmasq starts or a
1604 change to MAC address or hostname of an existing lease (also,
1605 lease length or expiry and client-id, if --leasefile-ro is set).
1606 If the MAC address is from a network type other than ethernet,
1607 it will have the network type prepended, eg
1608 "06-01:23:45:67:89:ab" for token ring. The process is run as
1609 root (assuming that dnsmasq was originally run as root) even if
1610 dnsmasq is configured to change UID to an unprivileged user.
1611 The environment is inherited from the invoker of dnsmasq, with
1613 some or all of the following variables added
1614 For both IPv4 and IPv6:
1616 DNSMASQ_DOMAIN if the fully-qualified domain name of the host is
1618 known, this is set to the domain part. (Note that the hostname
1619 passed to the script as an argument is never fully-qualified.)
1620 If the client provides a hostname, DNSMASQ_SUPPLIED_HOSTNAME
1622 If the client provides user-classes, DNSMASQ_USER_CLASS0..DNS‐
1624 MASQ_USER_CLASSn
1625 If dnsmasq was compiled with HAVE_BROKEN_RTC, then the length of
1627 the lease (in seconds) is stored in DNSMASQ_LEASE_LENGTH, other‐
1628 wise the time of lease expiry is stored in DNS‐
1629 MASQ_LEASE_EXPIRES. The number of seconds until lease expiry is
1630 always stored in DNSMASQ_TIME_REMAINING.
1631 If a lease used to have a hostname, which is removed, an "old"
1633 event is generated with the new state of the lease, ie no name,
1634 and the former name is provided in the environment variable DNS‐
1635 MASQ_OLD_HOSTNAME.
1636 DNSMASQ_INTERFACE stores the name of the interface on which the
1638 request arrived; this is not set for "old" actions when dnsmasq
1639 restarts.
1640 DNSMASQ_RELAY_ADDRESS is set if the client used a DHCP relay to
1642 contact dnsmasq and the IP address of the relay is known.
1643 DNSMASQ_TAGS contains all the tags set during the DHCP transac‐
1645 tion, separated by spaces.
1646 DNSMASQ_LOG_DHCP is set if --log-dhcp is in effect.
1648 For IPv4 only:
1650 DNSMASQ_CLIENT_ID if the host provided a client-id.
1652 DNSMASQ_CIRCUIT_ID, DNSMASQ_SUBSCRIBER_ID, DNSMASQ_REMOTE_ID if
1654 a DHCP relay-agent added any of these options.
1655 If the client provides vendor-class, DNSMASQ_VENDOR_CLASS.
1657 DNSMASQ_REQUESTED_OPTIONS a string containing the decimal values
1659 in the Parameter Request List option, comma separated, if the
1660 parameter request list option is provided by the client.
1661 For IPv6 only:
1663 If the client provides vendor-class, DNSMASQ_VENDOR_CLASS_ID,
1665 containing the IANA enterprise id for the class, and DNS‐
1666 MASQ_VENDOR_CLASS0..DNSMASQ_VENDOR_CLASSn for the data.
1667 DNSMASQ_SERVER_DUID containing the DUID of the server: this is
1669 the same for every call to the script.
1670 DNSMASQ_IAID containing the IAID for the lease. If the lease is
1672 a temporary allocation, this is prefixed to 'T'.
1673 DNSMASQ_MAC containing the MAC address of the client, if known.
1675 Note that the supplied hostname, vendorclass and userclass data
1677 is only supplied for "add" actions or "old" actions when a host
1678 resumes an existing lease, since these data are not held in dns‐
1679 masq's lease database.
1680 All file descriptors are closed except stdin, which is open to
1684 /dev/null, and stdout and stderr which capture output for log‐
1685 ging by dnsmasq. (In debug mode, stdio, stdout and stderr file
1686 are left as those inherited from the invoker of dnsmasq).
1687 The script is not invoked concurrently: at most one instance of
1689 the script is ever running (dnsmasq waits for an instance of
1690 script to exit before running the next). Changes to the lease
1691 database are which require the script to be invoked are queued
1692 awaiting exit of a running instance. If this queueing allows
1693 multiple state changes occur to a single lease before the script
1694 can be run then earlier states are discarded and the current
1695 state of that lease is reflected when the script finally runs.
1696 At dnsmasq startup, the script will be invoked for all existing
1698 leases as they are read from the lease file. Expired leases will
1699 be called with "del" and others with "old". When dnsmasq
1700 receives a HUP signal, the script will be invoked for existing
1701 leases with an "old" event.
1702 There are four further actions which may appear as the first
1705 argument to the script, "init", "arp-add", "arp-del" and "tftp".
1706 More may be added in the future, so scripts should be written to
1707 ignore unknown actions. "init" is described below in --lease‐
1708 file-ro The "tftp" action is invoked when a TFTP file transfer
1709 completes: the arguments are the file size in bytes, the address
1710 to which the file was sent, and the complete pathname of the
1711 file.
1712 The "arp-add" and "arp-del" actions are only called if enabled
1714 with --script-arp They are are supplied with a MAC address and
1715 IP address as arguments. "arp-add" indicates the arrival of a
1716 new entry in the ARP or neighbour table, and "arp-del" indicates
1717 the deletion of same.
1718 --dhcp-luascript=<path>
1721 Specify a script written in Lua, to be run when leases are cre‐
1722 ated, destroyed or changed. To use this option, dnsmasq must be
1723 compiled with the correct support. The Lua interpreter is ini‐
1724 tialised once, when dnsmasq starts, so that global variables
1725 persist between lease events. The Lua code must define a lease
1726 function, and may provide init and shutdown functions, which are
1727 called, without arguments when dnsmasq starts up and terminates.
1728 It may also provide a tftp function.
1729 The lease function receives the information detailed in --dhcp-
1731 script. It gets two arguments, firstly the action, which is a
1732 string containing, "add", "old" or "del", and secondly a table
1733 of tag value pairs. The tags mostly correspond to the environ‐
1734 ment variables detailed above, for instance the tag "domain"
1735 holds the same data as the environment variable DNSMASQ_DOMAIN.
1736 There are a few extra tags which hold the data supplied as argu‐
1737 ments to --dhcp-script. These are mac_address, ip_address and
1738 hostname for IPv4, and client_duid, ip_address and hostname for
1739 IPv6.
1740 The tftp function is called in the same way as the lease func‐
1742 tion, and the table holds the tags destination_address,
1743 file_name and file_size.
1744 The arp and arp-old functions are called only when enabled with
1746 --script-arp and have a table which holds the tags mac_address
1747 and client_address.
1748 --dhcp-scriptuser
1750 Specify the user as which to run the lease-change script or Lua
1751 script. This defaults to root, but can be changed to another
1752 user using this flag.
1753 --script-arp
1755 Enable the "arp" and "arp-old" functions in the --dhcp-script
1756 and --dhcp-luascript.
1757 -9, --leasefile-ro
1759 Completely suppress use of the lease database file. The file
1760 will not be created, read, or written. Change the way the lease-
1761 change script (if one is provided) is called, so that the lease
1762 database may be maintained in external storage by the script. In
1763 addition to the invocations given in --dhcp-script the lease-
1764 change script is called once, at dnsmasq startup, with the sin‐
1765 gle argument "init". When called like this the script should
1766 write the saved state of the lease database, in dnsmasq lease‐
1767 file format, to stdout and exit with zero exit code. Setting
1768 this option also forces the leasechange script to be called on
1769 changes to the client-id and lease length and expiry time.
1770 --bridge-interface=<interface>,<alias>[,<alias>]
1772 Treat DHCP (v4 and v6) requests and IPv6 Router Solicit packets
1773 arriving at any of the <alias> interfaces as if they had arrived
1774 at <interface>. This option allows dnsmasq to provide DHCP and
1775 RA service over unaddressed and unbridged Ethernet interfaces,
1776 e.g. on an OpenStack compute host where each such interface is a
1777 TAP interface to a VM, or as in "old style bridging" on BSD
1778 platforms. A trailing '*' wildcard can be used in each <alias>.
1779 It is permissible to add more than one alias using more than one
1781 --bridge-interface option since --bridge-inter‐
1782 face=int1,alias1,alias2 is exactly equivalent to --bridge-inter‐
1783 face=int1,alias1 --bridge-interface=int1,alias2
1784 -s, --domain=<domain>[,<address range>[,local]]
1786 Specifies DNS domains for the DHCP server. Domains may be be
1787 given unconditionally (without the IP range) or for limited IP
1788 ranges. This has two effects; firstly it causes the DHCP server
1789 to return the domain to any hosts which request it, and secondly
1790 it sets the domain which it is legal for DHCP-configured hosts
1791 to claim. The intention is to constrain hostnames so that an
1792 untrusted host on the LAN cannot advertise its name via dhcp as
1793 e.g. "microsoft.com" and capture traffic not meant for it. If no
1794 domain suffix is specified, then any DHCP hostname with a domain
1795 part (ie with a period) will be disallowed and logged. If suffix
1796 is specified, then hostnames with a domain part are allowed,
1797 provided the domain part matches the suffix. In addition, when a
1798 suffix is set then hostnames without a domain part have the suf‐
1799 fix added as an optional domain part. Eg on my network I can set
1800 --domain=thekelleys.org.uk and have a machine whose DHCP host‐
1801 name is "laptop". The IP address for that machine is available
1802 from dnsmasq both as "laptop" and "laptop.thekelleys.org.uk". If
1803 the domain is given as "#" then the domain is read from the
1804 first "search" directive in /etc/resolv.conf (or equivalent).
1805 The address range can be of the form <ip address>,<ip address>
1807 or <ip address>/<netmask> or just a single <ip address>. See
1808 --dhcp-fqdn which can change the behaviour of dnsmasq with
1809 domains.
1810 If the address range is given as ip-address/network-size, then a
1812 additional flag "local" may be supplied which has the effect of
1813 adding --local declarations for forward and reverse DNS queries.
1814 Eg. --domain=thekelleys.org.uk,192.168.0.0/24,local is identi‐
1815 cal to --domain=thekelleys.org.uk,192.168.0.0/24
1816 --local=/thekelleys.org.uk/ --local=/0.168.192.in-addr.arpa/ The
1817 network size must be 8, 16 or 24 for this to be legal.
1818 --dhcp-fqdn
1820 In the default mode, dnsmasq inserts the unqualified names of
1821 DHCP clients into the DNS. For this reason, the names must be
1822 unique, even if two clients which have the same name are in dif‐
1823 ferent domains. If a second DHCP client appears which has the
1824 same name as an existing client, the name is transferred to the
1825 new client. If --dhcp-fqdn is set, this behaviour changes: the
1826 unqualified name is no longer put in the DNS, only the qualified
1827 name. Two DHCP clients with the same name may both keep the
1828 name, provided that the domain part is different (ie the fully
1829 qualified names differ.) To ensure that all names have a domain
1830 part, there must be at least --domain without an address speci‐
1831 fied when --dhcp-fqdn is set.
1832 --dhcp-client-update
1834 Normally, when giving a DHCP lease, dnsmasq sets flags in the
1835 FQDN option to tell the client not to attempt a DDNS update with
1836 its name and IP address. This is because the name-IP pair is
1837 automatically added into dnsmasq's DNS view. This flag sup‐
1838 presses that behaviour, this is useful, for instance, to allow
1839 Windows clients to update Active Directory servers. See RFC 4702
1840 for details.
1841 --enable-ra
1843 Enable dnsmasq's IPv6 Router Advertisement feature. DHCPv6
1844 doesn't handle complete network configuration in the same way as
1845 DHCPv4. Router discovery and (possibly) prefix discovery for au‐
1846 tonomous address creation are handled by a different protocol.
1847 When DHCP is in use, only a subset of this is needed, and dns‐
1848 masq can handle it, using existing DHCP configuration to provide
1849 most data. When RA is enabled, dnsmasq will advertise a prefix
1850 for each --dhcp-range, with default router as the relevant
1851 link-local address on the machine running dnsmasq. By default,
1852 the "managed address" bits are set, and the "use SLAAC" bit is
1853 reset. This can be changed for individual subnets with the mode
1854 keywords described in --dhcp-range. RFC6106 DNS parameters are
1855 included in the advertisements. By default, the relevant link-
1856 local address of the machine running dnsmasq is sent as recur‐
1857 sive DNS server. If provided, the DHCPv6 options dns-server and
1858 domain-search are used for the DNS server (RDNSS) and the domain
1859 search list (DNSSL).
1860 --ra-param=<interface>,[mtu:<integer>|<interface>|off,][high,|low,]<ra-
1862 interval>[,<router lifetime>]
1863 Set non-default values for router advertisements sent via an
1864 interface. The priority field for the router may be altered from
1865 the default of medium with eg --ra-param=eth0,high. The inter‐
1866 val between router advertisements may be set (in seconds) with
1867 --ra-param=eth0,60. The lifetime of the route may be changed or
1868 set to zero, which allows a router to advertise prefixes but not
1869 a route via itself. --ra-parm=eth0,0,0 (A value of zero for the
1870 interval means the default value.) All four parameters may be
1871 set at once. --ra-param=eth0,mtu:1280,low,60,1200
1872 The interface field may include a wildcard.
1874 The mtu: parameter may be an arbitrary interface name, in which
1876 case the MTU value for that interface is used. This is useful
1877 for (eg) advertising the MTU of a WAN interface on the other
1878 interfaces of a router.
1879 --dhcp-reply-delay=[tag:<tag>,]<integer>
1881 Delays sending DHCPOFFER and proxydhcp replies for at least the
1882 specified number of seconds. This can be used as workaround for
1883 bugs in PXE boot firmware that does not function properly when
1884 receiving an instant reply. This option takes into account the
1885 time already spent waiting (e.g. performing ping check) if any.
1886 --enable-tftp[=<interface>[,<interface>]]
1888 Enable the TFTP server function. This is deliberately limited to
1889 that needed to net-boot a client. Only reading is allowed; the
1890 tsize and blksize extensions are supported (tsize is only sup‐
1891 ported in octet mode). Without an argument, the TFTP service is
1892 provided to the same set of interfaces as DHCP service. If the
1893 list of interfaces is provided, that defines which interfaces
1894 receive TFTP service.
1895 --tftp-root=<directory>[,<interface>]
1897 Look for files to transfer using TFTP relative to the given
1898 directory. When this is set, TFTP paths which include ".." are
1899 rejected, to stop clients getting outside the specified root.
1900 Absolute paths (starting with /) are allowed, but they must be
1901 within the tftp-root. If the optional interface argument is
1902 given, the directory is only used for TFTP requests via that
1903 interface.
1904 --tftp-no-fail
1906 Do not abort startup if specified tftp root directories are
1907 inaccessible.
1908 --tftp-unique-root[=ip|mac]
1910 Add the IP or hardware address of the TFTP client as a path com‐
1911 ponent on the end of the TFTP-root. Only valid if a --tftp-root
1912 is set and the directory exists. Defaults to adding IP address
1913 (in standard dotted-quad format). For instance, if --tftp-root
1914 is "/tftp" and client 1.2.3.4 requests file "myfile" then the
1915 effective path will be "/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4
1916 exists or /tftp/myfile otherwise. When "=mac" is specified it
1917 will append the MAC address instead, using lowercase zero padded
1918 digits separated by dashes, e.g.: 01-02-03-04-aa-bb Note that
1919 resolving MAC addresses is only possible if the client is in the
1920 local network or obtained a DHCP lease from us.
1921 --tftp-secure
1923 Enable TFTP secure mode: without this, any file which is read‐
1924 able by the dnsmasq process under normal unix access-control
1925 rules is available via TFTP. When the --tftp-secure flag is
1926 given, only files owned by the user running the dnsmasq process
1927 are accessible. If dnsmasq is being run as root, different rules
1928 apply: --tftp-secure has no effect, but only files which have
1929 the world-readable bit set are accessible. It is not recommended
1930 to run dnsmasq as root with TFTP enabled, and certainly not
1931 without specifying --tftp-root. Doing so can expose any world-
1932 readable file on the server to any host on the net.
1933 --tftp-lowercase
1935 Convert filenames in TFTP requests to all lowercase. This is
1936 useful for requests from Windows machines, which have case-
1937 insensitive filesystems and tend to play fast-and-loose with
1938 case in filenames. Note that dnsmasq's tftp server always con‐
1939 verts "\" to "/" in filenames.
1940 --tftp-max=<connections>
1942 Set the maximum number of concurrent TFTP connections allowed.
1943 This defaults to 50. When serving a large number of TFTP connec‐
1944 tions, per-process file descriptor limits may be encountered.
1945 Dnsmasq needs one file descriptor for each concurrent TFTP con‐
1946 nection and one file descriptor per unique file (plus a few oth‐
1947 ers). So serving the same file simultaneously to n clients will
1948 use require about n + 10 file descriptors, serving different
1949 files simultaneously to n clients will require about (2*n) + 10
1950 descriptors. If --tftp-port-range is given, that can affect the
1951 number of concurrent connections.
1952 --tftp-mtu=<mtu size>
1954 Use size as the ceiling of the MTU supported by the intervening
1955 network when negotiating TFTP blocksize, overriding the MTU set‐
1956 ting of the local interface if it is larger.
1957 --tftp-no-blocksize
1959 Stop the TFTP server from negotiating the "blocksize" option
1960 with a client. Some buggy clients request this option but then
1961 behave badly when it is granted.
1962 --tftp-port-range=<start>,<end>
1964 A TFTP server listens on a well-known port (69) for connection
1965 initiation, but it also uses a dynamically-allocated port for
1966 each connection. Normally these are allocated by the OS, but
1967 this option specifies a range of ports for use by TFTP trans‐
1968 fers. This can be useful when TFTP has to traverse a firewall.
1969 The start of the range cannot be lower than 1025 unless dnsmasq
1970 is running as root. The number of concurrent TFTP connections is
1971 limited by the size of the port range.
1972 -C, --conf-file=<file>
1974 Specify a different configuration file. The --conf-file option
1975 is also allowed in configuration files, to include multiple con‐
1976 figuration files. A filename of "-" causes dnsmasq to read con‐
1977 figuration from stdin.
1978 -7, --conf-dir=<directory>[,<file-extension>......],
1980 Read all the files in the given directory as configuration
1981 files. If extension(s) are given, any files which end in those
1982 extensions are skipped. Any files whose names end in ~ or start
1983 with . or start and end with # are always skipped. If the exten‐
1984 sion starts with * then only files which have that extension are
1985 loaded. So --conf-dir=/path/to/dir,*.conf loads all files with
1986 the suffix .conf in /path/to/dir. This flag may be given on the
1987 command line or in a configuration file. If giving it on the
1988 command line, be sure to escape * characters.
1989 --servers-file=<file>
1991 A special case of --conf-file which differs in two respects.
1992 Firstly, only --server and --rev-server are allowed in the con‐
1993 figuration file included. Secondly, the file is re-read and the
1994 configuration therein is updated when dnsmasq receives SIGHUP.
1995
1997 At startup, dnsmasq reads /etc/dnsmasq.conf, if it exists. (On FreeBSD,
1998 the file is /usr/local/etc/dnsmasq.conf ) (but see the --conf-file and
1999 --conf-dir options.) The format of this file consists of one option per
2000 line, exactly as the long options detailed in the OPTIONS section but
2001 without the leading "--". Lines starting with # are comments and
2002 ignored. For options which may only be specified once, the configura‐
2003 tion file overrides the command line. Quoting is allowed in a config
2004 file: between " quotes the special meanings of ,:. and # are removed
2005 and the following escapes are allowed: \\ \" \t \e \b \r and \n. The
2006 later corresponding to tab, escape, backspace, return and newline.
2007
2009 When it receives a SIGHUP, dnsmasq clears its cache and then re-loads
2010 /etc/hosts and /etc/ethers and any file given by --dhcp-hostsfile,
2011 --dhcp-hostsdir, --dhcp-optsfile, --dhcp-optsdir, --addn-hosts or
2012 --hostsdir. The dhcp lease change script is called for all existing
2013 DHCP leases. If --no-poll is set SIGHUP also re-reads /etc/resolv.conf.
2014 SIGHUP does NOT re-read the configuration file.
2015 When it receives a SIGUSR1, dnsmasq writes statistics to the system
2017 log. It writes the cache size, the number of names which have had to
2018 removed from the cache before they expired in order to make room for
2019 new names and the total number of names that have been inserted into
2020 the cache. The number of cache hits and misses and the number of
2021 authoritative queries answered are also given. For each upstream server
2022 it gives the number of queries sent, and the number which resulted in
2023 an error. In --no-daemon mode or when full logging is enabled (--log-
2024 queries), a complete dump of the contents of the cache is made.
2025 The cache statistics are also available in the DNS as answers to
2027 queries of class CHAOS and type TXT in domain bind. The domain names
2028 are cachesize.bind, insertions.bind, evictions.bind, misses.bind,
2029 hits.bind, auth.bind and servers.bind. An example command to query
2030 this, using the dig utility would be
2031 dig +short chaos txt cachesize.bind
2033 When it receives SIGUSR2 and it is logging direct to a file (see --log-
2036 facility ) dnsmasq will close and reopen the log file. Note that during
2037 this operation, dnsmasq will not be running as root. When it first cre‐
2038 ates the logfile dnsmasq changes the ownership of the file to the non-
2039 root user it will run as. Logrotate should be configured to create a
2040 new log file with the ownership which matches the existing one before
2041 sending SIGUSR2. If TCP DNS queries are in progress, the old logfile
2042 will remain open in child processes which are handling TCP queries and
2043 may continue to be written. There is a limit of 150 seconds, after
2044 which all existing TCP processes will have expired: for this reason, it
2045 is not wise to configure logfile compression for logfiles which have
2046 just been rotated. Using logrotate, the required options are create and
2047 delaycompress.
2048 Dnsmasq is a DNS query forwarder: it is not capable of recursively
2052 answering arbitrary queries starting from the root servers but forwards
2053 such queries to a fully recursive upstream DNS server which is typi‐
2054 cally provided by an ISP. By default, dnsmasq reads /etc/resolv.conf to
2055 discover the IP addresses of the upstream nameservers it should use,
2056 since the information is typically stored there. Unless --no-poll is
2057 used, dnsmasq checks the modification time of /etc/resolv.conf (or
2058 equivalent if --resolv-file is used) and re-reads it if it changes.
2059 This allows the DNS servers to be set dynamically by PPP or DHCP since
2060 both protocols provide the information. Absence of /etc/resolv.conf is
2061 not an error since it may not have been created before a PPP connection
2062 exists. Dnsmasq simply keeps checking in case /etc/resolv.conf is cre‐
2063 ated at any time. Dnsmasq can be told to parse more than one
2064 resolv.conf file. This is useful on a laptop, where both PPP and DHCP
2065 may be used: dnsmasq can be set to poll both /etc/ppp/resolv.conf and
2066 /etc/dhcpc/resolv.conf and will use the contents of whichever changed
2067 last, giving automatic switching between DNS servers.
2068 Upstream servers may also be specified on the command line or in the
2070 configuration file. These server specifications optionally take a
2071 domain name which tells dnsmasq to use that server only to find names
2072 in that particular domain.
2073 In order to configure dnsmasq to act as cache for the host on which it
2075 is running, put "nameserver 127.0.0.1" in /etc/resolv.conf to force
2076 local processes to send queries to dnsmasq. Then either specify the
2077 upstream servers directly to dnsmasq using --server options or put
2078 their addresses real in another file, say /etc/resolv.dnsmasq and run
2079 dnsmasq with the --resolv-file /etc/resolv.dnsmasq option. This second
2080 technique allows for dynamic update of the server addresses by PPP or
2081 DHCP.
2082 Addresses in /etc/hosts will "shadow" different addresses for the same
2084 names in the upstream DNS, so "mycompany.com 1.2.3.4" in /etc/hosts
2085 will ensure that queries for "mycompany.com" always return 1.2.3.4 even
2086 if queries in the upstream DNS would otherwise return a different
2087 address. There is one exception to this: if the upstream DNS contains a
2088 CNAME which points to a shadowed name, then looking up the CNAME
2089 through dnsmasq will result in the unshadowed address associated with
2090 the target of the CNAME. To work around this, add the CNAME to
2091 /etc/hosts so that the CNAME is shadowed too.
2092 The tag system works as follows: For each DHCP request, dnsmasq col‐
2095 lects a set of valid tags from active configuration lines which include
2096 set:<tag>, including one from the --dhcp-range used to allocate the
2097 address, one from any matching --dhcp-host (and "known" or "known-oth‐
2098 ernet" if a --dhcp-host matches) The tag "bootp" is set for BOOTP
2099 requests, and a tag whose name is the name of the interface on which
2100 the request arrived is also set.
2101 Any configuration lines which include one or more tag:<tag> constructs
2103 will only be valid if all that tags are matched in the set derived
2104 above. Typically this is --dhcp-option. --dhcp-option which has tags
2105 will be used in preference to an untagged --dhcp-option, provided that
2106 _all_ the tags match somewhere in the set collected as described above.
2107 The prefix '!' on a tag means 'not' so --dhcp-option=tag:!pur‐
2108 ple,3,1.2.3.4 sends the option when the tag purple is not in the set of
2109 valid tags. (If using this in a command line rather than a configura‐
2110 tion file, be sure to escape !, which is a shell metacharacter)
2111 When selecting --dhcp-options, a tag from --dhcp-range is second class
2113 relative to other tags, to make it easy to override options for indi‐
2114 vidual hosts, so --dhcp-range=set:interface1,...... --dhcp-
2115 host=set:myhost,..... --dhcp-option=tag:interface1,option:nis-
2116 domain,"domain1" --dhcp-option=tag:myhost,option:nis-domain,"domain2"
2117 will set the NIS-domain to domain1 for hosts in the range, but override
2118 that to domain2 for a particular host.
2119 Note that for --dhcp-range both tag:<tag> and set:<tag> are allowed, to
2122 both select the range in use based on (eg) --dhcp-host, and to affect
2123 the options sent, based on the range selected.
2124 This system evolved from an earlier, more limited one and for backward
2126 compatibility "net:" may be used instead of "tag:" and "set:" may be
2127 omitted. (Except in --dhcp-host, where "net:" may be used instead of
2128 "set:".) For the same reason, '#' may be used instead of '!' to indi‐
2129 cate NOT.
2130 The DHCP server in dnsmasq will function as a BOOTP server also, pro‐
2132 vided that the MAC address and IP address for clients are given, either
2133 using --dhcp-host configurations or in /etc/ethers , and a --dhcp-range
2134 configuration option is present to activate the DHCP server on a par‐
2135 ticular network. (Setting --bootp-dynamic removes the need for static
2136 address mappings.) The filename parameter in a BOOTP request is used as
2137 a tag, as is the tag "bootp", allowing some control over the options
2138 returned to different classes of hosts.
2139
2142 Configuring dnsmasq to act as an authoritative DNS server is compli‐
2143 cated by the fact that it involves configuration of external DNS
2144 servers to provide delegation. We will walk through three scenarios of
2145 increasing complexity. Prerequisites for all of these scenarios are a
2146 globally accessible IP address, an A or AAAA record pointing to that
2147 address, and an external DNS server capable of doing delegation of the
2148 zone in question. For the first part of this explanation, we will call
2149 the A (or AAAA) record for the globally accessible address server.exam‐
2150 ple.com, and the zone for which dnsmasq is authoritative our.zone.com.
2151 The simplest configuration consists of two lines of dnsmasq configura‐
2153 tion; something like
2154 --auth-server=server.example.com,eth0
2156 --auth-zone=our.zone.com,1.2.3.0/24
2157 and two records in the external DNS
2159 server.example.com A 192.0.43.10
2161 our.zone.com NS server.example.com
2162 eth0 is the external network interface on which dnsmasq is listening,
2164 and has (globally accessible) address 192.0.43.10.
2165 Note that the external IP address may well be dynamic (ie assigned from
2167 an ISP by DHCP or PPP) If so, the A record must be linked to this
2168 dynamic assignment by one of the usual dynamic-DNS systems.
2169 A more complex, but practically useful configuration has the address
2171 record for the globally accessible IP address residing in the authori‐
2172 tative zone which dnsmasq is serving, typically at the root. Now we
2173 have
2174 --auth-server=our.zone.com,eth0
2176 --auth-zone=our.zone.com,1.2.3.0/24
2177 our.zone.com A 1.2.3.4
2179 our.zone.com NS our.zone.com
2180 The A record for our.zone.com has now become a glue record, it solves
2182 the chicken-and-egg problem of finding the IP address of the nameserver
2183 for our.zone.com when the A record is within that zone. Note that this
2184 is the only role of this record: as dnsmasq is now authoritative from
2185 our.zone.com it too must provide this record. If the external address
2186 is static, this can be done with an /etc/hosts entry or --host-record.
2187 --auth-server=our.zone.com,eth0
2189 --host-record=our.zone.com,1.2.3.4
2190 --auth-zone=our.zone.com,1.2.3.0/24
2191 If the external address is dynamic, the address associated with
2193 our.zone.com must be derived from the address of the relevant inter‐
2194 face. This is done using --interface-name Something like:
2195 --auth-server=our.zone.com,eth0
2197 --interface-name=our.zone.com,eth0
2198 --auth-zone=our.zone.com,1.2.3.0/24,eth0
2199 (The "eth0" argument in --auth-zone adds the subnet containing eth0's
2201 dynamic address to the zone, so that the --interface-name returns the
2202 address in outside queries.)
2203 Our final configuration builds on that above, but also adds a secondary
2205 DNS server. This is another DNS server which learns the DNS data for
2206 the zone by doing zones transfer, and acts as a backup should the pri‐
2207 mary server become inaccessible. The configuration of the secondary is
2208 beyond the scope of this man-page, but the extra configuration of dns‐
2209 masq is simple:
2210 --auth-sec-servers=secondary.myisp.com
2212 and
2214 our.zone.com NS secondary.myisp.com
2216 Adding auth-sec-servers enables zone transfer in dnsmasq, to allow the
2218 secondary to collect the DNS data. If you wish to restrict this data to
2219 particular hosts then
2220 --auth-peer=<IP address of secondary>
2222 will do so.
2224 Dnsmasq acts as an authoritative server for in-addr.arpa and ip6.arpa
2226 domains associated with the subnets given in --auth-zone declarations,
2227 so reverse (address to name) lookups can be simply configured with a
2228 suitable NS record, for instance in this example, where we allow
2229 1.2.3.0/24 addresses.
2230 3.2.1.in-addr.arpa NS our.zone.com
2232 Note that at present, reverse (in-addr.arpa and ip6.arpa) zones are not
2234 available in zone transfers, so there is no point arranging secondary
2235 servers for reverse lookups.
2236 When dnsmasq is configured to act as an authoritative server, the fol‐
2239 lowing data is used to populate the authoritative zone.
2240 --mx-host, --srv-host, --dns-rr, --txt-record, --naptr-record, --caa-
2242 record, as long as the record names are in the authoritative domain.
2243 --cname as long as the record name is in the authoritative domain. If
2245 the target of the CNAME is unqualified, then it is qualified with the
2246 authoritative zone name. CNAME used in this way (only) may be wild‐
2247 cards, as in
2248 --cname=*.example.com,default.example.com
2250 IPv4 and IPv6 addresses from /etc/hosts (and --addn-hosts ) and --host-
2253 record and --interface-name provided the address falls into one of the
2254 subnets specified in the --auth-zone.
2255 Addresses of DHCP leases, provided the address falls into one of the
2257 subnets specified in the --auth-zone. (If constructed DHCP ranges are
2258 is use, which depend on the address dynamically assigned to an inter‐
2259 face, then the form of --auth-zone which defines subnets by the dynamic
2260 address of an interface should be used to ensure this condition is
2261 met.)
2262 In the default mode, where a DHCP lease has an unqualified name, and
2264 possibly a qualified name constructed using --domain then the name in
2265 the authoritative zone is constructed from the unqualified name and the
2266 zone's domain. This may or may not equal that specified by --domain.
2267 If --dhcp-fqdn is set, then the fully qualified names associated with
2268 DHCP leases are used, and must match the zone's domain.
2269
2274 0 - Dnsmasq successfully forked into the background, or terminated nor‐
2275 mally if backgrounding is not enabled.
2276 1 - A problem with configuration was detected.
2278 2 - A problem with network access occurred (address in use, attempt to
2280 use privileged ports without permission).
2281 3 - A problem occurred with a filesystem operation (missing file/direc‐
2283 tory, permissions).
2284 4 - Memory allocation failure.
2286 5 - Other miscellaneous problem.
2288 11 or greater - a non zero return code was received from the lease-
2290 script process "init" call. The exit code from dnsmasq is the script's
2291 exit code with 10 added.
2292
2295 The default values for resource limits in dnsmasq are generally conser‐
2296 vative, and appropriate for embedded router type devices with slow pro‐
2297 cessors and limited memory. On more capable hardware, it is possible to
2298 increase the limits, and handle many more clients. The following
2299 applies to dnsmasq-2.37: earlier versions did not scale as well.
2300 Dnsmasq is capable of handling DNS and DHCP for at least a thousand
2303 clients. The DHCP lease times should not be very short (less than one
2304 hour). The value of --dns-forward-max can be increased: start with it
2305 equal to the number of clients and increase if DNS seems slow. Note
2306 that DNS performance depends too on the performance of the upstream
2307 nameservers. The size of the DNS cache may be increased: the hard limit
2308 is 10000 names and the default (150) is very low. Sending SIGUSR1 to
2309 dnsmasq makes it log information which is useful for tuning the cache
2310 size. See the NOTES section for details.
2311 The built-in TFTP server is capable of many simultaneous file trans‐
2314 fers: the absolute limit is related to the number of file-handles
2315 allowed to a process and the ability of the select() system call to
2316 cope with large numbers of file handles. If the limit is set too high
2317 using --tftp-max it will be scaled down and the actual limit logged at
2318 start-up. Note that more transfers are possible when the same file is
2319 being sent than when each transfer sends a different file.
2320 It is possible to use dnsmasq to block Web advertising by using a list
2323 of known banner-ad servers, all resolving to 127.0.0.1 or 0.0.0.0, in
2324 /etc/hosts or an additional hosts file. The list can be very long, dns‐
2325 masq has been tested successfully with one million names. That size
2326 file needs a 1GHz processor and about 60Mb of RAM.
2327
2330 Dnsmasq can be compiled to support internationalisation. To do this,
2331 the make targets "all-i18n" and "install-i18n" should be used instead
2332 of the standard targets "all" and "install". When internationalisation
2333 is compiled in, dnsmasq will produce log messages in the local language
2334 and support internationalised domain names (IDN). Domain names in
2335 /etc/hosts, /etc/ethers and /etc/dnsmasq.conf which contain non-ASCII
2336 characters will be translated to the DNS-internal punycode representa‐
2337 tion. Note that dnsmasq determines both the language for messages and
2338 the assumed charset for configuration files from the LANG environment
2339 variable. This should be set to the system default value by the script
2340 which is responsible for starting dnsmasq. When editing the configura‐
2341 tion files, be careful to do so using only the system-default locale
2342 and not user-specific one, since dnsmasq has no direct way of determin‐
2343 ing the charset in use, and must assume that it is the system default.
2344
2347 /etc/dnsmasq.conf
2348 /usr/local/etc/dnsmasq.conf
2350 /etc/resolv.conf /var/run/dnsmasq/resolv.conf /etc/ppp/resolv.conf
2352 /etc/dhcpc/resolv.conf
2353 /etc/hosts
2355 /etc/ethers
2357 /var/lib/dnsmasq/dnsmasq.leases
2359 /var/db/dnsmasq.leases
2361 /var/run/dnsmasq.pid
2363
2365 hosts(5), resolver(5)
2366
2368 This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.
2369 DNSMASQ(8)