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