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 and DHCP server. It is intended to
13 provide coupled DNS and DHCP service to a LAN.
14 Dnsmasq accepts DNS queries and either answers them from a small,
16 local, cache or forwards them to a real, recursive, DNS server. It
17 loads the contents of /etc/hosts so that local hostnames which do not
18 appear in the global DNS can be resolved and also answers DNS queries
19 for DHCP configured hosts.
20 The dnsmasq DHCP server supports static address assignments and multi‐
22 ple networks. It automatically sends a sensible default set of DHCP
23 options, and can be configured to send any desired set of DHCP options,
24 including vendor-encapsulated options. It includes a secure, read-only,
25 TFTP server to allow net/PXE boot of DHCP hosts and also supports
26 BOOTP.
27 Dnsmasq supports IPv6 for DNS, but not DHCP.
29
31 Note that in general missing parameters are allowed and switch off
32 functions, for instance "--pid-file" disables writing a PID file. On
33 BSD, unless the GNU getopt library is linked, the long form of the
34 options does not work on the command line; it is still recognised in
35 the configuration file.
36 --test Read and syntax check configuration file(s). Exit with code 0 if
38 all is OK, or a non-zero code otherwise. Do not start up dns‐
39 masq.
40 -h, --no-hosts
42 Don't read the hostnames in /etc/hosts.
43 -H, --addn-hosts=<file>
45 Additional hosts file. Read the specified file as well as
46 /etc/hosts. If -h is given, read only the specified file. This
47 option may be repeated for more than one additional hosts file.
48 If a directory is given, then read all the files contained in
49 that directory.
50 -E, --expand-hosts
52 Add the domain to simple names (without a period) in /etc/hosts
53 in the same way as for DHCP-derived names. Note that this does
54 not apply to domain names in cnames, PTR records, TXT records
55 etc.
56 -T, --local-ttl=<time>
58 When replying with information from /etc/hosts or the DHCP
59 leases file dnsmasq by default sets the time-to-live field to
60 zero, meaning that the requestor should not itself cache the
61 information. This is the correct thing to do in almost all situ‐
62 ations. This option allows a time-to-live (in seconds) to be
63 given for these replies. This will reduce the load on the server
64 at the expense of clients using stale data under some circum‐
65 stances.
66 --neg-ttl=<time>
68 Negative replies from upstream servers normally contain time-to-
69 live information in SOA records which dnsmasq uses for caching.
70 If the replies from upstream servers omit this information, dns‐
71 masq does not cache the reply. This option gives a default value
72 for time-to-live (in seconds) which dnsmasq uses to cache nega‐
73 tive replies even in the absence of an SOA record.
74 -k, --keep-in-foreground
76 Do not go into the background at startup but otherwise run as
77 normal. This is intended for use when dnsmasq is run under dae‐
78 montools or launchd.
79 -d, --no-daemon
81 Debug mode: don't fork to the background, don't write a pid
82 file, don't change user id, generate a complete cache dump on
83 receipt on SIGUSR1, log to stderr as well as syslog, don't fork
84 new processes to handle TCP queries.
85 -q, --log-queries
87 Log the results of DNS queries handled by dnsmasq. Enable a full
88 cache dump on receipt of SIGUSR1.
89 -8, --log-facility=<facility>
91 Set the facility to which dnsmasq will send syslog entries, this
92 defaults to DAEMON, and to LOCAL0 when debug mode is in opera‐
93 tion. If the facility given contains at least one '/' character,
94 it is taken to be a filename, and dnsmasq logs to the given
95 file, instead of syslog. (Errors whilst reading configuration
96 will still go to syslog, but all output from a successful
97 startup, and all output whilst running, will go exclusively to
98 the file.) When logging to a file, dnsmasq will close and reopen
99 the file when it receives SIGUSR2. This allows the log file to
100 be rotated without stopping dnsmasq.
101 --log-async[=<lines>]
103 Enable asynchronous logging and optionally set the limit on the
104 number of lines which will be queued by dnsmasq when writing to
105 the syslog is slow. Dnsmasq can log asynchronously: this allows
106 it to continue functioning without being blocked by syslog, and
107 allows syslog to use dnsmasq for DNS queries without risking
108 deadlock. If the queue of log-lines becomes full, dnsmasq will
109 log the overflow, and the number of messages lost. The default
110 queue length is 5, a sane value would be 5-25, and a maximum
111 limit of 100 is imposed.
112 -x, --pid-file=<path>
114 Specify an alternate path for dnsmasq to record its process-id
115 in. Normally /var/run/dnsmasq.pid.
116 -u, --user=<username>
118 Specify the userid to which dnsmasq will change after startup.
119 Dnsmasq must normally be started as root, but it will drop root
120 privileges after startup by changing id to another user. Nor‐
121 mally this user is "nobody" but that can be over-ridden with
122 this switch.
123 -g, --group=<groupname>
125 Specify the group which dnsmasq will run as. The defaults to
126 "dip", if available, to facilitate access to
127 /etc/ppp/resolv.conf which is not normally world readable.
128 -v, --version
130 Print the version number.
131 -p, --port=<port>
133 Listen on <port> instead of the standard DNS port (53). Setting
134 this to zero completely disables DNS function, leaving only DHCP
135 and/or TFTP.
136 -P, --edns-packet-max=<size>
138 Specify the largest EDNS.0 UDP packet which is supported by the
139 DNS forwarder. Defaults to 4096, which is the RFC5625-recom‐
140 mended size.
141 -Q, --query-port=<query_port>
143 Send outbound DNS queries from, and listen for their replies on,
144 the specific UDP port <query_port> instead of using random
145 ports. NOTE that using this option will make dnsmasq less secure
146 against DNS spoofing attacks but it may be faster and use less
147 resources. Setting this option to zero makes dnsmasq use a sin‐
148 gle port allocated to it by the OS: this was the default behav‐
149 iour in versions prior to 2.43.
150 --min-port=<port>
152 Do not use ports less than that given as source for outbound DNS
153 queries. Dnsmasq picks random ports as source for outbound
154 queries: when this option is given, the ports used will always
155 to larger than that specified. Useful for systems behind fire‐
156 walls.
157 -i, --interface=<interface name>
159 Listen only on the specified interface(s). Dnsmasq automatically
160 adds the loopback (local) interface to the list of interfaces to
161 use when the --interface option is used. If no --interface or
162 --listen-address options are given dnsmasq listens on all avail‐
163 able interfaces except any given in --except-interface options.
164 IP alias interfaces (eg "eth1:0") cannot be used with --inter‐
165 face or --except-interface options, use --listen-address
166 instead.
167 -I, --except-interface=<interface name>
169 Do not listen on the specified interface. Note that the order of
170 --listen-address --interface and --except-interface options does
171 not matter and that --except-interface options always override
172 the others.
173 -2, --no-dhcp-interface=<interface name>
175 Do not provide DHCP or TFTP on the specified interface, but do
176 provide DNS service.
177 -a, --listen-address=<ipaddr>
179 Listen on the given IP address(es). Both --interface and --lis‐
180 ten-address options may be given, in which case the set of both
181 interfaces and addresses is used. Note that if no --interface
182 option is given, but --listen-address is, dnsmasq will not auto‐
183 matically listen on the loopback interface. To achieve this, its
184 IP address, 127.0.0.1, must be explicitly given as a --listen-
185 address option.
186 -z, --bind-interfaces
188 On systems which support it, dnsmasq binds the wildcard address,
189 even when it is listening on only some interfaces. It then dis‐
190 cards requests that it shouldn't reply to. This has the advan‐
191 tage of working even when interfaces come and go and change
192 address. This option forces dnsmasq to really bind only the
193 interfaces it is listening on. About the only time when this is
194 useful is when running another nameserver (or another instance
195 of dnsmasq) on the same machine. Setting this option also
196 enables multiple instances of dnsmasq which provide DHCP service
197 to run in the same machine.
198 -y, --localise-queries
200 Return answers to DNS queries from /etc/hosts which depend on
201 the interface over which the query was received. If a name in
202 /etc/hosts has more than one address associated with it, and at
203 least one of those addresses is on the same subnet as the inter‐
204 face to which the query was sent, then return only the
205 address(es) on that subnet. This allows for a server to have
206 multiple addresses in /etc/hosts corresponding to each of its
207 interfaces, and hosts will get the correct address based on
208 which network they are attached to. Currently this facility is
209 limited to IPv4.
210 -b, --bogus-priv
212 Bogus private reverse lookups. All reverse lookups for private
213 IP ranges (ie 192.168.x.x, etc) which are not found in
214 /etc/hosts or the DHCP leases file are answered with "no such
215 domain" rather than being forwarded upstream.
216 -V, --alias=[<old-ip>]|[<start-ip>-<end-ip>],<new-ip>[,<mask>]
218 Modify IPv4 addresses returned from upstream nameservers; old-ip
219 is replaced by new-ip. If the optional mask is given then any
220 address which matches the masked old-ip will be re-written. So,
221 for instance --alias=1.2.3.0,6.7.8.0,255.255.255.0 will map
222 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. This is what
223 Cisco PIX routers call "DNS doctoring". If the old IP is given
224 as range, then only addresses in the range, rather than a whole
225 subnet, are re-written. So
226 --alias=192.168.0.10-192.168.0.40,10.0.0.0,255.255.255.0 maps
227 192.168.0.10->192.168.0.40 to 10.0.0.10->10.0.0.40
228 -B, --bogus-nxdomain=<ipaddr>
230 Transform replies which contain the IP address given into "No
231 such domain" replies. This is intended to counteract a devious
232 move made by Verisign in September 2003 when they started
233 returning the address of an advertising web page in response to
234 queries for unregistered names, instead of the correct NXDOMAIN
235 response. This option tells dnsmasq to fake the correct response
236 when it sees this behaviour. As at Sept 2003 the IP address
237 being returned by Verisign is 64.94.110.11
238 -f, --filterwin2k
240 Later versions of windows make periodic DNS requests which don't
241 get sensible answers from the public DNS and can cause problems
242 by triggering dial-on-demand links. This flag turns on an option
243 to filter such requests. The requests blocked are for records of
244 types SOA and SRV, and type ANY where the requested name has
245 underscores, to catch LDAP requests.
246 -r, --resolv-file=<file>
248 Read the IP addresses of the upstream nameservers from <file>,
249 instead of /etc/resolv.conf. For the format of this file see
250 resolv.conf(5) the only lines relevant to dnsmasq are nameserver
251 ones. Dnsmasq can be told to poll more than one resolv.conf
252 file, the first file name specified overrides the default, sub‐
253 sequent ones add to the list. This is only allowed when polling;
254 the file with the currently latest modification time is the one
255 used.
256 -R, --no-resolv
258 Don't read /etc/resolv.conf. Get upstream servers only from the
259 command line or the dnsmasq configuration file.
260 -1, --enable-dbus
262 Allow dnsmasq configuration to be updated via DBus method calls.
263 The configuration which can be changed is upstream DNS servers
264 (and corresponding domains) and cache clear. Requires that dns‐
265 masq has been built with DBus support.
266 -o, --strict-order
268 By default, dnsmasq will send queries to any of the upstream
269 servers it knows about and tries to favour servers that are
270 known to be up. Setting this flag forces dnsmasq to try each
271 query with each server strictly in the order they appear in
272 /etc/resolv.conf
273 --all-servers
275 By default, when dnsmasq has more than one upstream server
276 available, it will send queries to just one server. Setting this
277 flag forces dnsmasq to send all queries to all available
278 servers. The reply from the server which answers first will be
279 returned to the original requestor.
280 --stop-dns-rebind
282 Reject (and log) addresses from upstream nameservers which are
283 in the private IP ranges. This blocks an attack where a browser
284 behind a firewall is used to probe machines on the local net‐
285 work.
286 -n, --no-poll
288 Don't poll /etc/resolv.conf for changes.
289 --clear-on-reload
291 Whenever /etc/resolv.conf is re-read, clear the DNS cache. This
292 is useful when new nameservers may have different data than that
293 held in cache.
294 -D, --domain-needed
296 Tells dnsmasq to never forward queries for plain names, without
297 dots or domain parts, to upstream nameservers. If the name is
298 not known from /etc/hosts or DHCP then a "not found" answer is
299 returned.
300 -S, --local,
302 --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>][@<source-ip>|<inter‐
303 face>[#<port>]]
304 Specify IP address of upstream servers directly. Setting this
305 flag does not suppress reading of /etc/resolv.conf, use -R to do
306 that. If one or more optional domains are given, that server is
307 used only for those domains and they are queried only using the
308 specified server. This is intended for private nameservers: if
309 you have a nameserver on your network which deals with names of
310 the form xxx.internal.thekelleys.org.uk at 192.168.1.1 then giv‐
311 ing the flag -S /internal.thekelleys.org.uk/192.168.1.1 will
312 send all queries for internal machines to that nameserver,
313 everything else will go to the servers in /etc/resolv.conf. An
314 empty domain specification, // has the special meaning of
315 "unqualified names only" ie names without any dots in them. A
316 non-standard port may be specified as part of the IP address
317 using a # character. More than one -S flag is allowed, with
318 repeated domain or ipaddr parts as required.
319 Also permitted is a -S flag which gives a domain but no IP
321 address; this tells dnsmasq that a domain is local and it may
322 answer queries from /etc/hosts or DHCP but should never forward
323 queries on that domain to any upstream servers. local is a syn‐
324 onym for server to make configuration files clearer in this
325 case.
326 The optional string after the @ character tells dnsmasq how to
328 set the source of the queries to this nameserver. It should be
329 an ip-address, which should belong to the machine on which dns‐
330 masq is running otherwise this server line will be logged and
331 then ignored, or an interface name. If an interface name is
332 given, then queries to the server will be forced via that inter‐
333 face; if an ip-address is given then the source address of the
334 queries will be set to that address. The query-port flag is
335 ignored for any servers which have a source address specified
336 but the port may be specified directly as part of the source
337 address. Forcing queries to an interface is not implemented on
338 all platforms supported by dnsmasq.
339 -A, --address=/<domain>/[domain/]<ipaddr>
341 Specify an IP address to return for any host in the given
342 domains. Queries in the domains are never forwarded and always
343 replied to with the specified IP address which may be IPv4 or
344 IPv6. To give both IPv4 and IPv6 addresses for a domain, use
345 repeated -A flags. Note that /etc/hosts and DHCP leases over‐
346 ride this for individual names. A common use of this is to redi‐
347 rect the entire doubleclick.net domain to some friendly local
348 web server to avoid banner ads. The domain specification works
349 in the same was as for --server, with the additional facility
350 that /#/ matches any domain. Thus --address=/#/1.2.3.4 will
351 always return 1.2.3.4 for any query not answered from /etc/hosts
352 or DHCP and not sent to an upstream nameserver by a more spe‐
353 cific --server directive.
354 -m, --mx-host=<mx name>[[,<hostname>],<preference>]
356 Return an MX record named <mx name> pointing to the given host‐
357 name (if given), or the host specified in the --mx-target switch
358 or, if that switch is not given, the host on which dnsmasq is
359 running. The default is useful for directing mail from systems
360 on a LAN to a central server. The preference value is optional,
361 and defaults to 1 if not given. More than one MX record may be
362 given for a host.
363 -t, --mx-target=<hostname>
365 Specify the default target for the MX record returned by dns‐
366 masq. See --mx-host. If --mx-target is given, but not --mx-
367 host, then dnsmasq returns a MX record containing the MX target
368 for MX queries on the hostname of the machine on which dnsmasq
369 is running.
370 -e, --selfmx
372 Return an MX record pointing to itself for each local machine.
373 Local machines are those in /etc/hosts or with DHCP leases.
374 -L, --localmx
376 Return an MX record pointing to the host given by mx-target (or
377 the machine on which dnsmasq is running) for each local machine.
378 Local machines are those in /etc/hosts or with DHCP leases.
379 -W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<prior‐
381 ity>[,<weight>]]]]
382 Return a SRV DNS record. See RFC2782 for details. If not sup‐
383 plied, the domain defaults to that given by --domain. The
384 default for the target domain is empty, and the default for port
385 is one and the defaults for weight and priority are zero. Be
386 careful if transposing data from BIND zone files: the port,
387 weight and priority numbers are in a different order. More than
388 one SRV record for a given service/domain is allowed, all that
389 match are returned.
390 -Y, --txt-record=<name>[[,<text>],<text>]
392 Return a TXT DNS record. The value of TXT record is a set of
393 strings, so any number may be included, split by commas.
394 --ptr-record=<name>[,<target>]
396 Return a PTR DNS record.
397 --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<reg‐
399 exp>[,<replacement>]
400 Return an NAPTR DNS record, as specified in RFC3403.
401 --cname=<cname>,<target>
403 Return a CNAME record which indicates that <cname> is really
404 <target>. There are significant limitations on the target; it
405 must be a DNS name which is known to dnsmasq from /etc/hosts (or
406 additional hosts files) or from DHCP. If the target does not
407 satisfy this criteria, the whole cname is ignored. The cname
408 must be unique, but it is permissable to have more than one
409 cname pointing to the same target.
410 --interface-name=<name>,<interface>
412 Return a DNS record associating the name with the primary
413 address on the given interface. This flag specifies an A record
414 for the given name in the same way as an /etc/hosts line, except
415 that the address is not constant, but taken from the given
416 interface. If the interface is down, not configured or non-exis‐
417 tent, an empty record is returned. The matching PTR record is
418 also created, mapping the interface address to the name. More
419 than one name may be associated with an interface address by
420 repeating the flag; in that case the first instance is used for
421 the reverse address-to-name mapping.
422 -c, --cache-size=<cachesize>
424 Set the size of dnsmasq's cache. The default is 150 names. Set‐
425 ting the cache size to zero disables caching.
426 -N, --no-negcache
428 Disable negative caching. Negative caching allows dnsmasq to
429 remember "no such domain" answers from upstream nameservers and
430 answer identical queries without forwarding them again.
431 -0, --dns-forward-max=<queries>
433 Set the maximum number of concurrent DNS queries. The default
434 value is 150, which should be fine for most setups. The only
435 known situation where this needs to be increased is when using
436 web-server log file resolvers, which can generate large numbers
437 of concurrent queries.
438 -F, --dhcp-range=[[net:]network-id,]<start-addr>,<end-addr>[,<net‐
440 mask>[,<broadcast>]][,<lease time>]
441 Enable the DHCP server. Addresses will be given out from the
442 range <start-addr> to <end-addr> and from statically defined
443 addresses given in dhcp-host options. If the lease time is
444 given, then leases will be given for that length of time. The
445 lease time is in seconds, or minutes (eg 45m) or hours (eg 1h)
446 or "infinite". If not given, the default lease time is one hour.
447 The minimum lease time is two minutes. This option may be
448 repeated, with different addresses, to enable DHCP service to
449 more than one network. For directly connected networks (ie, net‐
450 works on which the machine running dnsmasq has an interface) the
451 netmask is optional. It is, however, required for networks which
452 receive DHCP service via a relay agent. The broadcast address is
453 always optional. It is always allowed to have more than one
454 dhcp-range in a single subnet. The optional network-id is a
455 alphanumeric label which marks this network so that dhcp options
456 may be specified on a per-network basis. When it is prefixed
457 with 'net:' then its meaning changes from setting a tag to
458 matching it. Only one tag may be set, but more than one tag may
459 be matched. The end address may be replaced by the keyword
460 static which tells dnsmasq to enable DHCP for the network speci‐
461 fied, but not to dynamically allocate IP addresses: only hosts
462 which have static addresses given via dhcp-host or from
463 /etc/ethers will be served. The end address may be replaced by
464 the keyword proxy in which case dnsmasq will provide proxy-DHCP
465 on the specified subnet. (See pxe-prompt and pxe-service for
466 details.)
467 -G, --dhcp-
469 host=[<hwaddr>][,id:<client_id>|*][,net:<netid>][,<ipaddr>][,<host‐
470 name>][,<lease_time>][,ignore]
471 Specify per host parameters for the DHCP server. This allows a
472 machine with a particular hardware address to be always allo‐
473 cated the same hostname, IP address and lease time. A hostname
474 specified like this overrides any supplied by the DHCP client on
475 the machine. It is also allowable to ommit the hardware address
476 and include the hostname, in which case the IP address and lease
477 times will apply to any machine claiming that name. For example
478 --dhcp-host=00:20:e0:3b:13:af,wap,infinite tells dnsmasq to give
479 the machine with hardware address 00:20:e0:3b:13:af the name
480 wap, and an infinite DHCP lease. --dhcp-host=lap,192.168.0.199
481 tells dnsmasq to always allocate the machine lap the IP address
482 192.168.0.199. Addresses allocated like this are not constrained
483 to be in the range given by the --dhcp-range option, but they
484 must be on the network being served by the DHCP server. It is
485 allowed to use client identifiers rather than hardware addresses
486 to identify hosts by prefixing with 'id:'. Thus: --dhcp-
487 host=id:01:02:03:04,..... refers to the host with client iden‐
488 tifier 01:02:03:04. It is also allowed to specify the client ID
489 as text, like this: --dhcp-host=id:clientidastext,.....
490 The special option id:* means "ignore any client-id and use MAC
492 addresses only." This is useful when a client presents a client-
493 id sometimes but not others.
494 If a name appears in /etc/hosts, the associated address can be
496 allocated to a DHCP lease, but only if a --dhcp-host option
497 specifying the name also exists. The special keyword "ignore"
498 tells dnsmasq to never offer a DHCP lease to a machine. The
499 machine can be specified by hardware address, client ID or host‐
500 name, for instance --dhcp-host=00:20:e0:3b:13:af,ignore This is
501 useful when there is another DHCP server on the network which
502 should be used by some machines.
503 The net:<network-id> sets the network-id tag whenever this dhcp-
505 host directive is in use. This can be used to selectively send
506 DHCP options just for this host. When a host matches any dhcp-
507 host directive (or one implied by /etc/ethers) then the special
508 network-id tag "known" is set. This allows dnsmasq to be config‐
509 ured to ignore requests from unknown machines using --dhcp-
510 ignore=#known Ethernet addresses (but not client-ids) may have
511 wildcard bytes, so for example --dhcp-
512 host=00:20:e0:3b:13:*,ignore will cause dnsmasq to ignore a
513 range of hardware addresses. Note that the "*" will need to be
514 escaped or quoted on a command line, but not in the configura‐
515 tion file.
516 Hardware addresses normally match any network (ARP) type, but it
518 is possible to restrict them to a single ARP type by preceding
519 them with the ARP-type (in HEX) and "-". so --dhcp-
520 host=06-00:20:e0:3b:13:af,1.2.3.4 will only match a Token-Ring
521 hardware address, since the ARP-address type for token ring is
522 6.
523 As a special case, it is possible to include more than one hard‐
525 ware address. eg: --dhcp-
526 host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2 This allows
527 an IP address to be associated with multiple hardware addresses,
528 and gives dnsmasq permission to abandon a DHCP lease to one of
529 the hardware addresses when another one asks for a lease. Beware
530 that this is a dangerous thing to do, it will only work reliably
531 if only one of the hardware addresses is active at any time and
532 there is no way for dnsmasq to enforce this. It is, for
533 instance, useful to allocate a stable IP address to a laptop
534 which has both wired and wireless interfaces.
535 --dhcp-hostsfile=<file>
537 Read DHCP host information from the specified file. The file
538 contains information about one host per line. The format of a
539 line is the same as text to the right of '=' in --dhcp-host. The
540 advantage of storing DHCP host information in this file is that
541 it can be changed without re-starting dnsmasq: the file will be
542 re-read when dnsmasq receives SIGHUP.
543 --dhcp-optsfile=<file>
545 Read DHCP option information from the specified file. The advan‐
546 tage of using this option is the same as for --dhcp-hostsfile:
547 the dhcp-optsfile will be re-read when dnsmasq receives SIGHUP.
548 Note that it is possible to encode the information in a --dhcp-
549 boot flag as DHCP options, using the options names bootfile-
550 name, server-ip-address and tftp-server. This allows these to be
551 included in a dhcp-optsfile.
552 -Z, --read-ethers
554 Read /etc/ethers for information about hosts for the DHCP
555 server. The format of /etc/ethers is a hardware address, fol‐
556 lowed by either a hostname or dotted-quad IP address. When read
557 by dnsmasq these lines have exactly the same effect as --dhcp-
558 host options containing the same information. /etc/ethers is re-
559 read when dnsmasq receives SIGHUP.
560 -O, --dhcp-option=[<network-id>,[<network-id>,]][encap:<opt>,][vi-
562 encap:<enterprise>,][vendor:[<vendor-class>],][<opt>|option:<opt-
563 name>],[<value>[,<value>]]
564 Specify different or extra options to DHCP clients. By default,
565 dnsmasq sends some standard options to DHCP clients, the netmask
566 and broadcast address are set to the same as the host running
567 dnsmasq, and the DNS server and default route are set to the
568 address of the machine running dnsmasq. If the domain name
569 option has been set, that is sent. This configuration allows
570 these defaults to be overridden, or other options specified. The
571 option, to be sent may be given as a decimal number or as
572 "option:<option-name>" The option numbers are specified in
573 RFC2132 and subsequent RFCs. The set of option-names known by
574 dnsmasq can be discovered by running "dnsmasq --help dhcp". For
575 example, to set the default route option to 192.168.4.4, do
576 --dhcp-option=3,192.168.4.4 or --dhcp-option = option:router,
577 192.168.4.4 and to set the time-server address to 192.168.0.4,
578 do --dhcp-option = 42,192.168.0.4 or --dhcp-option = option:ntp-
579 server, 192.168.0.4 The special address 0.0.0.0 is taken to mean
580 "the address of the machine running dnsmasq". Data types allowed
581 are comma separated dotted-quad IP addresses, a decimal number,
582 colon-separated hex digits and a text string. If the optional
583 network-ids are given then this option is only sent when all the
584 network-ids are matched.
585 Special processing is done on a text argument for option 119, to
587 conform with RFC 3397. Text or dotted-quad IP addresses as argu‐
588 ments to option 120 are handled as per RFC 3361. Dotted-quad IP
589 addresses which are followed by a slash and then a netmask size
590 are encoded as described in RFC 3442.
591 Be careful: no checking is done that the correct type of data
593 for the option number is sent, it is quite possible to persuade
594 dnsmasq to generate illegal DHCP packets with injudicious use of
595 this flag. When the value is a decimal number, dnsmasq must
596 determine how large the data item is. It does this by examining
597 the option number and/or the value, but can be overridden by
598 appending a single letter flag as follows: b = one byte, s = two
599 bytes, i = four bytes. This is mainly useful with encapsulated
600 vendor class options (see below) where dnsmasq cannot determine
601 data size from the option number. Option data which consists
602 solely of periods and digits will be interpreted by dnsmasq as
603 an IP address, and inserted into an option as such. To force a
604 literal string, use quotes. For instance when using option 66 to
605 send a literal IP address as TFTP server name, it is necessary
606 to do --dhcp-option=66,"1.2.3.4"
607 Encapsulated Vendor-class options may also be specified using
609 --dhcp-option: for instance --dhcp-option=vendor:PXE‐
610 Client,1,0.0.0.0 sends the encapsulated vendor class-specific
611 option "mftp-address=0.0.0.0" to any client whose vendor-class
612 matches "PXEClient". The vendor-class matching is substring
613 based (see --dhcp-vendorclass for details). If a vendor-class
614 option (number 60) is sent by dnsmasq, then that is used for
615 selecting encapsulated options in preference to any sent by the
616 client. It is possible to omit the vendorclass completely;
617 --dhcp-option=vendor:,1,0.0.0.0 in which case the encapsulated
618 option is always sent.
619 Options may be encapsulated within other options: for instance
621 --dhcp-option=encap:175, 190, iscsi-client0 will send option
622 175, within which is the option 190. If multiple options are
623 given which are encapsulated with the same option number then
624 they will be correctly combined into one encapsulated option.
625 encap: and vendor: are may not both be set in the same dhcp-
626 option.
627 The final variant on encapsulated options is "Vendor-Identifying
629 Vendor Options" as specified by RFC3925. These are denoted like
630 this: --dhcp-option=vi-encap:2, 10, text The number in the vi-
631 encap: section is the IANA enterprise number used to identify
632 this option.
633 The address 0.0.0.0 is not treated specially in encapsulated
635 options.
636 --dhcp-option-force=[<network-id>,[<network-id>,]][encap:<opt>,][vi-
638 encap:<enterprise>,][vendor:[<vendor-class>],]<opt>,[<value>[,<value>]]
639 This works in exactly the same way as --dhcp-option except that
640 the option will always be sent, even if the client does not ask
641 for it in the parameter request list. This is sometimes needed,
642 for example when sending options to PXELinux.
643 --dhcp-no-override
645 Disable re-use of the DHCP servername and filename fields as
646 extra option space. If it can, dnsmasq moves the boot server and
647 filename information (from dhcp-boot) out of their dedicated
648 fields into DHCP options. This make extra space available in the
649 DHCP packet for options but can, rarely, confuse old or broken
650 clients. This flag forces "simple and safe" behaviour to avoid
651 problems in such a case.
652 -U, --dhcp-vendorclass=<network-id>,<vendor-class>
654 Map from a vendor-class string to a network id tag. Most DHCP
655 clients provide a "vendor class" which represents, in some
656 sense, the type of host. This option maps vendor classes to
657 tags, so that DHCP options may be selectively delivered to dif‐
658 ferent classes of hosts. For example dhcp-vendorclass=print‐
659 ers,Hewlett-Packard JetDirect will allow options to be set only
660 for HP printers like so: --dhcp-option=printers,3,192.168.4.4
661 The vendor-class string is substring matched against the vendor-
662 class supplied by the client, to allow fuzzy matching.
663 -j, --dhcp-userclass=<network-id>,<user-class>
665 Map from a user-class string to a network id tag (with substring
666 matching, like vendor classes). Most DHCP clients provide a
667 "user class" which is configurable. This option maps user
668 classes to tags, so that DHCP options may be selectively deliv‐
669 ered to different classes of hosts. It is possible, for instance
670 to use this to set a different printer server for hosts in the
671 class "accounts" than for hosts in the class "engineering".
672 -4, --dhcp-mac=<network-id>,<MAC address>
674 Map from a MAC address to a network-id tag. The MAC address may
675 include wildcards. For example --dhcp-mac=3com,01:34:23:*:*:*
676 will set the tag "3com" for any host whose MAC address matches
677 the pattern.
678 --dhcp-circuitid=<network-id>,<circuit-id>, --dhcp-remoteid=<network-
680 id>,<remote-id>
681 Map from RFC3046 relay agent options to network-id tags. This
682 data may be provided by DHCP relay agents. The circuit-id or
683 remote-id is normally given as colon-separated hex, but is also
684 allowed to be a simple string. If an exact match is achieved
685 between the circuit or agent ID and one provided by a relay
686 agent, the network-id tag is set.
687 --dhcp-subscrid=<network-id>,<subscriber-id>
689 Map from RFC3993 subscriber-id relay agent options to network-id
690 tags.
691 --dhcp-match=<network-id>,<option number>|option:<option name>|vi-
693 encap:<enterprise>[,<value>]
694 Without a value, set the network-id tag if the client sends a
695 DHCP option of the given number or name. When a value is given,
696 set the tag only if the option is sent and matches the value.
697 The value may be of the form "01:ff:*:02" in which case the
698 value must match (apart from widcards) but the option sent may
699 have unmatched data past the end of the value. The value may
700 also be of the same form as in dhcp-option in which case the
701 option sent is treated as an array, and one element must match,
702 so
703 --dhcp-match=efi-ia32,option:client-arch,6
705 will set the tag "efi-ia32" if the the number 6 appears in the
707 list of architectures sent by the client in option 93. (See RFC
708 4578 for details.) If the value is a string, substring matching
709 is used.
710 The special form with vi-encap:<enterpise number> matches
712 against vendor-identifying vendor classes for the specified
713 enterprise. Please see RFC 3925 for more details of the rare and
714 interesting beasts.
715 -J, --dhcp-ignore=<network-id>[,<network-id>]
717 When all the given network-ids match the set of network-ids
718 derived from the net, host, vendor and user classes, ignore the
719 host and do not allocate it a DHCP lease.
720 --dhcp-ignore-names[=<network-id>[,<network-id>]]
722 When all the given network-ids match the set of network-ids
723 derived from the net, host, vendor and user classes, ignore any
724 hostname provided by the host. Note that, unlike dhcp-ignore, it
725 is permissible to supply no netid tags, in which case DHCP-
726 client supplied hostnames are always ignored, and DHCP hosts are
727 added to the DNS using only dhcp-host configuration in dnsmasq
728 and the contents of /etc/hosts and /etc/ethers.
729 --dhcp-broadcast=<network-id>[,<network-id>]
731 When all the given network-ids match the set of network-ids
732 derived from the net, host, vendor and user classes, always use
733 broadcast to communicate with the host when it is unconfigured.
734 Most DHCP clients which need broadcast replies set a flag in
735 their requests so that this happens automatically, some old
736 BOOTP clients do not.
737 -M, --dhcp-boot=[net:<network-id>,]<filename>,[<servername>[,<server
739 address>]]
740 Set BOOTP options to be returned by the DHCP server. Server name
741 and address are optional: if not provided, the name is left
742 empty, and the address set to the address of the machine running
743 dnsmasq. If dnsmasq is providing a TFTP service (see --enable-
744 tftp ) then only the filename is required here to enable network
745 booting. If the optional network-id(s) are given, they must
746 match for this configuration to be sent. Note that network-ids
747 are prefixed by "net:" to distinguish them.
748 --pxe-service=[net:<network-id>,]<CSA>,<menu text>[,<basename>|<boot‐
750 servicetype>][,<server address>]
751 Most uses of PXE boot-ROMS simply allow the PXE system to obtain
752 an IP address and then download the file specified by dhcp-boot
753 and execute it. However the PXE system is capable of more com‐
754 plex functions when supported by a suitable DHCP server.
755 This specifies a boot option which may appear in a PXE boot
757 menu. <CSA> is client system type, only services of the correct
758 type will appear in a menu. The known types are x86PC, PC98,
759 IA64_EFI, Alpha, Arc_x86, Intel_Lean_Client, IA32_EFI, BC_EFI,
760 Xscale_EFI and X86-64_EFI; an integer may be used for other
761 types. The parameter after the menu text may be a file name, in
762 which case dnsmasq acts as a boot server and directs the PXE
763 client to download the file by TFTP, either from itself (
764 enable-tftp must be set for this to work) or another TFTP server
765 if the final IP address is given. Note that the "layer" suffix
766 (normally ".0") is supplied by PXE, and should not be added to
767 the basename. If an integer boot service type, rather than a
768 basename is given, then the PXE client will search for a suit‐
769 able boot service for that type on the network. This search may
770 be done by broadcast, or direct to a server if its IP address is
771 provided. If no boot service type or filename is provided (or a
772 boot service type of 0 is specified) then the menu entry will
773 abort the net boot procedure and continue booting from local
774 media.
775 --pxe-prompt=[net:<network-id>,]<prompt>[,<timeout>]
777 Setting this provides a prompt to be displayed after PXE boot.
778 If the timeout is given then after the timeout has elapsed with
779 no keyboard input, the first available menu option will be auto‐
780 matically executed. If the timeout is zero then the first avail‐
781 able menu item will be executed immediately. If pxe-prompt is
782 ommitted the system will wait for user input if there are multi‐
783 ple items in the menu, but boot immediately if there is only
784 one. See pxe-service for details of menu items.
785 Dnsmasq supports PXE "proxy-DHCP", in this case another DHCP
787 server on the network is responsible for allocating IP
788 addresses, and dnsmasq simply provides the information given in
789 pxe-prompt and pxe-service to allow netbooting. This mode is
790 enabled using the proxy keyword in dhcp-range.
791 -X, --dhcp-lease-max=<number>
793 Limits dnsmasq to the specified maximum number of DHCP leases.
794 The default is 150. This limit is to prevent DoS attacks from
795 hosts which create thousands of leases and use lots of memory in
796 the dnsmasq process.
797 -K, --dhcp-authoritative
799 Should be set when dnsmasq is definitely the only DHCP server on
800 a network. It changes the behaviour from strict RFC compliance
801 so that DHCP requests on unknown leases from unknown hosts are
802 not ignored. This allows new hosts to get a lease without a
803 tedious timeout under all circumstances. It also allows dnsmasq
804 to rebuild its lease database without each client needing to
805 reacquire a lease, if the database is lost.
806 --dhcp-alternate-port[=<server port>[,<client port>]]
808 Change the ports used for DHCP from the default. If this option
809 is given alone, without arguments, it changes the ports used for
810 DHCP from 67 and 68 to 1067 and 1068. If a single argument is
811 given, that port number is used for the server and the port num‐
812 ber plus one used for the client. Finally, two port numbers
813 allows arbitrary specification of both server and client ports
814 for DHCP.
815 -3, --bootp-dynamic[=<network-id>[,<network-id>]]
817 Enable dynamic allocation of IP addresses to BOOTP clients. Use
818 this with care, since each address allocated to a BOOTP client
819 is leased forever, and therefore becomes permanently unavailable
820 for re-use by other hosts. if this is given without tags, then
821 it unconditionally enables dynamic allocation. With tags, only
822 when the tags are all set. It may be repeated with different tag
823 sets.
824 -5, --no-ping
826 By default, the DHCP server will attempt to ensure that an
827 address in not in use before allocating it to a host. It does
828 this by sending an ICMP echo request (aka "ping") to the address
829 in question. If it gets a reply, then the address must already
830 be in use, and another is tried. This flag disables this check.
831 Use with caution.
832 --log-dhcp
834 Extra logging for DHCP: log all the options sent to DHCP clients
835 and the netid tags used to determine them.
836 -l, --dhcp-leasefile=<path>
838 Use the specified file to store DHCP lease information.
839 -6 --dhcp-script=<path>
841 Whenever a new DHCP lease is created, or an old one destroyed,
842 the executable specified by this option is run. The arguments to
843 the process are "add", "old" or "del", the MAC address of the
844 host, the IP address, and the hostname, if known. "add" means a
845 lease has been created, "del" means it has been destroyed, "old"
846 is a notification of an existing lease when dnsmasq starts or a
847 change to MAC address or hostname of an existing lease (also,
848 lease length or expiry and client-id, if leasefile-ro is set).
849 If the MAC address is from a network type other than ethernet,
850 it will have the network type prepended, eg
851 "06-01:23:45:67:89:ab" for token ring. The process is run as
852 root (assuming that dnsmasq was originally run as root) even if
853 dnsmasq is configured to change UID to an unprivileged user.
854 The environment is inherited from the invoker of dnsmasq, and if
855 the host provided a client-id, this is stored in the environment
856 variable DNSMASQ_CLIENT_ID. If the fully-qualified domain name
857 of the host is known, the domain part is stored in DNS‐
858 MASQ_DOMAIN. If the client provides vendor-class, hostname or
859 user-class,
860 these are provided in DNSMASQ_VENDOR_CLASS DNSMASQ_SUP‐
861 PLIED_HOSTNAME and DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn
862 variables, but only for "add" actions or "old" actions when a
863 host resumes an existing lease, since these data are not held in
864 dnsmasq's lease database. If dnsmasq was compiled with HAVE_BRO‐
865 KEN_RTC, then the length of the lease (in seconds) is stored in
866 DNSMASQ_LEASE_LENGTH, otherwise the time of lease expiry is
867 stored in DNSMASQ_LEASE_EXPIRES. The number of seconds until
868 lease expiry is always stored in DNSMASQ_TIME_REMAINING. If a
869 lease used to have a hostname, which is removed, an "old" event
870 is generated with the new state of the lease, ie no name, and
871 the former name is provided in the environment variable DNS‐
872 MASQ_OLD_HOSTNAME. DNSMASQ_INTERFACE stores the name of the
873 interface on which the request arrived; this is not set for
874 "old" actions when dnsmasq restarts. DNSMASQ_RELAY_ADDRESS is
875 set if the client used a DHCP relay to contact dnsmasq and the
876 IP address of the relay is known. DNSMASQ_TAGS contains all the
877 network-id tags set during the DHCP transaction, separated by
878 spaces. All file descriptors are closed except stdin, stdout
879 and stderr which are open to /dev/null (except in debug mode).
880 The script is not invoked concurrently: if subsequent lease
881 changes occur, the script is not invoked again until any exist‐
882 ing invocation exits. At dnsmasq startup, the script will be
883 invoked for all existing leases as they are read from the lease
884 file. Expired leases will be called with "del" and others with
885 "old". <path> must be an absolute pathname, no PATH search
886 occurs. When dnsmasq receives a HUP signal, the script will be
887 invoked for existing leases with an "old " event.
888 --dhcp-scriptuser
890 Specify the user as which to run the lease-change script. This
891 defaults to root, but can be changed to another user using this
892 flag.
893 -9, --leasefile-ro
895 Completely suppress use of the lease database file. The file
896 will not be created, read, or written. Change the way the lease-
897 change script (if one is provided) is called, so that the lease
898 database may be maintained in external storage by the script. In
899 addition to the invocations given in --dhcp-script the lease-
900 change script is called once, at dnsmasq startup, with the sin‐
901 gle argument "init". When called like this the script should
902 write the saved state of the lease database, in dnsmasq lease‐
903 file format, to stdout and exit with zero exit code. Setting
904 this option also forces the leasechange script to be called on
905 changes to the client-id and lease length and expiry time.
906 --bridge-interface=<interface>,<alias>[,<alias>]
908 Treat DHCP request packets arriving at any of the <alias> inter‐
909 faces as if they had arrived at <interface>. This option is nec‐
910 essary when using "old style" bridging on BSD platforms, since
911 packets arrive at tap interfaces which don't have an IP address.
912 -s, --domain=<domain>[,<address range>]
914 Specifies DNS domains for the DHCP server. Domains may be be
915 given unconditionally (without the IP range) or for limited IP
916 ranges. This has two effects; firstly it causes the DHCP server
917 to return the domain to any hosts which request it, and secondly
918 it sets the domain which it is legal for DHCP-configured hosts
919 to claim. The intention is to constrain hostnames so that an
920 untrusted host on the LAN cannot advertise its name via dhcp as
921 e.g. "microsoft.com" and capture traffic not meant for it. If no
922 domain suffix is specified, then any DHCP hostname with a domain
923 part (ie with a period) will be disallowed and logged. If suffix
924 is specified, then hostnames with a domain part are allowed,
925 provided the domain part matches the suffix. In addition, when a
926 suffix is set then hostnames without a domain part have the suf‐
927 fix added as an optional domain part. Eg on my network I can set
928 --domain=thekelleys.org.uk and have a machine whose DHCP host‐
929 name is "laptop". The IP address for that machine is available
930 from dnsmasq both as "laptop" and "laptop.thekelleys.org.uk". If
931 the domain is given as "#" then the domain is read from the
932 first "search" directive in /etc/resolv.conf (or equivalent).
933 The address range can be of the form <ip address>,<ip address>
934 or <ip address>/<netmask> or just a single <ip address>. See
935 --dhcp-fqdn which can change the behaviour of dnsmasq with
936 domains.
937 --dhcp-fqdn
939 In the default mode, dnsmasq inserts the unqualified names of
940 DHCP clients into the DNS. For this reason, the names must be
941 unique, even if two clients which have the same name are in dif‐
942 ferent domains. If a second DHCP client appears which has the
943 same name as an existing client, the name is transfered to the
944 new client. If --dhcp-fqdn is set, this behaviour changes: the
945 unqualified name is no longer put in the DNS, only the qualified
946 name. Two DHCP clients with the same name may both keep the
947 name, provided that the domain part is different (ie the fully
948 qualified names differ.) To ensure that all names have a domain
949 part, there must be at least --domain without an address speci‐
950 fied when --dhcp-fqdn is set.
951 --enable-tftp
953 Enable the TFTP server function. This is deliberately limited to
954 that needed to net-boot a client. Only reading is allowed; the
955 tsize and blksize extensions are supported (tsize is only sup‐
956 ported in octet mode).
957 --tftp-root=<directory>
959 Look for files to transfer using TFTP relative to the given
960 directory. When this is set, TFTP paths which include ".." are
961 rejected, to stop clients getting outside the specified root.
962 Absolute paths (starting with /) are allowed, but they must be
963 within the tftp-root.
964 --tftp-unique-root
966 Add the IP address of the TFTP client as a path component on the
967 end of the TFTP-root (in standard dotted-quad format). Only
968 valid if a tftp-root is set and the directory exists. For
969 instance, if tftp-root is "/tftp" and client 1.2.3.4 requests
970 file "myfile" then the effective path will be
971 "/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4 exists or /tftp/myfile
972 otherwise.
973 --tftp-secure
975 Enable TFTP secure mode: without this, any file which is read‐
976 able by the dnsmasq process under normal unix access-control
977 rules is available via TFTP. When the --tftp-secure flag is
978 given, only files owned by the user running the dnsmasq process
979 are accessible. If dnsmasq is being run as root, different rules
980 apply: --tftp-secure has no effect, but only files which have
981 the world-readable bit set are accessible. It is not recommended
982 to run dnsmasq as root with TFTP enabled, and certainly not
983 without specifying --tftp-root. Doing so can expose any world-
984 readable file on the server to any host on the net.
985 --tftp-max=<connections>
987 Set the maximum number of concurrent TFTP connections allowed.
988 This defaults to 50. When serving a large number of TFTP connec‐
989 tions, per-process file descriptor limits may be encountered.
990 Dnsmasq needs one file descriptor for each concurrent TFTP con‐
991 nection and one file descriptor per unique file (plus a few oth‐
992 ers). So serving the same file simultaneously to n clients will
993 use require about n + 10 file descriptors, serving different
994 files simultaneously to n clients will require about (2*n) + 10
995 descriptors. If --tftp-port-range is given, that can affect the
996 number of concurrent connections.
997 --tftp-no-blocksize
999 Stop the TFTP server from negotiating the "blocksize" option
1000 with a client. Some buggy clients request this option but then
1001 behave badly when it is granted.
1002 --tftp-port-range=<start>,<end>
1004 A TFTP server listens on a well-known port (69) for connection
1005 initiation, but it also uses a dynamically-allocated port for
1006 each connection. Normally these are allocated by the OS, but
1007 this option specifies a range of ports for use by TFTP trans‐
1008 fers. This can be useful when TFTP has to traverse a firewall.
1009 The start of the range cannot be lower than 1025 unless dnsmasq
1010 is running as root. The number of concurrent TFTP connections is
1011 limited by the size of the port range.
1012 -C, --conf-file=<file>
1014 Specify a different configuration file. The conf-file option is
1015 also allowed in configuration files, to include multiple config‐
1016 uration files.
1017 -7, --conf-dir=<directory>[,<file-extension>......]
1019 Read all the files in the given directory as configuration
1020 files. If extension(s) are given, any files which end in those
1021 extensions are skipped. Any files whose names end in ~ or start
1022 with . or start and end with # are always skipped. This flag may
1023 be given on the command line or in a configuration file.
1024
1026 At startup, dnsmasq reads /etc/dnsmasq.conf, if it exists. (On FreeBSD,
1027 the file is /usr/local/etc/dnsmasq.conf ) (but see the -C and -7
1028 options.) The format of this file consists of one option per line,
1029 exactly as the long options detailed in the OPTIONS section but without
1030 the leading "--". Lines starting with # are comments and ignored. For
1031 options which may only be specified once, the configuration file over‐
1032 rides the command line. Quoting is allowed in a config file: between "
1033 quotes the special meanings of ,:. and # are removed and the following
1034 escapes are allowed: \\ \" \t \e \b \r and \n. The later corresponding
1035 to tab, escape, backspace, return and newline.
1036
1038 When it receives a SIGHUP, dnsmasq clears its cache and then re-loads
1039 /etc/hosts and /etc/ethers and any file given by --dhcp-hostsfile,
1040 --dhcp-optsfile or --addn-hosts. The dhcp lease change script is
1041 called for all existing DHCP leases. If --no-poll is set SIGHUP also
1042 re-reads /etc/resolv.conf. SIGHUP does NOT re-read the configuration
1043 file.
1044 When it receives a SIGUSR1, dnsmasq writes statistics to the system
1046 log. It writes the cache size, the number of names which have had to
1047 removed from the cache before they expired in order to make room for
1048 new names and the total number of names that have been inserted into
1049 the cache. For each upstream server it gives the number of queries
1050 sent, and the number which resulted in an error. In --no-daemon mode or
1051 when full logging is enabled (-q), a complete dump of the contents of
1052 the cache is made.
1053 When it receives SIGUSR2 and it is logging direct to a file (see --log-
1055 facility ) dnsmasq will close and reopen the log file. Note that during
1056 this operation, dnsmasq will not be running as root. When it first cre‐
1057 ates the logfile dnsmasq changes the ownership of the file to the non-
1058 root user it will run as. Logrotate should be configured to create a
1059 new log file with the ownership which matches the existing one before
1060 sending SIGUSR2. If TCP DNS queries are in progress, the old logfile
1061 will remain open in child processes which are handling TCP queries and
1062 may continue to be written. There is a limit of 150 seconds, after
1063 which all existing TCP processes will have expired: for this reason, it
1064 is not wise to configure logfile compression for logfiles which have
1065 just been rotated. Using logrotate, the required options are create and
1066 delaycompress.
1067 Dnsmasq is a DNS query forwarder: it it not capable of recursively
1071 answering arbitrary queries starting from the root servers but forwards
1072 such queries to a fully recursive upstream DNS server which is typi‐
1073 cally provided by an ISP. By default, dnsmasq reads /etc/resolv.conf to
1074 discover the IP addresses of the upstream nameservers it should use,
1075 since the information is typically stored there. Unless --no-poll is
1076 used, dnsmasq checks the modification time of /etc/resolv.conf (or
1077 equivalent if --resolv-file is used) and re-reads it if it changes.
1078 This allows the DNS servers to be set dynamically by PPP or DHCP since
1079 both protocols provide the information. Absence of /etc/resolv.conf is
1080 not an error since it may not have been created before a PPP connection
1081 exists. Dnsmasq simply keeps checking in case /etc/resolv.conf is cre‐
1082 ated at any time. Dnsmasq can be told to parse more than one
1083 resolv.conf file. This is useful on a laptop, where both PPP and DHCP
1084 may be used: dnsmasq can be set to poll both /etc/ppp/resolv.conf and
1085 /etc/dhcpc/resolv.conf and will use the contents of whichever changed
1086 last, giving automatic switching between DNS servers.
1087 Upstream servers may also be specified on the command line or in the
1089 configuration file. These server specifications optionally take a
1090 domain name which tells dnsmasq to use that server only to find names
1091 in that particular domain.
1092 In order to configure dnsmasq to act as cache for the host on which it
1094 is running, put "nameserver 127.0.0.1" in /etc/resolv.conf to force
1095 local processes to send queries to dnsmasq. Then either specify the
1096 upstream servers directly to dnsmasq using --server options or put
1097 their addresses real in another file, say /etc/resolv.dnsmasq and run
1098 dnsmasq with the -r /etc/resolv.dnsmasq option. This second technique
1099 allows for dynamic update of the server addresses by PPP or DHCP.
1100 Addresses in /etc/hosts will "shadow" different addresses for the same
1102 names in the upstream DNS, so "mycompany.com 1.2.3.4" in /etc/hosts
1103 will ensure that queries for "mycompany.com" always return 1.2.3.4 even
1104 if queries in the upstream DNS would otherwise return a different
1105 address. There is one exception to this: if the upstream DNS contains a
1106 CNAME which points to a shadowed name, then looking up the CNAME
1107 through dnsmasq will result in the unshadowed address associated with
1108 the target of the CNAME. To work around this, add the CNAME to
1109 /etc/hosts so that the CNAME is shadowed too.
1110 The network-id system works as follows: For each DHCP request, dnsmasq
1113 collects a set of valid network-id tags, one from the dhcp-range used
1114 to allocate the address, one from any matching dhcp-host (and "known"
1115 if a dhcp-host matches) the tag "bootp" for BOOTP requests, a tag whose
1116 name is the name if the interface on which the request arrived, and
1117 possibly many from matching vendor classes and user classes sent by the
1118 DHCP client. Any dhcp-option which has network-id tags will be used in
1119 preference to an untagged dhcp-option, provided that _all_ the tags
1120 match somewhere in the set collected as described above. The prefix '#'
1121 on a tag means 'not' so --dhcp=option=#purple,3,1.2.3.4 sends the
1122 option when the network-id tag purple is not in the set of valid tags.
1123 If the network-id in a dhcp-range is prefixed with 'net:' then its
1125 meaning changes from setting a tag to matching it. Thus if there is
1126 more than dhcp-range on a subnet, and one is tagged with a network-id
1127 which is set (for instance from a vendorclass option) then hosts which
1128 set the netid tag will be allocated addresses in the tagged range.
1129 The DHCP server in dnsmasq will function as a BOOTP server also, pro‐
1131 vided that the MAC address and IP address for clients are given, either
1132 using dhcp-host configurations or in /etc/ethers , and a dhcp-range
1133 configuration option is present to activate the DHCP server on a par‐
1134 ticular network. (Setting --bootp-dynamic removes the need for static
1135 address mappings.) The filename parameter in a BOOTP request is matched
1136 against netids in dhcp-option configurations, as is the tag "bootp",
1137 allowing some control over the options returned to different classes of
1138 hosts.
1139
1142 0 - Dnsmasq successfully forked into the background, or terminated nor‐
1143 mally if backgrounding is not enabled.
1144 1 - A problem with configuration was detected.
1146 2 - A problem with network access occurred (address in use, attempt to
1148 use privileged ports without permission).
1149 3 - A problem occurred with a filesystem operation (missing file/direc‐
1151 tory, permissions).
1152 4 - Memory allocation failure.
1154 5 - Other miscellaneous problem.
1156 11 or greater - a non zero return code was received from the lease-
1158 script process "init" call. The exit code from dnsmasq is the script's
1159 exit code with 10 added.
1160
1163 The default values for resource limits in dnsmasq are generally conser‐
1164 vative, and appropriate for embedded router type devices with slow pro‐
1165 cessors and limited memory. On more capable hardware, it is possible to
1166 increase the limits, and handle many more clients. The following
1167 applies to dnsmasq-2.37: earlier versions did not scale as well.
1168 Dnsmasq is capable of handling DNS and DHCP for at least a thousand
1171 clients. Clearly to do this the value of --dhcp-lease-max must be
1172 increased, and lease times should not be very short (less than one
1173 hour). The value of --dns-forward-max can be increased: start with it
1174 equal to the number of clients and increase if DNS seems slow. Note
1175 that DNS performance depends too on the performance of the upstream
1176 nameservers. The size of the DNS cache may be increased: the hard limit
1177 is 10000 names and the default (150) is very low. Sending SIGUSR1 to
1178 dnsmasq makes it log information which is useful for tuning the cache
1179 size. See the NOTES section for details.
1180 The built-in TFTP server is capable of many simultaneous file trans‐
1183 fers: the absolute limit is related to the number of file-handles
1184 allowed to a process and the ability of the select() system call to
1185 cope with large numbers of file handles. If the limit is set too high
1186 using --tftp-max it will be scaled down and the actual limit logged at
1187 start-up. Note that more transfers are possible when the same file is
1188 being sent than when each transfer sends a different file.
1189 It is possible to use dnsmasq to block Web advertising by using a list
1192 of known banner-ad servers, all resolving to 127.0.0.1 or 0.0.0.0, in
1193 /etc/hosts or an additional hosts file. The list can be very long, dns‐
1194 masq has been tested successfully with one million names. That size
1195 file needs a 1GHz processor and about 60Mb of RAM.
1196
1199 Dnsmasq can be compiled to support internationalisation. To do this,
1200 the make targets "all-i18n" and "install-i18n" should be used instead
1201 of the standard targets "all" and "install". When internationalisation
1202 is compiled in, dnsmasq will produce log messages in the local language
1203 and support internationalised domain names (IDN). Domain names in
1204 /etc/hosts, /etc/ethers and /etc/dnsmasq.conf which contain non-ASCII
1205 characters will be translated to the DNS-internal punycode representa‐
1206 tion. Note that dnsmasq determines both the language for messages and
1207 the assumed charset for configuration files from the LANG environment
1208 variable. This should be set to the system default value by the script
1209 which is responsible for starting dnsmasq. When editing the configura‐
1210 tion files, be careful to do so using only the system-default locale
1211 and not user-specific one, since dnsmasq has no direct way of determin‐
1212 ing the charset in use, and must assume that it is the system default.
1213
1216 /etc/dnsmasq.conf
1217 /usr/local/etc/dnsmasq.conf
1219 /etc/resolv.conf
1221 /etc/hosts
1223 /etc/ethers
1225 /var/lib/dnsmasq/dnsmasq.leases
1227 /var/db/dnsmasq.leases
1229 /var/run/dnsmasq.pid
1231
1233 hosts(5), resolver(5)
1234
1236 This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.
1237 DNSMASQ(8)