3 dnsmasq \- A lightweight DHCP and caching DNS server.
9 is a lightweight DNS, TFTP and DHCP server. It is intended to provide
10 coupled DNS and DHCP service to a LAN.
12 Dnsmasq accepts DNS queries and either answers them from a small, local,
13 cache or forwards them to a real, recursive, DNS server. It loads the
14 contents of /etc/hosts so that local hostnames
15 which do not appear in the global DNS can be resolved and also answers
16 DNS queries for DHCP configured hosts.
18 The dnsmasq DHCP server supports static address assignments and multiple
19 networks. It automatically
20 sends a sensible default set of DHCP options, and can be configured to
21 send any desired set of DHCP options, including vendor-encapsulated
22 options. It includes a secure, read-only,
23 TFTP server to allow net/PXE boot of DHCP hosts and also supports BOOTP.
26 supports IPv6 for DNS and TFTP, but not DHCP.
28 Note that in general missing parameters are allowed and switch off
29 functions, for instance "--pid-file" disables writing a PID file. On
30 BSD, unless the GNU getopt library is linked, the long form of the
31 options does not work on the command line; it is still recognised in
32 the configuration file.
35 Read and syntax check configuration file(s). Exit with code 0 if all
36 is OK, or a non-zero code otherwise. Do not start up dnsmasq.
39 Don't read the hostnames in /etc/hosts.
41 .B \-H, --addn-hosts=<file>
42 Additional hosts file. Read the specified file as well as /etc/hosts. If -h is given, read
43 only the specified file. This option may be repeated for more than one
44 additional hosts file. If a directory is given, then read all the files contained in that directory.
46 .B \-E, --expand-hosts
47 Add the domain to simple names (without a period) in /etc/hosts
48 in the same way as for DHCP-derived names. Note that this does not
49 apply to domain names in cnames, PTR records, TXT records etc.
51 .B \-T, --local-ttl=<time>
52 When replying with information from /etc/hosts or the DHCP leases
53 file dnsmasq by default sets the time-to-live field to zero, meaning
54 that the requestor should not itself cache the information. This is
55 the correct thing to do in almost all situations. This option allows a
56 time-to-live (in seconds) to be given for these replies. This will
57 reduce the load on the server at the expense of clients using stale
58 data under some circumstances.
61 Negative replies from upstream servers normally contain time-to-live
62 information in SOA records which dnsmasq uses for caching. If the
63 replies from upstream servers omit this information, dnsmasq does not
64 cache the reply. This option gives a default value for time-to-live
65 (in seconds) which dnsmasq uses to cache negative replies even in
66 the absence of an SOA record.
69 Set a maximum TTL value that will be handed out to clients. The specified
70 maximum TTL will be given to clients instead of the true TTL value if it is
71 lower. The true TTL value is however kept in the cache to avoid flooding
72 the upstream DNS servers.
74 .B \-k, --keep-in-foreground
75 Do not go into the background at startup but otherwise run as
76 normal. This is intended for use when dnsmasq is run under daemontools
80 Debug mode: don't fork to the background, don't write a pid file,
81 don't change user id, generate a complete cache dump on receipt on
82 SIGUSR1, log to stderr as well as syslog, don't fork new processes
83 to handle TCP queries.
86 Log the results of DNS queries handled by dnsmasq. Enable a full cache dump on receipt of SIGUSR1.
88 .B \-8, --log-facility=<facility>
89 Set the facility to which dnsmasq will send syslog entries, this
90 defaults to DAEMON, and to LOCAL0 when debug mode is in operation. If
91 the facility given contains at least one '/' character, it is taken to
92 be a filename, and dnsmasq logs to the given file, instead of
93 syslog. If the facility is '-' then dnsmasq logs to stderr.
94 (Errors whilst reading configuration will still go to syslog,
95 but all output from a successful startup, and all output whilst
96 running, will go exclusively to the file.) When logging to a file,
97 dnsmasq will close and reopen the file when it receives SIGUSR2. This
98 allows the log file to be rotated without stopping dnsmasq.
100 .B --log-async[=<lines>]
101 Enable asynchronous logging and optionally set the limit on the
103 which will be queued by dnsmasq when writing to the syslog is slow.
104 Dnsmasq can log asynchronously: this
105 allows it to continue functioning without being blocked by syslog, and
106 allows syslog to use dnsmasq for DNS queries without risking deadlock.
107 If the queue of log-lines becomes full, dnsmasq will log the
108 overflow, and the number of messages lost. The default queue length is
109 5, a sane value would be 5-25, and a maximum limit of 100 is imposed.
111 .B \-x, --pid-file=<path>
112 Specify an alternate path for dnsmasq to record its process-id in. Normally /var/run/dnsmasq.pid.
114 .B \-u, --user=<username>
115 Specify the userid to which dnsmasq will change after startup. Dnsmasq must normally be started as root, but it will drop root
116 privileges after startup by changing id to another user. Normally this user is "nobody" but that
117 can be over-ridden with this switch.
119 .B \-g, --group=<groupname>
120 Specify the group which dnsmasq will run
121 as. The defaults to "dip", if available, to facilitate access to
122 /etc/ppp/resolv.conf which is not normally world readable.
125 Print the version number.
127 .B \-p, --port=<port>
128 Listen on <port> instead of the standard DNS port (53). Setting this
129 to zero completely disables DNS function, leaving only DHCP and/or TFTP.
131 .B \-P, --edns-packet-max=<size>
132 Specify the largest EDNS.0 UDP packet which is supported by the DNS
133 forwarder. Defaults to 4096, which is the RFC5625-recommended size.
135 .B \-Q, --query-port=<query_port>
136 Send outbound DNS queries from, and listen for their replies on, the
137 specific UDP port <query_port> instead of using random ports. NOTE
138 that using this option will make dnsmasq less secure against DNS
139 spoofing attacks but it may be faster and use less resources. Setting this option
140 to zero makes dnsmasq use a single port allocated to it by the
141 OS: this was the default behaviour in versions prior to 2.43.
144 Do not use ports less than that given as source for outbound DNS
145 queries. Dnsmasq picks random ports as source for outbound queries:
146 when this option is given, the ports used will always to larger
147 than that specified. Useful for systems behind firewalls.
149 .B \-i, --interface=<interface name>
150 Listen only on the specified interface(s). Dnsmasq automatically adds
151 the loopback (local) interface to the list of interfaces to use when
154 option is used. If no
158 options are given dnsmasq listens on all available interfaces except any
160 .B \--except-interface
161 options. IP alias interfaces (eg "eth1:0") cannot be used with
164 .B --except-interface
165 options, use --listen-address instead.
167 .B \-I, --except-interface=<interface name>
168 Do not listen on the specified interface. Note that the order of
172 .B --except-interface
173 options does not matter and that
174 .B --except-interface
175 options always override the others.
177 .B \-2, --no-dhcp-interface=<interface name>
178 Do not provide DHCP or TFTP on the specified interface, but do provide DNS service.
180 .B \-a, --listen-address=<ipaddr>
181 Listen on the given IP address(es). Both
185 options may be given, in which case the set of both interfaces and
186 addresses is used. Note that if no
190 is, dnsmasq will not automatically listen on the loopback
191 interface. To achieve this, its IP address, 127.0.0.1, must be
192 explicitly given as a
196 .B \-z, --bind-interfaces
197 On systems which support it, dnsmasq binds the wildcard address,
198 even when it is listening on only some interfaces. It then discards
199 requests that it shouldn't reply to. This has the advantage of
200 working even when interfaces come and go and change address. This
201 option forces dnsmasq to really bind only the interfaces it is
202 listening on. About the only time when this is useful is when
203 running another nameserver (or another instance of dnsmasq) on the
204 same machine. Setting this option also enables multiple instances of
205 dnsmasq which provide DHCP service to run in the same machine.
207 .B \-y, --localise-queries
208 Return answers to DNS queries from /etc/hosts which depend on the interface over which the query was
209 received. If a name in /etc/hosts has more than one address associated with
210 it, and at least one of those addresses is on the same subnet as the
211 interface to which the query was sent, then return only the
212 address(es) on that subnet. This allows for a server to have multiple
213 addresses in /etc/hosts corresponding to each of its interfaces, and
214 hosts will get the correct address based on which network they are
215 attached to. Currently this facility is limited to IPv4.
218 Bogus private reverse lookups. All reverse lookups for private IP ranges (ie 192.168.x.x, etc)
219 which are not found in /etc/hosts or the DHCP leases file are answered
220 with "no such domain" rather than being forwarded upstream.
222 .B \-V, --alias=[<old-ip>]|[<start-ip>-<end-ip>],<new-ip>[,<mask>]
223 Modify IPv4 addresses returned from upstream nameservers; old-ip is
224 replaced by new-ip. If the optional mask is given then any address
225 which matches the masked old-ip will be re-written. So, for instance
226 .B --alias=1.2.3.0,6.7.8.0,255.255.255.0
227 will map 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. This is what
228 Cisco PIX routers call "DNS doctoring". If the old IP is given as
229 range, then only addresses in the range, rather than a whole subnet,
231 .B --alias=192.168.0.10-192.168.0.40,10.0.0.0,255.255.255.0
232 maps 192.168.0.10->192.168.0.40 to 10.0.0.10->10.0.0.40
234 .B \-B, --bogus-nxdomain=<ipaddr>
235 Transform replies which contain the IP address given into "No such
236 domain" replies. This is intended to counteract a devious move made by
237 Verisign in September 2003 when they started returning the address of
238 an advertising web page in response to queries for unregistered names,
239 instead of the correct NXDOMAIN response. This option tells dnsmasq to
240 fake the correct response when it sees this behaviour. As at Sept 2003
241 the IP address being returned by Verisign is 64.94.110.11
243 .B \-f, --filterwin2k
244 Later versions of windows make periodic DNS requests which don't get sensible answers from
245 the public DNS and can cause problems by triggering dial-on-demand links. This flag turns on an option
246 to filter such requests. The requests blocked are for records of types SOA and SRV, and type ANY where the
247 requested name has underscores, to catch LDAP requests.
249 .B \-r, --resolv-file=<file>
250 Read the IP addresses of the upstream nameservers from <file>, instead of
251 /etc/resolv.conf. For the format of this file see
253 the only lines relevant to dnsmasq are nameserver ones. Dnsmasq can
254 be told to poll more than one resolv.conf file, the first file name specified
255 overrides the default, subsequent ones add to the list. This is only
256 allowed when polling; the file with the currently latest modification
257 time is the one used.
260 Don't read /etc/resolv.conf. Get upstream servers only from the command
261 line or the dnsmasq configuration file.
263 .B \-1, --enable-dbus
264 Allow dnsmasq configuration to be updated via DBus method calls. The
265 configuration which can be changed is upstream DNS servers (and
266 corresponding domains) and cache clear. Requires that dnsmasq has
267 been built with DBus support.
269 .B \-o, --strict-order
270 By default, dnsmasq will send queries to any of the upstream servers
271 it knows about and tries to favour servers that are known to
272 be up. Setting this flag forces dnsmasq to try each query with each
273 server strictly in the order they appear in /etc/resolv.conf
276 By default, when dnsmasq has more than one upstream server available,
277 it will send queries to just one server. Setting this flag forces
278 dnsmasq to send all queries to all available servers. The reply from
279 the server which answers first will be returned to the original requestor.
282 Reject (and log) addresses from upstream nameservers which are in the
283 private IP ranges. This blocks an attack where a browser behind a
284 firewall is used to probe machines on the local network.
286 .B --rebind-localhost-ok
287 Exempt 127.0.0.0/8 from rebinding checks. This address range is
288 returned by realtime black hole servers, so blocking it may disable
291 .B --rebind-domain-ok=[<domain>]|[[/<domain>/[<domain>/]
292 Do not detect and block dns-rebind on queries to these domains. The
293 argument may be either a single domain, or multiple domains surrounded
294 by '/', like the --server syntax, eg.
295 .B --rebind-domain-ok=/domain1/domain2/domain3/
298 Don't poll /etc/resolv.conf for changes.
301 Whenever /etc/resolv.conf is re-read, clear the DNS cache.
302 This is useful when new nameservers may have different
303 data than that held in cache.
305 .B \-D, --domain-needed
306 Tells dnsmasq to never forward queries for plain names, without dots
307 or domain parts, to upstream nameservers. If the name is not known
308 from /etc/hosts or DHCP then a "not found" answer is returned.
310 .B \-S, --local, --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>][@<source-ip>|<interface>[#<port>]]
311 Specify IP address of upstream servers directly. Setting this flag does
312 not suppress reading of /etc/resolv.conf, use -R to do that. If one or
314 optional domains are given, that server is used only for those domains
315 and they are queried only using the specified server. This is
316 intended for private nameservers: if you have a nameserver on your
317 network which deals with names of the form
318 xxx.internal.thekelleys.org.uk at 192.168.1.1 then giving the flag
319 .B -S /internal.thekelleys.org.uk/192.168.1.1
320 will send all queries for
321 internal machines to that nameserver, everything else will go to the
322 servers in /etc/resolv.conf. An empty domain specification,
324 has the special meaning of "unqualified names only" ie names without any
325 dots in them. A non-standard port may be specified as
327 address using a # character.
328 More than one -S flag is allowed, with
329 repeated domain or ipaddr parts as required.
331 More specific domains take precendence over less specific domains, so:
332 .B --server=/google.com/1.2.3.4
333 .B --server=/www.google.com/2.3.4.5
334 will send queries for *.google.com to 1.2.3.4, except *www.google.com,
335 which will go to 2.3.4.5
337 The special server address '#' means, "use the standard servers", so
338 .B --server=/google.com/1.2.3.4
339 .B --server=/www.google.com/#
340 will send queries for *.google.com to 1.2.3.4, except *www.google.com which will
341 be forwarded as usual.
343 Also permitted is a -S
344 flag which gives a domain but no IP address; this tells dnsmasq that
345 a domain is local and it may answer queries from /etc/hosts or DHCP
346 but should never forward queries on that domain to any upstream
351 to make configuration files clearer in this case.
353 The optional string after the @ character tells
354 dnsmasq how to set the source of the queries to this
355 nameserver. It should be an ip-address, which should belong to the machine on which
356 dnsmasq is running otherwise this server line will be logged and then
357 ignored, or an interface name. If an interface name is given, then
358 queries to the server will be forced via that interface; if an
359 ip-address is given then the source address of the queries will be set
361 The query-port flag is ignored for any servers which have a
362 source address specified but the port may be specified directly as
363 part of the source address. Forcing queries to an interface is not
364 implemented on all platforms supported by dnsmasq.
366 .B \-A, --address=/<domain>/[domain/]<ipaddr>
367 Specify an IP address to return for any host in the given domains.
368 Queries in the domains are never forwarded and always replied to
369 with the specified IP address which may be IPv4 or IPv6. To give
370 both IPv4 and IPv6 addresses for a domain, use repeated -A flags.
371 Note that /etc/hosts and DHCP leases override this for individual
372 names. A common use of this is to redirect the entire doubleclick.net
373 domain to some friendly local web server to avoid banner ads. The
374 domain specification works in the same was as for --server, with the
375 additional facility that /#/ matches any domain. Thus
376 --address=/#/1.2.3.4 will always return 1.2.3.4 for any query not
377 answered from /etc/hosts or DHCP and not sent to an upstream
378 nameserver by a more specific --server directive.
380 .B \-m, --mx-host=<mx name>[[,<hostname>],<preference>]
381 Return an MX record named <mx name> pointing to the given hostname (if
383 the host specified in the --mx-target switch
384 or, if that switch is not given, the host on which dnsmasq
385 is running. The default is useful for directing mail from systems on a LAN
386 to a central server. The preference value is optional, and defaults to
387 1 if not given. More than one MX record may be given for a host.
389 .B \-t, --mx-target=<hostname>
390 Specify the default target for the MX record returned by dnsmasq. See
391 --mx-host. If --mx-target is given, but not --mx-host, then dnsmasq
392 returns a MX record containing the MX target for MX queries on the
393 hostname of the machine on which dnsmasq is running.
396 Return an MX record pointing to itself for each local
397 machine. Local machines are those in /etc/hosts or with DHCP leases.
400 Return an MX record pointing to the host given by mx-target (or the
401 machine on which dnsmasq is running) for each
402 local machine. Local machines are those in /etc/hosts or with DHCP
405 .B \-W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<priority>[,<weight>]]]]
406 Return a SRV DNS record. See RFC2782 for details. If not supplied, the
407 domain defaults to that given by
409 The default for the target domain is empty, and the default for port
410 is one and the defaults for
411 weight and priority are zero. Be careful if transposing data from BIND
412 zone files: the port, weight and priority numbers are in a different
413 order. More than one SRV record for a given service/domain is allowed,
414 all that match are returned.
416 .B \-Y, --txt-record=<name>[[,<text>],<text>]
417 Return a TXT DNS record. The value of TXT record is a set of strings,
418 so any number may be included, delimited by commas; use quotes to put
419 commas into a string. Note that the maximum length of a single string
420 is 255 characters, longer strings are split into 255 character chunks.
422 .B --ptr-record=<name>[,<target>]
423 Return a PTR DNS record.
425 .B --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<regexp>[,<replacement>]
426 Return an NAPTR DNS record, as specified in RFC3403.
428 .B --cname=<cname>,<target>
429 Return a CNAME record which indicates that <cname> is really
430 <target>. There are significant limitations on the target; it must be a
431 DNS name which is known to dnsmasq from /etc/hosts (or additional
432 hosts files) or from DHCP. If the target does not satisfy this
433 criteria, the whole cname is ignored. The cname must be unique, but it
434 is permissable to have more than one cname pointing to the same target.
436 .B --interface-name=<name>,<interface>
437 Return a DNS record associating the name with the primary address on
438 the given interface. This flag specifies an A record for the given
439 name in the same way as an /etc/hosts line, except that the address is
440 not constant, but taken from the given interface. If the interface is
441 down, not configured or non-existent, an empty record is returned. The
442 matching PTR record is also created, mapping the interface address to
443 the name. More than one name may be associated with an interface
444 address by repeating the flag; in that case the first instance is used
445 for the reverse address-to-name mapping.
448 Add the MAC address of the requestor to DNS queries which are
449 forwarded upstream. This may be used to DNS filtering by the upstream
450 server. The MAC address can only be added if the requestor is on the same
451 subnet as the dnsmasq server. Note that the mechanism used to achieve this (an EDNS0 option)
452 is not yet standardised, so this should be considered
453 experimental. Also note that exposing MAC addresses in this way may
454 have security and privacy implications.
456 .B \-c, --cache-size=<cachesize>
457 Set the size of dnsmasq's cache. The default is 150 names. Setting the cache size to zero disables caching.
459 .B \-N, --no-negcache
460 Disable negative caching. Negative caching allows dnsmasq to remember
461 "no such domain" answers from upstream nameservers and answer
462 identical queries without forwarding them again.
464 .B \-0, --dns-forward-max=<queries>
465 Set the maximum number of concurrent DNS queries. The default value is
466 150, which should be fine for most setups. The only known situation
467 where this needs to be increased is when using web-server log file
468 resolvers, which can generate large numbers of concurrent queries.
471 A resolver on a client machine can do DNSSEC validation in two ways: it
472 can perform the cryptograhic operations on the reply it receives, or
473 it can rely on the upstream recursive nameserver to do the validation
474 and set a bit in the reply if it succeeds. Dnsmasq is not a DNSSEC
475 validator, so it cannot perform the validation role of the recursive nameserver,
476 but it can pass through the validation results from its own upstream
477 nameservers. This option enables this behaviour. You should only do
478 this if you trust all the configured upstream nameservers
479 .I and the network between you and them.
480 If you use the first DNSSEC mode, validating resolvers in clients,
481 this option is not required. Dnsmasq always returns all the data
482 needed for a client to do validation itself.
484 .B \-F, --dhcp-range=[interface:<interface>,][tag:<tag>[,tag:<tag>],][set:<tag],]<start-addr>,<end-addr>[,<netmask>[,<broadcast>]][,<lease time>]
485 Enable the DHCP server. Addresses will be given out from the range
486 <start-addr> to <end-addr> and from statically defined addresses given
489 options. If the lease time is given, then leases
490 will be given for that length of time. The lease time is in seconds,
491 or minutes (eg 45m) or hours (eg 1h) or "infinite". If not given,
492 the default lease time is one hour. The
493 minimum lease time is two minutes. This
494 option may be repeated, with different addresses, to enable DHCP
495 service to more than one network. For directly connected networks (ie,
496 networks on which the machine running dnsmasq has an interface) the
497 netmask is optional. It is, however, required for networks which
498 receive DHCP service via a relay agent. The broadcast address is
499 always optional. It is always
500 allowed to have more than one dhcp-range in a single subnet.
504 sets an alphanumeric label which marks this network so that
505 dhcp options may be specified on a per-network basis.
506 When it is prefixed with 'tag:' instead, then its meaning changes from setting
507 a tag to matching it. Only one tag may be set, but more than one tag may be matched.
508 The end address may be replaced by the keyword
510 which tells dnsmasq to enable DHCP for the network specified, but not
511 to dynamically allocate IP addresses: only hosts which have static
514 or from /etc/ethers will be served. The end address may be replaced by
517 in which case dnsmasq will provide proxy-DHCP on the specified
524 The interface:<interface name> section is not normally used. See the
525 NOTES section for details of this.
527 .B \-G, --dhcp-host=[<hwaddr>][,id:<client_id>|*][,set:<tag>][,<ipaddr>][,<hostname>][,<lease_time>][,ignore]
528 Specify per host parameters for the DHCP server. This allows a machine
529 with a particular hardware address to be always allocated the same
530 hostname, IP address and lease time. A hostname specified like this
531 overrides any supplied by the DHCP client on the machine. It is also
532 allowable to ommit the hardware address and include the hostname, in
533 which case the IP address and lease times will apply to any machine
534 claiming that name. For example
535 .B --dhcp-host=00:20:e0:3b:13:af,wap,infinite
536 tells dnsmasq to give
537 the machine with hardware address 00:20:e0:3b:13:af the name wap, and
538 an infinite DHCP lease.
539 .B --dhcp-host=lap,192.168.0.199
541 dnsmasq to always allocate the machine lap the IP address
544 Addresses allocated like this are not constrained to be
545 in the range given by the --dhcp-range option, but they must be in
546 the same subnet as some valid dhcp-range. For
547 subnets which don't need a pool of dynamically allocated addresses,
548 use the "static" keyword in the dhcp-range declaration.
550 It is allowed to use client identifiers rather than
551 hardware addresses to identify hosts by prefixing with 'id:'. Thus:
552 .B --dhcp-host=id:01:02:03:04,.....
553 refers to the host with client identifier 01:02:03:04. It is also
554 allowed to specify the client ID as text, like this:
555 .B --dhcp-host=id:clientidastext,.....
557 The special option id:* means "ignore any client-id
558 and use MAC addresses only." This is useful when a client presents a client-id sometimes
561 If a name appears in /etc/hosts, the associated address can be
562 allocated to a DHCP lease, but only if a
564 option specifying the name also exists. Only one hostname can be
567 option, but aliases are possible by using CNAMEs. (See
571 The special keyword "ignore"
572 tells dnsmasq to never offer a DHCP lease to a machine. The machine
573 can be specified by hardware address, client ID or hostname, for
575 .B --dhcp-host=00:20:e0:3b:13:af,ignore
577 useful when there is another DHCP server on the network which should
578 be used by some machines.
580 The set:<tag> contruct sets the tag
581 whenever this dhcp-host directive is in use. This can be used to
582 selectively send DHCP options just for this host. More than one tag
583 can be set in a dhcp-host directive (but not in other places where
584 "set:<tag>" is allowed). When a host matches any
585 dhcp-host directive (or one implied by /etc/ethers) then the special
586 tag "known" is set. This allows dnsmasq to be configured to
587 ignore requests from unknown machines using
588 .B --dhcp-ignore=tag:!known
589 Ethernet addresses (but not client-ids) may have
590 wildcard bytes, so for example
591 .B --dhcp-host=00:20:e0:3b:13:*,ignore
592 will cause dnsmasq to ignore a range of hardware addresses. Note that
593 the "*" will need to be escaped or quoted on a command line, but not
594 in the configuration file.
596 Hardware addresses normally match any
597 network (ARP) type, but it is possible to restrict them to a single
598 ARP type by preceding them with the ARP-type (in HEX) and "-". so
599 .B --dhcp-host=06-00:20:e0:3b:13:af,1.2.3.4
601 Token-Ring hardware address, since the ARP-address type for token ring
604 As a special case, it is possible to include more than one
605 hardware address. eg:
606 .B --dhcp-host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2
607 This allows an IP address to be associated with
608 multiple hardware addresses, and gives dnsmasq permission to abandon a
609 DHCP lease to one of the hardware addresses when another one asks for
610 a lease. Beware that this is a dangerous thing to do, it will only
611 work reliably if only one of the hardware addresses is active at any
612 time and there is no way for dnsmasq to enforce this. It is, for instance,
613 useful to allocate a stable IP address to a laptop which
614 has both wired and wireless interfaces.
616 .B --dhcp-hostsfile=<path>
617 Read DHCP host information from the specified file. If a directory
618 is given, then read all the files contained in that directory. The file contains
619 information about one host per line. The format of a line is the same
620 as text to the right of '=' in --dhcp-host. The advantage of storing DHCP host information
621 in this file is that it can be changed without re-starting dnsmasq:
622 the file will be re-read when dnsmasq receives SIGHUP.
624 .B --dhcp-optsfile=<path>
625 Read DHCP option information from the specified file. If a directory
626 is given, then read all the files contained in that directory. The advantage of
627 using this option is the same as for --dhcp-hostsfile: the
628 dhcp-optsfile will be re-read when dnsmasq receives SIGHUP. Note that
629 it is possible to encode the information in a
631 flag as DHCP options, using the options names bootfile-name,
632 server-ip-address and tftp-server. This allows these to be included
635 .B \-Z, --read-ethers
636 Read /etc/ethers for information about hosts for the DHCP server. The
637 format of /etc/ethers is a hardware address, followed by either a
638 hostname or dotted-quad IP address. When read by dnsmasq these lines
639 have exactly the same effect as
641 options containing the same information. /etc/ethers is re-read when
642 dnsmasq receives SIGHUP.
644 .B \-O, --dhcp-option=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<enterprise>,][vendor:[<vendor-class>],][<opt>|option:<opt-name>],[<value>[,<value>]]
645 Specify different or extra options to DHCP clients. By default,
646 dnsmasq sends some standard options to DHCP clients, the netmask and
647 broadcast address are set to the same as the host running dnsmasq, and
648 the DNS server and default route are set to the address of the machine
649 running dnsmasq. If the domain name option has been set, that is sent.
650 This configuration allows these defaults to be overridden,
651 or other options specified. The option, to be sent may be given as a
652 decimal number or as "option:<option-name>" The option numbers are
653 specified in RFC2132 and subsequent RFCs. The set of option-names
654 known by dnsmasq can be discovered by running "dnsmasq --help dhcp".
655 For example, to set the default route option to
657 .B --dhcp-option=3,192.168.4.4
659 .B --dhcp-option = option:router, 192.168.4.4
660 and to set the time-server address to 192.168.0.4, do
661 .B --dhcp-option = 42,192.168.0.4
663 .B --dhcp-option = option:ntp-server, 192.168.0.4
664 The special address 0.0.0.0 is taken to mean "the address of the
665 machine running dnsmasq". Data types allowed are comma separated
666 dotted-quad IP addresses, a decimal number, colon-separated hex digits
667 and a text string. If the optional tags are given then
668 this option is only sent when all the tags are matched.
670 Special processing is done on a text argument for option 119, to
671 conform with RFC 3397. Text or dotted-quad IP addresses as arguments
672 to option 120 are handled as per RFC 3361. Dotted-quad IP addresses
673 which are followed by a slash and then a netmask size are encoded as
674 described in RFC 3442.
676 Be careful: no checking is done that the correct type of data for the
677 option number is sent, it is quite possible to
678 persuade dnsmasq to generate illegal DHCP packets with injudicious use
679 of this flag. When the value is a decimal number, dnsmasq must determine how
680 large the data item is. It does this by examining the option number and/or the
681 value, but can be overridden by appending a single letter flag as follows:
682 b = one byte, s = two bytes, i = four bytes. This is mainly useful with
683 encapsulated vendor class options (see below) where dnsmasq cannot
684 determine data size from the option number. Option data which
685 consists solely of periods and digits will be interpreted by dnsmasq
686 as an IP address, and inserted into an option as such. To force a
687 literal string, use quotes. For instance when using option 66 to send
688 a literal IP address as TFTP server name, it is necessary to do
689 .B --dhcp-option=66,"1.2.3.4"
691 Encapsulated Vendor-class options may also be specified using
692 --dhcp-option: for instance
693 .B --dhcp-option=vendor:PXEClient,1,0.0.0.0
694 sends the encapsulated vendor
695 class-specific option "mftp-address=0.0.0.0" to any client whose
696 vendor-class matches "PXEClient". The vendor-class matching is
697 substring based (see --dhcp-vendorclass for details). If a
698 vendor-class option (number 60) is sent by dnsmasq, then that is used
699 for selecting encapsulated options in preference to any sent by the
701 possible to omit the vendorclass completely;
702 .B --dhcp-option=vendor:,1,0.0.0.0
703 in which case the encapsulated option is always sent.
705 Options may be encapsulated within other options: for instance
706 .B --dhcp-option=encap:175, 190, "iscsi-client0"
707 will send option 175, within which is the option 190. If multiple
708 options are given which are encapsulated with the same option number
709 then they will be correctly combined into one encapsulated option.
710 encap: and vendor: are may not both be set in the same dhcp-option.
712 The final variant on encapsulated options is "Vendor-Identifying
713 Vendor Options" as specified by RFC3925. These are denoted like this:
714 .B --dhcp-option=vi-encap:2, 10, "text"
715 The number in the vi-encap: section is the IANA enterprise number
716 used to identify this option.
718 The address 0.0.0.0 is not treated specially in
719 encapsulated options.
721 .B --dhcp-option-force=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<enterprise>,][vendor:[<vendor-class>],]<opt>,[<value>[,<value>]]
722 This works in exactly the same way as
724 except that the option will always be sent, even if the client does
725 not ask for it in the parameter request list. This is sometimes
726 needed, for example when sending options to PXELinux.
728 .B --dhcp-no-override
729 Disable re-use of the DHCP servername and filename fields as extra
730 option space. If it can, dnsmasq moves the boot server and filename
731 information (from dhcp-boot) out of their dedicated fields into
732 DHCP options. This make extra space available in the DHCP packet for
733 options but can, rarely, confuse old or broken clients. This flag
734 forces "simple and safe" behaviour to avoid problems in such a case.
736 .B \-U, --dhcp-vendorclass=set:<tag>,<vendor-class>
737 Map from a vendor-class string to a tag. Most DHCP clients provide a
738 "vendor class" which represents, in some sense, the type of host. This option
739 maps vendor classes to tags, so that DHCP options may be selectively delivered
740 to different classes of hosts. For example
741 .B dhcp-vendorclass=set:printers,Hewlett-Packard JetDirect
742 will allow options to be set only for HP printers like so:
743 .B --dhcp-option=tag:printers,3,192.168.4.4
744 The vendor-class string is
745 substring matched against the vendor-class supplied by the client, to
746 allow fuzzy matching. The set: prefix is optional but allowed for consistency.
748 .B \-j, --dhcp-userclass=set:<tag>,<user-class>
749 Map from a user-class string to a tag (with substring
750 matching, like vendor classes). Most DHCP clients provide a
751 "user class" which is configurable. This option
752 maps user classes to tags, so that DHCP options may be selectively delivered
753 to different classes of hosts. It is possible, for instance to use
754 this to set a different printer server for hosts in the class
755 "accounts" than for hosts in the class "engineering".
757 .B \-4, --dhcp-mac=set:<tag>,<MAC address>
758 Map from a MAC address to a tag. The MAC address may include
759 wildcards. For example
760 .B --dhcp-mac=set:3com,01:34:23:*:*:*
761 will set the tag "3com" for any host whose MAC address matches the pattern.
763 .B --dhcp-circuitid=set:<tag>,<circuit-id>, --dhcp-remoteid=set:<tag>,<remote-id>
764 Map from RFC3046 relay agent options to tags. This data may
765 be provided by DHCP relay agents. The circuit-id or remote-id is
766 normally given as colon-separated hex, but is also allowed to be a
767 simple string. If an exact match is achieved between the circuit or
768 agent ID and one provided by a relay agent, the tag is set.
770 .B --dhcp-subscrid=set:<tag>,<subscriber-id>
771 Map from RFC3993 subscriber-id relay agent options to tags.
773 .B --dhcp-proxy[=<ip addr>]......
774 A normal DHCP relay agent is only used to forward the initial parts of
775 a DHCP interaction to the DHCP server. Once a client is configured, it
776 communicates directly with the server. This is undesirable if the
777 relay agent is addding extra information to the DHCP packets, such as
782 A full relay implementation can use the RFC 5107 serverid-override
783 option to force the DHCP server to use the relay as a full proxy, with all
784 packets passing through it. This flag provides an alternative method
785 of doing the same thing, for relays which don't support RFC
786 5107. Given alone, it manipulates the server-id for all interactions
787 via relays. If a list of IP addresses is given, only interactions via
788 relays at those addresses are affected.
790 .B --dhcp-match=set:<tag>,<option number>|option:<option name>|vi-encap:<enterprise>[,<value>]
791 Without a value, set the tag if the client sends a DHCP
792 option of the given number or name. When a value is given, set the tag only if
793 the option is sent and matches the value. The value may be of the form
794 "01:ff:*:02" in which case the value must match (apart from widcards)
795 but the option sent may have unmatched data past the end of the
796 value. The value may also be of the same form as in
798 in which case the option sent is treated as an array, and one element
801 --dhcp-match=set:efi-ia32,option:client-arch,6
803 will set the tag "efi-ia32" if the the number 6 appears in the list of
804 architectures sent by the client in option 93. (See RFC 4578 for
805 details.) If the value is a string, substring matching is used.
807 The special form with vi-encap:<enterpise number> matches against
808 vendor-identifying vendor classes for the specified enterprise. Please
809 see RFC 3925 for more details of these rare and interesting beasts.
811 .B --tag-if=set:<tag>[,set:<tag>[,tag:<tag>[,tag:<tag>]]]
812 Perform boolean operations on tags. Any tag appearing as set:<tag> is set if
813 all the tags which appear as tag:<tag> are set, (or unset when tag:!<tag> is used)
814 If no tag:<tag> appears set:<tag> tags are set unconditionally.
815 Any number of set: and tag: forms may appear, in any order.
816 Tag-if lines ares executed in order, so if the tag in tag:<tag> is a
819 the line which sets the tag must precede the one which tests it.
821 .B \-J, --dhcp-ignore=tag:<tag>[,tag:<tag>]
822 When all the given tags appear in the tag set ignore the host and do
823 not allocate it a DHCP lease.
825 .B --dhcp-ignore-names[=tag:<tag>[,tag:<tag>]]
826 When all the given tags appear in the tag set, ignore any hostname
827 provided by the host. Note that, unlike dhcp-ignore, it is permissible
828 to supply no tags, in which case DHCP-client supplied hostnames
829 are always ignored, and DHCP hosts are added to the DNS using only
830 dhcp-host configuration in dnsmasq and the contents of /etc/hosts and
833 .B --dhcp-generate-names=tag:<tag>[,tag:<tag>]
834 Generate a name for DHCP clients which do not otherwise have one,
835 using the MAC address expressed in hex, seperated by dashes. Note that
836 if a host provides a name, it will be used by preference to this,
838 .B --dhcp-ignore-names
841 .B --dhcp-broadcast[=tag:<tag>[,tag:<tag>]]
842 When all the given tags appear in the tag set, always use broadcast to
843 communicate with the host when it is unconfigured. It is permissible
844 to supply no tags, in which case this is unconditional. Most DHCP clients which
845 need broadcast replies set a flag in their requests so that this
846 happens automatically, some old BOOTP clients do not.
848 .B \-M, --dhcp-boot=[tag:<tag>,]<filename>,[<servername>[,<server address>]]
849 Set BOOTP options to be returned by the DHCP server. Server name and
850 address are optional: if not provided, the name is left empty, and the
851 address set to the address of the machine running dnsmasq. If dnsmasq
852 is providing a TFTP service (see
854 ) then only the filename is required here to enable network booting.
855 If the optional tag(s) are given,
856 they must match for this configuration to be sent.
858 .B --pxe-service=[tag:<tag>,]<CSA>,<menu text>[,<basename>|<bootservicetype>][,<server address>]
859 Most uses of PXE boot-ROMS simply allow the PXE
860 system to obtain an IP address and then download the file specified by
862 and execute it. However the PXE system is capable of more complex
863 functions when supported by a suitable DHCP server.
865 This specifies a boot option which may appear in a PXE boot menu. <CSA> is
866 client system type, only services of the correct type will appear in a
867 menu. The known types are x86PC, PC98, IA64_EFI, Alpha, Arc_x86,
868 Intel_Lean_Client, IA32_EFI, BC_EFI, Xscale_EFI and X86-64_EFI; an
869 integer may be used for other types. The
870 parameter after the menu text may be a file name, in which case dnsmasq acts as a
871 boot server and directs the PXE client to download the file by TFTP,
874 must be set for this to work) or another TFTP server if the final IP
876 Note that the "layer"
877 suffix (normally ".0") is supplied by PXE, and should not be added to
878 the basename. If an integer boot service type, rather than a basename
879 is given, then the PXE client will search for a
880 suitable boot service for that type on the network. This search may be done
881 by broadcast, or direct to a server if its IP address is provided.
882 If no boot service type or filename is provided (or a boot service type of 0 is specified)
883 then the menu entry will abort the net boot procedure and
884 continue booting from local media.
886 .B --pxe-prompt=[tag:<tag>,]<prompt>[,<timeout>]
887 Setting this provides a prompt to be displayed after PXE boot. If the
888 timeout is given then after the
889 timeout has elapsed with no keyboard input, the first available menu
890 option will be automatically executed. If the timeout is zero then the first available menu
891 item will be executed immediately. If
893 is ommitted the system will wait for user input if there are multiple
894 items in the menu, but boot immediately if
895 there is only one. See
897 for details of menu items.
899 Dnsmasq supports PXE "proxy-DHCP", in this case another DHCP server on
900 the network is responsible for allocating IP addresses, and dnsmasq
901 simply provides the information given in
905 to allow netbooting. This mode is enabled using the
910 .B \-X, --dhcp-lease-max=<number>
911 Limits dnsmasq to the specified maximum number of DHCP leases. The
912 default is 1000. This limit is to prevent DoS attacks from hosts which
913 create thousands of leases and use lots of memory in the dnsmasq
916 .B \-K, --dhcp-authoritative
917 Should be set when dnsmasq is definitely the only DHCP server on a network.
918 It changes the behaviour from strict RFC compliance so that DHCP requests on
919 unknown leases from unknown hosts are not ignored. This allows new hosts
920 to get a lease without a tedious timeout under all circumstances. It also
921 allows dnsmasq to rebuild its lease database without each client needing to
922 reacquire a lease, if the database is lost.
924 .B --dhcp-alternate-port[=<server port>[,<client port>]]
925 Change the ports used for DHCP from the default. If this option is
926 given alone, without arguments, it changes the ports used for DHCP
927 from 67 and 68 to 1067 and 1068. If a single argument is given, that
928 port number is used for the server and the port number plus one used
929 for the client. Finally, two port numbers allows arbitrary
930 specification of both server and client ports for DHCP.
932 .B \-3, --bootp-dynamic[=<network-id>[,<network-id>]]
933 Enable dynamic allocation of IP addresses to BOOTP clients. Use this
934 with care, since each address allocated to a BOOTP client is leased
935 forever, and therefore becomes permanently unavailable for re-use by
936 other hosts. if this is given without tags, then it unconditionally
937 enables dynamic allocation. With tags, only when the tags are all
938 set. It may be repeated with different tag sets.
941 By default, the DHCP server will attempt to ensure that an address in
942 not in use before allocating it to a host. It does this by sending an
943 ICMP echo request (aka "ping") to the address in question. If it gets
944 a reply, then the address must already be in use, and another is
945 tried. This flag disables this check. Use with caution.
948 Extra logging for DHCP: log all the options sent to DHCP clients and
949 the tags used to determine them.
951 .B \-l, --dhcp-leasefile=<path>
952 Use the specified file to store DHCP lease information.
954 .B \-6 --dhcp-script=<path>
955 Whenever a new DHCP lease is created, or an old one destroyed, the
956 executable specified by this option is run. <path>
957 must be an absolute pathname, no PATH search occurs.
958 The arguments to the process
959 are "add", "old" or "del", the MAC
960 address of the host, the IP address, and the hostname,
961 if known. "add" means a lease has been created, "del" means it has
962 been destroyed, "old" is a notification of an existing lease when
963 dnsmasq starts or a change to MAC address or hostname of an existing
964 lease (also, lease length or expiry and client-id, if leasefile-ro is set).
965 If the MAC address is from a network type other than ethernet,
966 it will have the network type prepended, eg "06-01:23:45:67:89:ab" for
967 token ring. The process is run as root (assuming that dnsmasq was originally run as
968 root) even if dnsmasq is configured to change UID to an unprivileged user.
970 The environment is inherited from the invoker of dnsmasq, with some or
971 all of the following variables added.
973 DNSMASQ_CLIENT_ID if the host provided a client-id.
975 DNSMASQ_DOMAIN if the fully-qualified domain name of the host is
976 known, this is set to the domain part. (Note that the hostname passed
977 to the script as an argument is never fully-qualified.)
979 If the client provides vendor-class, hostname or user-class,
980 these are provided in DNSMASQ_VENDOR_CLASS
981 DNSMASQ_SUPPLIED_HOSTNAME and
982 DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn variables, but only for
983 "add" actions or "old" actions when a host resumes an existing lease,
984 since these data are not held in dnsmasq's lease
987 If dnsmasq was compiled with HAVE_BROKEN_RTC, then
988 the length of the lease (in seconds) is stored in
989 DNSMASQ_LEASE_LENGTH, otherwise the time of lease expiry is stored in
990 DNSMASQ_LEASE_EXPIRES. The number of seconds until lease expiry is
991 always stored in DNSMASQ_TIME_REMAINING.
993 If a lease used to have a hostname, which is
994 removed, an "old" event is generated with the new state of the lease,
995 ie no name, and the former name is provided in the environment
996 variable DNSMASQ_OLD_HOSTNAME.
998 DNSMASQ_INTERFACE stores the name of
999 the interface on which the request arrived; this is not set for "old"
1000 actions when dnsmasq restarts.
1002 DNSMASQ_RELAY_ADDRESS is set if the client
1003 used a DHCP relay to contact dnsmasq and the IP address of the relay
1006 DNSMASQ_TAGS contains all the tags set during the
1007 DHCP transaction, separated by spaces.
1009 All file descriptors are
1010 closed except stdin, stdout and stderr which are open to /dev/null
1011 (except in debug mode).
1013 The script is not invoked concurrently: at most one instance
1014 of the script is ever running (dnsmasq waits for an instance of script to exit
1015 before running the next). Changes to the lease database are which
1016 require the script to be invoked are queued awaiting exit of a running instance.
1017 If this queueing allows multiple state changes occur to a single
1018 lease before the script can be run then
1019 earlier states are discarded and the current state of that lease is
1020 reflected when the script finally runs.
1022 At dnsmasq startup, the script will be invoked for
1023 all existing leases as they are read from the lease file. Expired
1024 leases will be called with "del" and others with "old". When dnsmasq
1025 receives a HUP signal, the script will be invoked for existing leases
1026 with an "old " event.
1028 .B --dhcp-scriptuser
1029 Specify the user as which to run the lease-change script. This defaults to root, but can be changed to another user using this flag.
1031 .B \-9, --leasefile-ro
1032 Completely suppress use of the lease database file. The file will not
1033 be created, read, or written. Change the way the lease-change
1034 script (if one is provided) is called, so that the lease database may
1035 be maintained in external storage by the script. In addition to the
1036 invocations given in
1038 the lease-change script is called once, at dnsmasq startup, with the
1039 single argument "init". When called like this the script should write
1040 the saved state of the lease database, in dnsmasq leasefile format, to
1041 stdout and exit with zero exit code. Setting this
1042 option also forces the leasechange script to be called on changes
1043 to the client-id and lease length and expiry time.
1045 .B --bridge-interface=<interface>,<alias>[,<alias>]
1046 Treat DHCP request packets arriving at any of the <alias> interfaces
1047 as if they had arrived at <interface>. This option is necessary when
1048 using "old style" bridging on BSD platforms, since
1049 packets arrive at tap interfaces which don't have an IP address.
1051 .B \-s, --domain=<domain>[,<address range>[,local]]
1052 Specifies DNS domains for the DHCP server. Domains may be be given
1053 unconditionally (without the IP range) or for limited IP ranges. This has two effects;
1054 firstly it causes the DHCP server to return the domain to any hosts
1055 which request it, and secondly it sets the domain which it is legal
1056 for DHCP-configured hosts to claim. The intention is to constrain
1057 hostnames so that an untrusted host on the LAN cannot advertise
1058 its name via dhcp as e.g. "microsoft.com" and capture traffic not
1059 meant for it. If no domain suffix is specified, then any DHCP
1060 hostname with a domain part (ie with a period) will be disallowed
1061 and logged. If suffix is specified, then hostnames with a domain
1062 part are allowed, provided the domain part matches the suffix. In
1063 addition, when a suffix is set then hostnames without a domain
1064 part have the suffix added as an optional domain part. Eg on my network I can set
1065 .B --domain=thekelleys.org.uk
1066 and have a machine whose DHCP hostname is "laptop". The IP address for that machine is available from
1068 both as "laptop" and "laptop.thekelleys.org.uk". If the domain is
1069 given as "#" then the domain is read from the first "search" directive
1070 in /etc/resolv.conf (or equivalent).
1072 The address range can be of the form
1073 <ip address>,<ip address> or <ip address>/<netmask> or just a single
1076 which can change the behaviour of dnsmasq with domains.
1078 If the address range is given as ip-address/network-size, then a
1079 additional flag "local" may be supplied which has the effect of adding
1080 --local declarations for forward and reverse DNS queries. Eg.
1081 .B --domain=thekelleys.org.uk,192.168.0.0/24,local
1083 .B --domain=thekelleys.org.uk,192.168.0.0/24
1084 --local=/thekelleys.org.uk/ --local=/0.168.192.in-addr.arpa/
1085 The network size must be 8, 16 or 24 for this to be legal.
1088 In the default mode, dnsmasq inserts the unqualified names of
1089 DHCP clients into the DNS. For this reason, the names must be unique,
1090 even if two clients which have the same name are in different
1091 domains. If a second DHCP client appears which has the same name as an
1092 existing client, the name is transfered to the new client. If
1094 is set, this behaviour changes: the unqualified name is no longer
1095 put in the DNS, only the qualified name. Two DHCP clients with the
1096 same name may both keep the name, provided that the domain part is
1097 different (ie the fully qualified names differ.) To ensure that all
1098 names have a domain part, there must be at least
1100 without an address specified when
1104 .B --enable-tftp[=<interface>]
1105 Enable the TFTP server function. This is deliberately limited to that
1106 needed to net-boot a client. Only reading is allowed; the tsize and
1107 blksize extensions are supported (tsize is only supported in octet
1108 mode). See NOTES section for use of the interface argument.
1111 .B --tftp-root=<directory>[,<interface>]
1112 Look for files to transfer using TFTP relative to the given
1113 directory. When this is set, TFTP paths which include ".." are
1114 rejected, to stop clients getting outside the specified root.
1115 Absolute paths (starting with /) are allowed, but they must be within
1116 the tftp-root. If the optional interface argument is given, the
1117 directory is only used for TFTP requests via that interface.
1119 .B --tftp-unique-root
1120 Add the IP address of the TFTP client as a path component on the end
1121 of the TFTP-root (in standard dotted-quad format). Only valid if a
1122 tftp-root is set and the directory exists. For instance, if tftp-root is "/tftp" and client
1123 1.2.3.4 requests file "myfile" then the effective path will be
1124 "/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4 exists or /tftp/myfile otherwise.
1127 Enable TFTP secure mode: without this, any file which is readable by
1128 the dnsmasq process under normal unix access-control rules is
1129 available via TFTP. When the --tftp-secure flag is given, only files
1130 owned by the user running the dnsmasq process are accessible. If
1131 dnsmasq is being run as root, different rules apply: --tftp-secure
1132 has no effect, but only files which have the world-readable bit set
1133 are accessible. It is not recommended to run dnsmasq as root with TFTP
1134 enabled, and certainly not without specifying --tftp-root. Doing so
1135 can expose any world-readable file on the server to any host on the net.
1137 .B --tftp-max=<connections>
1138 Set the maximum number of concurrent TFTP connections allowed. This
1139 defaults to 50. When serving a large number of TFTP connections,
1140 per-process file descriptor limits may be encountered. Dnsmasq needs
1141 one file descriptor for each concurrent TFTP connection and one
1142 file descriptor per unique file (plus a few others). So serving the
1143 same file simultaneously to n clients will use require about n + 10 file
1144 descriptors, serving different files simultaneously to n clients will
1145 require about (2*n) + 10 descriptors. If
1146 .B --tftp-port-range
1147 is given, that can affect the number of concurrent connections.
1149 .B --tftp-no-blocksize
1150 Stop the TFTP server from negotiating the "blocksize" option with a
1151 client. Some buggy clients request this option but then behave badly
1154 .B --tftp-port-range=<start>,<end>
1155 A TFTP server listens on a well-known port (69) for connection initiation,
1156 but it also uses a dynamically-allocated port for each
1157 connection. Normally these are allocated by the OS, but this option
1158 specifies a range of ports for use by TFTP transfers. This can be
1159 useful when TFTP has to traverse a firewall. The start of the range
1160 cannot be lower than 1025 unless dnsmasq is running as root. The number
1161 of concurrent TFTP connections is limited by the size of the port range.
1163 .B \-C, --conf-file=<file>
1164 Specify a different configuration file. The conf-file option is also allowed in
1165 configuration files, to include multiple configuration files. A
1166 filename of "-" causes dnsmasq to read configuration from stdin.
1168 .B \-7, --conf-dir=<directory>[,<file-extension>......]
1169 Read all the files in the given directory as configuration
1170 files. If extension(s) are given, any files which end in those
1171 extensions are skipped. Any files whose names end in ~ or start with . or start and end
1172 with # are always skipped. This flag may be given on the command
1173 line or in a configuration file.
1175 At startup, dnsmasq reads
1176 .I /etc/dnsmasq.conf,
1178 FreeBSD, the file is
1179 .I /usr/local/etc/dnsmasq.conf
1184 options.) The format of this
1185 file consists of one option per line, exactly as the long options detailed
1186 in the OPTIONS section but without the leading "--". Lines starting with # are comments and ignored. For
1187 options which may only be specified once, the configuration file overrides
1188 the command line. Quoting is allowed in a config file:
1189 between " quotes the special meanings of ,:. and # are removed and the
1190 following escapes are allowed: \\\\ \\" \\t \\e \\b \\r and \\n. The later
1191 corresponding to tab, escape, backspace, return and newline.
1193 When it receives a SIGHUP,
1195 clears its cache and then re-loads
1199 and any file given by --dhcp-hostsfile, --dhcp-optsfile or --addn-hosts.
1200 The dhcp lease change script is called for all
1201 existing DHCP leases. If
1204 is set SIGHUP also re-reads
1205 .I /etc/resolv.conf.
1207 does NOT re-read the configuration file.
1209 When it receives a SIGUSR1,
1211 writes statistics to the system log. It writes the cache size,
1212 the number of names which have had to removed from the cache before
1213 they expired in order to make room for new names and the total number
1214 of names that have been inserted into the cache. For each upstream
1215 server it gives the number of queries sent, and the number which
1216 resulted in an error. In
1218 mode or when full logging is enabled (-q), a complete dump of the
1219 contents of the cache is made.
1221 When it receives SIGUSR2 and it is logging direct to a file (see
1225 will close and reopen the log file. Note that during this operation,
1226 dnsmasq will not be running as root. When it first creates the logfile
1227 dnsmasq changes the ownership of the file to the non-root user it will run
1228 as. Logrotate should be configured to create a new log file with
1229 the ownership which matches the existing one before sending SIGUSR2.
1230 If TCP DNS queries are in progress, the old logfile will remain open in
1231 child processes which are handling TCP queries and may continue to be
1232 written. There is a limit of 150 seconds, after which all existing TCP
1233 processes will have expired: for this reason, it is not wise to
1234 configure logfile compression for logfiles which have just been
1235 rotated. Using logrotate, the required options are
1242 Dnsmasq is a DNS query forwarder: it it not capable of recursively
1243 answering arbitrary queries starting from the root servers but
1244 forwards such queries to a fully recursive upstream DNS server which is
1245 typically provided by an ISP. By default, dnsmasq reads
1248 addresses of the upstream nameservers it should use, since the
1249 information is typically stored there. Unless
1253 checks the modification time of
1257 is used) and re-reads it if it changes. This allows the DNS servers to
1258 be set dynamically by PPP or DHCP since both protocols provide the
1263 since it may not have been created before a PPP connection exists. Dnsmasq
1264 simply keeps checking in case
1267 time. Dnsmasq can be told to parse more than one resolv.conf
1268 file. This is useful on a laptop, where both PPP and DHCP may be used:
1269 dnsmasq can be set to poll both
1270 .I /etc/ppp/resolv.conf
1272 .I /etc/dhcpc/resolv.conf
1273 and will use the contents of whichever changed
1274 last, giving automatic switching between DNS servers.
1276 Upstream servers may also be specified on the command line or in
1277 the configuration file. These server specifications optionally take a
1278 domain name which tells dnsmasq to use that server only to find names
1279 in that particular domain.
1281 In order to configure dnsmasq to act as cache for the host on which it is running, put "nameserver 127.0.0.1" in
1283 to force local processes to send queries to
1284 dnsmasq. Then either specify the upstream servers directly to dnsmasq
1287 options or put their addresses real in another file, say
1288 .I /etc/resolv.dnsmasq
1289 and run dnsmasq with the
1290 .B \-r /etc/resolv.dnsmasq
1291 option. This second technique allows for dynamic update of the server
1292 addresses by PPP or DHCP.
1294 Addresses in /etc/hosts will "shadow" different addresses for the same
1295 names in the upstream DNS, so "mycompany.com 1.2.3.4" in /etc/hosts will ensure that
1296 queries for "mycompany.com" always return 1.2.3.4 even if queries in
1297 the upstream DNS would otherwise return a different address. There is
1298 one exception to this: if the upstream DNS contains a CNAME which
1299 points to a shadowed name, then looking up the CNAME through dnsmasq
1300 will result in the unshadowed address associated with the target of
1301 the CNAME. To work around this, add the CNAME to /etc/hosts so that
1302 the CNAME is shadowed too.
1305 The tag system works as follows: For each DHCP request, dnsmasq
1306 collects a set of valid tags from active configuration lines which
1307 include set:<tag>, including one from the
1309 used to allocate the address, one from any matching
1311 (and "known" if a dhcp-host matches)
1312 The tag "bootp" is set for BOOTP requests, and a tag whose name is the
1313 name of the interface on which the request arrived is also set.
1315 Any configuration lines which includes one or more tag:<tag> contructs
1316 will only be valid if all that tags are matched in the set derived
1317 above. Typically this is dhcp-option.
1319 which has tags will be used in preference to an untagged
1321 provided that _all_ the tags match somewhere in the
1322 set collected as described above. The prefix '!' on a tag means 'not'
1323 so --dhcp=option=tag:!purple,3,1.2.3.4 sends the option when the
1324 tag purple is not in the set of valid tags. (If using this in a
1325 command line rather than a configuration file, be sure to escape !,
1326 which is a shell metacharacter)
1330 both tag:<tag> and set:<tag> are allowed, to both select the range in
1331 use based on (eg) dhcp-host, and to affect the options sent, based on
1334 This system evolved from an earlier, more limited one and for backward
1335 compatibility "net:" may be used instead of "tag:" and "set:" may be
1338 where "net:" may be used instead of "set:".) For the same reason, '#'
1339 may be used instead of '!' to indicate NOT.
1341 The DHCP server in dnsmasq will function as a BOOTP server also,
1342 provided that the MAC address and IP address for clients are given,
1345 configurations or in
1349 configuration option is present to activate the DHCP server
1350 on a particular network. (Setting --bootp-dynamic removes the need for
1351 static address mappings.) The filename
1352 parameter in a BOOTP request is used as a tag,
1353 as is the tag "bootp", allowing some control over the options returned to
1354 different classes of hosts.
1357 may have an interface name supplied as
1358 "interface:<interface-name>". The semantics if this are as follows:
1359 For DHCP, if any other dhcp-range exists _without_ an interface name,
1360 then the interface name is ignored and and dnsmasq behaves as if the
1361 interface parts did not exist, otherwise DHCP is only provided to
1362 interfaces mentioned in dhcp-range
1363 declarations. For DNS, if there are no
1367 flags, behaviour is unchanged by the interface part. If either of
1368 these flags are present, the interfaces mentioned in
1369 dhcp-ranges are added to the set which get DNS service.
1373 may take an interface name, which enables TFTP only for a particular
1381 .B --tftp-unique-root
1383 .B --tftp-no-blocksize
1384 are ignored for requests from such interfaces. (A
1386 directive giving a root path and an interface should be
1389 These rules may seem odd at first sight, but they
1390 allow a single line of the form "dhcp-range=interface:virt0,192.168.0.4,192.168.0.200"
1391 to be added to dnsmasq configuration which then supplies
1392 DHCP and DNS services to that interface, without affecting
1393 what services are supplied to other interfaces and irrespective of
1394 the existance or lack of "interface=<interface>"
1395 lines elsewhere in the dnsmasq configuration.
1396 "enable-tftp=virt0" and "tftp-root=<root>,virt0" do the same job for TFTP.
1398 that such a line can be added automatically by libvirt
1399 or equivalent systems, without disturbing any manual
1404 0 - Dnsmasq successfully forked into the background, or terminated
1405 normally if backgrounding is not enabled.
1407 1 - A problem with configuration was detected.
1409 2 - A problem with network access occurred (address in use, attempt
1410 to use privileged ports without permission).
1412 3 - A problem occurred with a filesystem operation (missing
1413 file/directory, permissions).
1415 4 - Memory allocation failure.
1417 5 - Other miscellaneous problem.
1419 11 or greater - a non zero return code was received from the
1420 lease-script process "init" call. The exit code from dnsmasq is the
1421 script's exit code with 10 added.
1424 The default values for resource limits in dnsmasq are generally
1425 conservative, and appropriate for embedded router type devices with
1426 slow processors and limited memory. On more capable hardware, it is
1427 possible to increase the limits, and handle many more clients. The
1428 following applies to dnsmasq-2.37: earlier versions did not scale as well.
1431 Dnsmasq is capable of handling DNS and DHCP for at least a thousand
1432 clients. The DHCP lease times should not be very short (less than one hour). The
1434 .B --dns-forward-max
1435 can be increased: start with it equal to
1436 the number of clients and increase if DNS seems slow. Note that DNS
1437 performance depends too on the performance of the upstream
1438 nameservers. The size of the DNS cache may be increased: the hard
1439 limit is 10000 names and the default (150) is very low. Sending
1440 SIGUSR1 to dnsmasq makes it log information which is useful for tuning
1441 the cache size. See the
1443 section for details.
1446 The built-in TFTP server is capable of many simultaneous file
1447 transfers: the absolute limit is related to the number of file-handles
1448 allowed to a process and the ability of the select() system call to
1449 cope with large numbers of file handles. If the limit is set too high
1452 it will be scaled down and the actual limit logged at
1453 start-up. Note that more transfers are possible when the same file is
1454 being sent than when each transfer sends a different file.
1457 It is possible to use dnsmasq to block Web advertising by using a list
1458 of known banner-ad servers, all resolving to 127.0.0.1 or 0.0.0.0, in
1460 or an additional hosts file. The list can be very long,
1461 dnsmasq has been tested successfully with one million names. That size
1462 file needs a 1GHz processor and about 60Mb of RAM.
1464 .SH INTERNATIONALISATION
1465 Dnsmasq can be compiled to support internationalisation. To do this,
1466 the make targets "all-i18n" and "install-i18n" should be used instead of
1467 the standard targets "all" and "install". When internationalisation
1468 is compiled in, dnsmasq will produce log messages in the local
1469 language and support internationalised domain names (IDN). Domain
1470 names in /etc/hosts, /etc/ethers and /etc/dnsmasq.conf which contain
1471 non-ASCII characters will be translated to the DNS-internal punycode
1472 representation. Note that
1473 dnsmasq determines both the language for messages and the assumed
1474 charset for configuration
1475 files from the LANG environment variable. This should be set to the system
1476 default value by the script which is responsible for starting
1477 dnsmasq. When editing the configuration files, be careful to do so
1478 using only the system-default locale and not user-specific one, since
1479 dnsmasq has no direct way of determining the charset in use, and must
1480 assume that it is the system default.
1483 .IR /etc/dnsmasq.conf
1485 .IR /usr/local/etc/dnsmasq.conf
1487 .IR /etc/resolv.conf
1488 .IR /var/run/dnsmasq/resolv.conf
1489 .IR /etc/ppp/resolv.conf
1490 .IR /etc/dhcpc/resolv.conf
1496 .IR /var/lib/misc/dnsmasq.leases
1498 .IR /var/db/dnsmasq.leases
1500 .IR /var/run/dnsmasq.pid
1505 This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.
projects / framework / connectivity / dnsmasq.git / blob