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, multiple
22 networks, DHCP-relay and RFC3011 subnet specifiers. It automatically
23 sends a sensible default set of DHCP options, and can be configured to
24 send any desired set of DHCP options, inlcuding vendor-encapsulated
25 options. It includes a secure, read-only, TFTP server to allow net/PXE
26 boot of DHCP hosts and also supports 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 -h, --no-hosts
38 Don't read the hostnames in /etc/hosts.
39 -H, --addn-hosts=<file>
41 Additional hosts file. Read the specified file as well as
42 /etc/hosts. If -h is given, read only the specified file. This
43 option may be repeated for more than one additional hosts file.
44 -E, --expand-hosts
46 Add the domain to simple names (without a period) in /etc/hosts
47 in the same way as for DHCP-derived names.
48 -T, --local-ttl=<time>
50 When replying with information from /etc/hosts or the DHCP
51 leases file dnsmasq by default sets the time-to-live field to
52 zero, meaning that the requestor should not itself cache the
53 information. This is the correct thing to do in almost all situ‐
54 ations. This option allows a time-to-live (in seconds) to be
55 given for these replies. This will reduce the load on the server
56 at the expense of clients using stale data under some circum‐
57 stances.
58 -k, --keep-in-foreground
60 Do not go into the background at startup but otherwise run as
61 normal. This is intended for use when dnsmasq is run under dae‐
62 montools or launchd.
63 -d, --no-daemon
65 Debug mode: don't fork to the background, don't write a pid
66 file, don't change user id, generate a complete cache dump on
67 receipt on SIGUSR1, log to stderr as well as syslog, don't fork
68 new processes to handle TCP queries.
69 -q, --log-queries
71 Log the results of DNS queries handled by dnsmasq. Enable a full
72 cache dump on receipt of SIGUSR1.
73 -8, --log-facility=<facility>
75 Set the facility to which dnsmasq will send syslog entries, this
76 defaults to DAEMON, and to LOCAL0 when debug mode is in opera‐
77 tion.
78 -x, --pid-file=<path>
80 Specify an alternate path for dnsmasq to record its process-id
81 in. Normally /var/run/dnsmasq.pid.
82 -u, --user=<username>
84 Specify the userid to which dnsmasq will change after startup.
85 Dnsmasq must normally be started as root, but it will drop root
86 privileges after startup by changing id to another user. Nor‐
87 mally this user is "nobody" but that can be over-ridden with
88 this switch.
89 -g, --group=<groupname>
91 Specify the group which dnsmasq will run as. The defaults to
92 "dip", if available, to facilitate access to
93 /etc/ppp/resolv.conf which is not normally world readable.
94 -v, --version
96 Print the version number.
97 -p, --port=<port>
99 Listen on <port> instead of the standard DNS port (53). Useful
100 mainly for debugging.
101 -P, --edns-packet-max=<size>
103 Specify the largest EDNS.0 UDP packet which is supported by the
104 DNS forwarder. Defaults to 1280, which is the RFC2671-recom‐
105 mended maximum for ethernet.
106 -Q, --query-port=<query_port>
108 Send outbound DNS queries from, and listen for their replies on,
109 the specific UDP port <query_port> instead of using one chosen
110 at runtime. Useful to simplify your firewall rules; without
111 this, your firewall would have to allow connections from outside
112 DNS servers to a range of UDP ports, or dynamically adapt to the
113 port being used by the current dnsmasq instance.
114 -i, --interface=<interface name>
116 Listen only on the specified interface(s). Dnsmasq automatically
117 adds the loopback (local) interface to the list of interfaces to
118 use when the --interface option is used. If no --interface or
119 --listen-address options are given dnsmasq listens on all avail‐
120 able interfaces except any given in --except-interface options.
121 IP alias interfaces (eg "eth1:0") cannot be used with --inter‐
122 face or --except-interface options, use --listen-address
123 instead.
124 -I, --except-interface=<interface name>
126 Do not listen on the specified interface. Note that the order of
127 --listen-address --interface and --except-interface options does
128 not matter and that --except-interface options always override
129 the others.
130 -2, --no-dhcp-interface=<interface name>
132 Do not provide DHCP or TFTP on the specified interface, but do
133 provide DNS service.
134 -a, --listen-address=<ipaddr>
136 Listen on the given IP address(es). Both --interface and --lis‐
137 ten-address options may be given, in which case the set of both
138 interfaces and addresses is used. Note that if no --interface
139 option is given, but --listen-address is, dnsmasq will not auto‐
140 matically listen on the loopback interface. To achieve this, its
141 IP address, 127.0.0.1, must be explicitly given as a --listen-
142 address option.
143 -z, --bind-interfaces
145 On systems which support it, dnsmasq binds the wildcard address,
146 even when it is listening on only some interfaces. It then dis‐
147 cards requests that it shouldn't reply to. This has the advan‐
148 tage of working even when interfaces come and go and change
149 address. This option forces dnsmasq to really bind only the
150 interfaces it is listening on. About the only time when this is
151 useful is when running another nameserver (or another instance
152 of dnsmasq) on the same machine. Setting this option also
153 enables multiple instances of dnsmasq which provide DHCP service
154 to run in the same machine.
155 -y, --localise-queries
157 Return answers to DNS queries from /etc/hosts which depend on
158 the interface over which the query was received. If a name in
159 /etc/hosts has more than one address associated with it, and at
160 least one of those addresses is on the same subnet as the inter‐
161 face to which the query was sent, then return only the
162 address(es) on that subnet. This allows for a server to have
163 multiple addresses in /etc/hosts corresponding to each of its
164 interfaces, and hosts will get the correct address based on
165 which network they are attached to. Currently this facility is
166 limited to IPv4.
167 -b, --bogus-priv
169 Bogus private reverse lookups. All reverse lookups for private
170 IP ranges (ie 192.168.x.x, etc) which are not found in
171 /etc/hosts or the DHCP leases file are answered with "no such
172 domain" rather than being forwarded upstream.
173 -V, --alias=<old-ip>,<new-ip>[,<mask>]
175 Modify IPv4 addresses returned from upstream nameservers; old-ip
176 is replaced by new-ip. If the optional mask is given then any
177 address which matches the masked old-ip will be re-written. So,
178 for instance --alias=1.2.3.0,6.7.8.0,255.255.255.0 will map
179 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. This is what
180 Cisco PIX routers call "DNS doctoring".
181 -B, --bogus-nxdomain=<ipaddr>
183 Transform replies which contain the IP address given into "No
184 such domain" replies. This is intended to counteract a devious
185 move made by Verisign in September 2003 when they started
186 returning the address of an advertising web page in response to
187 queries for unregistered names, instead of the correct NXDOMAIN
188 response. This option tells dnsmasq to fake the correct response
189 when it sees this behaviour. As at Sept 2003 the IP address
190 being returned by Verisign is 64.94.110.11
191 -f, --filterwin2k
193 Later versions of windows make periodic DNS requests which don't
194 get sensible answers from the public DNS and can cause problems
195 by triggering dial-on-demand links. This flag turns on an option
196 to filter such requests. The requests blocked are for records of
197 types SOA and SRV, and type ANY where the requested name has
198 underscores, to catch LDAP requests.
199 -r, --resolv-file=<file>
201 Read the IP addresses of the upstream nameservers from <file>,
202 instead of /etc/resolv.conf. For the format of this file see
203 resolv.conf(5) the only lines relevant to dnsmasq are nameserver
204 ones. Dnsmasq can be told to poll more than one resolv.conf
205 file, the first file name specified overrides the default, sub‐
206 sequent ones add to the list. This is only allowed when polling;
207 the file with the currently latest modification time is the one
208 used.
209 -R, --no-resolv
211 Don't read /etc/resolv.conf. Get upstream servers only from the
212 command line or the dnsmasq configuration file.
213 -1, --enable-dbus
215 Allow dnsmasq configuration to be updated via DBus method calls.
216 The configuration which can be changed is upstream DNS servers
217 (and corresponding domains) and cache clear. Requires that dns‐
218 masq has been built with DBus support.
219 -o, --strict-order
221 By default, dnsmasq will send queries to any of the upstream
222 servers it knows about and tries to favour servers to are known
223 to be up. Setting this flag forces dnsmasq to try each query
224 with each server strictly in the order they appear in
225 /etc/resolv.conf
226 -n, --no-poll
228 Don't poll /etc/resolv.conf for changes.
229 --clear-on-reload
231 Whenever /etc/resolv.conf is re-read, clear the DNS cache. This
232 is useful when new nameservers may have different data than that
233 held in cache.
234 -D, --domain-needed
236 Tells dnsmasq to never forward queries for plain names, without
237 dots or domain parts, to upstream nameservers. If the name is
238 not known from /etc/hosts or DHCP then a "not found" answer is
239 returned.
240 -S, --local,
242 --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>][@<source>[#<port>]]]
243 Specify IP address of upstream severs directly. Setting this
244 flag does not suppress reading of /etc/resolv.conf, use -R to do
245 that. If one or more optional domains are given, that server is
246 used only for those domains and they are queried only using the
247 specified server. This is intended for private nameservers: if
248 you have a nameserver on your network which deals with names of
249 the form xxx.internal.thekelleys.org.uk at 192.168.1.1 then giv‐
250 ing the flag -S /internal.thekelleys.org.uk/192.168.1.1 will
251 send all queries for internal machines to that nameserver,
252 everything else will go to the servers in /etc/resolv.conf. An
253 empty domain specification, // has the special meaning of
254 "unqualified names only" ie names without any dots in them. A
255 non-standard port may be specified as part of the IP address
256 using a # character. More than one -S flag is allowed, with
257 repeated domain or ipaddr parts as required.
258 Also permitted is a -S flag which gives a domain but no IP
260 address; this tells dnsmasq that a domain is local and it may
261 answer queries from /etc/hosts or DHCP but should never forward
262 queries on that domain to any upstream servers. local is a syn‐
263 onym for server to make configuration files clearer in this
264 case.
265 The optional second IP address after the @ character tells dns‐
267 masq how to set the source address of the queries to this name‐
268 server. It should be an address belonging to the machine on
269 which dnsmasq is running otherwise this server line will be
270 logged and then ignored. The query-port flag is ignored for any
271 servers which have a source address specified but the port may
272 be specified directly as part of the source address.
273 -A, --address=/<domain>/[domain/]<ipaddr>
275 Specify an IP address to return for any host in the given
276 domains. Queries in the domains are never forwarded and always
277 replied to with the specified IP address which may be IPv4 or
278 IPv6. To give both IPv4 and IPv6 addresses for a domain, use
279 repeated -A flags. Note that /etc/hosts and DHCP leases over‐
280 ride this for individual names. A common use of this is to redi‐
281 rect the entire doubleclick.net domain to some friendly local
282 web server to avoid banner ads. The domain specification works
283 in the same was as for --server, with the additional facility
284 that /#/ matches any domain. Thus --address=/#/1.2.3.4 will
285 always return 1.2.3.4 for any query not answered from /etc/hosts
286 or DHCP and not sent to an upstream nameserver by a more spe‐
287 cific --server directive.
288 -m, --mx-host=<mx name>[[,<hostname>],<preference>]
290 Return an MX record named <mx name> pointing to the given host‐
291 name (if given), or the host specified in the --mx-target switch
292 or, if that switch is not given, the host on which dnsmasq is
293 running. The default is useful for directing mail from systems
294 on a LAN to a central server. The preference value is optional,
295 and defaults to 1 if not given. More than one MX record may be
296 given for a host.
297 -t, --mx-target=<hostname>
299 Specify the default target for the MX record returned by dns‐
300 masq. See --mx-host. If --mx-target is given, but not --mx-
301 host, then dnsmasq returns a MX record containing the MX target
302 for MX queries on the hostname of the machine on which dnsmasq
303 is running.
304 -e, --selfmx
306 Return an MX record pointing to itself for each local machine.
307 Local machines are those in /etc/hosts or with DHCP leases.
308 -L, --localmx
310 Return an MX record pointing to the host given by mx-target (or
311 the machine on which dnsmasq is running) for each local machine.
312 Local machines are those in /etc/hosts or with DHCP leases.
313 -W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<prior‐
315 ity>[,<weight>]]]]
316 Return a SRV DNS record. See RFC2782 for details. If not sup‐
317 plied, the domain defaults to that given by --domain. The
318 default for the target domain is empty, and the default for port
319 is one and the defaults for weight and priority are zero. Be
320 careful if transposing data from BIND zone files: the port,
321 weight and priority numbers are in a different order. More than
322 one SRV record for a given service/domain is allowed, all that
323 match are returned.
324 -Y, --txt-record=<name>[[,<text>],<text>]
326 Return a TXT DNS record. The value of TXT record is a set of
327 strings, so any number may be included, split by commas.
328 --ptr-record=<name>[,<target>]
330 Return a PTR DNS record.
331 -c, --cache-size=<cachesize>
333 Set the size of dnsmasq's cache. The default is 150 names. Set‐
334 ting the cache size to zero disables caching.
335 -N, --no-negcache
337 Disable negative caching. Negative caching allows dnsmasq to
338 remember "no such domain" answers from upstream nameservers and
339 answer identical queries without forwarding them again. This
340 flag disables negative caching.
341 -0, --dns-forward-max=<queries>
343 Set the maximum number of concurrent DNS queries. The default
344 value is 150, which should be fine for most setups. The only
345 known situation where this needs to be increased is when using
346 web-server log file resolvers, which can generate large numbers
347 of concurrent queries.
348 -F, --dhcp-range=[[net:]network-id,]<start-addr>,<end-addr>[[,<net‐
350 mask>],<broadcast>][,<default lease time>]
351 Enable the DHCP server. Addresses will be given out from the
352 range <start-addr> to <end-addr> and from statically defined
353 addresses given in dhcp-host options. If the lease time is
354 given, then leases will be given for that length of time. The
355 lease time is in seconds, or minutes (eg 45m) or hours (eg 1h)
356 or the literal "infinite". This option may be repeated, with
357 different addresses, to enable DHCP service to more than one
358 network. For directly connected networks (ie, networks on which
359 the machine running dnsmasq has an interface) the netmask is
360 optional. It is, however, required for networks which receive
361 DHCP service via a relay agent. The broadcast address is always
362 optional. On some broken systems, dnsmasq can listen on only one
363 interface when using DHCP, and the name of that interface must
364 be given using the interface option. This limitation currently
365 affects OpenBSD before version 4.0. It is always allowed to have
366 more than one dhcp-range in a single subnet. The optional net‐
367 work-id is a alphanumeric label which marks this network so that
368 dhcp options may be specified on a per-network basis. When it
369 is prefixed with 'net:' then its meaning changes from setting a
370 tag to matching it. Only one tag may be set, but more than one
371 tag may be matched. The end address may be replaced by the key‐
372 word static which tells dnsmasq to enable DHCP for the network
373 specified, but not to dynamically allocate IP addresses. Only
374 hosts which have static addresses given via dhcp-host or from
375 /etc/ethers will be served.
376 -G, --dhcp-
378 host=[<hwaddr>][,id:<client_id>|*][,net:<netid>][,<ipaddr>][,<host‐
379 name>][,<lease_time>][,ignore]
380 Specify per host parameters for the DHCP server. This allows a
381 machine with a particular hardware address to be always allo‐
382 cated the same hostname, IP address and lease time. A hostname
383 specified like this overrides any supplied by the DHCP client on
384 the machine. It is also allowable to ommit the hardware address
385 and include the hostname, in which case the IP address and lease
386 times will apply to any machine claiming that name. For example
387 --dhcp-host=00:20:e0:3b:13:af,wap,infinite tells dnsmasq to give
388 the machine with hardware address 00:20:e0:3b:13:af the name
389 wap, and an infinite DHCP lease. --dhcp-host=lap,192.168.0.199
390 tells dnsmasq to always allocate the machine lap the IP address
391 192.168.0.199. Addresses allocated like this are not constrained
392 to be in the range given by the --dhcp-range option, but they
393 must be on the network being served by the DHCP server. It is
394 allowed to use client identifiers rather than hardware addresses
395 to identify hosts by prefixing with 'id:'. Thus: --dhcp-
396 host=id:01:02:03:04,..... refers to the host with client iden‐
397 tifier 01:02:03:04. It is also allowed to specify the client ID
398 as text, like this: --dhcp-host=id:clientidastext,..... The
399 special option id:* means "ignore any client-id and use MAC
400 addresses only." This is useful when a client presents a client-
401 id sometimes but not others. If a name appears in /etc/hosts,
402 the associated address can be allocated to a DHCP lease, but
403 only if a --dhcp-host option specifying the name also exists.
404 The special keyword "ignore" tells dnsmasq to never offer a DHCP
405 lease to a machine. The machine can be specified by hardware
406 address, client ID or hostname, for instance --dhcp-
407 host=00:20:e0:3b:13:af,ignore This is useful when there is
408 another DHCP server on the network which should be used by some
409 machines. The net:<network-id> sets the network-id tag whenever
410 this dhcp-host directive is in use. This can be used to selec‐
411 tively send DHCP options just for this host. Ethernet addresses
412 (but not client-ids) may have wildcard bytes, so for example
413 --dhcp-host=00:20:e0:3b:13:*,ignore will cause dnsmasq to ignore
414 a range of hardware addresses. Note that the "*" will need to be
415 escaped or quoted on a command line, but not in the configura‐
416 tion file. Hardware addresses normally match any network (ARP)
417 type, but it is possible to restrict them to a single ARP type
418 by preceding them with the ARP-type (in HEX) and "-". so --dhcp-
419 host=06-00:20:e0:3b:13:af,1.2.3.4 will only match a Token-Ring
420 hardware address, since the ARP-address type for token ring is
421 6.
422 -Z, --read-ethers
424 Read /etc/ethers for information about hosts for the DHCP
425 server. The format of /etc/ethers is a hardware address, fol‐
426 lowed by either a hostname or dotted-quad IP address. When read
427 by dnsmasq these lines have exactly the same effect as --dhcp-
428 host options containing the same information.
429 -O, --dhcp-option=[<network-id>,[<network-id>,]][vendor:[<vendor-
431 class>],]<opt>,[<value>[,<value>]]
432 Specify different or extra options to DHCP clients. By default,
433 dnsmasq sends some standard options to DHCP clients, the netmask
434 and broadcast address are set to the same as the host running
435 dnsmasq, and the DNS server and default route are set to the
436 address of the machine running dnsmasq. If the domain name
437 option has been set, that is sent. This option allows these
438 defaults to be overridden, or other options specified. The <opt>
439 is the number of the option, as specified in RFC2132. For exam‐
440 ple, to set the default route option to 192.168.4.4, do --dhcp-
441 option=3,192.168.4.4 and to set the time-server address to
442 192.168.0.4, do --dhcp-option=42,192.168.0.4 The special address
443 0.0.0.0 is taken to mean "the address of the machine running
444 dnsmasq". Data types allowed are comma separated dotted-quad IP
445 addresses, a decimal number, colon-separated hex digits and a
446 text string. If the optional network-ids are given then this
447 option is only sent when all the network-ids are matched.
448 Special processing is done on a text argument for option 119, to
450 conform with RFC 3397. Text or dotted-quad IP addresses as argu‐
451 ments to option 120 are handled as per RFC 3361. Dotted-quad IP
452 addresses which are followed by a slash and then a netmask size
453 are encoded as described in RFC 3442.
454 Be careful: no checking is done that the correct type of data
456 for the option number is sent, it is quite possible to persuade
457 dnsmasq to generate illegal DHCP packets with injudicious use of
458 this flag. When the value is a decimal number, dnsmasq must
459 determine how large the data item is. It does this by examining
460 the option number and/or the value, but can be overridden by
461 appending a single letter flag as follows: b = one byte, s = two
462 bytes, i = four bytes. This is mainly useful with encapsulated
463 vendor class options (see below) where dnsmasq cannot determine
464 data size from the option number. Option data which consists
465 solely of periods and digits will be interpreted by dnsmasq as
466 an IP address, and inserted into an option as such. To force a
467 literal string, use quotes. For instance when using option 66 to
468 send a literal IP address as TFTP server name, it is necessary
469 to do --dhcp-option=66,"1.2.3.4"
470 Encapsulated Vendor-class options may also be specified using
472 --dhcp-option: for instance --dhcp-option=vendor:PXE‐
473 Client,1,0.0.0.0 sends the encapsulated vendor class-specific
474 option "mftp-address=0.0.0.0" to any client whose vendor-class
475 matches "PXEClient". The vendor-class matching is substring
476 based (see --dhcp-vendorclass for details). If a vendor-class
477 option (number 60) is sent by dnsmasq, then that is used for
478 selecting encapsulated options in preference to any sent by the
479 client. It is possible to omit the vendorclass completely;
480 --dhcp-option=vendor:,1,0.0.0.0 in which case the encapsulated
481 option is always sent. The address 0.0.0.0 is not treated spe‐
482 cially in encapsulated vendor class options.
483 --dhcp-option-force=[<network-id>,[<network-id>,]][vendor:[<vendor-
485 class>],]<opt>,[<value>[,<value>]]
486 This works in exactly the same way as --dhcp-otion except that
487 the option will always be sent, even of the client does not ask
488 for it in the parameter request list. This is sometimes needed,
489 for example when sending options to PXELinux.
490 -U, --dhcp-vendorclass=<network-id>,<vendor-class>
492 Map from a vendor-class string to a network id. Most DHCP
493 clients provide a "vendor class" which represents, in some
494 sense, the type of host. This option maps vendor classes to net‐
495 work ids, so that DHCP options may be selectively delivered to
496 different classes of hosts. For example dhcp-vendorclass=print‐
497 ers,Hewlett-Packard JetDirect will allow options to be set only
498 for HP printers like so: --dhcp-option=printers,3,192.168.4.4
499 The vendor-class string is substring matched against the vendor-
500 class supplied by the client, to allow fuzzy matching.
501 -j, --dhcp-userclass=<network-id>,<user-class>
503 Map from a user-class string to a network id (with substring
504 matching, like vendor classes). Most DHCP clients provide a
505 "user class" which is configurable. This option maps user
506 classes to network ids, so that DHCP options may be selectively
507 delivered to different classes of hosts. It is possible, for
508 instance to use this to set a different printer server for hosts
509 in the class "accounts" than for hosts in the class "engineer‐
510 ing".
511 -4, --dhcp-mac=<network-id>,<MAC address>
513 Map from a MAC address to a network-id. The MAC address may
514 include wildcards. For example --dhcp-mac=3com,01:34:23:*:*:*
515 will set the tag "3com" for any host whose MAC address matches
516 the pattern.
517 -J, --dhcp-ignore=<network-id>[,<network-id>]
519 When all the given network-ids match the set of network-ids
520 derived from the net, host, vendor and user classes, ignore the
521 host and do not allocate it a DHCP lease.
522 --dhcp-ignore-name[=<network-id>[,<network-id>]]
524 When all the given network-ids match the set of network-ids
525 derived from the net, host, vendor and user classes, ignore any
526 hostname provided by the host. Note that, unlike dhcp-ignore, it
527 is permissable to supply no netid tags, in which case DHCP-
528 client supplied hostnames are always ignored, and DHCP hosts are
529 added to the DNS using only dhcp-host configuration in dnsmasq
530 and the contents of /etc/hosts and /etc/ethers.
531 -M, --dhcp-boot=[net:<network-id>,]<filename>,[<servername>[,<server
533 address>]]
534 Set BOOTP options to be returned by the DHCP server. Server name
535 and address are optional: if not provided, the name is left
536 empty, and the address set to the address of the machine running
537 dnsmasq. If dnsmasq is providing a TFTP service (see --enable-
538 tftp ) then only the filename is required here to enable network
539 booting. If the optional network-id(s) are given, they must
540 match for this configuration to be sent. Note that network-ids
541 are prefixed by "net:" to distinguish them.
542 -X, --dhcp-lease-max=<number>
544 Limits dnsmasq to the specified maximum number of DHCP leases.
545 The default is 150. This limit is to prevent DoS attacks from
546 hosts which create thousands of leases and use lots of memory in
547 the dnsmasq process.
548 -K, --dhcp-authoritative
550 Should be set when dnsmasq is definately the only DHCP server on
551 a network. It changes the behaviour from strict RFC compliance
552 so that DHCP requests on unknown leases from unknown hosts are
553 not ignored. This allows new hosts to get a lease without a
554 tedious timeout under all circumstances. It also allows dnsmasq
555 to rebuild its lease database without each client needing to
556 reaquire a lease, if the database is lost.
557 -3, --bootp-dynamic
559 Enable dynamic allocation of IP addresses to BOOTP clients. Use
560 this with care, since each address allocated to a BOOTP client
561 is leased forever, and therefore becomes permanently unavailable
562 for re-use by other hosts.
563 -5, --no-ping
565 By default, the DHCP server will attempt to ensure that an
566 address in not in use before allocating it to a host. It does
567 this by sending an ICMP echo request (aka "ping") to the address
568 in question. If it gets a reply, then the address must already
569 be in use, and another is tried. This flag disables this check.
570 Use with caution.
571 -l, --dhcp-leasefile=<path>
573 Use the specified file to store DHCP lease information. If this
574 option is given but no dhcp-range option is given then dnsmasq
575 version 1 behaviour is activated. The file given is assumed to
576 be an ISC dhcpd lease file and parsed for leases which are then
577 added to the DNS system if they have a hostname. This function‐
578 ality may have been excluded from dnsmasq at compile time, in
579 which case an error will occur. In any case note that ISC lease‐
580 file integration is a deprecated feature. It should not be used
581 in new installations, and will be removed in a future release.
582 -6 --dhcp-script=<path>
584 Whenever a new DHCP lease is created, or an old one destroyed,
585 the binary specified by this option is run. The arguments to the
586 process are "add", "old" or "del", the MAC address of the host
587 (or "<null>"), the IP address, and the hostname, if known. "add"
588 means a lease has been created, "del" means it has been
589 destroyed, "old" is a notification of an existing lease when
590 dnsmasq starts or a change to MAC address or hostname of an
591 existing lease (also, lease length or expiry and client-id, if
592 leasefile-ro is set). The process is run as root (assuming that
593 dnsmasq was originally run as root) even if dnsmasq is config‐
594 ured to change UID to an unprivileged user. The environment is
595 inherited from the invoker of dnsmasq, and if the host provided
596 a client-id, this is stored in the environment variable DNS‐
597 MASQ_CLIENT_ID. If the client provides vendor-class or user-
598 class information, these are provided in DNSMASQ_VENDOR_CLASS
599 and DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn variables, but only
600 for "add" actions or "old" actions when a host resumes an exist‐
601 ing lease, since these data are not held in dnsmasq's lease
602 database. If dnsmasq was compiled with HAVE_BROKEN_RTC, then the
603 length of the lease (in seconds) is stored in DNS‐
604 MASQ_LEASE_LENGTH, otherwise the time of lease expiry is stored
605 in DNSMASQ_LEASE_EXPIRES. If a lease used to have a hostname,
606 which is removed, an "old" event is generated with the new state
607 of the lease, ie no name, and the former name is provided in the
608 environment variable DNSMASQ_OLD_HOSTNAME. All file decriptors
609 are closed except stdin, stdout and stderr which are open to
610 /dev/null (except in debug mode). The script is not invoked
611 concurrently: if subsequent lease changes occur, the script is
612 not invoked again until any existing invokation exits. At dns‐
613 masq startup, the script will be invoked for all existing leases
614 as they are read from the lease file. Expired leases will be
615 called with "del" and others with "old". <path> must be an abso‐
616 lute pathname, no PATH search occurs.
617 -9, --leasefile-ro
619 Completely suppress use of the lease database file. The file
620 will not be created, read, or written. Change the way the lease-
621 change script (if one is provided) is called, so that the lease
622 database may be maintained in external storage by the script. In
623 addition to the invokations given in --dhcp-script the lease-
624 change script is called once, at dnsmasq startup, with the sin‐
625 gle argument "init". When called like this the script should
626 write the saved state of the lease database, in dnsmasq lease‐
627 file format, to stdout and exit with zero exit code. Setting
628 this option also forces the leasechange script to be called on
629 changes to the client-id and lease length and expiry time.
630 --bridge-interface=<interface>,<alias>[,<alias>]
632 Treat DHCP request packets arriving at any of the <alias> inter‐
633 faces as if they had arrived at <interface>. This option is only
634 available on FreeBSD and Dragonfly BSD, and is necessary when
635 using "old style" bridging, since packets arrive at tap inter‐
636 faces which don't have an IP address.
637 -s, --domain=<domain>
639 Specifies the domain for the DHCP server. This has two effects;
640 firstly it causes the DHCP server to return the domain to any
641 hosts which request it, and secondly it sets the domain which it
642 is legal for DHCP-configured hosts to claim. The intention is to
643 constrain hostnames so that an untrusted host on the LAN cannot
644 advertise its name via dhcp as e.g. "microsoft.com" and capture
645 traffic not meant for it. If no domain suffix is specified, then
646 any DHCP hostname with a domain part (ie with a period) will be
647 disallowed and logged. If suffix is specified, then hostnames
648 with a domain part are allowed, provided the domain part matches
649 the suffix. In addition, when a suffix is set then hostnames
650 without a domain part have the suffix added as an optional
651 domain part. Eg on my network I can set --domain=thekel‐
652 leys.org.uk and have a machine whose DHCP hostname is "laptop".
653 The IP address for that machine is available from dnsmasq both
654 as "laptop" and "laptop.thekelleys.org.uk". If the domain is
655 given as "#" then the domain is read from the first "search"
656 directive in /etc/resolv.conf (or equivalent).
657 --enable-tftp
659 Enable the TFTP server function. This is deliberately limited to
660 that needed to net-boot a client: Only reading is allowed, and
661 only in binary/octet mode. The tsize and blksize extensions are
662 supported.
663 --tftp-root=<directory>
665 Look for files to transfer using TFTP relative to the given
666 directory. When this is set, TFTP paths which include ".." are
667 rejected, to stop clients getting outside the specified root.
668 --tftp-secure
670 Enable TFTP secure mode: without this, any file which is readble
671 by the dnsmasq process under normal unix access-control rules is
672 available via TFTP. When the --tftp-secure flag is given, only
673 files owned by the user running the dnsmasq process are accessi‐
674 ble. If dnsmasq is being run as root, different rules apply:
675 --tftp-secure has no effect, but only files which have the
676 world-readable bit set are accessible. It is not recommended to
677 run dnsmasq as root with TFTP enabled, and certainly not without
678 specifying --tftp-root. Doing so can expose any world-readable
679 file on the server to any host on the net.
680 --tftp-max=<connections>
682 Set the maximum number of concurrent TFTP connections allowed.
683 This defaults to 50. When serving a large number of TFTP connec‐
684 tions, per-process file descriptor limits may be encountered.
685 Dnsmasq needs one file descriptor for each concurrent TFTP con‐
686 nection and one file descriptor per unique file (plus a few oth‐
687 ers). So serving the same file simultaneously to n clients will
688 use require about n + 10 file descriptors, serving different
689 files simultaneously to n clients will require about (2*n) + 10
690 descriptors.
691 --tftp-no-blocksize
693 Stop the TFTP server from negotiating the "blocksize" option
694 with a client. Some buggy clients request this option but then
695 behave badly when it is granted.
696 -C, --conf-file=<file>
698 Specify a different configuration file. The conf-file option is
699 also allowed in configuration files, to include multiple config‐
700 uration files.
701 -7, --conf-dir=<directory>
703 Read all the files in the given directory as configuration
704 files. Files whose names end in ~ or start with . or start and
705 end with # are skipped. This flag may be given on the command
706 line or in a configuration file.
707
709 At startup, dnsmasq reads /etc/dnsmasq.conf, if it exists. (On FreeBSD,
710 the file is /usr/local/etc/dnsmasq.conf ) (but see the -C and -7
711 options.) The format of this file consists of one option per line,
712 exactly as the long options detailed in the OPTIONS section but without
713 the leading "--". Lines starting with # are comments and ignored. For
714 options which may only be specified once, the configuration file over‐
715 rides the command line. Quoting is allowed in a config file: between "
716 quotes the special meanings of ,:. and # are removed and the following
717 escapes are allowed: \\ \" \t \a \b \r and \n. The later corresponding
718 to tab, bell, backspace, return and newline.
719
721 When it receives a SIGHUP, dnsmasq clears its cache and then re-loads
722 /etc/hosts. If --no-poll is set SIGHUP also re-reads /etc/resolv.conf.
723 SIGHUP does NOT re-read the configuration file.
724 When it receives a SIGUSR1, dnsmasq writes cache statistics to the sys‐
726 tem log. It writes the cache size, the number of names which have had
727 to removed from the cache before they expired in order to make room for
728 new names and the total number of names that have been inserted into
729 the cache. In --no-daemon mode or when full logging is enabled (-q), a
730 complete dump of the contents of the cache is made.
731 Dnsmasq is a DNS query forwarder: it it not capable of recursively
733 answering arbitrary queries starting from the root servers but forwards
734 such queries to a fully recursive upstream DNS server which is typi‐
735 cally provided by an ISP. By default, dnsmasq reads /etc/resolv.conf to
736 discover the IP addresses of the upstream nameservers it should use,
737 since the information is typically stored there. Unless --no-poll is
738 used, dnsmasq checks the modification time of /etc/resolv.conf (or
739 equivalent if --resolv-file is used) and re-reads it if it changes.
740 This allows the DNS servers to be set dynamically by PPP or DHCP since
741 both protocols provide the information. Absence of /etc/resolv.conf is
742 not an error since it may not have been created before a PPP connection
743 exists. Dnsmasq simply keeps checking in case /etc/resolv.conf is cre‐
744 ated at any time. Dnsmasq can be told to parse more than one
745 resolv.conf file. This is useful on a laptop, where both PPP and DHCP
746 may be used: dnsmasq can be set to poll both /etc/ppp/resolv.conf and
747 /etc/dhcpc/resolv.conf and will use the contents of whichever changed
748 last, giving automatic switching between DNS servers.
749 Upstream servers may also be specified on the command line or in the
751 configuration file. These server specifications optionally take a
752 domain name which tells dnsmasq to use that server only to find names
753 in that particular domain.
754 In order to configure dnsmasq to act as cache for the host on which it
756 is running, put "nameserver 127.0.0.1" in /etc/resolv.conf to force
757 local processes to send queries to dnsmasq. Then either specify the
758 upstream servers directly to dnsmasq using --server options or put
759 their addresses real in another file, say /etc/resolv.dnsmasq and run
760 dnsmasq with the -r /etc/resolv.dnsmasq option. This second technique
761 allows for dynamic update of the server addresses by PPP or DHCP.
762 Addresses in /etc/hosts will "shadow" different addresses for the same
764 names in the upstream DNS, so "mycompany.com 1.2.3.4" in /etc/hosts
765 will ensure that queries for "mycompany.com" always return 1.2.3.4 even
766 if queries in the upstream DNS would otherwise return a different
767 address. There is one exception to this: if the upstream DNS contains a
768 CNAME which points to a shadowed name, then looking up the CNAME
769 through dnsmasq will result in the unshadowed address associated with
770 the target of the CNAME. To work around this, add the CNAME to
771 /etc/hosts so that the CNAME is shadowed too.
772 The network-id system works as follows: For each DHCP request, dnsmasq
775 collects a set of valid network-id tags, one from the dhcp-range used
776 to allocate the address, one from any matching dhcp-host and possibly
777 many from matching vendor classes and user classes sent by the DHCP
778 client. Any dhcp-option which has network-id tags will be used in pref‐
779 erence to an untagged dhcp-option, provided that _all_ the tags match
780 somewhere in the set collected as described above. The prefix '#' on a
781 tag means 'not' so --dhcp=option=#purple,3,1.2.3.4 sends the option
782 when the network-id tag purple is not in the set of valid tags.
783 If the network-id in a dhcp-range is prefixed with 'net:' then its
785 meaning changes from setting a tag to matching it. Thus if there is
786 more than dhcp-range on a subnet, and one is tagged with a network-id
787 which is set (for instance from a vendorclass option) then hosts which
788 set the netid tag will be allocated addresses in the tagged range.
789 The DHCP server in dnsmasq will function as a BOOTP server also, pro‐
791 vided that the MAC address and IP address for clients are given, either
792 using dhcp-host configurations or in /etc/ethers , and a dhcp-range
793 configuration option is present to activate the DHCP server on a par‐
794 ticular network. (Setting --bootp-dynamic removes the need for static
795 address mappings.) The filename parameter in a BOOTP request is matched
796 against netids in dhcp-option configurations, as is the tag "bootp",
797 allowing some control over the options returned to different classes of
798 hosts.
799
802 The default values for resource limits in dnsmasq are generally conser‐
803 vative, and appropriate for embedded router type devices with slow pro‐
804 cessors and limited memory. On more capable hardware, it is possible to
805 increase the limits, and handle many more clients. The following
806 applies to dnsmasq-2.37: earlier versions did not scale as well.
807 Dnsmasq is capable of handling DNS and DHCP for at least a thousand
810 clients. Clearly to do this the value of --dhcp-max must be increased,
811 and lease times should not be very short (less than one hour). The
812 value of --dns-forward-max can be increased: start with it equal to the
813 number of clients and increase if DNS seems slow. Note that DNS perfor‐
814 mance depends too on the performance of the upstream nameservers. The
815 size of the DNS cache may be increased: the hard limit is 10000 names
816 and the default (150) is very low. Sending SIGUSR1 to dnsmasq makes it
817 log information which is useful for tuning the cache size. See the
818 NOTES section for details.
819 The built-in TFTP server is capable of many simultaneous file trans‐
822 fers: the absolute limit is related to the number of file-handles
823 allowed to a process and the ability of the select() system call to
824 cope with large numbers of file handles. If the limit is set too high
825 using --tftp-max it will be scaled down and the actual limit logged at
826 start-up. Note that more transfers are possible when the same file is
827 being sent than when each transfer sends a different file.
828 It is possible to use dnsmasq to block Web advertising by using a list
831 of known banner-ad servers, all resolving to 127.0.0.1 or 0.0.0.0, in
832 /etc/hosts or an additional hosts file. The list can be very long, dns‐
833 masq has been tested successfully with one million names. That size
834 file needs a 1GHz processor and about 60Mb of RAM.
835
838 /etc/dnsmasq.conf
839 /usr/local/etc/dnsmasq.conf
841 /etc/resolv.conf
843 /etc/hosts
845 /etc/ethers
847 /var/lib/misc/dnsmasq.leases
849 /var/db/dnsmasq.leases
851 /var/run/dnsmasq.pid
853
855 hosts(5), resolver(5)
856
858 This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.
859 DNSMASQ(8)