Annotation of embedaddon/dnsmasq/man/dnsmasq.8, revision 1.1.1.4
1.1.1.4 ! misho 1: .TH DNSMASQ 8 2020-04-05
1.1 misho 2: .SH NAME
3: dnsmasq \- A lightweight DHCP and caching DNS server.
4: .SH SYNOPSIS
5: .B dnsmasq
6: .I [OPTION]...
7: .SH "DESCRIPTION"
8: .BR dnsmasq
9: is a lightweight DNS, TFTP, PXE, router advertisement and DHCP server. It is intended to provide
10: coupled DNS and DHCP service to a LAN.
11: .PP
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
1.1.1.2 misho 16: DNS queries for DHCP configured hosts. It can also act as the
17: authoritative DNS server for one or more domains, allowing local names
18: to appear in the global DNS. It can be configured to do DNSSEC
19: validation.
1.1 misho 20: .PP
21: The dnsmasq DHCP server supports static address assignments and multiple
22: networks. It automatically
23: sends a sensible default set of DHCP options, and can be configured to
24: send any desired set of DHCP options, including vendor-encapsulated
25: options. It includes a secure, read-only,
26: TFTP server to allow net/PXE boot of DHCP hosts and also supports BOOTP. The PXE support is full featured, and includes a proxy mode which supplies PXE information to clients whilst DHCP address allocation is done by another server.
27: .PP
28: The dnsmasq DHCPv6 server provides the same set of features as the
29: DHCPv4 server, and in addition, it includes router advertisements and
1.1.1.4 ! misho 30: a neat feature which allows naming for clients which use DHCPv4 and
1.1 misho 31: stateless autoconfiguration only for IPv6 configuration. There is support for doing address allocation (both DHCPv6 and RA) from subnets which are dynamically delegated via DHCPv6 prefix delegation.
32: .PP
1.1.1.4 ! misho 33: Dnsmasq is coded with small embedded systems in mind. It aims for the smallest possible memory footprint compatible with the supported functions, and allows unneeded functions to be omitted from the compiled binary.
1.1 misho 34: .SH OPTIONS
35: Note that in general missing parameters are allowed and switch off
36: functions, for instance "--pid-file" disables writing a PID file. On
37: BSD, unless the GNU getopt library is linked, the long form of the
38: options does not work on the command line; it is still recognised in
39: the configuration file.
40: .TP
41: .B --test
42: Read and syntax check configuration file(s). Exit with code 0 if all
43: is OK, or a non-zero code otherwise. Do not start up dnsmasq.
44: .TP
1.1.1.3 misho 45: .B \-w, --help
46: Display all command-line options.
47: .B --help dhcp
48: will display known DHCPv4 configuration options, and
49: .B --help dhcp6
50: will display DHCPv6 options.
51: .TP
1.1 misho 52: .B \-h, --no-hosts
53: Don't read the hostnames in /etc/hosts.
54: .TP
55: .B \-H, --addn-hosts=<file>
1.1.1.4 ! misho 56: Additional hosts file. Read the specified file as well as /etc/hosts. If \fB--no-hosts\fP is given, read
1.1 misho 57: only the specified file. This option may be repeated for more than one
58: additional hosts file. If a directory is given, then read all the files contained in that directory.
59: .TP
1.1.1.3 misho 60: .B --hostsdir=<path>
61: Read all the hosts files contained in the directory. New or changed files
1.1.1.4 ! misho 62: are read automatically. See \fB--dhcp-hostsdir\fP for details.
1.1.1.3 misho 63: .TP
1.1 misho 64: .B \-E, --expand-hosts
65: Add the domain to simple names (without a period) in /etc/hosts
66: in the same way as for DHCP-derived names. Note that this does not
67: apply to domain names in cnames, PTR records, TXT records etc.
68: .TP
69: .B \-T, --local-ttl=<time>
1.1.1.3 misho 70: When replying with information from /etc/hosts or configuration or the DHCP leases
1.1 misho 71: file dnsmasq by default sets the time-to-live field to zero, meaning
72: that the requester should not itself cache the information. This is
73: the correct thing to do in almost all situations. This option allows a
74: time-to-live (in seconds) to be given for these replies. This will
75: reduce the load on the server at the expense of clients using stale
76: data under some circumstances.
77: .TP
1.1.1.3 misho 78: .B --dhcp-ttl=<time>
1.1.1.4 ! misho 79: As for \fB--local-ttl\fP, but affects only replies with information from DHCP leases. If both are given, \fB--dhcp-ttl\fP applies for DHCP information, and \fB--local-ttl\fP for others. Setting this to zero eliminates the effect of \fB--local-ttl\fP for DHCP.
1.1.1.3 misho 80: .TP
1.1 misho 81: .B --neg-ttl=<time>
82: Negative replies from upstream servers normally contain time-to-live
83: information in SOA records which dnsmasq uses for caching. If the
84: replies from upstream servers omit this information, dnsmasq does not
85: cache the reply. This option gives a default value for time-to-live
86: (in seconds) which dnsmasq uses to cache negative replies even in
87: the absence of an SOA record.
88: .TP
89: .B --max-ttl=<time>
90: Set a maximum TTL value that will be handed out to clients. The specified
91: maximum TTL will be given to clients instead of the true TTL value if it is
92: lower. The true TTL value is however kept in the cache to avoid flooding
93: the upstream DNS servers.
94: .TP
95: .B --max-cache-ttl=<time>
96: Set a maximum TTL value for entries in the cache.
97: .TP
1.1.1.3 misho 98: .B --min-cache-ttl=<time>
99: Extend short TTL values to the time given when caching them. Note that
100: artificially extending TTL values is in general a bad idea, do not do it
101: unless you have a good reason, and understand what you are doing.
102: Dnsmasq limits the value of this option to one hour, unless recompiled.
103: .TP
1.1 misho 104: .B --auth-ttl=<time>
105: Set the TTL value returned in answers from the authoritative server.
106: .TP
107: .B \-k, --keep-in-foreground
108: Do not go into the background at startup but otherwise run as
109: normal. This is intended for use when dnsmasq is run under daemontools
110: or launchd.
111: .TP
112: .B \-d, --no-daemon
113: Debug mode: don't fork to the background, don't write a pid file,
114: don't change user id, generate a complete cache dump on receipt on
115: SIGUSR1, log to stderr as well as syslog, don't fork new processes
116: to handle TCP queries. Note that this option is for use in debugging
117: only, to stop dnsmasq daemonising in production, use
1.1.1.4 ! misho 118: .B --keep-in-foreground.
1.1 misho 119: .TP
120: .B \-q, --log-queries
1.1.1.3 misho 121: Log the results of DNS queries handled by dnsmasq. Enable a full cache dump on receipt of SIGUSR1. If the argument "extra" is supplied, ie
122: .B --log-queries=extra
123: then the log has extra information at the start of each line.
124: This consists of a serial number which ties together the log lines associated with an individual query, and the IP address of the requestor.
1.1 misho 125: .TP
126: .B \-8, --log-facility=<facility>
127: Set the facility to which dnsmasq will send syslog entries, this
128: defaults to DAEMON, and to LOCAL0 when debug mode is in operation. If
129: the facility given contains at least one '/' character, it is taken to
130: be a filename, and dnsmasq logs to the given file, instead of
131: syslog. If the facility is '-' then dnsmasq logs to stderr.
132: (Errors whilst reading configuration will still go to syslog,
133: but all output from a successful startup, and all output whilst
134: running, will go exclusively to the file.) When logging to a file,
135: dnsmasq will close and reopen the file when it receives SIGUSR2. This
136: allows the log file to be rotated without stopping dnsmasq.
137: .TP
138: .B --log-async[=<lines>]
139: Enable asynchronous logging and optionally set the limit on the
140: number of lines
141: which will be queued by dnsmasq when writing to the syslog is slow.
142: Dnsmasq can log asynchronously: this
143: allows it to continue functioning without being blocked by syslog, and
144: allows syslog to use dnsmasq for DNS queries without risking deadlock.
145: If the queue of log-lines becomes full, dnsmasq will log the
146: overflow, and the number of messages lost. The default queue length is
147: 5, a sane value would be 5-25, and a maximum limit of 100 is imposed.
148: .TP
149: .B \-x, --pid-file=<path>
150: Specify an alternate path for dnsmasq to record its process-id in. Normally /var/run/dnsmasq.pid.
151: .TP
152: .B \-u, --user=<username>
153: Specify the userid to which dnsmasq will change after startup. Dnsmasq must normally be started as root, but it will drop root
154: privileges after startup by changing id to another user. Normally this user is "nobody" but that
155: can be over-ridden with this switch.
156: .TP
157: .B \-g, --group=<groupname>
158: Specify the group which dnsmasq will run
1.1.1.4 ! misho 159: as. The default is "dip", if available, to facilitate access to
1.1 misho 160: /etc/ppp/resolv.conf which is not normally world readable.
161: .TP
162: .B \-v, --version
163: Print the version number.
164: .TP
165: .B \-p, --port=<port>
166: Listen on <port> instead of the standard DNS port (53). Setting this
167: to zero completely disables DNS function, leaving only DHCP and/or TFTP.
168: .TP
169: .B \-P, --edns-packet-max=<size>
170: Specify the largest EDNS.0 UDP packet which is supported by the DNS
171: forwarder. Defaults to 4096, which is the RFC5625-recommended size.
172: .TP
173: .B \-Q, --query-port=<query_port>
174: Send outbound DNS queries from, and listen for their replies on, the
175: specific UDP port <query_port> instead of using random ports. NOTE
176: that using this option will make dnsmasq less secure against DNS
177: spoofing attacks but it may be faster and use less resources. Setting this option
178: to zero makes dnsmasq use a single port allocated to it by the
179: OS: this was the default behaviour in versions prior to 2.43.
180: .TP
181: .B --min-port=<port>
182: Do not use ports less than that given as source for outbound DNS
183: queries. Dnsmasq picks random ports as source for outbound queries:
184: when this option is given, the ports used will always to larger
1.1.1.4 ! misho 185: than that specified. Useful for systems behind firewalls. If not specified,
! 186: defaults to 1024.
1.1 misho 187: .TP
1.1.1.3 misho 188: .B --max-port=<port>
189: Use ports lower than that given as source for outbound DNS queries.
190: Dnsmasq picks random ports as source for outbound queries:
191: when this option is given, the ports used will always be lower
192: than that specified. Useful for systems behind firewalls.
193: .TP
1.1 misho 194: .B \-i, --interface=<interface name>
195: Listen only on the specified interface(s). Dnsmasq automatically adds
196: the loopback (local) interface to the list of interfaces to use when
197: the
198: .B \--interface
199: option is used. If no
200: .B \--interface
201: or
202: .B \--listen-address
203: options are given dnsmasq listens on all available interfaces except any
204: given in
205: .B \--except-interface
1.1.1.4 ! misho 206: options. On Linux, when
! 207: .B \--bind-interfaces
1.1 misho 208: or
1.1.1.4 ! misho 209: .B \--bind-dynamic
! 210: are in effect, IP alias interface labels (eg "eth1:0") are checked, rather than
! 211: interface names. In the degenerate case when an interface has one address, this amounts to the same thing but when an interface has multiple addresses it
! 212: allows control over which of those addresses are accepted.
! 213: The same effect is achievable in default mode by using
! 214: .B \--listen-address.
! 215: A simple wildcard, consisting of a trailing '*',
! 216: can be used in
1.1 misho 217: .B \--interface
218: and
219: .B \--except-interface
220: options.
221: .TP
222: .B \-I, --except-interface=<interface name>
223: Do not listen on the specified interface. Note that the order of
224: .B \--listen-address
225: .B --interface
226: and
227: .B --except-interface
228: options does not matter and that
229: .B --except-interface
1.1.1.4 ! misho 230: options always override the others. The comments about interface labels for
! 231: .B --listen-address
! 232: apply here.
1.1 misho 233: .TP
1.1.1.4 ! misho 234: .B --auth-server=<domain>,[<interface>|<ip-address>...]
1.1 misho 235: Enable DNS authoritative mode for queries arriving at an interface or address. Note that the interface or address
236: need not be mentioned in
237: .B --interface
238: or
239: .B --listen-address
240: configuration, indeed
241: .B --auth-server
1.1.1.4 ! misho 242: will override these and provide a different DNS service on the
1.1.1.2 misho 243: specified interface. The <domain> is the "glue record". It should
1.1.1.4 ! misho 244: resolve in the global DNS to an A and/or AAAA record which points to
1.1.1.2 misho 245: the address dnsmasq is listening on. When an interface is specified,
246: it may be qualified with "/4" or "/6" to specify only the IPv4 or IPv6
1.1.1.4 ! misho 247: addresses associated with the interface. Since any defined authoritative zones are also available as part of the normal recusive DNS service supplied by dnsmasq, it can make sense to have an --auth-server declaration with no interfaces or address, but simply specifying the primary external nameserver.
1.1.1.2 misho 248: .TP
249: .B --local-service
250: Accept DNS queries only from hosts whose address is on a local subnet,
251: ie a subnet for which an interface exists on the server. This option
1.1.1.4 ! misho 252: only has effect if there are no \fB--interface\fP, \fB--except-interface\fP,
! 253: \fB--listen-address\fP or \fB--auth-server\fP options. It is intended to be set as
1.1.1.2 misho 254: a default on installation, to allow unconfigured installations to be
255: useful but also safe from being used for DNS amplification attacks.
1.1 misho 256: .TP
257: .B \-2, --no-dhcp-interface=<interface name>
258: Do not provide DHCP or TFTP on the specified interface, but do provide DNS service.
259: .TP
260: .B \-a, --listen-address=<ipaddr>
261: Listen on the given IP address(es). Both
262: .B \--interface
263: and
264: .B \--listen-address
265: options may be given, in which case the set of both interfaces and
266: addresses is used. Note that if no
267: .B \--interface
268: option is given, but
269: .B \--listen-address
270: is, dnsmasq will not automatically listen on the loopback
271: interface. To achieve this, its IP address, 127.0.0.1, must be
272: explicitly given as a
273: .B \--listen-address
274: option.
275: .TP
276: .B \-z, --bind-interfaces
277: On systems which support it, dnsmasq binds the wildcard address,
278: even when it is listening on only some interfaces. It then discards
279: requests that it shouldn't reply to. This has the advantage of
280: working even when interfaces come and go and change address. This
281: option forces dnsmasq to really bind only the interfaces it is
282: listening on. About the only time when this is useful is when
283: running another nameserver (or another instance of dnsmasq) on the
284: same machine. Setting this option also enables multiple instances of
285: dnsmasq which provide DHCP service to run in the same machine.
286: .TP
287: .B --bind-dynamic
288: Enable a network mode which is a hybrid between
289: .B --bind-interfaces
290: and the default. Dnsmasq binds the address of individual interfaces,
291: allowing multiple dnsmasq instances, but if new interfaces or
292: addresses appear, it automatically listens on those (subject to any
293: access-control configuration). This makes dynamically created
294: interfaces work in the same way as the default. Implementing this
295: option requires non-standard networking APIs and it is only available
1.1.1.4 ! misho 296: under Linux. On other platforms it falls-back to \fB--bind-interfaces\fP mode.
1.1 misho 297: .TP
298: .B \-y, --localise-queries
1.1.1.4 ! misho 299: Return answers to DNS queries from /etc/hosts and \fB--interface-name\fP which depend on the interface over which the query was
! 300: received. If a name has more than one address associated with
1.1 misho 301: it, and at least one of those addresses is on the same subnet as the
302: interface to which the query was sent, then return only the
303: address(es) on that subnet. This allows for a server to have multiple
304: addresses in /etc/hosts corresponding to each of its interfaces, and
305: hosts will get the correct address based on which network they are
306: attached to. Currently this facility is limited to IPv4.
307: .TP
308: .B \-b, --bogus-priv
309: Bogus private reverse lookups. All reverse lookups for private IP ranges (ie 192.168.x.x, etc)
310: which are not found in /etc/hosts or the DHCP leases file are answered
1.1.1.4 ! misho 311: with "no such domain" rather than being forwarded upstream. The
! 312: set of prefixes affected is the list given in RFC6303, for IPv4 and IPv6.
1.1 misho 313: .TP
314: .B \-V, --alias=[<old-ip>]|[<start-ip>-<end-ip>],<new-ip>[,<mask>]
315: Modify IPv4 addresses returned from upstream nameservers; old-ip is
316: replaced by new-ip. If the optional mask is given then any address
317: which matches the masked old-ip will be re-written. So, for instance
318: .B --alias=1.2.3.0,6.7.8.0,255.255.255.0
319: will map 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. This is what
320: Cisco PIX routers call "DNS doctoring". If the old IP is given as
321: range, then only addresses in the range, rather than a whole subnet,
322: are re-written. So
323: .B --alias=192.168.0.10-192.168.0.40,10.0.0.0,255.255.255.0
324: maps 192.168.0.10->192.168.0.40 to 10.0.0.10->10.0.0.40
325: .TP
326: .B \-B, --bogus-nxdomain=<ipaddr>
327: Transform replies which contain the IP address given into "No such
328: domain" replies. This is intended to counteract a devious move made by
329: Verisign in September 2003 when they started returning the address of
330: an advertising web page in response to queries for unregistered names,
331: instead of the correct NXDOMAIN response. This option tells dnsmasq to
332: fake the correct response when it sees this behaviour. As at Sept 2003
333: the IP address being returned by Verisign is 64.94.110.11
1.1.1.3 misho 334: .TP
335: .B --ignore-address=<ipaddr>
336: Ignore replies to A-record queries which include the specified address.
337: No error is generated, dnsmasq simply continues to listen for another reply.
338: This is useful to defeat blocking strategies which rely on quickly supplying a
339: forged answer to a DNS request for certain domain, before the correct answer can arrive.
1.1 misho 340: .TP
341: .B \-f, --filterwin2k
342: Later versions of windows make periodic DNS requests which don't get sensible answers from
343: the public DNS and can cause problems by triggering dial-on-demand links. This flag turns on an option
344: to filter such requests. The requests blocked are for records of types SOA and SRV, and type ANY where the
345: requested name has underscores, to catch LDAP requests.
346: .TP
347: .B \-r, --resolv-file=<file>
348: Read the IP addresses of the upstream nameservers from <file>, instead of
349: /etc/resolv.conf. For the format of this file see
350: .BR resolv.conf (5).
351: The only lines relevant to dnsmasq are nameserver ones. Dnsmasq can
352: be told to poll more than one resolv.conf file, the first file name specified
353: overrides the default, subsequent ones add to the list. This is only
354: allowed when polling; the file with the currently latest modification
355: time is the one used.
356: .TP
357: .B \-R, --no-resolv
358: Don't read /etc/resolv.conf. Get upstream servers only from the command
359: line or the dnsmasq configuration file.
360: .TP
361: .B \-1, --enable-dbus[=<service-name>]
362: Allow dnsmasq configuration to be updated via DBus method calls. The
363: configuration which can be changed is upstream DNS servers (and
364: corresponding domains) and cache clear. Requires that dnsmasq has
365: been built with DBus support. If the service name is given, dnsmasq
366: provides service at that name, rather than the default which is
367: .B uk.org.thekelleys.dnsmasq
368: .TP
1.1.1.4 ! misho 369: .B --enable-ubus[=<service-name>]
! 370: Enable dnsmasq UBus interface. It sends notifications via UBus on
! 371: DHCPACK and DHCPRELEASE events. Furthermore it offers metrics.
! 372: Requires that dnsmasq has been built with UBus support. If the service
! 373: name is given, dnsmasq provides service at that namespace, rather than
! 374: the default which is
! 375: .B dnsmasq
! 376: .TP
1.1 misho 377: .B \-o, --strict-order
378: By default, dnsmasq will send queries to any of the upstream servers
379: it knows about and tries to favour servers that are known to
380: be up. Setting this flag forces dnsmasq to try each query with each
381: server strictly in the order they appear in /etc/resolv.conf
382: .TP
383: .B --all-servers
384: By default, when dnsmasq has more than one upstream server available,
385: it will send queries to just one server. Setting this flag forces
386: dnsmasq to send all queries to all available servers. The reply from
387: the server which answers first will be returned to the original requester.
388: .TP
1.1.1.3 misho 389: .B --dns-loop-detect
390: Enable code to detect DNS forwarding loops; ie the situation where a query sent to one
391: of the upstream server eventually returns as a new query to the dnsmasq instance. The
392: process works by generating TXT queries of the form <hex>.test and sending them to
393: each upstream server. The hex is a UID which encodes the instance of dnsmasq sending the query
394: and the upstream server to which it was sent. If the query returns to the server which sent it, then
395: the upstream server through which it was sent is disabled and this event is logged. Each time the
396: set of upstream servers changes, the test is re-run on all of them, including ones which
397: were previously disabled.
398: .TP
1.1 misho 399: .B --stop-dns-rebind
400: Reject (and log) addresses from upstream nameservers which are in the
1.1.1.4 ! misho 401: private ranges. This blocks an attack where a browser behind a
! 402: firewall is used to probe machines on the local network. For IPv6, the
! 403: private range covers the IPv4-mapped addresses in private space plus
! 404: all link-local (LL) and site-local (ULA) addresses.
1.1 misho 405: .TP
406: .B --rebind-localhost-ok
1.1.1.4 ! misho 407: Exempt 127.0.0.0/8 and ::1 from rebinding checks. This address range is
1.1 misho 408: returned by realtime black hole servers, so blocking it may disable
409: these services.
410: .TP
411: .B --rebind-domain-ok=[<domain>]|[[/<domain>/[<domain>/]
412: Do not detect and block dns-rebind on queries to these domains. The
413: argument may be either a single domain, or multiple domains surrounded
1.1.1.4 ! misho 414: by '/', like the \fB--server\fP syntax, eg.
1.1 misho 415: .B --rebind-domain-ok=/domain1/domain2/domain3/
416: .TP
417: .B \-n, --no-poll
418: Don't poll /etc/resolv.conf for changes.
419: .TP
420: .B --clear-on-reload
1.1.1.2 misho 421: Whenever /etc/resolv.conf is re-read or the upstream servers are set
422: via DBus, clear the DNS cache.
1.1 misho 423: This is useful when new nameservers may have different
424: data than that held in cache.
425: .TP
426: .B \-D, --domain-needed
427: Tells dnsmasq to never forward A or AAAA queries for plain names, without dots
428: or domain parts, to upstream nameservers. If the name is not known
429: from /etc/hosts or DHCP then a "not found" answer is returned.
430: .TP
1.1.1.4 ! misho 431: .B \-S, --local, --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>]][@<source-ip>|<interface>[#<port>]]
1.1 misho 432: Specify IP address of upstream servers directly. Setting this flag does
1.1.1.4 ! misho 433: not suppress reading of /etc/resolv.conf, use \fB--no-resolv\fP to do that. If one or more
1.1 misho 434: optional domains are given, that server is used only for those domains
435: and they are queried only using the specified server. This is
436: intended for private nameservers: if you have a nameserver on your
437: network which deals with names of the form
438: xxx.internal.thekelleys.org.uk at 192.168.1.1 then giving the flag
1.1.1.4 ! misho 439: .B --server=/internal.thekelleys.org.uk/192.168.1.1
1.1 misho 440: will send all queries for
441: internal machines to that nameserver, everything else will go to the
1.1.1.3 misho 442: servers in /etc/resolv.conf. DNSSEC validation is turned off for such
443: private nameservers, UNLESS a
444: .B --trust-anchor
445: is specified for the domain in question. An empty domain specification,
1.1 misho 446: .B //
447: has the special meaning of "unqualified names only" ie names without any
448: dots in them. A non-standard port may be specified as
449: part of the IP
450: address using a # character.
1.1.1.4 ! misho 451: More than one \fB--server\fP flag is allowed, with
1.1 misho 452: repeated domain or ipaddr parts as required.
453:
1.1.1.4 ! misho 454: More specific domains take precedence over less specific domains, so:
1.1 misho 455: .B --server=/google.com/1.2.3.4
456: .B --server=/www.google.com/2.3.4.5
457: will send queries for *.google.com to 1.2.3.4, except *www.google.com,
458: which will go to 2.3.4.5
459:
460: The special server address '#' means, "use the standard servers", so
461: .B --server=/google.com/1.2.3.4
462: .B --server=/www.google.com/#
463: will send queries for *.google.com to 1.2.3.4, except *www.google.com which will
464: be forwarded as usual.
465:
466: Also permitted is a -S
467: flag which gives a domain but no IP address; this tells dnsmasq that
468: a domain is local and it may answer queries from /etc/hosts or DHCP
469: but should never forward queries on that domain to any upstream
470: servers.
1.1.1.4 ! misho 471: .B --local
1.1 misho 472: is a synonym for
1.1.1.4 ! misho 473: .B --server
1.1 misho 474: to make configuration files clearer in this case.
475:
1.1.1.4 ! misho 476: IPv6 addresses may include an %interface scope-id, eg
1.1 misho 477: fe80::202:a412:4512:7bbf%eth0.
478:
1.1.1.4 ! misho 479: The optional string after the @ character tells dnsmasq how to set the source of
! 480: the queries to this nameserver. It can either be an ip-address, an interface
! 481: name or both. The ip-address should belong to the machine on which dnsmasq is
! 482: running, otherwise this server line will be logged and then ignored. If an
! 483: interface name is given, then queries to the server will be forced via that
! 484: interface; if an ip-address is given then the source address of the queries will
! 485: be set to that address; and if both are given then a combination of ip-address
! 486: and interface name will be used to steer requests to the server.
1.1 misho 487: The query-port flag is ignored for any servers which have a
488: source address specified but the port may be specified directly as
489: part of the source address. Forcing queries to an interface is not
490: implemented on all platforms supported by dnsmasq.
491: .TP
1.1.1.4 ! misho 492: .B --rev-server=<ip-address>/<prefix-len>[,<ipaddr>][#<port>][@<source-ip>|<interface>[#<port>]]
1.1.1.2 misho 493: This is functionally the same as
494: .B --server,
495: but provides some syntactic sugar to make specifying address-to-name queries easier. For example
496: .B --rev-server=1.2.3.0/24,192.168.0.1
497: is exactly equivalent to
498: .B --server=/3.2.1.in-addr.arpa/192.168.0.1
499: .TP
1.1.1.4 ! misho 500: .B \-A, --address=/<domain>[/<domain>...]/[<ipaddr>]
1.1 misho 501: Specify an IP address to return for any host in the given domains.
502: Queries in the domains are never forwarded and always replied to
503: with the specified IP address which may be IPv4 or IPv6. To give
1.1.1.4 ! misho 504: both IPv4 and IPv6 addresses for a domain, use repeated \fB--address\fP flags.
! 505: To include multiple IP addresses for a single query, use
! 506: \fB--addn-hosts=<path>\fP instead.
1.1 misho 507: Note that /etc/hosts and DHCP leases override this for individual
508: names. A common use of this is to redirect the entire doubleclick.net
509: domain to some friendly local web server to avoid banner ads. The
1.1.1.4 ! misho 510: domain specification works in the same was as for \fB--server\fP, with
! 511: the additional facility that \fB/#/\fP matches any domain. Thus
! 512: \fB--address=/#/1.2.3.4\fP will always return \fB1.2.3.4\fP for any
! 513: query not answered from \fB/etc/hosts\fP or DHCP and not sent to an
! 514: upstream nameserver by a more specific \fB--server\fP directive. As for
! 515: \fB--server\fP, one or more domains with no address returns a
! 516: no-such-domain answer, so \fB--address=/example.com/\fP is equivalent to
! 517: \fB--server=/example.com/\fP and returns NXDOMAIN for example.com and
! 518: all its subdomains. An address specified as '#' translates to the NULL
! 519: address of 0.0.0.0 and its IPv6 equivalent of :: so
! 520: \fB--address=/example.com/#\fP will return NULL addresses for example.com and
! 521: its subdomains. This is partly syntactic sugar for \fB--address=/example.com/0.0.0.0\fP
! 522: and \fB--address=/example.com/::\fP but is also more efficient than including both
! 523: as separate configuration lines. Note that NULL addresses normally work in the same way as localhost, so beware that clients looking up these names are likely to end up talking to themselves.
! 524: .TP
! 525: .B --ipset=/<domain>[/<domain>...]/<ipset>[,<ipset>...]
! 526: Places the resolved IP addresses of queries for one or more domains in
! 527: the specified Netfilter IP set. If multiple setnames are given, then the
! 528: addresses are placed in each of them, subject to the limitations of an
! 529: IP set (IPv4 addresses cannot be stored in an IPv6 IP set and vice
! 530: versa). Domains and subdomains are matched in the same way as
! 531: \fB--address\fP.
! 532: These IP sets must already exist. See
! 533: .BR ipset (8)
! 534: for more details.
1.1 misho 535: .TP
536: .B \-m, --mx-host=<mx name>[[,<hostname>],<preference>]
537: Return an MX record named <mx name> pointing to the given hostname (if
538: given), or
1.1.1.4 ! misho 539: the host specified in the \fB--mx-target\fP switch
1.1 misho 540: or, if that switch is not given, the host on which dnsmasq
541: is running. The default is useful for directing mail from systems on a LAN
542: to a central server. The preference value is optional, and defaults to
543: 1 if not given. More than one MX record may be given for a host.
544: .TP
545: .B \-t, --mx-target=<hostname>
546: Specify the default target for the MX record returned by dnsmasq. See
1.1.1.4 ! misho 547: \fB--mx-host\fP. If \fB--mx-target\fP is given, but not \fB--mx-host\fP, then dnsmasq
1.1 misho 548: returns a MX record containing the MX target for MX queries on the
549: hostname of the machine on which dnsmasq is running.
550: .TP
551: .B \-e, --selfmx
552: Return an MX record pointing to itself for each local
553: machine. Local machines are those in /etc/hosts or with DHCP leases.
554: .TP
555: .B \-L, --localmx
1.1.1.4 ! misho 556: Return an MX record pointing to the host given by \fB--mx-target\fP (or the
1.1 misho 557: machine on which dnsmasq is running) for each
558: local machine. Local machines are those in /etc/hosts or with DHCP
559: leases.
560: .TP
561: .B \-W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<priority>[,<weight>]]]]
562: Return a SRV DNS record. See RFC2782 for details. If not supplied, the
563: domain defaults to that given by
564: .B --domain.
565: The default for the target domain is empty, and the default for port
566: is one and the defaults for
567: weight and priority are zero. Be careful if transposing data from BIND
568: zone files: the port, weight and priority numbers are in a different
569: order. More than one SRV record for a given service/domain is allowed,
570: all that match are returned.
571: .TP
1.1.1.3 misho 572: .B --host-record=<name>[,<name>....],[<IPv4-address>],[<IPv6-address>][,<TTL>]
1.1 misho 573: Add A, AAAA and PTR records to the DNS. This adds one or more names to
574: the DNS with associated IPv4 (A) and IPv6 (AAAA) records. A name may
575: appear in more than one
1.1.1.4 ! misho 576: .B --host-record
1.1 misho 577: and therefore be assigned more than one address. Only the first
578: address creates a PTR record linking the address to the name. This is
579: the same rule as is used reading hosts-files.
1.1.1.4 ! misho 580: .B --host-record
1.1 misho 581: options are considered to be read before host-files, so a name
582: appearing there inhibits PTR-record creation if it appears in
583: hosts-file also. Unlike hosts-files, names are not expanded, even when
1.1.1.4 ! misho 584: .B --expand-hosts
1.1 misho 585: is in effect. Short and long names may appear in the same
1.1.1.4 ! misho 586: .B --host-record,
1.1 misho 587: eg.
588: .B --host-record=laptop,laptop.thekelleys.org,192.168.0.1,1234::100
1.1.1.3 misho 589:
590: If the time-to-live is given, it overrides the default, which is zero
1.1.1.4 ! misho 591: or the value of \fB--local-ttl\fP. The value is a positive integer and gives
1.1.1.3 misho 592: the time-to-live in seconds.
1.1 misho 593: .TP
594: .B \-Y, --txt-record=<name>[[,<text>],<text>]
595: Return a TXT DNS record. The value of TXT record is a set of strings,
596: so any number may be included, delimited by commas; use quotes to put
597: commas into a string. Note that the maximum length of a single string
598: is 255 characters, longer strings are split into 255 character chunks.
599: .TP
600: .B --ptr-record=<name>[,<target>]
601: Return a PTR DNS record.
602: .TP
603: .B --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<regexp>[,<replacement>]
604: Return an NAPTR DNS record, as specified in RFC3403.
605: .TP
1.1.1.4 ! misho 606: .B --caa-record=<name>,<flags>,<tag>,<value>
! 607: Return a CAA DNS record, as specified in RFC6844.
! 608: .TP
! 609: .B --cname=<cname>,[<cname>,]<target>[,<TTL>]
1.1 misho 610: Return a CNAME record which indicates that <cname> is really
1.1.1.4 ! misho 611: <target>. There is a significant limitation on the target; it must be a
! 612: DNS record which is known to dnsmasq and NOT a DNS record which comes from
! 613: an upstream server. The cname must be unique, but it
! 614: is permissible to have more than one cname pointing to the same target. Indeed
! 615: it's possible to declare multiple cnames to a target in a single line, like so:
! 616: .B --cname=cname1,cname2,target
1.1.1.3 misho 617:
618: If the time-to-live is given, it overrides the default, which is zero
1.1.1.4 ! misho 619: or the value of \fB--local-ttl\fP. The value is a positive integer and gives
1.1.1.3 misho 620: the time-to-live in seconds.
1.1 misho 621: .TP
622: .B --dns-rr=<name>,<RR-number>,[<hex data>]
623: Return an arbitrary DNS Resource Record. The number is the type of the
624: record (which is always in the C_IN class). The value of the record is
625: given by the hex data, which may be of the form 01:23:45 or 01 23 45 or
626: 012345 or any mixture of these.
627: .TP
1.1.1.2 misho 628: .B --interface-name=<name>,<interface>[/4|/6]
1.1.1.4 ! misho 629: Return DNS records associating the name with the address(es) of
1.1.1.2 misho 630: the given interface. This flag specifies an A or AAAA record for the given
1.1 misho 631: name in the same way as an /etc/hosts line, except that the address is
1.1.1.2 misho 632: not constant, but taken from the given interface. The interface may be
633: followed by "/4" or "/6" to specify that only IPv4 or IPv6 addresses
634: of the interface should be used. If the interface is
1.1 misho 635: down, not configured or non-existent, an empty record is returned. The
636: matching PTR record is also created, mapping the interface address to
637: the name. More than one name may be associated with an interface
638: address by repeating the flag; in that case the first instance is used
1.1.1.4 ! misho 639: for the reverse address-to-name mapping. Note that a name used in
! 640: \fB--interface-name\fP may not appear in /etc/hosts.
1.1 misho 641: .TP
1.1.1.4 ! misho 642: .B --synth-domain=<domain>,<address range>[,<prefix>[*]]
1.1.1.2 misho 643: Create artificial A/AAAA and PTR records for an address range. The
1.1.1.4 ! misho 644: records either seqential numbers or the address, with periods (or colons for IPv6) replaced with dashes.
1.1.1.2 misho 645:
1.1.1.4 ! misho 646: An examples should make this clearer. First sequential numbers.
! 647: .B --synth-domain=thekelleys.org.uk,192.168.0.50,192.168.0.70,internal-*
! 648: results in the name internal-0.thekelleys.org.uk. returning 192.168.0.50, internal-1.thekelleys.org.uk returning 192.168.0.51 and so on. (note the *) The same principle applies to IPv6 addresses (where the numbers may be very large). Reverse lookups from address to name behave as expected.
! 649:
! 650: Second,
! 651: .B --synth-domain=thekelleys.org.uk,192.168.0.0/24,internal- (no *)
1.1.1.2 misho 652: will result in a query for internal-192-168-0-56.thekelleys.org.uk returning
653: 192.168.0.56 and a reverse query vice versa. The same applies to IPv6,
654: but IPv6 addresses may start with '::'
655: but DNS labels may not start with '-' so in this case if no prefix is
656: configured a zero is added in front of the label. ::1 becomes 0--1.
657:
1.1.1.4 ! misho 658: V4 mapped IPv6 addresses, which have a representation like ::ffff:1.2.3.4 are handled specially, and become like 0--ffff-1-2-3-4
! 659:
1.1.1.2 misho 660: The address range can be of the form
1.1.1.4 ! misho 661: <ip address>,<ip address> or <ip address>/<netmask> in both forms of the option.
! 662: .TP
! 663: .B --dumpfile=<path/to/file>
! 664: Specify the location of a pcap-format file which dnsmasq uses to dump copies of network packets for debugging purposes. If the file exists when dnsmasq starts, it is not deleted; new packets are added to the end.
! 665: .TP
! 666: .B --dumpmask=<mask>
! 667: Specify which types of packets should be added to the dumpfile. The argument should be the OR of the bitmasks for each type of packet to be dumped: it can be specified in hex by preceding the number with 0x in the normal way. Each time a packet is written to the dumpfile, dnsmasq logs the packet sequence and the mask
! 668: representing its type. The current types are: 0x0001 - DNS queries from clients 0x0002 DNS replies to clients 0x0004 - DNS queries to upstream 0x0008 - DNS replies from upstream 0x0010 - queries send upstream for DNSSEC validation 0x0020 - replies to queries for DNSSEC validation 0x0040 - replies to client queries which fail DNSSEC validation 0x0080 replies to queries for DNSSEC validation which fail validation.
1.1.1.2 misho 669: .TP
1.1.1.3 misho 670: .B --add-mac[=base64|text]
1.1 misho 671: Add the MAC address of the requestor to DNS queries which are
672: forwarded upstream. This may be used to DNS filtering by the upstream
673: server. The MAC address can only be added if the requestor is on the same
674: subnet as the dnsmasq server. Note that the mechanism used to achieve this (an EDNS0 option)
675: is not yet standardised, so this should be considered
676: experimental. Also note that exposing MAC addresses in this way may
1.1.1.2 misho 677: have security and privacy implications. The warning about caching
1.1.1.4 ! misho 678: given for \fB--add-subnet\fP applies to \fB--add-mac\fP too. An alternative encoding of the
1.1.1.3 misho 679: MAC, as base64, is enabled by adding the "base64" parameter and a human-readable encoding of hex-and-colons is enabled by added the "text" parameter.
680: .TP
681: .B --add-cpe-id=<string>
1.1.1.4 ! misho 682: Add an arbitrary identifying string to DNS queries which are
1.1.1.3 misho 683: forwarded upstream.
1.1.1.2 misho 684: .TP
1.1.1.3 misho 685: .B --add-subnet[[=[<IPv4 address>/]<IPv4 prefix length>][,[<IPv6 address>/]<IPv6 prefix length>]]
686: Add a subnet address to the DNS queries which are forwarded
687: upstream. If an address is specified in the flag, it will be used,
688: otherwise, the address of the requestor will be used. The amount of
689: the address forwarded depends on the prefix length parameter: 32 (128
690: for IPv6) forwards the whole address, zero forwards none of it but
691: still marks the request so that no upstream nameserver will add client
692: address information either. The default is zero for both IPv4 and
693: IPv6. Note that upstream nameservers may be configured to return
694: different results based on this information, but the dnsmasq cache
1.1.1.4 ! misho 695: does not take account. Caching is therefore disabled for such replies,
! 696: unless the subnet address being added is constant.
1.1.1.3 misho 697:
698: For example,
699: .B --add-subnet=24,96
700: will add the /24 and /96 subnets of the requestor for IPv4 and IPv6 requestors, respectively.
701: .B --add-subnet=1.2.3.4/24
702: will add 1.2.3.0/24 for IPv4 requestors and ::/0 for IPv6 requestors.
703: .B --add-subnet=1.2.3.4/24,1.2.3.4/24
704: will add 1.2.3.0/24 for both IPv4 and IPv6 requestors.
705:
1.1 misho 706: .TP
707: .B \-c, --cache-size=<cachesize>
1.1.1.4 ! misho 708: Set the size of dnsmasq's cache. The default is 150 names. Setting the cache size to zero disables caching. Note: huge cache size impacts performance.
1.1 misho 709: .TP
710: .B \-N, --no-negcache
711: Disable negative caching. Negative caching allows dnsmasq to remember
712: "no such domain" answers from upstream nameservers and answer
713: identical queries without forwarding them again.
714: .TP
715: .B \-0, --dns-forward-max=<queries>
716: Set the maximum number of concurrent DNS queries. The default value is
717: 150, which should be fine for most setups. The only known situation
718: where this needs to be increased is when using web-server log file
719: resolvers, which can generate large numbers of concurrent queries.
720: .TP
1.1.1.2 misho 721: .B --dnssec
722: Validate DNS replies and cache DNSSEC data. When forwarding DNS queries, dnsmasq requests the
723: DNSSEC records needed to validate the replies. The replies are validated and the result returned as
724: the Authenticated Data bit in the DNS packet. In addition the DNSSEC records are stored in the cache, making
725: validation by clients more efficient. Note that validation by clients is the most secure DNSSEC mode, but for
726: clients unable to do validation, use of the AD bit set by dnsmasq is useful, provided that the network between
727: the dnsmasq server and the client is trusted. Dnsmasq must be compiled with HAVE_DNSSEC enabled, and DNSSEC
728: trust anchors provided, see
729: .B --trust-anchor.
730: Because the DNSSEC validation process uses the cache, it is not
731: permitted to reduce the cache size below the default when DNSSEC is
732: enabled. The nameservers upstream of dnsmasq must be DNSSEC-capable,
733: ie capable of returning DNSSEC records with data. If they are not,
734: then dnsmasq will not be able to determine the trusted status of
1.1.1.4 ! misho 735: answers and this means that DNS service will be entirely broken.
1.1.1.2 misho 736: .TP
737: .B --trust-anchor=[<class>],<domain>,<key-tag>,<algorithm>,<digest-type>,<digest>
738: Provide DS records to act a trust anchors for DNSSEC
1.1.1.4 ! misho 739: validation. Typically these will be the DS record(s) for Key Signing
! 740: key(s) (KSK) of the root zone,
1.1.1.2 misho 741: but trust anchors for limited domains are also possible. The current
1.1.1.3 misho 742: root-zone trust anchors may be downloaded from https://data.iana.org/root-anchors/root-anchors.xml
1.1.1.2 misho 743: .TP
1.1.1.4 ! misho 744: .B --dnssec-check-unsigned[=no]
! 745: As a default, dnsmasq checks that unsigned DNS replies are
! 746: legitimate: this entails possible extra queries even for the majority of DNS
! 747: zones which are not, at the moment, signed. If
! 748: .B --dnssec-check-unsigned=no
! 749: appears in the configuration, then such replies they are assumed to be valid and passed on (without the
1.1.1.2 misho 750: "authentic data" bit set, of course). This does not protect against an
751: attacker forging unsigned replies for signed DNS zones, but it is
1.1.1.4 ! misho 752: fast.
! 753:
! 754: Versions of dnsmasq prior to 2.80 defaulted to not checking unsigned replies, and used
! 755: .B --dnssec-check-unsigned
! 756: to switch this on. Such configurations will continue to work as before, but those which used the default of no checking will need to be altered to explicitly select no checking. The new default is because switching off checking for unsigned replies is inherently dangerous. Not only does it open the possiblity of forged replies, but it allows everything to appear to be working even when the upstream namesevers do not support DNSSEC, and in this case no DNSSEC validation at all is occurring.
1.1.1.2 misho 757: .TP
758: .B --dnssec-no-timecheck
759: DNSSEC signatures are only valid for specified time windows, and should be rejected outside those windows. This generates an
760: interesting chicken-and-egg problem for machines which don't have a hardware real time clock. For these machines to determine the correct
761: time typically requires use of NTP and therefore DNS, but validating DNS requires that the correct time is already known. Setting this flag
1.1.1.4 ! misho 762: removes the time-window checks (but not other DNSSEC validation.) only until the dnsmasq process receives SIGINT. The intention is
1.1.1.2 misho 763: that dnsmasq should be started with this flag when the platform determines that reliable time is not currently available. As soon as
1.1.1.4 ! misho 764: reliable time is established, a SIGINT should be sent to dnsmasq, which enables time checking, and purges the cache of DNS records
! 765: which have not been thoroughly checked.
! 766:
! 767: Earlier versions of dnsmasq overloaded SIGHUP (which re-reads much configuration) to also enable time validation.
! 768:
! 769: If dnsmasq is run in debug mode (\fB--no-daemon\fP flag) then SIGINT retains its usual meaning of terminating the dnsmasq process.
1.1.1.2 misho 770: .TP
1.1.1.3 misho 771: .B --dnssec-timestamp=<path>
1.1.1.4 ! misho 772: Enables an alternative way of checking the validity of the system time for DNSSEC (see \fB--dnssec-no-timecheck\fP). In this case, the
1.1.1.3 misho 773: system time is considered to be valid once it becomes later than the timestamp on the specified file. The file is created and
774: its timestamp set automatically by dnsmasq. The file must be stored on a persistent filesystem, so that it and its mtime are carried
775: over system restarts. The timestamp file is created after dnsmasq has dropped root, so it must be in a location writable by the
776: unprivileged user that dnsmasq runs as.
777: .TP
1.1 misho 778: .B --proxy-dnssec
1.1.1.4 ! misho 779: Copy the DNSSEC Authenticated Data bit from upstream servers to downstream clients. This is an
1.1.1.2 misho 780: alternative to having dnsmasq validate DNSSEC, but it depends on the security of the network between
1.1.1.4 ! misho 781: dnsmasq and the upstream servers, and the trustworthiness of the upstream servers. Note that caching the
! 782: Authenticated Data bit correctly in all cases is not technically possible. If the AD bit is to be relied upon
! 783: when using this option, then the cache should be disabled using --cache-size=0. In most cases, enabling DNSSEC validation
! 784: within dnsmasq is a better option. See --dnssec for details.
1.1.1.2 misho 785: .TP
786: .B --dnssec-debug
787: Set debugging mode for the DNSSEC validation, set the Checking Disabled bit on upstream queries,
788: and don't convert replies which do not validate to responses with
789: a return code of SERVFAIL. Note that
790: setting this may affect DNS behaviour in bad ways, it is not an
791: extra-logging flag and should not be set in production.
1.1 misho 792: .TP
1.1.1.4 ! misho 793: .B --auth-zone=<domain>[,<subnet>[/<prefix length>][,<subnet>[/<prefix length>].....][,exclude:<subnet>[/<prefix length>]].....]
1.1 misho 794: Define a DNS zone for which dnsmasq acts as authoritative server. Locally defined DNS records which are in the domain
1.1.1.2 misho 795: will be served. If subnet(s) are given, A and AAAA records must be in one of the
796: specified subnets.
797:
798: As alternative to directly specifying the subnets, it's possible to
799: give the name of an interface, in which case the subnets implied by
800: that interface's configured addresses and netmask/prefix-length are
801: used; this is useful when using constructed DHCP ranges as the actual
802: address is dynamic and not known when configuring dnsmasq. The
803: interface addresses may be confined to only IPv6 addresses using
804: <interface>/6 or to only IPv4 using <interface>/4. This is useful when
805: an interface has dynamically determined global IPv6 addresses which should
806: appear in the zone, but RFC1918 IPv4 addresses which should not.
807: Interface-name and address-literal subnet specifications may be used
1.1.1.4 ! misho 808: freely in the same \fB--auth-zone\fP declaration.
! 809:
! 810: It's possible to exclude certain IP addresses from responses. It can be
! 811: used, to make sure that answers contain only global routeable IP
! 812: addresses (by excluding loopback, RFC1918 and ULA addresses).
1.1.1.2 misho 813:
814: The subnet(s) are also used to define in-addr.arpa and
815: ip6.arpa domains which are served for reverse-DNS queries. If not
816: specified, the prefix length defaults to 24 for IPv4 and 64 for IPv6.
817: For IPv4 subnets, the prefix length should be have the value 8, 16 or 24
818: unless you are familiar with RFC 2317 and have arranged the
819: in-addr.arpa delegation accordingly. Note that if no subnets are
820: specified, then no reverse queries are answered.
1.1 misho 821: .TP
822: .B --auth-soa=<serial>[,<hostmaster>[,<refresh>[,<retry>[,<expiry>]]]]
823: Specify fields in the SOA record associated with authoritative
824: zones. Note that this is optional, all the values are set to sane defaults.
825: .TP
826: .B --auth-sec-servers=<domain>[,<domain>[,<domain>...]]
827: Specify any secondary servers for a zone for which dnsmasq is
828: authoritative. These servers must be configured to get zone data from
829: dnsmasq by zone transfer, and answer queries for the same
830: authoritative zones as dnsmasq.
831: .TP
832: .B --auth-peer=<ip-address>[,<ip-address>[,<ip-address>...]]
833: Specify the addresses of secondary servers which are allowed to
834: initiate zone transfer (AXFR) requests for zones for which dnsmasq is
1.1.1.4 ! misho 835: authoritative. If this option is not given but --auth-sec-servers is,
! 836: then AXFR requests will be
! 837: accepted from any secondary. Specifying
! 838: .B --auth-peer
! 839: without
! 840: .B --auth-sec-servers
! 841: enables zone transfer but does not advertise the secondary in NS records returned by dnsmasq.
1.1 misho 842: .TP
843: .B --conntrack
844: Read the Linux connection track mark associated with incoming DNS
845: queries and set the same mark value on upstream traffic used to answer
846: those queries. This allows traffic generated by dnsmasq to be
847: associated with the queries which cause it, useful for bandwidth
848: accounting and firewalling. Dnsmasq must have conntrack support
849: compiled in and the kernel must have conntrack support
850: included and configured. This option cannot be combined with
1.1.1.4 ! misho 851: .B --query-port.
1.1 misho 852: .TP
1.1.1.3 misho 853: .B \-F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-addr>[,<end-addr>|<mode>][,<netmask>[,<broadcast>]][,<lease time>]
1.1 misho 854: .TP
855: .B \-F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-IPv6addr>[,<end-IPv6addr>|constructor:<interface>][,<mode>][,<prefix-len>][,<lease time>]
856:
857: Enable the DHCP server. Addresses will be given out from the range
858: <start-addr> to <end-addr> and from statically defined addresses given
859: in
1.1.1.4 ! misho 860: .B --dhcp-host
1.1 misho 861: options. If the lease time is given, then leases
862: will be given for that length of time. The lease time is in seconds,
863: or minutes (eg 45m) or hours (eg 1h) or "infinite". If not given,
1.1.1.4 ! misho 864: the default lease time is one hour for IPv4 and one day for IPv6. The
1.1 misho 865: minimum lease time is two minutes. For IPv6 ranges, the lease time
866: maybe "deprecated"; this sets the preferred lifetime sent in a DHCP
867: lease or router advertisement to zero, which causes clients to use
868: other addresses, if available, for new connections as a prelude to renumbering.
869:
870: This option may be repeated, with different addresses, to enable DHCP
871: service to more than one network. For directly connected networks (ie,
872: networks on which the machine running dnsmasq has an interface) the
873: netmask is optional: dnsmasq will determine it from the interface
874: configuration. For networks which receive DHCP service via a relay
875: agent, dnsmasq cannot determine the netmask itself, so it should be
876: specified, otherwise dnsmasq will have to guess, based on the class (A, B or
877: C) of the network address. The broadcast address is
878: always optional. It is always
1.1.1.4 ! misho 879: allowed to have more than one \fB--dhcp-range\fP in a single subnet.
1.1 misho 880:
881: For IPv6, the parameters are slightly different: instead of netmask
1.1.1.2 misho 882: and broadcast address, there is an optional prefix length which must
883: be equal to or larger then the prefix length on the local interface. If not
1.1 misho 884: given, this defaults to 64. Unlike the IPv4 case, the prefix length is not
1.1.1.4 ! misho 885: automatically derived from the interface configuration. The minimum
1.1 misho 886: size of the prefix length is 64.
887:
888: IPv6 (only) supports another type of range. In this, the start address and optional end address contain only the network part (ie ::1) and they are followed by
889: .B constructor:<interface>.
890: This forms a template which describes how to create ranges, based on the addresses assigned to the interface. For instance
891:
892: .B --dhcp-range=::1,::400,constructor:eth0
893:
1.1.1.2 misho 894: will look for addresses on
895: eth0 and then create a range from <network>::1 to <network>::400. If
896: the interface is assigned more than one network, then the
897: corresponding ranges will be automatically created, and then
898: deprecated and finally removed again as the address is deprecated and
899: then deleted. The interface name may have a final "*" wildcard. Note
900: that just any address on eth0 will not do: it must not be an
901: autoconfigured or privacy address, or be deprecated.
902:
1.1.1.4 ! misho 903: If a \fB--dhcp-range\fP is only being used for stateless DHCP and/or SLAAC,
1.1.1.2 misho 904: then the address can be simply ::
905:
906: .B --dhcp-range=::,constructor:eth0
907:
1.1 misho 908:
909: The optional
910: .B set:<tag>
911: sets an alphanumeric label which marks this network so that
1.1.1.4 ! misho 912: DHCP options may be specified on a per-network basis.
1.1 misho 913: When it is prefixed with 'tag:' instead, then its meaning changes from setting
914: a tag to matching it. Only one tag may be set, but more than one tag
915: may be matched.
916:
917: The optional <mode> keyword may be
918: .B static
919: which tells dnsmasq to enable DHCP for the network specified, but not
920: to dynamically allocate IP addresses: only hosts which have static
921: addresses given via
1.1.1.4 ! misho 922: .B --dhcp-host
1.1 misho 923: or from /etc/ethers will be served. A static-only subnet with address
924: all zeros may be used as a "catch-all" address to enable replies to all
925: Information-request packets on a subnet which is provided with
926: stateless DHCPv6, ie
1.1.1.2 misho 927: .B --dhcp-range=::,static
1.1 misho 928:
929: For IPv4, the <mode> may be
930: .B proxy
931: in which case dnsmasq will provide proxy-DHCP on the specified
932: subnet. (See
1.1.1.4 ! misho 933: .B --pxe-prompt
1.1 misho 934: and
1.1.1.4 ! misho 935: .B --pxe-service
1.1 misho 936: for details.)
937:
938: For IPv6, the mode may be some combination of
1.1.1.3 misho 939: .B ra-only, slaac, ra-names, ra-stateless, ra-advrouter, off-link.
1.1 misho 940:
941: .B ra-only
942: tells dnsmasq to offer Router Advertisement only on this subnet,
943: and not DHCP.
944:
945: .B slaac
946: tells dnsmasq to offer Router Advertisement on this subnet and to set
947: the A bit in the router advertisement, so that the client will use
948: SLAAC addresses. When used with a DHCP range or static DHCP address
949: this results in the client having both a DHCP-assigned and a SLAAC
950: address.
951:
952: .B ra-stateless
953: sends router advertisements with the O and A bits set, and provides a
954: stateless DHCP service. The client will use a SLAAC address, and use
955: DHCP for other configuration information.
956:
957: .B ra-names
958: enables a mode
959: which gives DNS names to dual-stack hosts which do SLAAC for
960: IPv6. Dnsmasq uses the host's IPv4 lease to derive the name, network
961: segment and MAC address and assumes that the host will also have an
962: IPv6 address calculated using the SLAAC algorithm, on the same network
963: segment. The address is pinged, and if a reply is received, an AAAA
964: record is added to the DNS for this IPv6
965: address. Note that this is only happens for directly-connected
966: networks, (not one doing DHCP via a relay) and it will not work
967: if a host is using privacy extensions.
968: .B ra-names
969: can be combined with
970: .B ra-stateless
971: and
972: .B slaac.
973:
1.1.1.3 misho 974: .B ra-advrouter
975: enables a mode where router address(es) rather than prefix(es) are included in the advertisements.
976: This is described in RFC-3775 section 7.2 and is used in mobile IPv6. In this mode the interval option
977: is also included, as described in RFC-3775 section 7.3.
978:
979: .B off-link
980: tells dnsmasq to advertise the prefix without the on-link (aka L) bit set.
981:
1.1 misho 982: .TP
1.1.1.4 ! misho 983: .B \-G, --dhcp-host=[<hwaddr>][,id:<client_id>|*][,set:<tag>][tag:<tag>][,<ipaddr>][,<hostname>][,<lease_time>][,ignore]
1.1 misho 984: Specify per host parameters for the DHCP server. This allows a machine
985: with a particular hardware address to be always allocated the same
986: hostname, IP address and lease time. A hostname specified like this
987: overrides any supplied by the DHCP client on the machine. It is also
988: allowable to omit the hardware address and include the hostname, in
989: which case the IP address and lease times will apply to any machine
990: claiming that name. For example
991: .B --dhcp-host=00:20:e0:3b:13:af,wap,infinite
992: tells dnsmasq to give
993: the machine with hardware address 00:20:e0:3b:13:af the name wap, and
994: an infinite DHCP lease.
995: .B --dhcp-host=lap,192.168.0.199
996: tells
997: dnsmasq to always allocate the machine lap the IP address
998: 192.168.0.199.
999:
1000: Addresses allocated like this are not constrained to be
1.1.1.4 ! misho 1001: in the range given by the \fB--dhcp-range\fP option, but they must be in
1.1 misho 1002: the same subnet as some valid dhcp-range. For
1003: subnets which don't need a pool of dynamically allocated addresses,
1.1.1.4 ! misho 1004: use the "static" keyword in the \fB--dhcp-range\fP declaration.
1.1 misho 1005:
1.1.1.2 misho 1006: It is allowed to use client identifiers (called client
1.1.1.4 ! misho 1007: DUID in IPv6-land) rather than
1.1 misho 1008: hardware addresses to identify hosts by prefixing with 'id:'. Thus:
1009: .B --dhcp-host=id:01:02:03:04,.....
1010: refers to the host with client identifier 01:02:03:04. It is also
1011: allowed to specify the client ID as text, like this:
1012: .B --dhcp-host=id:clientidastext,.....
1013:
1014: A single
1.1.1.4 ! misho 1015: .B --dhcp-host
! 1016: may contain an IPv4 address or one or more IPv6 addresses, or both. IPv6 addresses must be bracketed by square brackets thus:
1.1 misho 1017: .B --dhcp-host=laptop,[1234::56]
1018: IPv6 addresses may contain only the host-identifier part:
1019: .B --dhcp-host=laptop,[::56]
1.1.1.4 ! misho 1020: in which case they act as wildcards in constructed DHCP ranges, with
! 1021: the appropriate network part inserted. For IPv6, an address may include a prefix length:
! 1022: .B --dhcp-host=laptop,[1234:50/126]
! 1023: which (in this case) specifies four addresses, 1234::50 to 1234::53. This (an the ability
! 1024: to specify multiple addresses) is useful
! 1025: when a host presents either a consistent name or hardware-ID, but varying DUIDs, since it allows
! 1026: dnsmasq to honour the static address allocation but assign a different adddress for each DUID. This
! 1027: typically occurs when chain netbooting, as each stage of the chain gets in turn allocates an address.
! 1028:
1.1.1.2 misho 1029: Note that in IPv6 DHCP, the hardware address may not be
1030: available, though it normally is for direct-connected clients, or
1031: clients using DHCP relays which support RFC 6939.
1.1 misho 1032:
1.1.1.2 misho 1033:
1034: For DHCPv4, the special option id:* means "ignore any client-id
1.1 misho 1035: and use MAC addresses only." This is useful when a client presents a client-id sometimes
1036: but not others.
1037:
1038: If a name appears in /etc/hosts, the associated address can be
1039: allocated to a DHCP lease, but only if a
1040: .B --dhcp-host
1041: option specifying the name also exists. Only one hostname can be
1042: given in a
1.1.1.4 ! misho 1043: .B --dhcp-host
1.1 misho 1044: option, but aliases are possible by using CNAMEs. (See
1045: .B --cname
1046: ).
1047:
1048: The special keyword "ignore"
1049: tells dnsmasq to never offer a DHCP lease to a machine. The machine
1050: can be specified by hardware address, client ID or hostname, for
1051: instance
1052: .B --dhcp-host=00:20:e0:3b:13:af,ignore
1053: This is
1054: useful when there is another DHCP server on the network which should
1055: be used by some machines.
1056:
1.1.1.2 misho 1057: The set:<tag> construct sets the tag
1.1.1.4 ! misho 1058: whenever this \fB--dhcp-host\fP directive is in use. This can be used to
1.1 misho 1059: selectively send DHCP options just for this host. More than one tag
1.1.1.4 ! misho 1060: can be set in a \fB--dhcp-host\fP directive (but not in other places where
1.1 misho 1061: "set:<tag>" is allowed). When a host matches any
1.1.1.4 ! misho 1062: \fB--dhcp-host\fP directive (or one implied by /etc/ethers) then the special
1.1 misho 1063: tag "known" is set. This allows dnsmasq to be configured to
1064: ignore requests from unknown machines using
1065: .B --dhcp-ignore=tag:!known
1.1.1.4 ! misho 1066: If the host matches only a \fB--dhcp-host\fP directive which cannot
! 1067: be used because it specifies an address on different subnet, the tag "known-othernet" is set.
! 1068:
! 1069: The tag:<tag> construct filters which dhcp-host directives are used. Tagged directives are used in preference to untagged ones.
! 1070:
1.1 misho 1071: Ethernet addresses (but not client-ids) may have
1072: wildcard bytes, so for example
1073: .B --dhcp-host=00:20:e0:3b:13:*,ignore
1074: will cause dnsmasq to ignore a range of hardware addresses. Note that
1075: the "*" will need to be escaped or quoted on a command line, but not
1076: in the configuration file.
1077:
1078: Hardware addresses normally match any
1079: network (ARP) type, but it is possible to restrict them to a single
1080: ARP type by preceding them with the ARP-type (in HEX) and "-". so
1081: .B --dhcp-host=06-00:20:e0:3b:13:af,1.2.3.4
1082: will only match a
1083: Token-Ring hardware address, since the ARP-address type for token ring
1084: is 6.
1085:
1086: As a special case, in DHCPv4, it is possible to include more than one
1087: hardware address. eg:
1088: .B --dhcp-host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2
1089: This allows an IP address to be associated with
1090: multiple hardware addresses, and gives dnsmasq permission to abandon a
1091: DHCP lease to one of the hardware addresses when another one asks for
1092: a lease. Beware that this is a dangerous thing to do, it will only
1093: work reliably if only one of the hardware addresses is active at any
1094: time and there is no way for dnsmasq to enforce this. It is, for instance,
1095: useful to allocate a stable IP address to a laptop which
1096: has both wired and wireless interfaces.
1097: .TP
1098: .B --dhcp-hostsfile=<path>
1099: Read DHCP host information from the specified file. If a directory
1100: is given, then read all the files contained in that directory. The file contains
1101: information about one host per line. The format of a line is the same
1.1.1.4 ! misho 1102: as text to the right of '=' in \fB--dhcp-host\fP. The advantage of storing DHCP host information
1.1 misho 1103: in this file is that it can be changed without re-starting dnsmasq:
1104: the file will be re-read when dnsmasq receives SIGHUP.
1105: .TP
1106: .B --dhcp-optsfile=<path>
1107: Read DHCP option information from the specified file. If a directory
1108: is given, then read all the files contained in that directory. The advantage of
1.1.1.4 ! misho 1109: using this option is the same as for \fB--dhcp-hostsfile\fP: the
! 1110: \fB--dhcp-optsfile\fP will be re-read when dnsmasq receives SIGHUP. Note that
1.1 misho 1111: it is possible to encode the information in a
1.1.1.4 ! misho 1112: .B --dhcp-boot
! 1113: flag as DHCP options, using the options names bootfile-name,
! 1114: server-ip-address and tftp-server. This allows these to be included
! 1115: in a \fB--dhcp-optsfile\fP.
1.1.1.3 misho 1116: .TP
1117: .B --dhcp-hostsdir=<path>
1.1.1.4 ! misho 1118: This is equivalent to \fB--dhcp-hostsfile\fP, except for the following. The path MUST be a
1.1.1.3 misho 1119: directory, and not an individual file. Changed or new files within
1120: the directory are read automatically, without the need to send SIGHUP.
1.1.1.4 ! misho 1121: If a file is deleted or changed after it has been read by dnsmasq, then the
! 1122: host record it contained will remain until dnsmasq receives a SIGHUP, or
1.1.1.3 misho 1123: is restarted; ie host records are only added dynamically.
1124: .TP
1125: .B --dhcp-optsdir=<path>
1.1.1.4 ! misho 1126: This is equivalent to \fB--dhcp-optsfile\fP, with the differences noted for \fB--dhcp-hostsdir\fP.
1.1 misho 1127: .TP
1128: .B \-Z, --read-ethers
1129: Read /etc/ethers for information about hosts for the DHCP server. The
1130: format of /etc/ethers is a hardware address, followed by either a
1131: hostname or dotted-quad IP address. When read by dnsmasq these lines
1132: have exactly the same effect as
1133: .B --dhcp-host
1134: options containing the same information. /etc/ethers is re-read when
1135: dnsmasq receives SIGHUP. IPv6 addresses are NOT read from /etc/ethers.
1136: .TP
1137: .B \-O, --dhcp-option=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<enterprise>,][vendor:[<vendor-class>],][<opt>|option:<opt-name>|option6:<opt>|option6:<opt-name>],[<value>[,<value>]]
1138: Specify different or extra options to DHCP clients. By default,
1139: dnsmasq sends some standard options to DHCP clients, the netmask and
1140: broadcast address are set to the same as the host running dnsmasq, and
1141: the DNS server and default route are set to the address of the machine
1142: running dnsmasq. (Equivalent rules apply for IPv6.) If the domain name option has been set, that is sent.
1143: This configuration allows these defaults to be overridden,
1144: or other options specified. The option, to be sent may be given as a
1145: decimal number or as "option:<option-name>" The option numbers are
1146: specified in RFC2132 and subsequent RFCs. The set of option-names
1147: known by dnsmasq can be discovered by running "dnsmasq --help dhcp".
1148: For example, to set the default route option to
1149: 192.168.4.4, do
1150: .B --dhcp-option=3,192.168.4.4
1151: or
1152: .B --dhcp-option = option:router, 192.168.4.4
1153: and to set the time-server address to 192.168.0.4, do
1154: .B --dhcp-option = 42,192.168.0.4
1155: or
1156: .B --dhcp-option = option:ntp-server, 192.168.0.4
1.1.1.2 misho 1157: The special address 0.0.0.0 is taken to mean "the address of the
1158: machine running dnsmasq".
1159:
1160: Data types allowed are comma separated
1161: dotted-quad IPv4 addresses, []-wrapped IPv6 addresses, a decimal number, colon-separated hex digits
1.1 misho 1162: and a text string. If the optional tags are given then
1163: this option is only sent when all the tags are matched.
1164:
1165: Special processing is done on a text argument for option 119, to
1166: conform with RFC 3397. Text or dotted-quad IP addresses as arguments
1167: to option 120 are handled as per RFC 3361. Dotted-quad IP addresses
1168: which are followed by a slash and then a netmask size are encoded as
1169: described in RFC 3442.
1170:
1171: IPv6 options are specified using the
1172: .B option6:
1173: keyword, followed by the option number or option name. The IPv6 option
1174: name space is disjoint from the IPv4 option name space. IPv6 addresses
1175: in options must be bracketed with square brackets, eg.
1176: .B --dhcp-option=option6:ntp-server,[1234::56]
1.1.1.2 misho 1177: For IPv6, [::] means "the global address of
1178: the machine running dnsmasq", whilst [fd00::] is replaced with the
1179: ULA, if it exists, and [fe80::] with the link-local address.
1.1 misho 1180:
1181: Be careful: no checking is done that the correct type of data for the
1182: option number is sent, it is quite possible to
1183: persuade dnsmasq to generate illegal DHCP packets with injudicious use
1184: of this flag. When the value is a decimal number, dnsmasq must determine how
1185: large the data item is. It does this by examining the option number and/or the
1186: value, but can be overridden by appending a single letter flag as follows:
1187: b = one byte, s = two bytes, i = four bytes. This is mainly useful with
1188: encapsulated vendor class options (see below) where dnsmasq cannot
1189: determine data size from the option number. Option data which
1190: consists solely of periods and digits will be interpreted by dnsmasq
1191: as an IP address, and inserted into an option as such. To force a
1192: literal string, use quotes. For instance when using option 66 to send
1193: a literal IP address as TFTP server name, it is necessary to do
1194: .B --dhcp-option=66,"1.2.3.4"
1195:
1196: Encapsulated Vendor-class options may also be specified (IPv4 only) using
1.1.1.4 ! misho 1197: \fB--dhcp-option\fP: for instance
1.1 misho 1198: .B --dhcp-option=vendor:PXEClient,1,0.0.0.0
1199: sends the encapsulated vendor
1200: class-specific option "mftp-address=0.0.0.0" to any client whose
1201: vendor-class matches "PXEClient". The vendor-class matching is
1.1.1.4 ! misho 1202: substring based (see \fB--dhcp-vendorclass\fP for details). If a
1.1 misho 1203: vendor-class option (number 60) is sent by dnsmasq, then that is used
1204: for selecting encapsulated options in preference to any sent by the
1205: client. It is
1206: possible to omit the vendorclass completely;
1207: .B --dhcp-option=vendor:,1,0.0.0.0
1208: in which case the encapsulated option is always sent.
1209:
1210: Options may be encapsulated (IPv4 only) within other options: for instance
1211: .B --dhcp-option=encap:175, 190, "iscsi-client0"
1212: will send option 175, within which is the option 190. If multiple
1213: options are given which are encapsulated with the same option number
1214: then they will be correctly combined into one encapsulated option.
1.1.1.4 ! misho 1215: encap: and vendor: are may not both be set in the same \fB--dhcp-option\fP.
1.1 misho 1216:
1217: The final variant on encapsulated options is "Vendor-Identifying
1218: Vendor Options" as specified by RFC3925. These are denoted like this:
1219: .B --dhcp-option=vi-encap:2, 10, "text"
1220: The number in the vi-encap: section is the IANA enterprise number
1221: used to identify this option. This form of encapsulation is supported
1222: in IPv6.
1223:
1224: The address 0.0.0.0 is not treated specially in
1225: encapsulated options.
1226: .TP
1227: .B --dhcp-option-force=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<enterprise>,][vendor:[<vendor-class>],]<opt>,[<value>[,<value>]]
1228: This works in exactly the same way as
1229: .B --dhcp-option
1230: except that the option will always be sent, even if the client does
1231: not ask for it in the parameter request list. This is sometimes
1232: needed, for example when sending options to PXELinux.
1233: .TP
1234: .B --dhcp-no-override
1235: (IPv4 only) Disable re-use of the DHCP servername and filename fields as extra
1236: option space. If it can, dnsmasq moves the boot server and filename
1.1.1.4 ! misho 1237: information (from \fB--dhcp-boot\fP) out of their dedicated fields into
1.1 misho 1238: DHCP options. This make extra space available in the DHCP packet for
1239: options but can, rarely, confuse old or broken clients. This flag
1240: forces "simple and safe" behaviour to avoid problems in such a case.
1241: .TP
1.1.1.2 misho 1242: .B --dhcp-relay=<local address>,<server address>[,<interface]
1243: Configure dnsmasq to do DHCP relay. The local address is an address
1244: allocated to an interface on the host running dnsmasq. All DHCP
1245: requests arriving on that interface will we relayed to a remote DHCP
1246: server at the server address. It is possible to relay from a single local
1.1.1.4 ! misho 1247: address to multiple remote servers by using multiple \fB--dhcp-relay\fP
1.1.1.2 misho 1248: configs with the same local address and different server
1249: addresses. A server address must be an IP literal address, not a
1250: domain name. In the case of DHCPv6, the server address may be the
1251: ALL_SERVERS multicast address, ff05::1:3. In this case the interface
1252: must be given, not be wildcard, and is used to direct the multicast to the
1253: correct interface to reach the DHCP server.
1254:
1255: Access control for DHCP clients has the same rules as for the DHCP
1.1.1.4 ! misho 1256: server, see \fB--interface\fP, \fB--except-interface\fP, etc. The optional
! 1257: interface name in the \fB--dhcp-relay\fP config has a different function: it
1.1.1.2 misho 1258: controls on which interface DHCP replies from the server will be
1259: accepted. This is intended for configurations which have three
1260: interfaces: one being relayed from, a second connecting the DHCP
1261: server, and a third untrusted network, typically the wider
1262: internet. It avoids the possibility of spoof replies arriving via this
1263: third interface.
1264:
1265: It is allowed to have dnsmasq act as a DHCP server on one set of
1266: interfaces and relay from a disjoint set of interfaces. Note that
1267: whilst it is quite possible to write configurations which appear to
1268: act as a server and a relay on the same interface, this is not
1269: supported: the relay function will take precedence.
1270:
1271: Both DHCPv4 and DHCPv6 relay is supported. It's not possible to relay
1272: DHCPv4 to a DHCPv6 server or vice-versa.
1273: .TP
1.1 misho 1274: .B \-U, --dhcp-vendorclass=set:<tag>,[enterprise:<IANA-enterprise number>,]<vendor-class>
1275: Map from a vendor-class string to a tag. Most DHCP clients provide a
1276: "vendor class" which represents, in some sense, the type of host. This option
1277: maps vendor classes to tags, so that DHCP options may be selectively delivered
1278: to different classes of hosts. For example
1.1.1.4 ! misho 1279: .B --dhcp-vendorclass=set:printers,Hewlett-Packard JetDirect
1.1 misho 1280: will allow options to be set only for HP printers like so:
1281: .B --dhcp-option=tag:printers,3,192.168.4.4
1282: The vendor-class string is
1283: substring matched against the vendor-class supplied by the client, to
1284: allow fuzzy matching. The set: prefix is optional but allowed for
1285: consistency.
1286:
1287: Note that in IPv6 only, vendorclasses are namespaced with an
1288: IANA-allocated enterprise number. This is given with enterprise:
1289: keyword and specifies that only vendorclasses matching the specified
1290: number should be searched.
1291: .TP
1292: .B \-j, --dhcp-userclass=set:<tag>,<user-class>
1293: Map from a user-class string to a tag (with substring
1294: matching, like vendor classes). Most DHCP clients provide a
1295: "user class" which is configurable. This option
1296: maps user classes to tags, so that DHCP options may be selectively delivered
1297: to different classes of hosts. It is possible, for instance to use
1298: this to set a different printer server for hosts in the class
1299: "accounts" than for hosts in the class "engineering".
1300: .TP
1301: .B \-4, --dhcp-mac=set:<tag>,<MAC address>
1.1.1.2 misho 1302: Map from a MAC address to a tag. The MAC address may include
1.1 misho 1303: wildcards. For example
1304: .B --dhcp-mac=set:3com,01:34:23:*:*:*
1305: will set the tag "3com" for any host whose MAC address matches the pattern.
1306: .TP
1307: .B --dhcp-circuitid=set:<tag>,<circuit-id>, --dhcp-remoteid=set:<tag>,<remote-id>
1308: Map from RFC3046 relay agent options to tags. This data may
1309: be provided by DHCP relay agents. The circuit-id or remote-id is
1310: normally given as colon-separated hex, but is also allowed to be a
1311: simple string. If an exact match is achieved between the circuit or
1312: agent ID and one provided by a relay agent, the tag is set.
1313:
1.1.1.4 ! misho 1314: .B --dhcp-remoteid
! 1315: (but not \fB--dhcp-circuitid\fP) is supported in IPv6.
1.1 misho 1316: .TP
1317: .B --dhcp-subscrid=set:<tag>,<subscriber-id>
1318: (IPv4 and IPv6) Map from RFC3993 subscriber-id relay agent options to tags.
1319: .TP
1320: .B --dhcp-proxy[=<ip addr>]......
1321: (IPv4 only) A normal DHCP relay agent is only used to forward the initial parts of
1322: a DHCP interaction to the DHCP server. Once a client is configured, it
1323: communicates directly with the server. This is undesirable if the
1.1.1.2 misho 1324: relay agent is adding extra information to the DHCP packets, such as
1.1 misho 1325: that used by
1.1.1.4 ! misho 1326: .B --dhcp-circuitid
1.1 misho 1327: and
1.1.1.4 ! misho 1328: .B --dhcp-remoteid.
1.1 misho 1329: A full relay implementation can use the RFC 5107 serverid-override
1330: option to force the DHCP server to use the relay as a full proxy, with all
1331: packets passing through it. This flag provides an alternative method
1332: of doing the same thing, for relays which don't support RFC
1333: 5107. Given alone, it manipulates the server-id for all interactions
1334: via relays. If a list of IP addresses is given, only interactions via
1335: relays at those addresses are affected.
1336: .TP
1337: .B --dhcp-match=set:<tag>,<option number>|option:<option name>|vi-encap:<enterprise>[,<value>]
1338: Without a value, set the tag if the client sends a DHCP
1339: option of the given number or name. When a value is given, set the tag only if
1340: the option is sent and matches the value. The value may be of the form
1.1.1.2 misho 1341: "01:ff:*:02" in which case the value must match (apart from wildcards)
1.1 misho 1342: but the option sent may have unmatched data past the end of the
1343: value. The value may also be of the same form as in
1.1.1.4 ! misho 1344: .B --dhcp-option
1.1 misho 1345: in which case the option sent is treated as an array, and one element
1346: must match, so
1.1.1.4 ! misho 1347: .B --dhcp-match=set:efi-ia32,option:client-arch,6
1.1 misho 1348: will set the tag "efi-ia32" if the the number 6 appears in the list of
1349: architectures sent by the client in option 93. (See RFC 4578 for
1350: details.) If the value is a string, substring matching is used.
1351:
1.1.1.2 misho 1352: The special form with vi-encap:<enterprise number> matches against
1.1 misho 1353: vendor-identifying vendor classes for the specified enterprise. Please
1354: see RFC 3925 for more details of these rare and interesting beasts.
1355: .TP
1.1.1.4 ! misho 1356: .B --dhcp-name-match=set:<tag>,<name>[*]
! 1357: Set the tag if the given name is supplied by a DHCP client. There may be a single trailing wildcard *, which has the usual meaning. Combined with dhcp-ignore or dhcp-ignore-names this gives the ability to ignore certain clients by name, or disallow certain hostnames from being claimed by a client.
! 1358: .TP
1.1 misho 1359: .B --tag-if=set:<tag>[,set:<tag>[,tag:<tag>[,tag:<tag>]]]
1360: Perform boolean operations on tags. Any tag appearing as set:<tag> is set if
1361: all the tags which appear as tag:<tag> are set, (or unset when tag:!<tag> is used)
1362: If no tag:<tag> appears set:<tag> tags are set unconditionally.
1363: Any number of set: and tag: forms may appear, in any order.
1.1.1.4 ! misho 1364: \fB--tag-if\fP lines are executed in order, so if the tag in tag:<tag> is a
1.1 misho 1365: tag set by another
1.1.1.4 ! misho 1366: .B --tag-if,
1.1 misho 1367: the line which sets the tag must precede the one which tests it.
1368: .TP
1369: .B \-J, --dhcp-ignore=tag:<tag>[,tag:<tag>]
1370: When all the given tags appear in the tag set ignore the host and do
1371: not allocate it a DHCP lease.
1372: .TP
1373: .B --dhcp-ignore-names[=tag:<tag>[,tag:<tag>]]
1374: When all the given tags appear in the tag set, ignore any hostname
1.1.1.4 ! misho 1375: provided by the host. Note that, unlike \fB--dhcp-ignore\fP, it is permissible
1.1 misho 1376: to supply no tags, in which case DHCP-client supplied hostnames
1377: are always ignored, and DHCP hosts are added to the DNS using only
1.1.1.4 ! misho 1378: \fB--dhcp-host\fP configuration in dnsmasq and the contents of /etc/hosts and
1.1 misho 1379: /etc/ethers.
1380: .TP
1381: .B --dhcp-generate-names=tag:<tag>[,tag:<tag>]
1382: (IPv4 only) Generate a name for DHCP clients which do not otherwise have one,
1.1.1.2 misho 1383: using the MAC address expressed in hex, separated by dashes. Note that
1.1 misho 1384: if a host provides a name, it will be used by preference to this,
1385: unless
1386: .B --dhcp-ignore-names
1387: is set.
1388: .TP
1389: .B --dhcp-broadcast[=tag:<tag>[,tag:<tag>]]
1390: (IPv4 only) When all the given tags appear in the tag set, always use broadcast to
1391: communicate with the host when it is unconfigured. It is permissible
1392: to supply no tags, in which case this is unconditional. Most DHCP clients which
1393: need broadcast replies set a flag in their requests so that this
1394: happens automatically, some old BOOTP clients do not.
1395: .TP
1396: .B \-M, --dhcp-boot=[tag:<tag>,]<filename>,[<servername>[,<server address>|<tftp_servername>]]
1397: (IPv4 only) Set BOOTP options to be returned by the DHCP server. Server name and
1398: address are optional: if not provided, the name is left empty, and the
1399: address set to the address of the machine running dnsmasq. If dnsmasq
1400: is providing a TFTP service (see
1401: .B --enable-tftp
1402: ) then only the filename is required here to enable network booting.
1403: If the optional tag(s) are given,
1404: they must match for this configuration to be sent.
1405: Instead of an IP address, the TFTP server address can be given as a domain
1406: name which is looked up in /etc/hosts. This name can be associated in
1407: /etc/hosts with multiple IP addresses, which are used round-robin.
1408: This facility can be used to load balance the tftp load among a set of servers.
1409: .TP
1410: .B --dhcp-sequential-ip
1411: Dnsmasq is designed to choose IP addresses for DHCP clients using a
1412: hash of the client's MAC address. This normally allows a client's
1413: address to remain stable long-term, even if the client sometimes allows its DHCP
1414: lease to expire. In this default mode IP addresses are distributed
1415: pseudo-randomly over the entire available address range. There are
1416: sometimes circumstances (typically server deployment) where it is more
1417: convenient to have IP
1418: addresses allocated sequentially, starting from the lowest available
1419: address, and setting this flag enables this mode. Note that in the
1420: sequential mode, clients which allow a lease to expire are much more
1421: likely to move IP address; for this reason it should not be generally used.
1422: .TP
1.1.1.4 ! misho 1423: .B --dhcp-ignore-clid
! 1424: Dnsmasq is reading 'client identifier' (RFC 2131) option sent by clients
! 1425: (if available) to identify clients. This allow to serve same IP address
! 1426: for a host using several interfaces. Use this option to disable 'client identifier'
! 1427: reading, i.e. to always identify a host using the MAC address.
! 1428: .TP
1.1 misho 1429: .B --pxe-service=[tag:<tag>,]<CSA>,<menu text>[,<basename>|<bootservicetype>][,<server address>|<server_name>]
1430: Most uses of PXE boot-ROMS simply allow the PXE
1431: system to obtain an IP address and then download the file specified by
1.1.1.4 ! misho 1432: .B --dhcp-boot
1.1 misho 1433: and execute it. However the PXE system is capable of more complex
1434: functions when supported by a suitable DHCP server.
1435:
1436: This specifies a boot option which may appear in a PXE boot menu. <CSA> is
1437: client system type, only services of the correct type will appear in a
1438: menu. The known types are x86PC, PC98, IA64_EFI, Alpha, Arc_x86,
1.1.1.3 misho 1439: Intel_Lean_Client, IA32_EFI, X86-64_EFI, Xscale_EFI, BC_EFI, ARM32_EFI and ARM64_EFI; an
1.1 misho 1440: integer may be used for other types. The
1441: parameter after the menu text may be a file name, in which case dnsmasq acts as a
1442: boot server and directs the PXE client to download the file by TFTP,
1443: either from itself (
1.1.1.4 ! misho 1444: .B --enable-tftp
1.1 misho 1445: must be set for this to work) or another TFTP server if the final server
1446: address/name is given.
1447: Note that the "layer"
1.1.1.3 misho 1448: suffix (normally ".0") is supplied by PXE, and need not be added to
1449: the basename. Alternatively, the basename may be a filename, complete with suffix, in which case
1450: no layer suffix is added. If an integer boot service type, rather than a basename
1.1 misho 1451: is given, then the PXE client will search for a
1452: suitable boot service for that type on the network. This search may be done
1453: by broadcast, or direct to a server if its IP address/name is provided.
1454: If no boot service type or filename is provided (or a boot service type of 0 is specified)
1455: then the menu entry will abort the net boot procedure and
1456: continue booting from local media. The server address can be given as a domain
1457: name which is looked up in /etc/hosts. This name can be associated in
1458: /etc/hosts with multiple IP addresses, which are used round-robin.
1459: .TP
1460: .B --pxe-prompt=[tag:<tag>,]<prompt>[,<timeout>]
1461: Setting this provides a prompt to be displayed after PXE boot. If the
1462: timeout is given then after the
1463: timeout has elapsed with no keyboard input, the first available menu
1464: option will be automatically executed. If the timeout is zero then the first available menu
1465: item will be executed immediately. If
1.1.1.4 ! misho 1466: .B --pxe-prompt
1.1.1.2 misho 1467: is omitted the system will wait for user input if there are multiple
1.1 misho 1468: items in the menu, but boot immediately if
1469: there is only one. See
1.1.1.4 ! misho 1470: .B --pxe-service
1.1 misho 1471: for details of menu items.
1472:
1473: Dnsmasq supports PXE "proxy-DHCP", in this case another DHCP server on
1474: the network is responsible for allocating IP addresses, and dnsmasq
1475: simply provides the information given in
1.1.1.4 ! misho 1476: .B --pxe-prompt
1.1 misho 1477: and
1.1.1.4 ! misho 1478: .B --pxe-service
1.1 misho 1479: to allow netbooting. This mode is enabled using the
1480: .B proxy
1481: keyword in
1.1.1.4 ! misho 1482: .B --dhcp-range.
! 1483: .TP
! 1484: .B --dhcp-pxe-vendor=<vendor>[,...]
! 1485: According to UEFI and PXE specifications, DHCP packets between PXE clients and
! 1486: proxy PXE servers should have
! 1487: .I PXEClient
! 1488: in their vendor-class field. However, the firmware of computers from a few
! 1489: vendors is customized to carry a different identifier in that field. This option
! 1490: is used to consider such identifiers valid for identifying PXE clients. For
! 1491: instance
! 1492:
! 1493: .B --dhcp-pxe-vendor=PXEClient,HW-Client
! 1494:
! 1495: will enable dnsmasq to also provide proxy PXE service to those PXE clients with
! 1496: .I HW-Client
! 1497: in as their identifier.
! 1498: >>>>>>> 907def3... pxe: support pxe clients with custom vendor-class
1.1 misho 1499: .TP
1500: .B \-X, --dhcp-lease-max=<number>
1501: Limits dnsmasq to the specified maximum number of DHCP leases. The
1502: default is 1000. This limit is to prevent DoS attacks from hosts which
1503: create thousands of leases and use lots of memory in the dnsmasq
1504: process.
1505: .TP
1506: .B \-K, --dhcp-authoritative
1507: Should be set when dnsmasq is definitely the only DHCP server on a network.
1508: For DHCPv4, it changes the behaviour from strict RFC compliance so that DHCP requests on
1509: unknown leases from unknown hosts are not ignored. This allows new hosts
1510: to get a lease without a tedious timeout under all circumstances. It also
1511: allows dnsmasq to rebuild its lease database without each client needing to
1512: reacquire a lease, if the database is lost. For DHCPv6 it sets the
1513: priority in replies to 255 (the maximum) instead of 0 (the minimum).
1514: .TP
1.1.1.4 ! misho 1515: .B --dhcp-rapid-commit
! 1516: Enable DHCPv4 Rapid Commit Option specified in RFC 4039. When enabled, dnsmasq
! 1517: will respond to a DHCPDISCOVER message including a Rapid Commit
! 1518: option with a DHCPACK including a Rapid Commit option and fully committed
! 1519: address and configuration information. Should only be enabled if either the
! 1520: server is the only server for the subnet, or multiple servers are present and they each commit a binding for all clients.
! 1521: .TP
1.1 misho 1522: .B --dhcp-alternate-port[=<server port>[,<client port>]]
1523: (IPv4 only) Change the ports used for DHCP from the default. If this option is
1524: given alone, without arguments, it changes the ports used for DHCP
1525: from 67 and 68 to 1067 and 1068. If a single argument is given, that
1526: port number is used for the server and the port number plus one used
1527: for the client. Finally, two port numbers allows arbitrary
1528: specification of both server and client ports for DHCP.
1529: .TP
1530: .B \-3, --bootp-dynamic[=<network-id>[,<network-id>]]
1531: (IPv4 only) Enable dynamic allocation of IP addresses to BOOTP clients. Use this
1532: with care, since each address allocated to a BOOTP client is leased
1533: forever, and therefore becomes permanently unavailable for re-use by
1534: other hosts. if this is given without tags, then it unconditionally
1535: enables dynamic allocation. With tags, only when the tags are all
1536: set. It may be repeated with different tag sets.
1537: .TP
1538: .B \-5, --no-ping
1.1.1.3 misho 1539: (IPv4 only) By default, the DHCP server will attempt to ensure that an address is
1.1 misho 1540: not in use before allocating it to a host. It does this by sending an
1541: ICMP echo request (aka "ping") to the address in question. If it gets
1542: a reply, then the address must already be in use, and another is
1543: tried. This flag disables this check. Use with caution.
1544: .TP
1545: .B --log-dhcp
1546: Extra logging for DHCP: log all the options sent to DHCP clients and
1547: the tags used to determine them.
1548: .TP
1.1.1.2 misho 1549: .B --quiet-dhcp, --quiet-dhcp6, --quiet-ra
1550: Suppress logging of the routine operation of these protocols. Errors and
1.1.1.4 ! misho 1551: problems will still be logged. \fB--quiet-dhcp\fP and quiet-dhcp6 are
! 1552: over-ridden by \fB--log-dhcp\fP.
1.1.1.2 misho 1553: .TP
1.1 misho 1554: .B \-l, --dhcp-leasefile=<path>
1555: Use the specified file to store DHCP lease information.
1556: .TP
1557: .B --dhcp-duid=<enterprise-id>,<uid>
1558: (IPv6 only) Specify the server persistent UID which the DHCPv6 server
1559: will use. This option is not normally required as dnsmasq creates a
1560: DUID automatically when it is first needed. When given, this option
1561: provides dnsmasq the data required to create a DUID-EN type DUID. Note
1562: that once set, the DUID is stored in the lease database, so to change between DUID-EN and
1563: automatically created DUIDs or vice-versa, the lease database must be
1.1.1.4 ! misho 1564: re-initialised. The enterprise-id is assigned by IANA, and the uid is a
1.1 misho 1565: string of hex octets unique to a particular device.
1566: .TP
1567: .B \-6 --dhcp-script=<path>
1568: Whenever a new DHCP lease is created, or an old one destroyed, or a
1569: TFTP file transfer completes, the
1570: executable specified by this option is run. <path>
1571: must be an absolute pathname, no PATH search occurs.
1572: The arguments to the process
1573: are "add", "old" or "del", the MAC
1574: address of the host (or DUID for IPv6) , the IP address, and the hostname,
1575: if known. "add" means a lease has been created, "del" means it has
1576: been destroyed, "old" is a notification of an existing lease when
1577: dnsmasq starts or a change to MAC address or hostname of an existing
1.1.1.4 ! misho 1578: lease (also, lease length or expiry and client-id, if \fB--leasefile-ro\fP is set
! 1579: and lease expiry if \fB--script-on-renewal\fP is set).
1.1 misho 1580: If the MAC address is from a network type other than ethernet,
1581: it will have the network type prepended, eg "06-01:23:45:67:89:ab" for
1582: token ring. The process is run as root (assuming that dnsmasq was originally run as
1583: root) even if dnsmasq is configured to change UID to an unprivileged user.
1584:
1585: The environment is inherited from the invoker of dnsmasq, with some or
1586: all of the following variables added
1587:
1588: For both IPv4 and IPv6:
1589:
1590: DNSMASQ_DOMAIN if the fully-qualified domain name of the host is
1591: known, this is set to the domain part. (Note that the hostname passed
1592: to the script as an argument is never fully-qualified.)
1593:
1594: If the client provides a hostname, DNSMASQ_SUPPLIED_HOSTNAME
1595:
1596: If the client provides user-classes, DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn
1597:
1598: If dnsmasq was compiled with HAVE_BROKEN_RTC, then
1599: the length of the lease (in seconds) is stored in
1600: DNSMASQ_LEASE_LENGTH, otherwise the time of lease expiry is stored in
1601: DNSMASQ_LEASE_EXPIRES. The number of seconds until lease expiry is
1602: always stored in DNSMASQ_TIME_REMAINING.
1603:
1604: If a lease used to have a hostname, which is
1605: removed, an "old" event is generated with the new state of the lease,
1606: ie no name, and the former name is provided in the environment
1607: variable DNSMASQ_OLD_HOSTNAME.
1608:
1609: DNSMASQ_INTERFACE stores the name of
1610: the interface on which the request arrived; this is not set for "old"
1611: actions when dnsmasq restarts.
1612:
1613: DNSMASQ_RELAY_ADDRESS is set if the client
1614: used a DHCP relay to contact dnsmasq and the IP address of the relay
1615: is known.
1616:
1617: DNSMASQ_TAGS contains all the tags set during the
1618: DHCP transaction, separated by spaces.
1619:
1620: DNSMASQ_LOG_DHCP is set if
1621: .B --log-dhcp
1622: is in effect.
1623:
1624: For IPv4 only:
1625:
1626: DNSMASQ_CLIENT_ID if the host provided a client-id.
1627:
1628: DNSMASQ_CIRCUIT_ID, DNSMASQ_SUBSCRIBER_ID, DNSMASQ_REMOTE_ID if a
1629: DHCP relay-agent added any of these options.
1630:
1631: If the client provides vendor-class, DNSMASQ_VENDOR_CLASS.
1632:
1.1.1.4 ! misho 1633: DNSMASQ_REQUESTED_OPTIONS a string containing the decimal values in the Parameter Request List option, comma separated, if the parameter request list option is provided by the client.
! 1634:
1.1 misho 1635: For IPv6 only:
1636:
1637: If the client provides vendor-class, DNSMASQ_VENDOR_CLASS_ID,
1638: containing the IANA enterprise id for the class, and
1639: DNSMASQ_VENDOR_CLASS0..DNSMASQ_VENDOR_CLASSn for the data.
1640:
1641: DNSMASQ_SERVER_DUID containing the DUID of the server: this is the same for
1642: every call to the script.
1643:
1644: DNSMASQ_IAID containing the IAID for the lease. If the lease is a
1645: temporary allocation, this is prefixed to 'T'.
1646:
1.1.1.2 misho 1647: DNSMASQ_MAC containing the MAC address of the client, if known.
1.1 misho 1648:
1649: Note that the supplied hostname, vendorclass and userclass data is
1650: only supplied for
1651: "add" actions or "old" actions when a host resumes an existing lease,
1652: since these data are not held in dnsmasq's lease
1653: database.
1654:
1655:
1656:
1657: All file descriptors are
1.1.1.4 ! misho 1658: closed except stdin, which is open to /dev/null, and stdout and stderr which capture output for logging by dnsmasq.
! 1659: (In debug mode, stdio, stdout and stderr file are left as those inherited from the invoker of dnsmasq).
1.1 misho 1660:
1661: The script is not invoked concurrently: at most one instance
1662: of the script is ever running (dnsmasq waits for an instance of script to exit
1663: before running the next). Changes to the lease database are which
1664: require the script to be invoked are queued awaiting exit of a running instance.
1665: If this queueing allows multiple state changes occur to a single
1666: lease before the script can be run then
1667: earlier states are discarded and the current state of that lease is
1668: reflected when the script finally runs.
1669:
1670: At dnsmasq startup, the script will be invoked for
1671: all existing leases as they are read from the lease file. Expired
1672: leases will be called with "del" and others with "old". When dnsmasq
1673: receives a HUP signal, the script will be invoked for existing leases
1.1.1.3 misho 1674: with an "old" event.
1.1 misho 1675:
1676:
1.1.1.3 misho 1677: There are four further actions which may appear as the first argument
1678: to the script, "init", "arp-add", "arp-del" and "tftp". More may be added in the future, so
1.1 misho 1679: scripts should be written to ignore unknown actions. "init" is
1680: described below in
1681: .B --leasefile-ro
1682: The "tftp" action is invoked when a TFTP file transfer completes: the
1683: arguments are the file size in bytes, the address to which the file
1684: was sent, and the complete pathname of the file.
1685:
1.1.1.3 misho 1686: The "arp-add" and "arp-del" actions are only called if enabled with
1687: .B --script-arp
1688: They are are supplied with a MAC address and IP address as arguments. "arp-add" indicates
1689: the arrival of a new entry in the ARP or neighbour table, and "arp-del" indicates the deletion of same.
1690:
1.1 misho 1691: .TP
1692: .B --dhcp-luascript=<path>
1693: Specify a script written in Lua, to be run when leases are created,
1694: destroyed or changed. To use this option, dnsmasq must be compiled
1.1.1.4 ! misho 1695: with the correct support. The Lua interpreter is initialised once, when
1.1 misho 1696: dnsmasq starts, so that global variables persist between lease
1697: events. The Lua code must define a
1698: .B lease
1699: function, and may provide
1700: .B init
1701: and
1702: .B shutdown
1703: functions, which are called, without arguments when dnsmasq starts up
1704: and terminates. It may also provide a
1705: .B tftp
1706: function.
1707:
1708: The
1709: .B lease
1710: function receives the information detailed in
1711: .B --dhcp-script.
1712: It gets two arguments, firstly the action, which is a string
1713: containing, "add", "old" or "del", and secondly a table of tag value
1714: pairs. The tags mostly correspond to the environment variables
1715: detailed above, for instance the tag "domain" holds the same data as
1716: the environment variable DNSMASQ_DOMAIN. There are a few extra tags
1717: which hold the data supplied as arguments to
1718: .B --dhcp-script.
1719: These are
1720: .B mac_address, ip_address
1721: and
1722: .B hostname
1723: for IPv4, and
1724: .B client_duid, ip_address
1725: and
1726: .B hostname
1727: for IPv6.
1728:
1729: The
1730: .B tftp
1731: function is called in the same way as the lease function, and the
1732: table holds the tags
1733: .B destination_address,
1734: .B file_name
1735: and
1736: .B file_size.
1.1.1.3 misho 1737:
1738: The
1739: .B arp
1740: and
1741: .B arp-old
1742: functions are called only when enabled with
1743: .B --script-arp
1744: and have a table which holds the tags
1.1.1.4 ! misho 1745: .B mac_address
1.1.1.3 misho 1746: and
1747: .B client_address.
1.1 misho 1748: .TP
1749: .B --dhcp-scriptuser
1750: Specify the user as which to run the lease-change script or Lua script. This defaults to root, but can be changed to another user using this flag.
1.1.1.3 misho 1751: .TP
1752: .B --script-arp
1.1.1.4 ! misho 1753: Enable the "arp" and "arp-old" functions in the \fB--dhcp-script\fP and \fB--dhcp-luascript\fP.
1.1.1.3 misho 1754: .TP
1.1 misho 1755: .B \-9, --leasefile-ro
1756: Completely suppress use of the lease database file. The file will not
1757: be created, read, or written. Change the way the lease-change
1758: script (if one is provided) is called, so that the lease database may
1759: be maintained in external storage by the script. In addition to the
1760: invocations given in
1761: .B --dhcp-script
1762: the lease-change script is called once, at dnsmasq startup, with the
1763: single argument "init". When called like this the script should write
1764: the saved state of the lease database, in dnsmasq leasefile format, to
1765: stdout and exit with zero exit code. Setting this
1766: option also forces the leasechange script to be called on changes
1767: to the client-id and lease length and expiry time.
1768: .TP
1.1.1.4 ! misho 1769: .B --script-on-renewal
! 1770: Call the DHCP script when the lease expiry time changes, for instance when the
! 1771: lease is renewed.
! 1772: .TP
1.1 misho 1773: .B --bridge-interface=<interface>,<alias>[,<alias>]
1.1.1.4 ! misho 1774: Treat DHCP (v4 and v6) requests and IPv6 Router Solicit packets
1.1.1.3 misho 1775: arriving at any of the <alias> interfaces as if they had arrived at
1776: <interface>. This option allows dnsmasq to provide DHCP and RA
1777: service over unaddressed and unbridged Ethernet interfaces, e.g. on an
1778: OpenStack compute host where each such interface is a TAP interface to
1779: a VM, or as in "old style bridging" on BSD platforms. A trailing '*'
1780: wildcard can be used in each <alias>.
1.1.1.4 ! misho 1781:
! 1782: It is permissible to add more than one alias using more than one \fB--bridge-interface\fP option since
! 1783: \fB--bridge-interface=int1,alias1,alias2\fP is exactly equivalent to
! 1784: \fB--bridge-interface=int1,alias1 --bridge-interface=int1,alias2\fP
! 1785: .TP
! 1786: .B --shared-network=<interface>,<addr>
! 1787: .PD 0
! 1788: .TP
! 1789: .B --shared-network=<addr>,<addr>
! 1790: .PD 1v
! 1791: The DHCP server determines which DHCP ranges are useable for allocating an
! 1792: address to a DHCP client based on the network from which the DHCP request arrives,
! 1793: and the IP configuration of the server's interface on that network. The shared-network
! 1794: option extends the available subnets (and therefore DHCP ranges) beyond the
! 1795: subnets configured on the arrival interface.
! 1796:
! 1797: The first argument is either the
! 1798: name of an interface, or an address that is configured on a local interface, and the
! 1799: second argument is an address which defines another subnet on which addresses can be allocated.
! 1800:
! 1801: To be useful, there must be a suitable dhcp-range which allows address allocation on this subnet
! 1802: and this dhcp-range MUST include the netmask.
! 1803:
! 1804: Using shared-network also needs extra
! 1805: consideration of routing. Dnsmasq does not have the usual information that it uses to
! 1806: determine the default route, so the default route option (or other routing) MUST be
! 1807: configured manually. The client must have a route to the server: if the two-address form
! 1808: of shared-network is used, this needs to be to the first specified address. If the interface,address
! 1809: form is used, there must be a route to all of the addresses configured on the interface.
! 1810:
! 1811: The two-address form of shared-network is also usable with a DHCP relay: the first address
! 1812: is the address of the relay and the second, as before, specifies an extra subnet which
! 1813: addresses may be allocated from.
! 1814:
1.1 misho 1815: .TP
1816: .B \-s, --domain=<domain>[,<address range>[,local]]
1817: Specifies DNS domains for the DHCP server. Domains may be be given
1818: unconditionally (without the IP range) or for limited IP ranges. This has two effects;
1819: firstly it causes the DHCP server to return the domain to any hosts
1820: which request it, and secondly it sets the domain which it is legal
1821: for DHCP-configured hosts to claim. The intention is to constrain
1822: hostnames so that an untrusted host on the LAN cannot advertise
1.1.1.4 ! misho 1823: its name via DHCP as e.g. "microsoft.com" and capture traffic not
1.1 misho 1824: meant for it. If no domain suffix is specified, then any DHCP
1825: hostname with a domain part (ie with a period) will be disallowed
1826: and logged. If suffix is specified, then hostnames with a domain
1827: part are allowed, provided the domain part matches the suffix. In
1828: addition, when a suffix is set then hostnames without a domain
1829: part have the suffix added as an optional domain part. Eg on my network I can set
1830: .B --domain=thekelleys.org.uk
1831: and have a machine whose DHCP hostname is "laptop". The IP address for that machine is available from
1832: .B dnsmasq
1833: both as "laptop" and "laptop.thekelleys.org.uk". If the domain is
1834: given as "#" then the domain is read from the first "search" directive
1835: in /etc/resolv.conf (or equivalent).
1836:
1837: The address range can be of the form
1838: <ip address>,<ip address> or <ip address>/<netmask> or just a single
1839: <ip address>. See
1840: .B --dhcp-fqdn
1841: which can change the behaviour of dnsmasq with domains.
1842:
1843: If the address range is given as ip-address/network-size, then a
1844: additional flag "local" may be supplied which has the effect of adding
1.1.1.4 ! misho 1845: \fB--local\fP declarations for forward and reverse DNS queries. Eg.
1.1 misho 1846: .B --domain=thekelleys.org.uk,192.168.0.0/24,local
1847: is identical to
1848: .B --domain=thekelleys.org.uk,192.168.0.0/24
1.1.1.4 ! misho 1849: .B --local=/thekelleys.org.uk/ --local=/0.168.192.in-addr.arpa/
1.1 misho 1850: The network size must be 8, 16 or 24 for this to be legal.
1851: .TP
1852: .B --dhcp-fqdn
1853: In the default mode, dnsmasq inserts the unqualified names of
1854: DHCP clients into the DNS. For this reason, the names must be unique,
1855: even if two clients which have the same name are in different
1856: domains. If a second DHCP client appears which has the same name as an
1.1.1.2 misho 1857: existing client, the name is transferred to the new client. If
1.1 misho 1858: .B --dhcp-fqdn
1859: is set, this behaviour changes: the unqualified name is no longer
1860: put in the DNS, only the qualified name. Two DHCP clients with the
1861: same name may both keep the name, provided that the domain part is
1862: different (ie the fully qualified names differ.) To ensure that all
1863: names have a domain part, there must be at least
1864: .B --domain
1865: without an address specified when
1866: .B --dhcp-fqdn
1867: is set.
1868: .TP
1869: .B --dhcp-client-update
1870: Normally, when giving a DHCP lease, dnsmasq sets flags in the FQDN
1871: option to tell the client not to attempt a DDNS update with its name
1872: and IP address. This is because the name-IP pair is automatically
1873: added into dnsmasq's DNS view. This flag suppresses that behaviour,
1874: this is useful, for instance, to allow Windows clients to update
1875: Active Directory servers. See RFC 4702 for details.
1876: .TP
1877: .B --enable-ra
1878: Enable dnsmasq's IPv6 Router Advertisement feature. DHCPv6 doesn't
1879: handle complete network configuration in the same way as DHCPv4. Router
1880: discovery and (possibly) prefix discovery for autonomous address
1881: creation are handled by a different protocol. When DHCP is in use,
1882: only a subset of this is needed, and dnsmasq can handle it, using
1883: existing DHCP configuration to provide most data. When RA is enabled,
1.1.1.4 ! misho 1884: dnsmasq will advertise a prefix for each \fB--dhcp-range\fP, with default
1.1.1.3 misho 1885: router as the relevant link-local address on
1886: the machine running dnsmasq. By default, the "managed address" bits are set, and
1.1 misho 1887: the "use SLAAC" bit is reset. This can be changed for individual
1888: subnets with the mode keywords described in
1889: .B --dhcp-range.
1890: RFC6106 DNS parameters are included in the advertisements. By default,
1891: the relevant link-local address of the machine running dnsmasq is sent
1892: as recursive DNS server. If provided, the DHCPv6 options dns-server and
1.1.1.4 ! misho 1893: domain-search are used for the DNS server (RDNSS) and the domain search list (DNSSL).
1.1 misho 1894: .TP
1.1.1.4 ! misho 1895: .B --ra-param=<interface>,[mtu:<integer>|<interface>|off,][high,|low,]<ra-interval>[,<router lifetime>]
1.1.1.2 misho 1896: Set non-default values for router advertisements sent via an
1897: interface. The priority field for the router may be altered from the
1898: default of medium with eg
1899: .B --ra-param=eth0,high.
1900: The interval between router advertisements may be set (in seconds) with
1901: .B --ra-param=eth0,60.
1902: The lifetime of the route may be changed or set to zero, which allows
1903: a router to advertise prefixes but not a route via itself.
1.1.1.4 ! misho 1904: .B --ra-param=eth0,0,0
! 1905: (A value of zero for the interval means the default value.) All four parameters may be set at once.
! 1906: .B --ra-param=eth0,mtu:1280,low,60,1200
! 1907:
1.1.1.2 misho 1908: The interface field may include a wildcard.
1.1.1.4 ! misho 1909:
! 1910: The mtu: parameter may be an arbitrary interface name, in which case the MTU value for that interface is used. This is useful
! 1911: for (eg) advertising the MTU of a WAN interface on the other interfaces of a router.
! 1912: .TP
! 1913: .B --dhcp-reply-delay=[tag:<tag>,]<integer>
! 1914: Delays sending DHCPOFFER and PROXYDHCP replies for at least the specified number of seconds.
! 1915: This can be used as workaround for bugs in PXE boot firmware that does not function properly when
! 1916: receiving an instant reply.
! 1917: This option takes into account the time already spent waiting (e.g. performing ping check) if any.
1.1.1.2 misho 1918: .TP
1919: .B --enable-tftp[=<interface>[,<interface>]]
1.1 misho 1920: Enable the TFTP server function. This is deliberately limited to that
1921: needed to net-boot a client. Only reading is allowed; the tsize and
1922: blksize extensions are supported (tsize is only supported in octet
1.1.1.2 misho 1923: mode). Without an argument, the TFTP service is provided to the same set of interfaces as DHCP service.
1.1.1.4 ! misho 1924: If the list of interfaces is provided, that defines which interfaces receive TFTP service.
1.1 misho 1925: .TP
1926: .B --tftp-root=<directory>[,<interface>]
1927: Look for files to transfer using TFTP relative to the given
1928: directory. When this is set, TFTP paths which include ".." are
1929: rejected, to stop clients getting outside the specified root.
1930: Absolute paths (starting with /) are allowed, but they must be within
1931: the tftp-root. If the optional interface argument is given, the
1932: directory is only used for TFTP requests via that interface.
1933: .TP
1.1.1.3 misho 1934: .B --tftp-no-fail
1935: Do not abort startup if specified tftp root directories are inaccessible.
1936: .TP
1.1.1.4 ! misho 1937: .B --tftp-unique-root[=ip|mac]
! 1938: Add the IP or hardware address of the TFTP client as a path component on the end
! 1939: of the TFTP-root. Only valid if a \fB--tftp-root\fP is set and the directory exists.
! 1940: Defaults to adding IP address (in standard dotted-quad format).
! 1941: For instance, if \fB--tftp-root\fP is "/tftp" and client 1.2.3.4 requests file "myfile"
! 1942: then the effective path will be "/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4 exists or /tftp/myfile otherwise.
! 1943: When "=mac" is specified it will append the MAC address instead, using lowercase zero padded digits
! 1944: separated by dashes, e.g.: 01-02-03-04-aa-bb
! 1945: Note that resolving MAC addresses is only possible if the client is in the local network or obtained
! 1946: a DHCP lease from us.
1.1 misho 1947: .TP
1948: .B --tftp-secure
1949: Enable TFTP secure mode: without this, any file which is readable by
1950: the dnsmasq process under normal unix access-control rules is
1.1.1.4 ! misho 1951: available via TFTP. When the \fB--tftp-secure\fP flag is given, only files
1.1 misho 1952: owned by the user running the dnsmasq process are accessible. If
1.1.1.4 ! misho 1953: dnsmasq is being run as root, different rules apply: \fB--tftp-secure\fP
1.1 misho 1954: has no effect, but only files which have the world-readable bit set
1955: are accessible. It is not recommended to run dnsmasq as root with TFTP
1.1.1.4 ! misho 1956: enabled, and certainly not without specifying \fB--tftp-root\fP. Doing so
1.1 misho 1957: can expose any world-readable file on the server to any host on the net.
1958: .TP
1959: .B --tftp-lowercase
1960: Convert filenames in TFTP requests to all lowercase. This is useful
1961: for requests from Windows machines, which have case-insensitive
1962: filesystems and tend to play fast-and-loose with case in filenames.
1963: Note that dnsmasq's tftp server always converts "\\" to "/" in filenames.
1964: .TP
1965: .B --tftp-max=<connections>
1966: Set the maximum number of concurrent TFTP connections allowed. This
1967: defaults to 50. When serving a large number of TFTP connections,
1968: per-process file descriptor limits may be encountered. Dnsmasq needs
1969: one file descriptor for each concurrent TFTP connection and one
1970: file descriptor per unique file (plus a few others). So serving the
1971: same file simultaneously to n clients will use require about n + 10 file
1972: descriptors, serving different files simultaneously to n clients will
1973: require about (2*n) + 10 descriptors. If
1974: .B --tftp-port-range
1975: is given, that can affect the number of concurrent connections.
1976: .TP
1.1.1.3 misho 1977: .B --tftp-mtu=<mtu size>
1978: Use size as the ceiling of the MTU supported by the intervening network when
1979: negotiating TFTP blocksize, overriding the MTU setting of the local interface if it is larger.
1980: .TP
1.1 misho 1981: .B --tftp-no-blocksize
1982: Stop the TFTP server from negotiating the "blocksize" option with a
1983: client. Some buggy clients request this option but then behave badly
1984: when it is granted.
1985: .TP
1986: .B --tftp-port-range=<start>,<end>
1987: A TFTP server listens on a well-known port (69) for connection initiation,
1988: but it also uses a dynamically-allocated port for each
1989: connection. Normally these are allocated by the OS, but this option
1990: specifies a range of ports for use by TFTP transfers. This can be
1991: useful when TFTP has to traverse a firewall. The start of the range
1992: cannot be lower than 1025 unless dnsmasq is running as root. The number
1993: of concurrent TFTP connections is limited by the size of the port range.
1.1.1.4 ! misho 1994: .TP
! 1995: .B --tftp-single-port
! 1996: Run in a mode where the TFTP server uses ONLY the well-known port (69) for its end
! 1997: of the TFTP transfer. This allows TFTP to work when there in NAT is the path between client and server. Note that
! 1998: this is not strictly compliant with the RFCs specifying the TFTP protocol: use at your own risk.
! 1999: .TP
1.1 misho 2000: .B \-C, --conf-file=<file>
1.1.1.4 ! misho 2001: Specify a configuration file. The presence of this option stops dnsmasq from reading the default configuration
! 2002: file (normally /etc/dnsmasq.conf). Multiple files may be specified by repeating the option
! 2003: either on the command line or in configuration files. A
1.1 misho 2004: filename of "-" causes dnsmasq to read configuration from stdin.
2005: .TP
1.1.1.3 misho 2006: .B \-7, --conf-dir=<directory>[,<file-extension>......],
1.1 misho 2007: Read all the files in the given directory as configuration
2008: files. If extension(s) are given, any files which end in those
2009: extensions are skipped. Any files whose names end in ~ or start with . or start and end
1.1.1.3 misho 2010: with # are always skipped. If the extension starts with * then only files
2011: which have that extension are loaded. So
2012: .B --conf-dir=/path/to/dir,*.conf
2013: loads all files with the suffix .conf in /path/to/dir. This flag may be given on the command
2014: line or in a configuration file. If giving it on the command line, be sure to
1.1.1.4 ! misho 2015: escape * characters. Files are loaded in alphabetical order of filename.
1.1.1.2 misho 2016: .TP
2017: .B --servers-file=<file>
2018: A special case of
2019: .B --conf-file
1.1.1.4 ! misho 2020: which differs in two respects. Firstly, only \fB--server\fP and \fB--rev-server\fP are allowed
1.1.1.2 misho 2021: in the configuration file included. Secondly, the file is re-read and the configuration
1.1.1.4 ! misho 2022: therein is updated when dnsmasq receives SIGHUP.
1.1 misho 2023: .SH CONFIG FILE
2024: At startup, dnsmasq reads
2025: .I /etc/dnsmasq.conf,
2026: if it exists. (On
2027: FreeBSD, the file is
2028: .I /usr/local/etc/dnsmasq.conf
2029: ) (but see the
1.1.1.4 ! misho 2030: .B \--conf-file
1.1 misho 2031: and
1.1.1.4 ! misho 2032: .B \--conf-dir
1.1 misho 2033: options.) The format of this
2034: file consists of one option per line, exactly as the long options detailed
2035: in the OPTIONS section but without the leading "--". Lines starting with # are comments and ignored. For
2036: options which may only be specified once, the configuration file overrides
2037: the command line. Quoting is allowed in a config file:
2038: between " quotes the special meanings of ,:. and # are removed and the
2039: following escapes are allowed: \\\\ \\" \\t \\e \\b \\r and \\n. The later
2040: corresponding to tab, escape, backspace, return and newline.
2041: .SH NOTES
2042: When it receives a SIGHUP,
2043: .B dnsmasq
2044: clears its cache and then re-loads
2045: .I /etc/hosts
2046: and
2047: .I /etc/ethers
1.1.1.4 ! misho 2048: and any file given by \fB--dhcp-hostsfile\fP, \fB--dhcp-hostsdir\fP, \fB--dhcp-optsfile\fP,
! 2049: \fB--dhcp-optsdir\fP, \fB--addn-hosts\fP or \fB--hostsdir\fP.
! 2050: The DHCP lease change script is called for all
1.1 misho 2051: existing DHCP leases. If
2052: .B
2053: --no-poll
2054: is set SIGHUP also re-reads
2055: .I /etc/resolv.conf.
2056: SIGHUP
2057: does NOT re-read the configuration file.
2058: .PP
2059: When it receives a SIGUSR1,
2060: .B dnsmasq
2061: writes statistics to the system log. It writes the cache size,
2062: the number of names which have had to removed from the cache before
2063: they expired in order to make room for new names and the total number
1.1.1.2 misho 2064: of names that have been inserted into the cache. The number of cache hits and
2065: misses and the number of authoritative queries answered are also given. For each upstream
1.1 misho 2066: server it gives the number of queries sent, and the number which
2067: resulted in an error. In
2068: .B --no-daemon
1.1.1.4 ! misho 2069: mode or when full logging is enabled (\fB--log-queries\fP), a complete dump of the
1.1.1.2 misho 2070: contents of the cache is made.
2071:
2072: The cache statistics are also available in the DNS as answers to
2073: queries of class CHAOS and type TXT in domain bind. The domain names are cachesize.bind, insertions.bind, evictions.bind,
2074: misses.bind, hits.bind, auth.bind and servers.bind. An example command to query this, using the
2075: .B dig
2076: utility would be
2077:
2078: dig +short chaos txt cachesize.bind
2079:
1.1 misho 2080: .PP
2081: When it receives SIGUSR2 and it is logging direct to a file (see
2082: .B --log-facility
2083: )
2084: .B dnsmasq
2085: will close and reopen the log file. Note that during this operation,
2086: dnsmasq will not be running as root. When it first creates the logfile
2087: dnsmasq changes the ownership of the file to the non-root user it will run
2088: as. Logrotate should be configured to create a new log file with
2089: the ownership which matches the existing one before sending SIGUSR2.
2090: If TCP DNS queries are in progress, the old logfile will remain open in
2091: child processes which are handling TCP queries and may continue to be
2092: written. There is a limit of 150 seconds, after which all existing TCP
2093: processes will have expired: for this reason, it is not wise to
2094: configure logfile compression for logfiles which have just been
2095: rotated. Using logrotate, the required options are
2096: .B create
2097: and
2098: .B delaycompress.
2099:
2100:
2101: .PP
1.1.1.4 ! misho 2102: Dnsmasq is a DNS query forwarder: it is not capable of recursively
1.1 misho 2103: answering arbitrary queries starting from the root servers but
2104: forwards such queries to a fully recursive upstream DNS server which is
2105: typically provided by an ISP. By default, dnsmasq reads
2106: .I /etc/resolv.conf
2107: to discover the IP
2108: addresses of the upstream nameservers it should use, since the
2109: information is typically stored there. Unless
2110: .B --no-poll
2111: is used,
2112: .B dnsmasq
2113: checks the modification time of
2114: .I /etc/resolv.conf
2115: (or equivalent if
2116: .B \--resolv-file
2117: is used) and re-reads it if it changes. This allows the DNS servers to
2118: be set dynamically by PPP or DHCP since both protocols provide the
2119: information.
2120: Absence of
2121: .I /etc/resolv.conf
2122: is not an error
2123: since it may not have been created before a PPP connection exists. Dnsmasq
2124: simply keeps checking in case
2125: .I /etc/resolv.conf
2126: is created at any
2127: time. Dnsmasq can be told to parse more than one resolv.conf
2128: file. This is useful on a laptop, where both PPP and DHCP may be used:
2129: dnsmasq can be set to poll both
2130: .I /etc/ppp/resolv.conf
2131: and
2132: .I /etc/dhcpc/resolv.conf
2133: and will use the contents of whichever changed
2134: last, giving automatic switching between DNS servers.
2135: .PP
2136: Upstream servers may also be specified on the command line or in
2137: the configuration file. These server specifications optionally take a
2138: domain name which tells dnsmasq to use that server only to find names
2139: in that particular domain.
2140: .PP
2141: In order to configure dnsmasq to act as cache for the host on which it is running, put "nameserver 127.0.0.1" in
2142: .I /etc/resolv.conf
2143: to force local processes to send queries to
2144: dnsmasq. Then either specify the upstream servers directly to dnsmasq
2145: using
2146: .B \--server
2147: options or put their addresses real in another file, say
2148: .I /etc/resolv.dnsmasq
2149: and run dnsmasq with the
1.1.1.4 ! misho 2150: .B \--resolv-file /etc/resolv.dnsmasq
1.1 misho 2151: option. This second technique allows for dynamic update of the server
2152: addresses by PPP or DHCP.
2153: .PP
2154: Addresses in /etc/hosts will "shadow" different addresses for the same
2155: names in the upstream DNS, so "mycompany.com 1.2.3.4" in /etc/hosts will ensure that
2156: queries for "mycompany.com" always return 1.2.3.4 even if queries in
2157: the upstream DNS would otherwise return a different address. There is
2158: one exception to this: if the upstream DNS contains a CNAME which
2159: points to a shadowed name, then looking up the CNAME through dnsmasq
2160: will result in the unshadowed address associated with the target of
2161: the CNAME. To work around this, add the CNAME to /etc/hosts so that
2162: the CNAME is shadowed too.
2163:
2164: .PP
2165: The tag system works as follows: For each DHCP request, dnsmasq
2166: collects a set of valid tags from active configuration lines which
2167: include set:<tag>, including one from the
1.1.1.4 ! misho 2168: .B --dhcp-range
1.1 misho 2169: used to allocate the address, one from any matching
1.1.1.4 ! misho 2170: .B --dhcp-host
! 2171: (and "known" or "known-othernet" if a \fB--dhcp-host\fP matches)
1.1 misho 2172: The tag "bootp" is set for BOOTP requests, and a tag whose name is the
2173: name of the interface on which the request arrived is also set.
2174:
1.1.1.2 misho 2175: Any configuration lines which include one or more tag:<tag> constructs
1.1 misho 2176: will only be valid if all that tags are matched in the set derived
1.1.1.4 ! misho 2177: above. Typically this is \fB--dhcp-option\fP.
! 2178: .B --dhcp-option
1.1 misho 2179: which has tags will be used in preference to an untagged
1.1.1.4 ! misho 2180: .B --dhcp-option,
1.1 misho 2181: provided that _all_ the tags match somewhere in the
2182: set collected as described above. The prefix '!' on a tag means 'not'
1.1.1.4 ! misho 2183: so \fB--dhcp-option=tag:!purple,3,1.2.3.4\fP sends the option when the
1.1 misho 2184: tag purple is not in the set of valid tags. (If using this in a
2185: command line rather than a configuration file, be sure to escape !,
2186: which is a shell metacharacter)
2187:
1.1.1.4 ! misho 2188: When selecting \fB--dhcp-options\fP, a tag from \fB--dhcp-range\fP is second class
1.1 misho 2189: relative to other tags, to make it easy to override options for
2190: individual hosts, so
1.1.1.4 ! misho 2191: .B --dhcp-range=set:interface1,......
! 2192: .B --dhcp-host=set:myhost,.....
! 2193: .B --dhcp-option=tag:interface1,option:nis-domain,"domain1"
! 2194: .B --dhcp-option=tag:myhost,option:nis-domain,"domain2"
1.1 misho 2195: will set the NIS-domain to domain1 for hosts in the range, but
2196: override that to domain2 for a particular host.
2197:
2198: .PP
2199: Note that for
1.1.1.4 ! misho 2200: .B --dhcp-range
1.1 misho 2201: both tag:<tag> and set:<tag> are allowed, to both select the range in
1.1.1.4 ! misho 2202: use based on (eg) \fB--dhcp-host\fP, and to affect the options sent, based on
1.1 misho 2203: the range selected.
2204:
2205: This system evolved from an earlier, more limited one and for backward
2206: compatibility "net:" may be used instead of "tag:" and "set:" may be
2207: omitted. (Except in
1.1.1.4 ! misho 2208: .B --dhcp-host,
1.1 misho 2209: where "net:" may be used instead of "set:".) For the same reason, '#'
2210: may be used instead of '!' to indicate NOT.
2211: .PP
2212: The DHCP server in dnsmasq will function as a BOOTP server also,
2213: provided that the MAC address and IP address for clients are given,
2214: either using
1.1.1.4 ! misho 2215: .B --dhcp-host
1.1 misho 2216: configurations or in
2217: .I /etc/ethers
2218: , and a
1.1.1.4 ! misho 2219: .B --dhcp-range
1.1 misho 2220: configuration option is present to activate the DHCP server
1.1.1.4 ! misho 2221: on a particular network. (Setting \fB--bootp-dynamic\fP removes the need for
1.1 misho 2222: static address mappings.) The filename
2223: parameter in a BOOTP request is used as a tag,
2224: as is the tag "bootp", allowing some control over the options returned to
2225: different classes of hosts.
2226:
2227: .SH AUTHORITATIVE CONFIGURATION
2228: Configuring dnsmasq to act as an authoritative DNS server is
2229: complicated by the fact that it involves configuration of external DNS
2230: servers to provide delegation. We will walk through three scenarios of
2231: increasing complexity. Prerequisites for all of these scenarios
2232: are a globally accessible IP address, an A or AAAA record pointing to that address,
2233: and an external DNS server capable of doing delegation of the zone in
2234: question. For the first part of this explanation, we will call the A (or AAAA) record
2235: for the globally accessible address server.example.com, and the zone
2236: for which dnsmasq is authoritative our.zone.com.
2237:
2238: The simplest configuration consists of two lines of dnsmasq configuration; something like
2239:
2240: .nf
1.1.1.4 ! misho 2241: .B --auth-server=server.example.com,eth0
! 2242: .B --auth-zone=our.zone.com,1.2.3.0/24
1.1 misho 2243: .fi
2244:
2245: and two records in the external DNS
2246:
2247: .nf
2248: server.example.com A 192.0.43.10
2249: our.zone.com NS server.example.com
2250: .fi
2251:
2252: eth0 is the external network interface on which dnsmasq is listening,
2253: and has (globally accessible) address 192.0.43.10.
2254:
2255: Note that the external IP address may well be dynamic (ie assigned
2256: from an ISP by DHCP or PPP) If so, the A record must be linked to this
2257: dynamic assignment by one of the usual dynamic-DNS systems.
2258:
2259: A more complex, but practically useful configuration has the address
2260: record for the globally accessible IP address residing in the
2261: authoritative zone which dnsmasq is serving, typically at the root. Now
2262: we have
2263:
2264: .nf
1.1.1.4 ! misho 2265: .B --auth-server=our.zone.com,eth0
! 2266: .B --auth-zone=our.zone.com,1.2.3.0/24
1.1 misho 2267: .fi
2268:
2269: .nf
2270: our.zone.com A 1.2.3.4
2271: our.zone.com NS our.zone.com
2272: .fi
2273:
2274: The A record for our.zone.com has now become a glue record, it solves
2275: the chicken-and-egg problem of finding the IP address of the
2276: nameserver for our.zone.com when the A record is within that
2277: zone. Note that this is the only role of this record: as dnsmasq is
2278: now authoritative from our.zone.com it too must provide this
2279: record. If the external address is static, this can be done with an
2280: .B /etc/hosts
2281: entry or
2282: .B --host-record.
2283:
2284: .nf
1.1.1.4 ! misho 2285: .B --auth-server=our.zone.com,eth0
! 2286: .B --host-record=our.zone.com,1.2.3.4
! 2287: .B --auth-zone=our.zone.com,1.2.3.0/24
1.1 misho 2288: .fi
2289:
2290: If the external address is dynamic, the address
2291: associated with our.zone.com must be derived from the address of the
2292: relevant interface. This is done using
1.1.1.4 ! misho 2293: .B --interface-name
1.1 misho 2294: Something like:
2295:
2296: .nf
1.1.1.4 ! misho 2297: .B --auth-server=our.zone.com,eth0
! 2298: .B --interface-name=our.zone.com,eth0
! 2299: .B --auth-zone=our.zone.com,1.2.3.0/24,eth0
1.1 misho 2300: .fi
2301:
1.1.1.4 ! misho 2302: (The "eth0" argument in \fB--auth-zone\fP adds the subnet containing eth0's
! 2303: dynamic address to the zone, so that the \fB--interface-name\fP returns the
1.1.1.2 misho 2304: address in outside queries.)
2305:
1.1 misho 2306: Our final configuration builds on that above, but also adds a
2307: secondary DNS server. This is another DNS server which learns the DNS data
2308: for the zone by doing zones transfer, and acts as a backup should
2309: the primary server become inaccessible. The configuration of the
2310: secondary is beyond the scope of this man-page, but the extra
2311: configuration of dnsmasq is simple:
2312:
2313: .nf
1.1.1.4 ! misho 2314: .B --auth-sec-servers=secondary.myisp.com
1.1 misho 2315: .fi
2316:
2317: and
2318:
2319: .nf
2320: our.zone.com NS secondary.myisp.com
2321: .fi
2322:
2323: Adding auth-sec-servers enables zone transfer in dnsmasq, to allow the
2324: secondary to collect the DNS data. If you wish to restrict this data
2325: to particular hosts then
2326:
2327: .nf
1.1.1.4 ! misho 2328: .B --auth-peer=<IP address of secondary>
1.1 misho 2329: .fi
2330:
2331: will do so.
2332:
2333: Dnsmasq acts as an authoritative server for in-addr.arpa and
1.1.1.4 ! misho 2334: ip6.arpa domains associated with the subnets given in \fB--auth-zone\fP
1.1 misho 2335: declarations, so reverse (address to name) lookups can be simply
2336: configured with a suitable NS record, for instance in this example,
2337: where we allow 1.2.3.0/24 addresses.
2338:
2339: .nf
2340: 3.2.1.in-addr.arpa NS our.zone.com
2341: .fi
2342:
2343: Note that at present, reverse (in-addr.arpa and ip6.arpa) zones are
2344: not available in zone transfers, so there is no point arranging
2345: secondary servers for reverse lookups.
2346:
2347: .PP
2348: When dnsmasq is configured to act as an authoritative server, the
2349: following data is used to populate the authoritative zone.
2350: .PP
1.1.1.4 ! misho 2351: .B --mx-host, --srv-host, --dns-rr, --txt-record, --naptr-record, --caa-record,
! 2352: as long as the record names are in the authoritative domain.
1.1 misho 2353: .PP
2354: .B --cname
2355: as long as the record name is in the authoritative domain. If the
2356: target of the CNAME is unqualified, then it is qualified with the
1.1.1.4 ! misho 2357: authoritative zone name. CNAME used in this way (only) may be wildcards, as in
! 2358:
! 2359: .nf
! 2360: .B --cname=*.example.com,default.example.com
! 2361: .fi
! 2362:
1.1 misho 2363: .PP
2364: IPv4 and IPv6 addresses from /etc/hosts (and
2365: .B --addn-hosts
2366: ) and
2367: .B --host-record
1.1.1.2 misho 2368: and
2369: .B --interface-name
1.1 misho 2370: provided the address falls into one of the subnets specified in the
2371: .B --auth-zone.
2372: .PP
2373: Addresses of DHCP leases, provided the address falls into one of the subnets specified in the
1.1.1.2 misho 2374: .B --auth-zone.
1.1.1.4 ! misho 2375: (If constructed DHCP ranges are is use, which depend on the address dynamically
1.1.1.2 misho 2376: assigned to an interface, then the form of
1.1 misho 2377: .B --auth-zone
1.1.1.2 misho 2378: which defines subnets by the dynamic address of an interface should
2379: be used to ensure this condition is met.)
2380: .PP
2381: In the default mode, where a DHCP lease
1.1 misho 2382: has an unqualified name, and possibly a qualified name constructed
2383: using
2384: .B --domain
2385: then the name in the authoritative zone is constructed from the
2386: unqualified name and the zone's domain. This may or may not equal
2387: that specified by
2388: .B --domain.
2389: If
2390: .B --dhcp-fqdn
2391: is set, then the fully qualified names associated with DHCP leases are
2392: used, and must match the zone's domain.
2393:
2394:
2395:
2396: .SH EXIT CODES
2397: 0 - Dnsmasq successfully forked into the background, or terminated
2398: normally if backgrounding is not enabled.
2399: .PP
2400: 1 - A problem with configuration was detected.
2401: .PP
2402: 2 - A problem with network access occurred (address in use, attempt
2403: to use privileged ports without permission).
2404: .PP
2405: 3 - A problem occurred with a filesystem operation (missing
2406: file/directory, permissions).
2407: .PP
2408: 4 - Memory allocation failure.
2409: .PP
2410: 5 - Other miscellaneous problem.
2411: .PP
2412: 11 or greater - a non zero return code was received from the
2413: lease-script process "init" call. The exit code from dnsmasq is the
2414: script's exit code with 10 added.
2415:
2416: .SH LIMITS
2417: The default values for resource limits in dnsmasq are generally
2418: conservative, and appropriate for embedded router type devices with
2419: slow processors and limited memory. On more capable hardware, it is
2420: possible to increase the limits, and handle many more clients. The
2421: following applies to dnsmasq-2.37: earlier versions did not scale as well.
2422:
2423: .PP
2424: Dnsmasq is capable of handling DNS and DHCP for at least a thousand
2425: clients. The DHCP lease times should not be very short (less than one hour). The
2426: value of
2427: .B --dns-forward-max
2428: can be increased: start with it equal to
2429: the number of clients and increase if DNS seems slow. Note that DNS
2430: performance depends too on the performance of the upstream
2431: nameservers. The size of the DNS cache may be increased: the hard
2432: limit is 10000 names and the default (150) is very low. Sending
2433: SIGUSR1 to dnsmasq makes it log information which is useful for tuning
2434: the cache size. See the
2435: .B NOTES
2436: section for details.
2437:
2438: .PP
2439: The built-in TFTP server is capable of many simultaneous file
2440: transfers: the absolute limit is related to the number of file-handles
2441: allowed to a process and the ability of the select() system call to
2442: cope with large numbers of file handles. If the limit is set too high
2443: using
2444: .B --tftp-max
2445: it will be scaled down and the actual limit logged at
2446: start-up. Note that more transfers are possible when the same file is
2447: being sent than when each transfer sends a different file.
2448:
2449: .PP
2450: It is possible to use dnsmasq to block Web advertising by using a list
2451: of known banner-ad servers, all resolving to 127.0.0.1 or 0.0.0.0, in
2452: .B /etc/hosts
2453: or an additional hosts file. The list can be very long,
2454: dnsmasq has been tested successfully with one million names. That size
2455: file needs a 1GHz processor and about 60Mb of RAM.
2456:
2457: .SH INTERNATIONALISATION
2458: Dnsmasq can be compiled to support internationalisation. To do this,
2459: the make targets "all-i18n" and "install-i18n" should be used instead of
2460: the standard targets "all" and "install". When internationalisation
2461: is compiled in, dnsmasq will produce log messages in the local
2462: language and support internationalised domain names (IDN). Domain
2463: names in /etc/hosts, /etc/ethers and /etc/dnsmasq.conf which contain
2464: non-ASCII characters will be translated to the DNS-internal punycode
2465: representation. Note that
2466: dnsmasq determines both the language for messages and the assumed
2467: charset for configuration
2468: files from the LANG environment variable. This should be set to the system
2469: default value by the script which is responsible for starting
2470: dnsmasq. When editing the configuration files, be careful to do so
2471: using only the system-default locale and not user-specific one, since
2472: dnsmasq has no direct way of determining the charset in use, and must
2473: assume that it is the system default.
2474:
2475: .SH FILES
2476: .IR /etc/dnsmasq.conf
2477:
2478: .IR /usr/local/etc/dnsmasq.conf
2479:
2480: .IR /etc/resolv.conf
2481: .IR /var/run/dnsmasq/resolv.conf
2482: .IR /etc/ppp/resolv.conf
2483: .IR /etc/dhcpc/resolv.conf
2484:
2485: .IR /etc/hosts
2486:
2487: .IR /etc/ethers
2488:
2489: .IR /var/lib/misc/dnsmasq.leases
2490:
2491: .IR /var/db/dnsmasq.leases
2492:
2493: .IR /var/run/dnsmasq.pid
2494: .SH SEE ALSO
2495: .BR hosts (5),
2496: .BR resolver (5)
2497: .SH AUTHOR
2498: This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.
2499:
2500:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to dnsmasq.8 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dnsmasq / man