]>
Commit | Line | Data |
---|---|---|
9e4abcb5 SK |
1 | .TH DNSMASQ 8 |
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 | |
5aabfc78 SK |
9 | is a lightweight DNS, TFTP and DHCP server. It is intended to provide |
10 | coupled DNS and DHCP service to a LAN. | |
9e4abcb5 SK |
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 | |
16 | DNS queries for DHCP configured hosts. | |
17 | .PP | |
73a08a24 SK |
18 | The dnsmasq DHCP server supports static address assignments and multiple |
19 | networks. It automatically | |
3be34541 | 20 | sends a sensible default set of DHCP options, and can be configured to |
f2621c7f | 21 | send any desired set of DHCP options, including vendor-encapsulated |
1b7ecd11 SK |
22 | options. It includes a secure, read-only, |
23 | TFTP server to allow net/PXE boot of DHCP hosts and also supports BOOTP. | |
9e4abcb5 | 24 | .PP |
3be34541 | 25 | Dnsmasq |
c81d390f | 26 | supports IPv6 for all functions and a minimal router-advertisemnet daemon. |
9e4abcb5 SK |
27 | .SH OPTIONS |
28 | Note that in general missing parameters are allowed and switch off | |
832af0ba | 29 | functions, for instance "--pid-file" disables writing a PID file. On |
33820b7e SK |
30 | BSD, unless the GNU getopt library is linked, the long form of the |
31 | options does not work on the command line; it is still recognised in | |
32 | the configuration file. | |
9e4abcb5 | 33 | .TP |
7622fc06 SK |
34 | .B --test |
35 | Read and syntax check configuration file(s). Exit with code 0 if all | |
36 | is OK, or a non-zero code otherwise. Do not start up dnsmasq. | |
37 | .TP | |
9e4abcb5 SK |
38 | .B \-h, --no-hosts |
39 | Don't read the hostnames in /etc/hosts. | |
40 | .TP | |
41 | .B \-H, --addn-hosts=<file> | |
42 | Additional hosts file. Read the specified file as well as /etc/hosts. If -h is given, read | |
fd9fa481 | 43 | only the specified file. This option may be repeated for more than one |
7622fc06 | 44 | additional hosts file. If a directory is given, then read all the files contained in that directory. |
9e4abcb5 | 45 | .TP |
832af0ba SK |
46 | .B \-E, --expand-hosts |
47 | Add the domain to simple names (without a period) in /etc/hosts | |
1f15b81d SK |
48 | in the same way as for DHCP-derived names. Note that this does not |
49 | apply to domain names in cnames, PTR records, TXT records etc. | |
832af0ba | 50 | .TP |
9e4abcb5 SK |
51 | .B \-T, --local-ttl=<time> |
52 | When replying with information from /etc/hosts or the DHCP leases | |
53 | file dnsmasq by default sets the time-to-live field to zero, meaning | |
c72daea8 | 54 | that the requester should not itself cache the information. This is |
9e4abcb5 SK |
55 | the correct thing to do in almost all situations. This option allows a |
56 | time-to-live (in seconds) to be given for these replies. This will | |
57 | reduce the load on the server at the expense of clients using stale | |
58 | data under some circumstances. | |
59 | .TP | |
824af85b SK |
60 | .B --neg-ttl=<time> |
61 | Negative replies from upstream servers normally contain time-to-live | |
62 | information in SOA records which dnsmasq uses for caching. If the | |
63 | replies from upstream servers omit this information, dnsmasq does not | |
64 | cache the reply. This option gives a default value for time-to-live | |
65 | (in seconds) which dnsmasq uses to cache negative replies even in | |
66 | the absence of an SOA record. | |
67 | .TP | |
8ef5ada2 SK |
68 | .B --max-ttl=<time> |
69 | Set a maximum TTL value that will be handed out to clients. The specified | |
70 | maximum TTL will be given to clients instead of the true TTL value if it is | |
71 | lower. The true TTL value is however kept in the cache to avoid flooding | |
72 | the upstream DNS servers. | |
73 | .TP | |
3be34541 SK |
74 | .B \-k, --keep-in-foreground |
75 | Do not go into the background at startup but otherwise run as | |
3d8df260 SK |
76 | normal. This is intended for use when dnsmasq is run under daemontools |
77 | or launchd. | |
3be34541 | 78 | .TP |
9e4abcb5 SK |
79 | .B \-d, --no-daemon |
80 | Debug mode: don't fork to the background, don't write a pid file, | |
81 | don't change user id, generate a complete cache dump on receipt on | |
3be34541 SK |
82 | SIGUSR1, log to stderr as well as syslog, don't fork new processes |
83 | to handle TCP queries. | |
9e4abcb5 SK |
84 | .TP |
85 | .B \-q, --log-queries | |
86 | Log the results of DNS queries handled by dnsmasq. Enable a full cache dump on receipt of SIGUSR1. | |
87 | .TP | |
849a8357 SK |
88 | .B \-8, --log-facility=<facility> |
89 | Set the facility to which dnsmasq will send syslog entries, this | |
f2621c7f | 90 | defaults to DAEMON, and to LOCAL0 when debug mode is in operation. If |
9e038946 | 91 | the facility given contains at least one '/' character, it is taken to |
f2621c7f | 92 | be a filename, and dnsmasq logs to the given file, instead of |
8ef5ada2 SK |
93 | syslog. If the facility is '-' then dnsmasq logs to stderr. |
94 | (Errors whilst reading configuration will still go to syslog, | |
f2621c7f | 95 | but all output from a successful startup, and all output whilst |
5aabfc78 SK |
96 | running, will go exclusively to the file.) When logging to a file, |
97 | dnsmasq will close and reopen the file when it receives SIGUSR2. This | |
98 | allows the log file to be rotated without stopping dnsmasq. | |
f2621c7f SK |
99 | .TP |
100 | .B --log-async[=<lines>] | |
101 | Enable asynchronous logging and optionally set the limit on the | |
102 | number of lines | |
103 | which will be queued by dnsmasq when writing to the syslog is slow. | |
104 | Dnsmasq can log asynchronously: this | |
105 | allows it to continue functioning without being blocked by syslog, and | |
106 | allows syslog to use dnsmasq for DNS queries without risking deadlock. | |
107 | If the queue of log-lines becomes full, dnsmasq will log the | |
108 | overflow, and the number of messages lost. The default queue length is | |
109 | 5, a sane value would be 5-25, and a maximum limit of 100 is imposed. | |
849a8357 | 110 | .TP |
9e4abcb5 SK |
111 | .B \-x, --pid-file=<path> |
112 | Specify an alternate path for dnsmasq to record its process-id in. Normally /var/run/dnsmasq.pid. | |
113 | .TP | |
114 | .B \-u, --user=<username> | |
115 | Specify the userid to which dnsmasq will change after startup. Dnsmasq must normally be started as root, but it will drop root | |
b8187c80 | 116 | privileges after startup by changing id to another user. Normally this user is "nobody" but that |
9e4abcb5 SK |
117 | can be over-ridden with this switch. |
118 | .TP | |
119 | .B \-g, --group=<groupname> | |
120 | Specify the group which dnsmasq will run | |
121 | as. The defaults to "dip", if available, to facilitate access to | |
122 | /etc/ppp/resolv.conf which is not normally world readable. | |
123 | .TP | |
124 | .B \-v, --version | |
125 | Print the version number. | |
126 | .TP | |
127 | .B \-p, --port=<port> | |
824af85b SK |
128 | Listen on <port> instead of the standard DNS port (53). Setting this |
129 | to zero completely disables DNS function, leaving only DHCP and/or TFTP. | |
9e4abcb5 | 130 | .TP |
feba5c1d SK |
131 | .B \-P, --edns-packet-max=<size> |
132 | Specify the largest EDNS.0 UDP packet which is supported by the DNS | |
316e2730 | 133 | forwarder. Defaults to 4096, which is the RFC5625-recommended size. |
feba5c1d | 134 | .TP |
9e4abcb5 | 135 | .B \-Q, --query-port=<query_port> |
1a6bca81 SK |
136 | Send outbound DNS queries from, and listen for their replies on, the |
137 | specific UDP port <query_port> instead of using random ports. NOTE | |
138 | that using this option will make dnsmasq less secure against DNS | |
139 | spoofing attacks but it may be faster and use less resources. Setting this option | |
140 | to zero makes dnsmasq use a single port allocated to it by the | |
141 | OS: this was the default behaviour in versions prior to 2.43. | |
142 | .TP | |
143 | .B --min-port=<port> | |
144 | Do not use ports less than that given as source for outbound DNS | |
145 | queries. Dnsmasq picks random ports as source for outbound queries: | |
146 | when this option is given, the ports used will always to larger | |
147 | than that specified. Useful for systems behind firewalls. | |
9e4abcb5 SK |
148 | .TP |
149 | .B \-i, --interface=<interface name> | |
feba5c1d SK |
150 | Listen only on the specified interface(s). Dnsmasq automatically adds |
151 | the loopback (local) interface to the list of interfaces to use when | |
152 | the | |
153 | .B \--interface | |
154 | option is used. If no | |
155 | .B \--interface | |
9e4abcb5 | 156 | or |
feba5c1d SK |
157 | .B \--listen-address |
158 | options are given dnsmasq listens on all available interfaces except any | |
159 | given in | |
160 | .B \--except-interface | |
309331f5 | 161 | options. IP alias interfaces (eg "eth1:0") cannot be used with |
8a911ccc SK |
162 | .B --interface |
163 | or | |
164 | .B --except-interface | |
309331f5 | 165 | options, use --listen-address instead. |
9e4abcb5 SK |
166 | .TP |
167 | .B \-I, --except-interface=<interface name> | |
feba5c1d SK |
168 | Do not listen on the specified interface. Note that the order of |
169 | .B \--listen-address | |
170 | .B --interface | |
171 | and | |
172 | .B --except-interface | |
173 | options does not matter and that | |
174 | .B --except-interface | |
175 | options always override the others. | |
9e4abcb5 | 176 | .TP |
3d8df260 | 177 | .B \-2, --no-dhcp-interface=<interface name> |
832af0ba | 178 | Do not provide DHCP or TFTP on the specified interface, but do provide DNS service. |
3d8df260 | 179 | .TP |
44a2a316 | 180 | .B \-a, --listen-address=<ipaddr> |
feba5c1d SK |
181 | Listen on the given IP address(es). Both |
182 | .B \--interface | |
183 | and | |
184 | .B \--listen-address | |
185 | options may be given, in which case the set of both interfaces and | |
186 | addresses is used. Note that if no | |
187 | .B \--interface | |
188 | option is given, but | |
189 | .B \--listen-address | |
190 | is, dnsmasq will not automatically listen on the loopback | |
191 | interface. To achieve this, its IP address, 127.0.0.1, must be | |
192 | explicitly given as a | |
193 | .B \--listen-address | |
194 | option. | |
9e4abcb5 | 195 | .TP |
44a2a316 SK |
196 | .B \-z, --bind-interfaces |
197 | On systems which support it, dnsmasq binds the wildcard address, | |
198 | even when it is listening on only some interfaces. It then discards | |
199 | requests that it shouldn't reply to. This has the advantage of | |
200 | working even when interfaces come and go and change address. This | |
201 | option forces dnsmasq to really bind only the interfaces it is | |
202 | listening on. About the only time when this is useful is when | |
f6b7dc47 | 203 | running another nameserver (or another instance of dnsmasq) on the |
309331f5 | 204 | same machine. Setting this option also enables multiple instances of |
f6b7dc47 SK |
205 | dnsmasq which provide DHCP service to run in the same machine. |
206 | .TP | |
207 | .B \-y, --localise-queries | |
208 | Return answers to DNS queries from /etc/hosts which depend on the interface over which the query was | |
b8187c80 | 209 | received. If a name in /etc/hosts has more than one address associated with |
f6b7dc47 SK |
210 | it, and at least one of those addresses is on the same subnet as the |
211 | interface to which the query was sent, then return only the | |
212 | address(es) on that subnet. This allows for a server to have multiple | |
213 | addresses in /etc/hosts corresponding to each of its interfaces, and | |
214 | hosts will get the correct address based on which network they are | |
215 | attached to. Currently this facility is limited to IPv4. | |
44a2a316 | 216 | .TP |
9e4abcb5 SK |
217 | .B \-b, --bogus-priv |
218 | Bogus private reverse lookups. All reverse lookups for private IP ranges (ie 192.168.x.x, etc) | |
feba5c1d SK |
219 | which are not found in /etc/hosts or the DHCP leases file are answered |
220 | with "no such domain" rather than being forwarded upstream. | |
9e4abcb5 | 221 | .TP |
73a08a24 | 222 | .B \-V, --alias=[<old-ip>]|[<start-ip>-<end-ip>],<new-ip>[,<mask>] |
1cff166d SK |
223 | Modify IPv4 addresses returned from upstream nameservers; old-ip is |
224 | replaced by new-ip. If the optional mask is given then any address | |
225 | which matches the masked old-ip will be re-written. So, for instance | |
226 | .B --alias=1.2.3.0,6.7.8.0,255.255.255.0 | |
227 | will map 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. This is what | |
73a08a24 SK |
228 | Cisco PIX routers call "DNS doctoring". If the old IP is given as |
229 | range, then only addresses in the range, rather than a whole subnet, | |
230 | are re-written. So | |
231 | .B --alias=192.168.0.10-192.168.0.40,10.0.0.0,255.255.255.0 | |
232 | maps 192.168.0.10->192.168.0.40 to 10.0.0.10->10.0.0.40 | |
1cff166d | 233 | .TP |
9e4abcb5 SK |
234 | .B \-B, --bogus-nxdomain=<ipaddr> |
235 | Transform replies which contain the IP address given into "No such | |
236 | domain" replies. This is intended to counteract a devious move made by | |
b8187c80 | 237 | Verisign in September 2003 when they started returning the address of |
9e4abcb5 SK |
238 | an advertising web page in response to queries for unregistered names, |
239 | instead of the correct NXDOMAIN response. This option tells dnsmasq to | |
240 | fake the correct response when it sees this behaviour. As at Sept 2003 | |
b8187c80 | 241 | the IP address being returned by Verisign is 64.94.110.11 |
9e4abcb5 SK |
242 | .TP |
243 | .B \-f, --filterwin2k | |
244 | Later versions of windows make periodic DNS requests which don't get sensible answers from | |
245 | the public DNS and can cause problems by triggering dial-on-demand links. This flag turns on an option | |
246 | to filter such requests. The requests blocked are for records of types SOA and SRV, and type ANY where the | |
247 | requested name has underscores, to catch LDAP requests. | |
248 | .TP | |
249 | .B \-r, --resolv-file=<file> | |
250 | Read the IP addresses of the upstream nameservers from <file>, instead of | |
251 | /etc/resolv.conf. For the format of this file see | |
7de060b0 SK |
252 | .BR resolv.conf (5). |
253 | The only lines relevant to dnsmasq are nameserver ones. Dnsmasq can | |
9e4abcb5 SK |
254 | be told to poll more than one resolv.conf file, the first file name specified |
255 | overrides the default, subsequent ones add to the list. This is only | |
256 | allowed when polling; the file with the currently latest modification | |
257 | time is the one used. | |
258 | .TP | |
259 | .B \-R, --no-resolv | |
260 | Don't read /etc/resolv.conf. Get upstream servers only from the command | |
b49644f3 | 261 | line or the dnsmasq configuration file. |
9e4abcb5 | 262 | .TP |
3d8df260 SK |
263 | .B \-1, --enable-dbus |
264 | Allow dnsmasq configuration to be updated via DBus method calls. The | |
265 | configuration which can be changed is upstream DNS servers (and | |
b8187c80 | 266 | corresponding domains) and cache clear. Requires that dnsmasq has |
3d8df260 SK |
267 | been built with DBus support. |
268 | .TP | |
9e4abcb5 SK |
269 | .B \-o, --strict-order |
270 | By default, dnsmasq will send queries to any of the upstream servers | |
824af85b | 271 | it knows about and tries to favour servers that are known to |
9e4abcb5 SK |
272 | be up. Setting this flag forces dnsmasq to try each query with each |
273 | server strictly in the order they appear in /etc/resolv.conf | |
274 | .TP | |
824af85b SK |
275 | .B --all-servers |
276 | By default, when dnsmasq has more than one upstream server available, | |
277 | it will send queries to just one server. Setting this flag forces | |
278 | dnsmasq to send all queries to all available servers. The reply from | |
c72daea8 | 279 | the server which answers first will be returned to the original requester. |
824af85b SK |
280 | .TP |
281 | .B --stop-dns-rebind | |
282 | Reject (and log) addresses from upstream nameservers which are in the | |
283 | private IP ranges. This blocks an attack where a browser behind a | |
284 | firewall is used to probe machines on the local network. | |
285 | .TP | |
8ef5ada2 SK |
286 | .B --rebind-localhost-ok |
287 | Exempt 127.0.0.0/8 from rebinding checks. This address range is | |
288 | returned by realtime black hole servers, so blocking it may disable | |
289 | these services. | |
290 | .TP | |
291 | .B --rebind-domain-ok=[<domain>]|[[/<domain>/[<domain>/] | |
292 | Do not detect and block dns-rebind on queries to these domains. The | |
293 | argument may be either a single domain, or multiple domains surrounded | |
294 | by '/', like the --server syntax, eg. | |
295 | .B --rebind-domain-ok=/domain1/domain2/domain3/ | |
296 | .TP | |
9e4abcb5 SK |
297 | .B \-n, --no-poll |
298 | Don't poll /etc/resolv.conf for changes. | |
299 | .TP | |
1697269c SK |
300 | .B --clear-on-reload |
301 | Whenever /etc/resolv.conf is re-read, clear the DNS cache. | |
302 | This is useful when new nameservers may have different | |
303 | data than that held in cache. | |
304 | .TP | |
9e4abcb5 | 305 | .B \-D, --domain-needed |
7de060b0 | 306 | Tells dnsmasq to never forward A or AAAA queries for plain names, without dots |
3d8df260 | 307 | or domain parts, to upstream nameservers. If the name is not known |
9e4abcb5 SK |
308 | from /etc/hosts or DHCP then a "not found" answer is returned. |
309 | .TP | |
824af85b | 310 | .B \-S, --local, --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>][@<source-ip>|<interface>[#<port>]] |
5aabfc78 | 311 | Specify IP address of upstream servers directly. Setting this flag does |
9e4abcb5 SK |
312 | not suppress reading of /etc/resolv.conf, use -R to do that. If one or |
313 | more | |
314 | optional domains are given, that server is used only for those domains | |
315 | and they are queried only using the specified server. This is | |
316 | intended for private nameservers: if you have a nameserver on your | |
317 | network which deals with names of the form | |
318 | xxx.internal.thekelleys.org.uk at 192.168.1.1 then giving the flag | |
b8187c80 | 319 | .B -S /internal.thekelleys.org.uk/192.168.1.1 |
9e4abcb5 SK |
320 | will send all queries for |
321 | internal machines to that nameserver, everything else will go to the | |
322 | servers in /etc/resolv.conf. An empty domain specification, | |
323 | .B // | |
324 | has the special meaning of "unqualified names only" ie names without any | |
325 | dots in them. A non-standard port may be specified as | |
326 | part of the IP | |
327 | address using a # character. | |
328 | More than one -S flag is allowed, with | |
8ef5ada2 SK |
329 | repeated domain or ipaddr parts as required. |
330 | ||
331 | More specific domains take precendence over less specific domains, so: | |
332 | .B --server=/google.com/1.2.3.4 | |
333 | .B --server=/www.google.com/2.3.4.5 | |
334 | will send queries for *.google.com to 1.2.3.4, except *www.google.com, | |
335 | which will go to 2.3.4.5 | |
336 | ||
337 | The special server address '#' means, "use the standard servers", so | |
338 | .B --server=/google.com/1.2.3.4 | |
339 | .B --server=/www.google.com/# | |
340 | will send queries for *.google.com to 1.2.3.4, except *www.google.com which will | |
341 | be forwarded as usual. | |
9e4abcb5 SK |
342 | |
343 | Also permitted is a -S | |
344 | flag which gives a domain but no IP address; this tells dnsmasq that | |
345 | a domain is local and it may answer queries from /etc/hosts or DHCP | |
346 | but should never forward queries on that domain to any upstream | |
347 | servers. | |
348 | .B local | |
349 | is a synonym for | |
350 | .B server | |
351 | to make configuration files clearer in this case. | |
352 | ||
7de060b0 SK |
353 | IPv6 addresses may include a %interface scope-id, eg |
354 | fe80::202:a412:4512:7bbf%eth0. | |
355 | ||
824af85b SK |
356 | The optional string after the @ character tells |
357 | dnsmasq how to set the source of the queries to this | |
358 | nameserver. It should be an ip-address, which should belong to the machine on which | |
9e4abcb5 | 359 | dnsmasq is running otherwise this server line will be logged and then |
824af85b SK |
360 | ignored, or an interface name. If an interface name is given, then |
361 | queries to the server will be forced via that interface; if an | |
362 | ip-address is given then the source address of the queries will be set | |
363 | to that address. | |
364 | The query-port flag is ignored for any servers which have a | |
9e4abcb5 | 365 | source address specified but the port may be specified directly as |
824af85b SK |
366 | part of the source address. Forcing queries to an interface is not |
367 | implemented on all platforms supported by dnsmasq. | |
9e4abcb5 SK |
368 | .TP |
369 | .B \-A, --address=/<domain>/[domain/]<ipaddr> | |
370 | Specify an IP address to return for any host in the given domains. | |
371 | Queries in the domains are never forwarded and always replied to | |
372 | with the specified IP address which may be IPv4 or IPv6. To give | |
373 | both IPv4 and IPv6 addresses for a domain, use repeated -A flags. | |
374 | Note that /etc/hosts and DHCP leases override this for individual | |
375 | names. A common use of this is to redirect the entire doubleclick.net | |
a222641c SK |
376 | domain to some friendly local web server to avoid banner ads. The |
377 | domain specification works in the same was as for --server, with the | |
378 | additional facility that /#/ matches any domain. Thus | |
379 | --address=/#/1.2.3.4 will always return 1.2.3.4 for any query not | |
380 | answered from /etc/hosts or DHCP and not sent to an upstream | |
381 | nameserver by a more specific --server directive. | |
9e4abcb5 | 382 | .TP |
f6b7dc47 | 383 | .B \-m, --mx-host=<mx name>[[,<hostname>],<preference>] |
de37951c SK |
384 | Return an MX record named <mx name> pointing to the given hostname (if |
385 | given), or | |
386 | the host specified in the --mx-target switch | |
9e4abcb5 | 387 | or, if that switch is not given, the host on which dnsmasq |
f6b7dc47 SK |
388 | is running. The default is useful for directing mail from systems on a LAN |
389 | to a central server. The preference value is optional, and defaults to | |
390 | 1 if not given. More than one MX record may be given for a host. | |
9e4abcb5 SK |
391 | .TP |
392 | .B \-t, --mx-target=<hostname> | |
f6b7dc47 SK |
393 | Specify the default target for the MX record returned by dnsmasq. See |
394 | --mx-host. If --mx-target is given, but not --mx-host, then dnsmasq | |
395 | returns a MX record containing the MX target for MX queries on the | |
396 | hostname of the machine on which dnsmasq is running. | |
9e4abcb5 SK |
397 | .TP |
398 | .B \-e, --selfmx | |
399 | Return an MX record pointing to itself for each local | |
400 | machine. Local machines are those in /etc/hosts or with DHCP leases. | |
401 | .TP | |
402 | .B \-L, --localmx | |
403 | Return an MX record pointing to the host given by mx-target (or the | |
404 | machine on which dnsmasq is running) for each | |
405 | local machine. Local machines are those in /etc/hosts or with DHCP | |
406 | leases. | |
407 | .TP | |
f6b7dc47 SK |
408 | .B \-W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<priority>[,<weight>]]]] |
409 | Return a SRV DNS record. See RFC2782 for details. If not supplied, the | |
410 | domain defaults to that given by | |
411 | .B --domain. | |
412 | The default for the target domain is empty, and the default for port | |
413 | is one and the defaults for | |
414 | weight and priority are zero. Be careful if transposing data from BIND | |
415 | zone files: the port, weight and priority numbers are in a different | |
416 | order. More than one SRV record for a given service/domain is allowed, | |
3d8df260 | 417 | all that match are returned. |
f6b7dc47 | 418 | .TP |
e759d426 SK |
419 | .B --host-record=<name>[,<name>....][<IPv4-address>],[IPv6-address] |
420 | Add A, AAAA and PTR records to the DNS. This adds one or more names to | |
421 | the DNS with associated IPv4 (A) and IPv6 (AAAA) records. A name may | |
422 | appear in more than one | |
423 | .B host-record | |
424 | and therefore be assigned more than one address. Only the first | |
425 | address creates a PTR record linking the address to the name. This is | |
426 | the same rule as is used reading hosts-files. | |
427 | .B host-record | |
428 | options are considered to be read before host-files, so a name | |
429 | appearing there inhibits PTR-record creation if it appears in | |
430 | hosts-file also. Unlike host-files, names are not expanded, even when | |
431 | .B expand-hosts | |
432 | is in effect. Short and long names may appear in the same | |
433 | .B host-record, eg. --host-record=laptop,laptop.thekelleys.org,192.168.0.1,1234::100 | |
434 | .TP | |
0a852541 SK |
435 | .B \-Y, --txt-record=<name>[[,<text>],<text>] |
436 | Return a TXT DNS record. The value of TXT record is a set of strings, | |
28866e95 SK |
437 | so any number may be included, delimited by commas; use quotes to put |
438 | commas into a string. Note that the maximum length of a single string | |
439 | is 255 characters, longer strings are split into 255 character chunks. | |
0a852541 | 440 | .TP |
832af0ba SK |
441 | .B --ptr-record=<name>[,<target>] |
442 | Return a PTR DNS record. | |
443 | .TP | |
1a6bca81 SK |
444 | .B --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<regexp>[,<replacement>] |
445 | Return an NAPTR DNS record, as specified in RFC3403. | |
446 | .TP | |
9009d746 SK |
447 | .B --cname=<cname>,<target> |
448 | Return a CNAME record which indicates that <cname> is really | |
449 | <target>. There are significant limitations on the target; it must be a | |
450 | DNS name which is known to dnsmasq from /etc/hosts (or additional | |
451 | hosts files) or from DHCP. If the target does not satisfy this | |
452 | criteria, the whole cname is ignored. The cname must be unique, but it | |
453 | is permissable to have more than one cname pointing to the same target. | |
454 | .TP | |
f2621c7f SK |
455 | .B --interface-name=<name>,<interface> |
456 | Return a DNS record associating the name with the primary address on | |
457 | the given interface. This flag specifies an A record for the given | |
458 | name in the same way as an /etc/hosts line, except that the address is | |
459 | not constant, but taken from the given interface. If the interface is | |
9e038946 | 460 | down, not configured or non-existent, an empty record is returned. The |
f2621c7f SK |
461 | matching PTR record is also created, mapping the interface address to |
462 | the name. More than one name may be associated with an interface | |
463 | address by repeating the flag; in that case the first instance is used | |
464 | for the reverse address-to-name mapping. | |
465 | .TP | |
28866e95 SK |
466 | .B --add-mac |
467 | Add the MAC address of the requestor to DNS queries which are | |
468 | forwarded upstream. This may be used to DNS filtering by the upstream | |
469 | server. The MAC address can only be added if the requestor is on the same | |
470 | subnet as the dnsmasq server. Note that the mechanism used to achieve this (an EDNS0 option) | |
471 | is not yet standardised, so this should be considered | |
472 | experimental. Also note that exposing MAC addresses in this way may | |
473 | have security and privacy implications. | |
474 | .TP | |
9e4abcb5 SK |
475 | .B \-c, --cache-size=<cachesize> |
476 | Set the size of dnsmasq's cache. The default is 150 names. Setting the cache size to zero disables caching. | |
477 | .TP | |
478 | .B \-N, --no-negcache | |
479 | Disable negative caching. Negative caching allows dnsmasq to remember | |
480 | "no such domain" answers from upstream nameservers and answer | |
5aabfc78 | 481 | identical queries without forwarding them again. |
9e4abcb5 | 482 | .TP |
1697269c SK |
483 | .B \-0, --dns-forward-max=<queries> |
484 | Set the maximum number of concurrent DNS queries. The default value is | |
485 | 150, which should be fine for most setups. The only known situation | |
486 | where this needs to be increased is when using web-server log file | |
487 | resolvers, which can generate large numbers of concurrent queries. | |
208b65c5 | 488 | .TP |
28866e95 SK |
489 | .B --proxy-dnssec |
490 | A resolver on a client machine can do DNSSEC validation in two ways: it | |
491 | can perform the cryptograhic operations on the reply it receives, or | |
492 | it can rely on the upstream recursive nameserver to do the validation | |
493 | and set a bit in the reply if it succeeds. Dnsmasq is not a DNSSEC | |
494 | validator, so it cannot perform the validation role of the recursive nameserver, | |
495 | but it can pass through the validation results from its own upstream | |
496 | nameservers. This option enables this behaviour. You should only do | |
497 | this if you trust all the configured upstream nameservers | |
498 | .I and the network between you and them. | |
499 | If you use the first DNSSEC mode, validating resolvers in clients, | |
500 | this option is not required. Dnsmasq always returns all the data | |
501 | needed for a client to do validation itself. | |
502 | .TP | |
7de060b0 SK |
503 | .B --conntrack |
504 | Read the Linux connection track mark associated with incoming DNS | |
505 | queries and set the same mark value on upstream traffic used to answer | |
506 | those queries. This allows traffic generated by dnsmasq to be | |
507 | associated with the queries which cause it, useful for bandwidth | |
508 | accounting and firewalling. Dnsmasq must have conntrack support | |
509 | compiled in and the kernel must have conntrack support | |
510 | included and configured. This option cannot be combined with | |
511 | --query-port. | |
512 | .TP | |
e8ca69ea | 513 | .B \-F, --dhcp-range=[interface:<interface>,][tag:<tag>[,tag:<tag>],][set:<tag],]<start-addr>[,<end-addr>][,<mode>][,<netmask>[,<broadcast>]][,<lease time>] |
1adadf58 | 514 | .TP |
e8ca69ea | 515 | .B \-F, --dhcp-range=[interface:<interface>,][tag:<tag>[,tag:<tag>],][set:<tag],]<start-IPv6addr>[,<end-IPv6addr>][,<mode>][,<prefix-len>][,<lease time>] |
1adadf58 | 516 | |
9e4abcb5 | 517 | Enable the DHCP server. Addresses will be given out from the range |
44a2a316 SK |
518 | <start-addr> to <end-addr> and from statically defined addresses given |
519 | in | |
520 | .B dhcp-host | |
521 | options. If the lease time is given, then leases | |
b8187c80 | 522 | will be given for that length of time. The lease time is in seconds, |
7622fc06 SK |
523 | or minutes (eg 45m) or hours (eg 1h) or "infinite". If not given, |
524 | the default lease time is one hour. The | |
c8257540 SK |
525 | minimum lease time is two minutes. For IPv6 ranges, the lease time |
526 | maybe "deprecated"; this sets the preferred lifetime sent in a DHCP | |
527 | lease or router advertisement to zero, which causes clients to use | |
528 | other addresses, if available, for new connections as a prelude to renumbering. | |
529 | ||
530 | This option may be repeated, with different addresses, to enable DHCP | |
44a2a316 SK |
531 | service to more than one network. For directly connected networks (ie, |
532 | networks on which the machine running dnsmasq has an interface) the | |
7de060b0 SK |
533 | netmask is optional: dnsmasq will determine it from the interface |
534 | configuration. For networks which receive DHCP service via a relay | |
535 | agent, dnsmasq cannot determine the netmask itself, so it should be | |
536 | specified, otherwise dnsmasq will have to guess, based on the class (A, B or | |
537 | C) of the network address. The broadcast address is | |
7622fc06 | 538 | always optional. It is always |
8ef5ada2 SK |
539 | allowed to have more than one dhcp-range in a single subnet. |
540 | ||
1adadf58 SK |
541 | For IPv6, the parameters are slightly different: instead of netmask |
542 | and broadcast address, there is an optional prefix length. If not | |
543 | given, this defaults to 64. Unlike the IPv4 case, the prefix length is not | |
544 | automatically derived from the interface configuration. The mimimum | |
545 | size of the prefix length is 64. | |
546 | ||
8ef5ada2 SK |
547 | The optional |
548 | .B set:<tag> | |
549 | sets an alphanumeric label which marks this network so that | |
0a852541 | 550 | dhcp options may be specified on a per-network basis. |
8ef5ada2 | 551 | When it is prefixed with 'tag:' instead, then its meaning changes from setting |
c5ad4e79 SK |
552 | a tag to matching it. Only one tag may be set, but more than one tag |
553 | may be matched. | |
554 | ||
e8ca69ea | 555 | The optional <mode> keyword may be |
33820b7e SK |
556 | .B static |
557 | which tells dnsmasq to enable DHCP for the network specified, but not | |
7622fc06 | 558 | to dynamically allocate IP addresses: only hosts which have static |
33820b7e SK |
559 | addresses given via |
560 | .B dhcp-host | |
c5ad4e79 SK |
561 | or from /etc/ethers will be served. |
562 | ||
e8ca69ea | 563 | Fot IPv4, the <mode> may be |
7622fc06 SK |
564 | .B proxy |
565 | in which case dnsmasq will provide proxy-DHCP on the specified | |
566 | subnet. (See | |
567 | .B pxe-prompt | |
568 | and | |
569 | .B pxe-service | |
e8ca69ea SK |
570 | for details.) |
571 | ||
572 | For IPv6, the mode may be some combination of | |
573 | .B ra-only, slaac, ra-names, ra-stateless. | |
8ef5ada2 | 574 | |
c5ad4e79 | 575 | .B ra-only |
e8ca69ea SK |
576 | tells dnsmasq to offer Router Advertisement only on this subnet, |
577 | and not DHCP. | |
578 | ||
579 | .B slaac | |
580 | tells dnsmasq to offer Router Advertisement on this subnet and to set | |
581 | the A bit in the router advertisement, so that the client will use | |
582 | SLAAC addresses. When used with a DHCP range or static DHCP address | |
583 | this results in the client having both a DHCP-assigned and a SLAAC | |
584 | address. | |
585 | ||
586 | .B ra-stateless | |
587 | sends router advertisements with the O and A bits set, and provides a | |
588 | stateless DHCP service. The client will use a SLAAC address, and use | |
589 | DHCP for other configuration information. | |
590 | ||
7023e382 | 591 | .B ra-names |
e8ca69ea | 592 | enables a mode |
7023e382 | 593 | which gives DNS names to dual-stack hosts which do SLAAC for |
884a6dfe | 594 | IPv6. Dnsmasq uses the host's IPv4 lease to derive the name, network |
7023e382 SK |
595 | segment and MAC address and assumes that the host will also have an |
596 | IPv6 address calculated using the SLAAC alogrithm, on the same network | |
884a6dfe SK |
597 | segment. The address is pinged, and if a reply is received, an AAAA |
598 | record is added to the DNS for this IPv6 | |
7023e382 | 599 | address. Note that this is only happens for directly-connected |
884a6dfe SK |
600 | networks, (not one doing DHCP via a relay) and it will not work |
601 | if a host is using privacy extensions. | |
e8ca69ea SK |
602 | .B ra-names |
603 | can be combined with | |
604 | .B ra-stateless | |
605 | and | |
606 | .B slaac. | |
c5ad4e79 | 607 | |
8ef5ada2 SK |
608 | The interface:<interface name> section is not normally used. See the |
609 | NOTES section for details of this. | |
9e4abcb5 | 610 | .TP |
8ef5ada2 | 611 | .B \-G, --dhcp-host=[<hwaddr>][,id:<client_id>|*][,set:<tag>][,<ipaddr>][,<hostname>][,<lease_time>][,ignore] |
9e4abcb5 SK |
612 | Specify per host parameters for the DHCP server. This allows a machine |
613 | with a particular hardware address to be always allocated the same | |
614 | hostname, IP address and lease time. A hostname specified like this | |
615 | overrides any supplied by the DHCP client on the machine. It is also | |
c72daea8 | 616 | allowable to omit the hardware address and include the hostname, in |
9e4abcb5 SK |
617 | which case the IP address and lease times will apply to any machine |
618 | claiming that name. For example | |
619 | .B --dhcp-host=00:20:e0:3b:13:af,wap,infinite | |
620 | tells dnsmasq to give | |
cdeda28f | 621 | the machine with hardware address 00:20:e0:3b:13:af the name wap, and |
9e4abcb5 SK |
622 | an infinite DHCP lease. |
623 | .B --dhcp-host=lap,192.168.0.199 | |
624 | tells | |
625 | dnsmasq to always allocate the machine lap the IP address | |
8ef5ada2 SK |
626 | 192.168.0.199. |
627 | ||
628 | Addresses allocated like this are not constrained to be | |
629 | in the range given by the --dhcp-range option, but they must be in | |
630 | the same subnet as some valid dhcp-range. For | |
631 | subnets which don't need a pool of dynamically allocated addresses, | |
632 | use the "static" keyword in the dhcp-range declaration. | |
633 | ||
634 | It is allowed to use client identifiers rather than | |
9e4abcb5 SK |
635 | hardware addresses to identify hosts by prefixing with 'id:'. Thus: |
636 | .B --dhcp-host=id:01:02:03:04,..... | |
637 | refers to the host with client identifier 01:02:03:04. It is also | |
638 | allowed to specify the client ID as text, like this: | |
a84fa1d0 | 639 | .B --dhcp-host=id:clientidastext,..... |
9009d746 | 640 | |
1adadf58 SK |
641 | A single |
642 | .B dhcp-host | |
643 | may contain an IPv4 address or an IPv6 address, or both. IPv6 addresses must be bracketed by square brackets thus: | |
644 | .B --dhcp-host=laptop,[1234::56] | |
a156cae9 | 645 | Note that in IPv6 DHCP, the hardware address is not normally available, so a client must be identified by client-id (called client DUID in IPv6-land) or hostname. |
1adadf58 | 646 | |
a84fa1d0 SK |
647 | The special option id:* means "ignore any client-id |
648 | and use MAC addresses only." This is useful when a client presents a client-id sometimes | |
649 | but not others. | |
9009d746 | 650 | |
1ab84e2f SK |
651 | If a name appears in /etc/hosts, the associated address can be |
652 | allocated to a DHCP lease, but only if a | |
653 | .B --dhcp-host | |
8ef5ada2 SK |
654 | option specifying the name also exists. Only one hostname can be |
655 | given in a | |
656 | .B dhcp-host | |
657 | option, but aliases are possible by using CNAMEs. (See | |
658 | .B --cname | |
659 | ). | |
660 | ||
661 | The special keyword "ignore" | |
33820b7e SK |
662 | tells dnsmasq to never offer a DHCP lease to a machine. The machine |
663 | can be specified by hardware address, client ID or hostname, for | |
664 | instance | |
665 | .B --dhcp-host=00:20:e0:3b:13:af,ignore | |
666 | This is | |
667 | useful when there is another DHCP server on the network which should | |
9009d746 SK |
668 | be used by some machines. |
669 | ||
8ef5ada2 | 670 | The set:<tag> contruct sets the tag |
9009d746 | 671 | whenever this dhcp-host directive is in use. This can be used to |
8ef5ada2 SK |
672 | selectively send DHCP options just for this host. More than one tag |
673 | can be set in a dhcp-host directive (but not in other places where | |
674 | "set:<tag>" is allowed). When a host matches any | |
5aabfc78 | 675 | dhcp-host directive (or one implied by /etc/ethers) then the special |
8ef5ada2 | 676 | tag "known" is set. This allows dnsmasq to be configured to |
5aabfc78 | 677 | ignore requests from unknown machines using |
8ef5ada2 | 678 | .B --dhcp-ignore=tag:!known |
0a852541 SK |
679 | Ethernet addresses (but not client-ids) may have |
680 | wildcard bytes, so for example | |
681 | .B --dhcp-host=00:20:e0:3b:13:*,ignore | |
cdeda28f | 682 | will cause dnsmasq to ignore a range of hardware addresses. Note that |
0a852541 | 683 | the "*" will need to be escaped or quoted on a command line, but not |
9009d746 SK |
684 | in the configuration file. |
685 | ||
686 | Hardware addresses normally match any | |
cdeda28f SK |
687 | network (ARP) type, but it is possible to restrict them to a single |
688 | ARP type by preceding them with the ARP-type (in HEX) and "-". so | |
689 | .B --dhcp-host=06-00:20:e0:3b:13:af,1.2.3.4 | |
690 | will only match a | |
691 | Token-Ring hardware address, since the ARP-address type for token ring | |
9009d746 SK |
692 | is 6. |
693 | ||
1adadf58 | 694 | As a special case, in DHCPv4, it is possible to include more than one |
73a08a24 SK |
695 | hardware address. eg: |
696 | .B --dhcp-host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2 | |
697 | This allows an IP address to be associated with | |
9009d746 SK |
698 | multiple hardware addresses, and gives dnsmasq permission to abandon a |
699 | DHCP lease to one of the hardware addresses when another one asks for | |
700 | a lease. Beware that this is a dangerous thing to do, it will only | |
701 | work reliably if only one of the hardware addresses is active at any | |
73a08a24 SK |
702 | time and there is no way for dnsmasq to enforce this. It is, for instance, |
703 | useful to allocate a stable IP address to a laptop which | |
9009d746 | 704 | has both wired and wireless interfaces. |
5aabfc78 | 705 | .TP |
28866e95 SK |
706 | .B --dhcp-hostsfile=<path> |
707 | Read DHCP host information from the specified file. If a directory | |
708 | is given, then read all the files contained in that directory. The file contains | |
5aabfc78 SK |
709 | information about one host per line. The format of a line is the same |
710 | as text to the right of '=' in --dhcp-host. The advantage of storing DHCP host information | |
711 | in this file is that it can be changed without re-starting dnsmasq: | |
712 | the file will be re-read when dnsmasq receives SIGHUP. | |
824af85b | 713 | .TP |
28866e95 SK |
714 | .B --dhcp-optsfile=<path> |
715 | Read DHCP option information from the specified file. If a directory | |
716 | is given, then read all the files contained in that directory. The advantage of | |
824af85b | 717 | using this option is the same as for --dhcp-hostsfile: the |
1f15b81d SK |
718 | dhcp-optsfile will be re-read when dnsmasq receives SIGHUP. Note that |
719 | it is possible to encode the information in a | |
720 | .B --dhcp-boot | |
721 | flag as DHCP options, using the options names bootfile-name, | |
722 | server-ip-address and tftp-server. This allows these to be included | |
723 | in a dhcp-optsfile. | |
44a2a316 SK |
724 | .TP |
725 | .B \-Z, --read-ethers | |
726 | Read /etc/ethers for information about hosts for the DHCP server. The | |
727 | format of /etc/ethers is a hardware address, followed by either a | |
728 | hostname or dotted-quad IP address. When read by dnsmasq these lines | |
729 | have exactly the same effect as | |
730 | .B --dhcp-host | |
5aabfc78 | 731 | options containing the same information. /etc/ethers is re-read when |
1adadf58 | 732 | dnsmasq receives SIGHUP. IPv6 addresses are NOT read from /etc/ethers. |
9e4abcb5 | 733 | .TP |
1adadf58 | 734 | .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>]] |
b8187c80 | 735 | Specify different or extra options to DHCP clients. By default, |
9e4abcb5 SK |
736 | dnsmasq sends some standard options to DHCP clients, the netmask and |
737 | broadcast address are set to the same as the host running dnsmasq, and | |
738 | the DNS server and default route are set to the address of the machine | |
1adadf58 | 739 | running dnsmasq. (Equivalent rules apply for IPv6.) If the domain name option has been set, that is sent. |
f2621c7f SK |
740 | This configuration allows these defaults to be overridden, |
741 | or other options specified. The option, to be sent may be given as a | |
742 | decimal number or as "option:<option-name>" The option numbers are | |
743 | specified in RFC2132 and subsequent RFCs. The set of option-names | |
744 | known by dnsmasq can be discovered by running "dnsmasq --help dhcp". | |
745 | For example, to set the default route option to | |
9e4abcb5 | 746 | 192.168.4.4, do |
f2621c7f SK |
747 | .B --dhcp-option=3,192.168.4.4 |
748 | or | |
749 | .B --dhcp-option = option:router, 192.168.4.4 | |
9e4abcb5 | 750 | and to set the time-server address to 192.168.0.4, do |
f2621c7f SK |
751 | .B --dhcp-option = 42,192.168.0.4 |
752 | or | |
753 | .B --dhcp-option = option:ntp-server, 192.168.0.4 | |
0010b474 | 754 | The special address 0.0.0.0 (or [::] for DHCPv6) is taken to mean "the address of the |
f6b7dc47 SK |
755 | machine running dnsmasq". Data types allowed are comma separated |
756 | dotted-quad IP addresses, a decimal number, colon-separated hex digits | |
8ef5ada2 SK |
757 | and a text string. If the optional tags are given then |
758 | this option is only sent when all the tags are matched. | |
91dccd09 | 759 | |
cdeda28f | 760 | Special processing is done on a text argument for option 119, to |
832af0ba SK |
761 | conform with RFC 3397. Text or dotted-quad IP addresses as arguments |
762 | to option 120 are handled as per RFC 3361. Dotted-quad IP addresses | |
763 | which are followed by a slash and then a netmask size are encoded as | |
764 | described in RFC 3442. | |
cdeda28f | 765 | |
1adadf58 SK |
766 | IPv6 options are specified using the |
767 | .B option6: | |
768 | keyword, followed by the option number or option name. The IPv6 option | |
769 | name space is disjoint from the IPv4 option name space. IPv6 addresses | |
770 | in options must be bracketed with square brackets, eg. | |
771 | .B --dhcp-option=option6:ntp-server,[1234::56] | |
772 | ||
773 | ||
9e4abcb5 | 774 | Be careful: no checking is done that the correct type of data for the |
26128d27 | 775 | option number is sent, it is quite possible to |
9e4abcb5 | 776 | persuade dnsmasq to generate illegal DHCP packets with injudicious use |
91dccd09 SK |
777 | of this flag. When the value is a decimal number, dnsmasq must determine how |
778 | large the data item is. It does this by examining the option number and/or the | |
b8187c80 | 779 | value, but can be overridden by appending a single letter flag as follows: |
91dccd09 | 780 | b = one byte, s = two bytes, i = four bytes. This is mainly useful with |
3d8df260 SK |
781 | encapsulated vendor class options (see below) where dnsmasq cannot |
782 | determine data size from the option number. Option data which | |
783 | consists solely of periods and digits will be interpreted by dnsmasq | |
784 | as an IP address, and inserted into an option as such. To force a | |
785 | literal string, use quotes. For instance when using option 66 to send | |
786 | a literal IP address as TFTP server name, it is necessary to do | |
787 | .B --dhcp-option=66,"1.2.3.4" | |
91dccd09 | 788 | |
1adadf58 | 789 | Encapsulated Vendor-class options may also be specified (IPv4 only) using |
91dccd09 | 790 | --dhcp-option: for instance |
1b7ecd11 SK |
791 | .B --dhcp-option=vendor:PXEClient,1,0.0.0.0 |
792 | sends the encapsulated vendor | |
793 | class-specific option "mftp-address=0.0.0.0" to any client whose | |
794 | vendor-class matches "PXEClient". The vendor-class matching is | |
6b01084f SK |
795 | substring based (see --dhcp-vendorclass for details). If a |
796 | vendor-class option (number 60) is sent by dnsmasq, then that is used | |
797 | for selecting encapsulated options in preference to any sent by the | |
798 | client. It is | |
1b7ecd11 SK |
799 | possible to omit the vendorclass completely; |
800 | .B --dhcp-option=vendor:,1,0.0.0.0 | |
1adadf58 | 801 | in which case the encapsulated option is always sent. |
73a08a24 | 802 | |
1adadf58 | 803 | Options may be encapsulated (IPv4 only) within other options: for instance |
73a08a24 SK |
804 | .B --dhcp-option=encap:175, 190, "iscsi-client0" |
805 | will send option 175, within which is the option 190. If multiple | |
806 | options are given which are encapsulated with the same option number | |
807 | then they will be correctly combined into one encapsulated option. | |
808 | encap: and vendor: are may not both be set in the same dhcp-option. | |
809 | ||
316e2730 SK |
810 | The final variant on encapsulated options is "Vendor-Identifying |
811 | Vendor Options" as specified by RFC3925. These are denoted like this: | |
812 | .B --dhcp-option=vi-encap:2, 10, "text" | |
813 | The number in the vi-encap: section is the IANA enterprise number | |
1adadf58 SK |
814 | used to identify this option. This form of encapsulation is supported |
815 | in IPv6. | |
816 | ||
1b7ecd11 | 817 | The address 0.0.0.0 is not treated specially in |
73a08a24 | 818 | encapsulated options. |
9e4abcb5 | 819 | .TP |
8ef5ada2 | 820 | .B --dhcp-option-force=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<enterprise>,][vendor:[<vendor-class>],]<opt>,[<value>[,<value>]] |
6b01084f | 821 | This works in exactly the same way as |
f2621c7f SK |
822 | .B --dhcp-option |
823 | except that the option will always be sent, even if the client does | |
6b01084f SK |
824 | not ask for it in the parameter request list. This is sometimes |
825 | needed, for example when sending options to PXELinux. | |
826 | .TP | |
824af85b | 827 | .B --dhcp-no-override |
1adadf58 | 828 | (IPv4 only) Disable re-use of the DHCP servername and filename fields as extra |
824af85b SK |
829 | option space. If it can, dnsmasq moves the boot server and filename |
830 | information (from dhcp-boot) out of their dedicated fields into | |
831 | DHCP options. This make extra space available in the DHCP packet for | |
832 | options but can, rarely, confuse old or broken clients. This flag | |
833 | forces "simple and safe" behaviour to avoid problems in such a case. | |
834 | .TP | |
1adadf58 | 835 | .B \-U, --dhcp-vendorclass=set:<tag>,[enterprise:<IANA-enterprise number>,]<vendor-class> |
8ef5ada2 | 836 | Map from a vendor-class string to a tag. Most DHCP clients provide a |
a222641c | 837 | "vendor class" which represents, in some sense, the type of host. This option |
f2621c7f | 838 | maps vendor classes to tags, so that DHCP options may be selectively delivered |
a84fa1d0 | 839 | to different classes of hosts. For example |
8ef5ada2 | 840 | .B dhcp-vendorclass=set:printers,Hewlett-Packard JetDirect |
a84fa1d0 | 841 | will allow options to be set only for HP printers like so: |
8ef5ada2 | 842 | .B --dhcp-option=tag:printers,3,192.168.4.4 |
a222641c SK |
843 | The vendor-class string is |
844 | substring matched against the vendor-class supplied by the client, to | |
1adadf58 SK |
845 | allow fuzzy matching. The set: prefix is optional but allowed for |
846 | consistency. | |
847 | ||
848 | Note that in IPv6 only, vendorclasses are namespaced with an | |
849 | IANA-allocated enterprise number. This is given with enterprise: | |
850 | keyword and specifies that only vendorclasses matching the specified | |
851 | number should be searched. | |
a222641c | 852 | .TP |
8ef5ada2 SK |
853 | .B \-j, --dhcp-userclass=set:<tag>,<user-class> |
854 | Map from a user-class string to a tag (with substring | |
a222641c SK |
855 | matching, like vendor classes). Most DHCP clients provide a |
856 | "user class" which is configurable. This option | |
f2621c7f | 857 | maps user classes to tags, so that DHCP options may be selectively delivered |
a222641c SK |
858 | to different classes of hosts. It is possible, for instance to use |
859 | this to set a different printer server for hosts in the class | |
860 | "accounts" than for hosts in the class "engineering". | |
a84fa1d0 | 861 | .TP |
8ef5ada2 | 862 | .B \-4, --dhcp-mac=set:<tag>,<MAC address> |
1adadf58 | 863 | (IPv4 only) Map from a MAC address to a tag. The MAC address may include |
cdeda28f | 864 | wildcards. For example |
8ef5ada2 | 865 | .B --dhcp-mac=set:3com,01:34:23:*:*:* |
cdeda28f SK |
866 | will set the tag "3com" for any host whose MAC address matches the pattern. |
867 | .TP | |
8ef5ada2 SK |
868 | .B --dhcp-circuitid=set:<tag>,<circuit-id>, --dhcp-remoteid=set:<tag>,<remote-id> |
869 | Map from RFC3046 relay agent options to tags. This data may | |
f2621c7f SK |
870 | be provided by DHCP relay agents. The circuit-id or remote-id is |
871 | normally given as colon-separated hex, but is also allowed to be a | |
872 | simple string. If an exact match is achieved between the circuit or | |
1adadf58 SK |
873 | agent ID and one provided by a relay agent, the tag is set. |
874 | ||
875 | .B dhcp-remoteid | |
876 | (but not dhcp-circuitid) is supported in IPv6. | |
8ef5ada2 SK |
877 | .TP |
878 | .B --dhcp-subscrid=set:<tag>,<subscriber-id> | |
1adadf58 | 879 | (IPv4 and IPv6) Map from RFC3993 subscriber-id relay agent options to tags. |
8ef5ada2 SK |
880 | .TP |
881 | .B --dhcp-proxy[=<ip addr>]...... | |
0793380b | 882 | (IPv4 only) A normal DHCP relay agent is only used to forward the initial parts of |
8ef5ada2 SK |
883 | a DHCP interaction to the DHCP server. Once a client is configured, it |
884 | communicates directly with the server. This is undesirable if the | |
885 | relay agent is addding extra information to the DHCP packets, such as | |
886 | that used by | |
887 | .B dhcp-circuitid | |
888 | and | |
889 | .B dhcp-remoteid. | |
890 | A full relay implementation can use the RFC 5107 serverid-override | |
891 | option to force the DHCP server to use the relay as a full proxy, with all | |
892 | packets passing through it. This flag provides an alternative method | |
893 | of doing the same thing, for relays which don't support RFC | |
894 | 5107. Given alone, it manipulates the server-id for all interactions | |
895 | via relays. If a list of IP addresses is given, only interactions via | |
896 | relays at those addresses are affected. | |
897 | .TP | |
898 | .B --dhcp-match=set:<tag>,<option number>|option:<option name>|vi-encap:<enterprise>[,<value>] | |
899 | Without a value, set the tag if the client sends a DHCP | |
73a08a24 SK |
900 | option of the given number or name. When a value is given, set the tag only if |
901 | the option is sent and matches the value. The value may be of the form | |
902 | "01:ff:*:02" in which case the value must match (apart from widcards) | |
903 | but the option sent may have unmatched data past the end of the | |
904 | value. The value may also be of the same form as in | |
905 | .B dhcp-option | |
906 | in which case the option sent is treated as an array, and one element | |
907 | must match, so | |
908 | ||
8ef5ada2 | 909 | --dhcp-match=set:efi-ia32,option:client-arch,6 |
73a08a24 SK |
910 | |
911 | will set the tag "efi-ia32" if the the number 6 appears in the list of | |
912 | architectures sent by the client in option 93. (See RFC 4578 for | |
316e2730 SK |
913 | details.) If the value is a string, substring matching is used. |
914 | ||
915 | The special form with vi-encap:<enterpise number> matches against | |
916 | vendor-identifying vendor classes for the specified enterprise. Please | |
8ef5ada2 SK |
917 | see RFC 3925 for more details of these rare and interesting beasts. |
918 | .TP | |
919 | .B --tag-if=set:<tag>[,set:<tag>[,tag:<tag>[,tag:<tag>]]] | |
920 | Perform boolean operations on tags. Any tag appearing as set:<tag> is set if | |
921 | all the tags which appear as tag:<tag> are set, (or unset when tag:!<tag> is used) | |
922 | If no tag:<tag> appears set:<tag> tags are set unconditionally. | |
923 | Any number of set: and tag: forms may appear, in any order. | |
924 | Tag-if lines ares executed in order, so if the tag in tag:<tag> is a | |
925 | tag set by another | |
926 | .B tag-if, | |
927 | the line which sets the tag must precede the one which tests it. | |
928 | .TP | |
929 | .B \-J, --dhcp-ignore=tag:<tag>[,tag:<tag>] | |
930 | When all the given tags appear in the tag set ignore the host and do | |
26128d27 SK |
931 | not allocate it a DHCP lease. |
932 | .TP | |
8ef5ada2 SK |
933 | .B --dhcp-ignore-names[=tag:<tag>[,tag:<tag>]] |
934 | When all the given tags appear in the tag set, ignore any hostname | |
9e038946 | 935 | provided by the host. Note that, unlike dhcp-ignore, it is permissible |
8ef5ada2 | 936 | to supply no tags, in which case DHCP-client supplied hostnames |
832af0ba SK |
937 | are always ignored, and DHCP hosts are added to the DNS using only |
938 | dhcp-host configuration in dnsmasq and the contents of /etc/hosts and | |
939 | /etc/ethers. | |
940 | .TP | |
8ef5ada2 | 941 | .B --dhcp-generate-names=tag:<tag>[,tag:<tag>] |
1adadf58 | 942 | (IPv4 only) Generate a name for DHCP clients which do not otherwise have one, |
8ef5ada2 SK |
943 | using the MAC address expressed in hex, seperated by dashes. Note that |
944 | if a host provides a name, it will be used by preference to this, | |
945 | unless | |
946 | .B --dhcp-ignore-names | |
947 | is set. | |
948 | .TP | |
949 | .B --dhcp-broadcast[=tag:<tag>[,tag:<tag>]] | |
1adadf58 | 950 | (IPv4 only) When all the given tags appear in the tag set, always use broadcast to |
8ef5ada2 SK |
951 | communicate with the host when it is unconfigured. It is permissible |
952 | to supply no tags, in which case this is unconditional. Most DHCP clients which | |
824af85b SK |
953 | need broadcast replies set a flag in their requests so that this |
954 | happens automatically, some old BOOTP clients do not. | |
955 | .TP | |
7de060b0 | 956 | .B \-M, --dhcp-boot=[tag:<tag>,]<filename>,[<servername>[,<server address>|<tftp_servername>]] |
1adadf58 | 957 | (IPv4 only) Set BOOTP options to be returned by the DHCP server. Server name and |
832af0ba SK |
958 | address are optional: if not provided, the name is left empty, and the |
959 | address set to the address of the machine running dnsmasq. If dnsmasq | |
960 | is providing a TFTP service (see | |
961 | .B --enable-tftp | |
962 | ) then only the filename is required here to enable network booting. | |
8ef5ada2 SK |
963 | If the optional tag(s) are given, |
964 | they must match for this configuration to be sent. | |
7de060b0 SK |
965 | Instead of an IP address, the TFTP server address can be given as a domain |
966 | name which is looked up in /etc/hosts. This name can be associated in | |
967 | /etc/hosts with multiple IP addresses, which are used round-robin. | |
968 | This facility can be used to load balance the tftp load among a set of servers. | |
969 | .TP | |
970 | .B --dhcp-sequential-ip | |
971 | Dnsmasq is designed to choose IP addresses for DHCP clients using a | |
972 | hash of the client's MAC address. This normally allows a client's | |
973 | address to remain stable long-term, even if the client sometimes allows its DHCP | |
974 | lease to expire. In this default mode IP addresses are distributed | |
975 | pseudo-randomly over the entire available address range. There are | |
976 | sometimes circumstances (typically server deployment) where it is more | |
977 | convenient to have IP | |
978 | addresses allocated sequentially, starting from the lowest available | |
979 | address, and setting this flag enables this mode. Note that in the | |
980 | sequential mode, clients which allow a lease to expire are much more | |
981 | likely to move IP address; for this reason it should not be generally used. | |
7622fc06 | 982 | .TP |
751d6f4a | 983 | .B --pxe-service=[tag:<tag>,]<CSA>,<menu text>[,<basename>|<bootservicetype>][,<server address>|<server_name>] |
7622fc06 SK |
984 | Most uses of PXE boot-ROMS simply allow the PXE |
985 | system to obtain an IP address and then download the file specified by | |
986 | .B dhcp-boot | |
987 | and execute it. However the PXE system is capable of more complex | |
988 | functions when supported by a suitable DHCP server. | |
989 | ||
990 | This specifies a boot option which may appear in a PXE boot menu. <CSA> is | |
991 | client system type, only services of the correct type will appear in a | |
992 | menu. The known types are x86PC, PC98, IA64_EFI, Alpha, Arc_x86, | |
993 | Intel_Lean_Client, IA32_EFI, BC_EFI, Xscale_EFI and X86-64_EFI; an | |
994 | integer may be used for other types. The | |
995 | parameter after the menu text may be a file name, in which case dnsmasq acts as a | |
996 | boot server and directs the PXE client to download the file by TFTP, | |
997 | either from itself ( | |
998 | .B enable-tftp | |
751d6f4a SK |
999 | must be set for this to work) or another TFTP server if the final server |
1000 | address/name is given. | |
7622fc06 SK |
1001 | Note that the "layer" |
1002 | suffix (normally ".0") is supplied by PXE, and should not be added to | |
1003 | the basename. If an integer boot service type, rather than a basename | |
1004 | is given, then the PXE client will search for a | |
1005 | suitable boot service for that type on the network. This search may be done | |
751d6f4a | 1006 | by broadcast, or direct to a server if its IP address/name is provided. |
316e2730 SK |
1007 | If no boot service type or filename is provided (or a boot service type of 0 is specified) |
1008 | then the menu entry will abort the net boot procedure and | |
751d6f4a SK |
1009 | continue booting from local media. The server address can be given as a domain |
1010 | name which is looked up in /etc/hosts. This name can be associated in | |
1011 | /etc/hosts with multiple IP addresses, which are used round-robin. | |
7622fc06 | 1012 | .TP |
8ef5ada2 | 1013 | .B --pxe-prompt=[tag:<tag>,]<prompt>[,<timeout>] |
7622fc06 SK |
1014 | Setting this provides a prompt to be displayed after PXE boot. If the |
1015 | timeout is given then after the | |
1016 | timeout has elapsed with no keyboard input, the first available menu | |
1017 | option will be automatically executed. If the timeout is zero then the first available menu | |
1018 | item will be executed immediately. If | |
1019 | .B pxe-prompt | |
1020 | is ommitted the system will wait for user input if there are multiple | |
1021 | items in the menu, but boot immediately if | |
1022 | there is only one. See | |
1023 | .B pxe-service | |
1024 | for details of menu items. | |
1025 | ||
1026 | Dnsmasq supports PXE "proxy-DHCP", in this case another DHCP server on | |
1027 | the network is responsible for allocating IP addresses, and dnsmasq | |
1028 | simply provides the information given in | |
1029 | .B pxe-prompt | |
1030 | and | |
1031 | .B pxe-service | |
1032 | to allow netbooting. This mode is enabled using the | |
1033 | .B proxy | |
1034 | keyword in | |
1035 | .B dhcp-range. | |
9e4abcb5 | 1036 | .TP |
44a2a316 SK |
1037 | .B \-X, --dhcp-lease-max=<number> |
1038 | Limits dnsmasq to the specified maximum number of DHCP leases. The | |
8ef5ada2 | 1039 | default is 1000. This limit is to prevent DoS attacks from hosts which |
44a2a316 SK |
1040 | create thousands of leases and use lots of memory in the dnsmasq |
1041 | process. | |
1042 | .TP | |
fd9fa481 | 1043 | .B \-K, --dhcp-authoritative |
1adadf58 | 1044 | (IPv4 only) Should be set when dnsmasq is definitely the only DHCP server on a network. |
fd9fa481 SK |
1045 | It changes the behaviour from strict RFC compliance so that DHCP requests on |
1046 | unknown leases from unknown hosts are not ignored. This allows new hosts | |
cdeda28f SK |
1047 | to get a lease without a tedious timeout under all circumstances. It also |
1048 | allows dnsmasq to rebuild its lease database without each client needing to | |
9e038946 SK |
1049 | reacquire a lease, if the database is lost. |
1050 | .TP | |
1051 | .B --dhcp-alternate-port[=<server port>[,<client port>]] | |
1adadf58 | 1052 | (IPv4 only) Change the ports used for DHCP from the default. If this option is |
9e038946 SK |
1053 | given alone, without arguments, it changes the ports used for DHCP |
1054 | from 67 and 68 to 1067 and 1068. If a single argument is given, that | |
1055 | port number is used for the server and the port number plus one used | |
1056 | for the client. Finally, two port numbers allows arbitrary | |
1057 | specification of both server and client ports for DHCP. | |
fd9fa481 | 1058 | .TP |
9009d746 | 1059 | .B \-3, --bootp-dynamic[=<network-id>[,<network-id>]] |
1adadf58 | 1060 | (IPv4 only) Enable dynamic allocation of IP addresses to BOOTP clients. Use this |
3d8df260 SK |
1061 | with care, since each address allocated to a BOOTP client is leased |
1062 | forever, and therefore becomes permanently unavailable for re-use by | |
9009d746 SK |
1063 | other hosts. if this is given without tags, then it unconditionally |
1064 | enables dynamic allocation. With tags, only when the tags are all | |
1065 | set. It may be repeated with different tag sets. | |
3d8df260 | 1066 | .TP |
5e9e0efb | 1067 | .B \-5, --no-ping |
1adadf58 | 1068 | (IPv4 only) By default, the DHCP server will attempt to ensure that an address in |
5e9e0efb SK |
1069 | not in use before allocating it to a host. It does this by sending an |
1070 | ICMP echo request (aka "ping") to the address in question. If it gets | |
1071 | a reply, then the address must already be in use, and another is | |
1072 | tried. This flag disables this check. Use with caution. | |
1073 | .TP | |
f2621c7f SK |
1074 | .B --log-dhcp |
1075 | Extra logging for DHCP: log all the options sent to DHCP clients and | |
8ef5ada2 | 1076 | the tags used to determine them. |
f2621c7f | 1077 | .TP |
9e4abcb5 | 1078 | .B \-l, --dhcp-leasefile=<path> |
73a08a24 | 1079 | Use the specified file to store DHCP lease information. |
208b65c5 | 1080 | .TP |
8b372704 SK |
1081 | .B --dhcp-duid=<enterprise-id>,<uid> |
1082 | (IPv6 only) Specify the server persistent UID which the DHCPv6 server | |
1083 | will use. This option is not normally required as dnsmasq creates a | |
1084 | DUID automatically when it is first needed. When given, this option | |
1085 | provides dnsmasq the data required to create a DUID-EN type DUID. Note | |
1086 | that once set, the DUID is stored in the lease database, so to change between DUID-EN and | |
1087 | automatically created DUIDs or vice-versa, the lease database must be | |
1088 | re-intialised. The enterprise-id is assigned by IANA, and the uid is a | |
1089 | string of hex octets unique to a particular device. | |
1090 | .TP | |
7cebd20f | 1091 | .B \-6 --dhcp-script=<path> |
a9530964 SK |
1092 | Whenever a new DHCP lease is created, or an old one destroyed, or a |
1093 | TFTP file transfer completes, the | |
8ef5ada2 SK |
1094 | executable specified by this option is run. <path> |
1095 | must be an absolute pathname, no PATH search occurs. | |
1096 | The arguments to the process | |
7cebd20f | 1097 | are "add", "old" or "del", the MAC |
1adadf58 | 1098 | address of the host (or DUID for IPv6) , the IP address, and the hostname, |
7cebd20f SK |
1099 | if known. "add" means a lease has been created, "del" means it has |
1100 | been destroyed, "old" is a notification of an existing lease when | |
208b65c5 SK |
1101 | dnsmasq starts or a change to MAC address or hostname of an existing |
1102 | lease (also, lease length or expiry and client-id, if leasefile-ro is set). | |
9009d746 SK |
1103 | If the MAC address is from a network type other than ethernet, |
1104 | it will have the network type prepended, eg "06-01:23:45:67:89:ab" for | |
1105 | token ring. The process is run as root (assuming that dnsmasq was originally run as | |
1697269c | 1106 | root) even if dnsmasq is configured to change UID to an unprivileged user. |
8ef5ada2 SK |
1107 | |
1108 | The environment is inherited from the invoker of dnsmasq, with some or | |
1adadf58 | 1109 | all of the following variables added |
8ef5ada2 | 1110 | |
1adadf58 | 1111 | For both IPv4 and IPv6: |
8ef5ada2 SK |
1112 | |
1113 | DNSMASQ_DOMAIN if the fully-qualified domain name of the host is | |
28866e95 SK |
1114 | known, this is set to the domain part. (Note that the hostname passed |
1115 | to the script as an argument is never fully-qualified.) | |
8ef5ada2 | 1116 | |
1adadf58 SK |
1117 | If the client provides a hostname, DNSMASQ_SUPPLIED_HOSTNAME |
1118 | ||
1119 | If the client provides user-classes, DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn | |
8ef5ada2 SK |
1120 | |
1121 | If dnsmasq was compiled with HAVE_BROKEN_RTC, then | |
208b65c5 | 1122 | the length of the lease (in seconds) is stored in |
1697269c | 1123 | DNSMASQ_LEASE_LENGTH, otherwise the time of lease expiry is stored in |
5aabfc78 SK |
1124 | DNSMASQ_LEASE_EXPIRES. The number of seconds until lease expiry is |
1125 | always stored in DNSMASQ_TIME_REMAINING. | |
8ef5ada2 | 1126 | |
5aabfc78 | 1127 | If a lease used to have a hostname, which is |
1697269c SK |
1128 | removed, an "old" event is generated with the new state of the lease, |
1129 | ie no name, and the former name is provided in the environment | |
8ef5ada2 SK |
1130 | variable DNSMASQ_OLD_HOSTNAME. |
1131 | ||
1132 | DNSMASQ_INTERFACE stores the name of | |
9e038946 | 1133 | the interface on which the request arrived; this is not set for "old" |
8ef5ada2 SK |
1134 | actions when dnsmasq restarts. |
1135 | ||
1136 | DNSMASQ_RELAY_ADDRESS is set if the client | |
316e2730 | 1137 | used a DHCP relay to contact dnsmasq and the IP address of the relay |
8ef5ada2 SK |
1138 | is known. |
1139 | ||
1140 | DNSMASQ_TAGS contains all the tags set during the | |
316e2730 | 1141 | DHCP transaction, separated by spaces. |
8ef5ada2 | 1142 | |
a9530964 SK |
1143 | DNSMASQ_LOG_DHCP is set if --log-dhcp is in effect. |
1144 | ||
1adadf58 SK |
1145 | For IPv4 only: |
1146 | ||
1147 | DNSMASQ_CLIENT_ID if the host provided a client-id. | |
1148 | ||
1149 | If the client provides vendor-class, DNSMASQ_VENDOR_CLASS. | |
1150 | ||
1151 | For IPv6 only: | |
1152 | ||
1153 | If the client provides vendor-class, DNSMASQ_VENDOR_CLASS_ID, | |
1154 | containing the IANA enterprise id for the class, and | |
1155 | DNSMASQ_VENDOR_CLASS0..DNSMASQ_VENDOR_CLASSn for the data. | |
1156 | ||
57f460de | 1157 | DNSMASQ_SERVER_DUID containing the DUID of the server: this is the same for |
1adadf58 SK |
1158 | every call to the script. |
1159 | ||
1160 | DNSMASQ_IAID containing the IAID for the lease. If the lease is a | |
1161 | temporary allocation, this is prefixed to 'T'. | |
1162 | ||
1163 | ||
1164 | ||
1165 | Note that the supplied hostname, vendorclass and userclass data is | |
1166 | only supplied for | |
1167 | "add" actions or "old" actions when a host resumes an existing lease, | |
1168 | since these data are not held in dnsmasq's lease | |
1169 | database. | |
1170 | ||
a9530964 SK |
1171 | |
1172 | ||
9e038946 | 1173 | All file descriptors are |
7cebd20f SK |
1174 | closed except stdin, stdout and stderr which are open to /dev/null |
1175 | (except in debug mode). | |
8ef5ada2 SK |
1176 | |
1177 | The script is not invoked concurrently: at most one instance | |
1178 | of the script is ever running (dnsmasq waits for an instance of script to exit | |
1179 | before running the next). Changes to the lease database are which | |
1180 | require the script to be invoked are queued awaiting exit of a running instance. | |
1181 | If this queueing allows multiple state changes occur to a single | |
1182 | lease before the script can be run then | |
1183 | earlier states are discarded and the current state of that lease is | |
1184 | reflected when the script finally runs. | |
1185 | ||
1186 | At dnsmasq startup, the script will be invoked for | |
7cebd20f | 1187 | all existing leases as they are read from the lease file. Expired |
8ef5ada2 | 1188 | leases will be called with "del" and others with "old". When dnsmasq |
5aabfc78 | 1189 | receives a HUP signal, the script will be invoked for existing leases |
9e038946 | 1190 | with an "old " event. |
a9530964 SK |
1191 | |
1192 | ||
1193 | There are two further actions which may appear as the first argument | |
1194 | to the script, "init" and "tftp". More may be added in the future, so | |
1195 | scripts should be written to ignore unknown actions. "init" is | |
1196 | decsribed below in | |
1197 | .B --leasefile-ro | |
1198 | The "tftp" action is invoked when a TFTP file transfer completes: the | |
1199 | arguments are the file size in bytes, the address to which the file | |
1200 | was sent, and the complete pathname of the file. | |
1201 | ||
9e038946 | 1202 | .TP |
57f460de SK |
1203 | .B --dhcp-luascript=<path> |
1204 | Specify a script written in Lua, to be run when leases are created, | |
1205 | destroyed or changed. To use this option, dnsmasq must be compiled | |
1206 | with the correct support. The Lua interpreter is intialised once, when | |
1207 | dnsmasq starts, so that global variables persist between lease | |
1208 | events. The Lua code must define a | |
1209 | .B lease | |
1210 | function, and may provide | |
1211 | .B init | |
1212 | and | |
1213 | .B shutdown | |
1214 | functions, which are called, without arguments when dnsmasq starts up | |
a9530964 SK |
1215 | and terminates. It may also provide a |
1216 | .B tftp | |
1217 | function. | |
57f460de SK |
1218 | |
1219 | The | |
1220 | .B lease | |
a9530964 | 1221 | function receives the information detailed in |
57f460de SK |
1222 | .B --dhcp-script. |
1223 | It gets two arguments, firstly the action, which is a string | |
1224 | containing, "add", "old" or "del", and secondly a table of tag value | |
1225 | pairs. The tags mostly correspond to the environment variables | |
1226 | detailed above, for instance the tag "domain" holds the same data as | |
1227 | the environment variable DNSMASQ_DOMAIN. There are a few extra tags | |
1228 | which hold the data supplied as arguments to | |
1229 | .B --dhcp-script. | |
1230 | These are | |
1231 | .B mac_address, ip_address | |
1232 | and | |
1233 | .B hostname | |
1234 | for IPv4, and | |
1235 | .B client_duid, ip_address | |
1236 | and | |
1237 | .B hostname | |
a9530964 SK |
1238 | for IPv6. |
1239 | ||
1240 | The | |
1241 | .B tftp | |
1242 | function is called in the same way as the lease function, and the | |
1243 | table holds the tags | |
1244 | .B destination_address, | |
1245 | .B file_name | |
1246 | and | |
1247 | .B file_size. | |
57f460de | 1248 | .TP |
9e038946 | 1249 | .B --dhcp-scriptuser |
57f460de | 1250 | 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. |
208b65c5 SK |
1251 | .TP |
1252 | .B \-9, --leasefile-ro | |
1253 | Completely suppress use of the lease database file. The file will not | |
1254 | be created, read, or written. Change the way the lease-change | |
1255 | script (if one is provided) is called, so that the lease database may | |
1256 | be maintained in external storage by the script. In addition to the | |
f2621c7f | 1257 | invocations given in |
208b65c5 SK |
1258 | .B --dhcp-script |
1259 | the lease-change script is called once, at dnsmasq startup, with the | |
1260 | single argument "init". When called like this the script should write | |
1261 | the saved state of the lease database, in dnsmasq leasefile format, to | |
1262 | stdout and exit with zero exit code. Setting this | |
1263 | option also forces the leasechange script to be called on changes | |
1264 | to the client-id and lease length and expiry time. | |
9e4abcb5 | 1265 | .TP |
832af0ba SK |
1266 | .B --bridge-interface=<interface>,<alias>[,<alias>] |
1267 | Treat DHCP request packets arriving at any of the <alias> interfaces | |
7622fc06 SK |
1268 | as if they had arrived at <interface>. This option is necessary when |
1269 | using "old style" bridging on BSD platforms, since | |
832af0ba SK |
1270 | packets arrive at tap interfaces which don't have an IP address. |
1271 | .TP | |
28866e95 | 1272 | .B \-s, --domain=<domain>[,<address range>[,local]] |
9009d746 SK |
1273 | Specifies DNS domains for the DHCP server. Domains may be be given |
1274 | unconditionally (without the IP range) or for limited IP ranges. This has two effects; | |
9e4abcb5 SK |
1275 | firstly it causes the DHCP server to return the domain to any hosts |
1276 | which request it, and secondly it sets the domain which it is legal | |
1b7ecd11 SK |
1277 | for DHCP-configured hosts to claim. The intention is to constrain |
1278 | hostnames so that an untrusted host on the LAN cannot advertise | |
1279 | its name via dhcp as e.g. "microsoft.com" and capture traffic not | |
1280 | meant for it. If no domain suffix is specified, then any DHCP | |
1281 | hostname with a domain part (ie with a period) will be disallowed | |
1282 | and logged. If suffix is specified, then hostnames with a domain | |
1283 | part are allowed, provided the domain part matches the suffix. In | |
1284 | addition, when a suffix is set then hostnames without a domain | |
1285 | part have the suffix added as an optional domain part. Eg on my network I can set | |
3d8df260 | 1286 | .B --domain=thekelleys.org.uk |
9e4abcb5 SK |
1287 | and have a machine whose DHCP hostname is "laptop". The IP address for that machine is available from |
1288 | .B dnsmasq | |
de37951c SK |
1289 | both as "laptop" and "laptop.thekelleys.org.uk". If the domain is |
1290 | given as "#" then the domain is read from the first "search" directive | |
28866e95 SK |
1291 | in /etc/resolv.conf (or equivalent). |
1292 | ||
1293 | The address range can be of the form | |
9009d746 SK |
1294 | <ip address>,<ip address> or <ip address>/<netmask> or just a single |
1295 | <ip address>. See | |
1296 | .B --dhcp-fqdn | |
1297 | which can change the behaviour of dnsmasq with domains. | |
28866e95 SK |
1298 | |
1299 | If the address range is given as ip-address/network-size, then a | |
1300 | additional flag "local" may be supplied which has the effect of adding | |
1301 | --local declarations for forward and reverse DNS queries. Eg. | |
1302 | .B --domain=thekelleys.org.uk,192.168.0.0/24,local | |
1303 | is identical to | |
1304 | .B --domain=thekelleys.org.uk,192.168.0.0/24 | |
1305 | --local=/thekelleys.org.uk/ --local=/0.168.192.in-addr.arpa/ | |
1306 | The network size must be 8, 16 or 24 for this to be legal. | |
9009d746 SK |
1307 | .TP |
1308 | .B --dhcp-fqdn | |
1309 | In the default mode, dnsmasq inserts the unqualified names of | |
1310 | DHCP clients into the DNS. For this reason, the names must be unique, | |
1311 | even if two clients which have the same name are in different | |
1312 | domains. If a second DHCP client appears which has the same name as an | |
1313 | existing client, the name is transfered to the new client. If | |
1314 | .B --dhcp-fqdn | |
1315 | is set, this behaviour changes: the unqualified name is no longer | |
1316 | put in the DNS, only the qualified name. Two DHCP clients with the | |
1317 | same name may both keep the name, provided that the domain part is | |
1318 | different (ie the fully qualified names differ.) To ensure that all | |
1319 | names have a domain part, there must be at least | |
1320 | .B --domain | |
1321 | without an address specified when | |
1322 | .B --dhcp-fqdn | |
1323 | is set. | |
9e4abcb5 | 1324 | .TP |
c72daea8 SK |
1325 | .B --dhcp-client-update |
1326 | Normally, when giving a DHCP lease, dnsmasq sets flags in the FQDN | |
1327 | option to tell the client not to attempt a DDNS update with its name | |
1328 | and IP address. This is because the name-IP pair is automatically | |
1329 | added into dnsmasq's DNS view. This flag suppresses that behaviour, | |
1330 | this is useful, for instance, to allow Windows clients to update | |
1331 | Active Directory servers. See RFC 4702 for details. | |
1332 | .TP | |
c5ad4e79 SK |
1333 | .B --enable-ra |
1334 | Enable dnsmasq's IPv6 Router Advertisement feature. DHCPv6 doesn't | |
1335 | handle complete network configuration in the same way as DHCPv4. Router | |
1336 | discovery and (possibly) prefix discovery for autonomous address | |
1337 | creation are handled by a different protocol. When DHCP is in use, | |
1338 | only a subset of this is needed, and dnsmasq can handle it, using | |
1339 | existing DHCP configuration to provide most data. When RA is enabled, | |
1340 | dnsmasq will advertise a prefix for each dhcp-range, with default | |
1341 | router and recursive DNS server as the relevant link-local address on | |
e8ca69ea SK |
1342 | the machine running dnsmasq. By default, he "managed address" bits are set, and |
1343 | the "use SLAAC" bit is reset. This can be changed for individual | |
1344 | subnets with the mode keywords described in | |
1345 | .B --dhcp-range. | |
c5ad4e79 | 1346 | .TP |
8ef5ada2 | 1347 | .B --enable-tftp[=<interface>] |
832af0ba | 1348 | Enable the TFTP server function. This is deliberately limited to that |
9e038946 | 1349 | needed to net-boot a client. Only reading is allowed; the tsize and |
8ef5ada2 SK |
1350 | blksize extensions are supported (tsize is only supported in octet |
1351 | mode). See NOTES section for use of the interface argument. | |
1352 | ||
832af0ba | 1353 | .TP |
8ef5ada2 | 1354 | .B --tftp-root=<directory>[,<interface>] |
832af0ba SK |
1355 | Look for files to transfer using TFTP relative to the given |
1356 | directory. When this is set, TFTP paths which include ".." are | |
1357 | rejected, to stop clients getting outside the specified root. | |
f2621c7f | 1358 | Absolute paths (starting with /) are allowed, but they must be within |
8ef5ada2 SK |
1359 | the tftp-root. If the optional interface argument is given, the |
1360 | directory is only used for TFTP requests via that interface. | |
832af0ba | 1361 | .TP |
5aabfc78 SK |
1362 | .B --tftp-unique-root |
1363 | Add the IP address of the TFTP client as a path component on the end | |
1364 | of the TFTP-root (in standard dotted-quad format). Only valid if a | |
1365 | tftp-root is set and the directory exists. For instance, if tftp-root is "/tftp" and client | |
1366 | 1.2.3.4 requests file "myfile" then the effective path will be | |
1367 | "/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4 exists or /tftp/myfile otherwise. | |
1368 | .TP | |
832af0ba | 1369 | .B --tftp-secure |
5aabfc78 | 1370 | Enable TFTP secure mode: without this, any file which is readable by |
832af0ba SK |
1371 | the dnsmasq process under normal unix access-control rules is |
1372 | available via TFTP. When the --tftp-secure flag is given, only files | |
1373 | owned by the user running the dnsmasq process are accessible. If | |
1374 | dnsmasq is being run as root, different rules apply: --tftp-secure | |
1b7ecd11 | 1375 | has no effect, but only files which have the world-readable bit set |
832af0ba SK |
1376 | are accessible. It is not recommended to run dnsmasq as root with TFTP |
1377 | enabled, and certainly not without specifying --tftp-root. Doing so | |
1378 | can expose any world-readable file on the server to any host on the net. | |
1379 | .TP | |
1380 | .B --tftp-max=<connections> | |
1381 | Set the maximum number of concurrent TFTP connections allowed. This | |
1382 | defaults to 50. When serving a large number of TFTP connections, | |
1383 | per-process file descriptor limits may be encountered. Dnsmasq needs | |
1384 | one file descriptor for each concurrent TFTP connection and one | |
1385 | file descriptor per unique file (plus a few others). So serving the | |
1386 | same file simultaneously to n clients will use require about n + 10 file | |
1387 | descriptors, serving different files simultaneously to n clients will | |
824af85b SK |
1388 | require about (2*n) + 10 descriptors. If |
1389 | .B --tftp-port-range | |
1390 | is given, that can affect the number of concurrent connections. | |
6b01084f SK |
1391 | .TP |
1392 | .B --tftp-no-blocksize | |
1393 | Stop the TFTP server from negotiating the "blocksize" option with a | |
1394 | client. Some buggy clients request this option but then behave badly | |
1395 | when it is granted. | |
824af85b SK |
1396 | .TP |
1397 | .B --tftp-port-range=<start>,<end> | |
1398 | A TFTP server listens on a well-known port (69) for connection initiation, | |
1399 | but it also uses a dynamically-allocated port for each | |
1400 | connection. Normally these are allocated by the OS, but this option | |
1401 | specifies a range of ports for use by TFTP transfers. This can be | |
1402 | useful when TFTP has to traverse a firewall. The start of the range | |
1403 | cannot be lower than 1025 unless dnsmasq is running as root. The number | |
1404 | of concurrent TFTP connections is limited by the size of the port range. | |
832af0ba | 1405 | .TP |
b8187c80 SK |
1406 | .B \-C, --conf-file=<file> |
1407 | Specify a different configuration file. The conf-file option is also allowed in | |
28866e95 SK |
1408 | configuration files, to include multiple configuration files. A |
1409 | filename of "-" causes dnsmasq to read configuration from stdin. | |
849a8357 | 1410 | .TP |
1f15b81d | 1411 | .B \-7, --conf-dir=<directory>[,<file-extension>......] |
849a8357 | 1412 | Read all the files in the given directory as configuration |
1f15b81d SK |
1413 | files. If extension(s) are given, any files which end in those |
1414 | extensions are skipped. Any files whose names end in ~ or start with . or start and end | |
1415 | with # are always skipped. This flag may be given on the command | |
849a8357 | 1416 | line or in a configuration file. |
9e4abcb5 | 1417 | .SH CONFIG FILE |
3be34541 SK |
1418 | At startup, dnsmasq reads |
1419 | .I /etc/dnsmasq.conf, | |
1420 | if it exists. (On | |
1421 | FreeBSD, the file is | |
1422 | .I /usr/local/etc/dnsmasq.conf | |
b8187c80 SK |
1423 | ) (but see the |
1424 | .B \-C | |
849a8357 SK |
1425 | and |
1426 | .B \-7 | |
1427 | options.) The format of this | |
9e4abcb5 SK |
1428 | file consists of one option per line, exactly as the long options detailed |
1429 | in the OPTIONS section but without the leading "--". Lines starting with # are comments and ignored. For | |
b49644f3 | 1430 | options which may only be specified once, the configuration file overrides |
b8187c80 | 1431 | the command line. Quoting is allowed in a config file: |
3d8df260 | 1432 | between " quotes the special meanings of ,:. and # are removed and the |
824af85b SK |
1433 | following escapes are allowed: \\\\ \\" \\t \\e \\b \\r and \\n. The later |
1434 | corresponding to tab, escape, backspace, return and newline. | |
9e4abcb5 SK |
1435 | .SH NOTES |
1436 | When it receives a SIGHUP, | |
1437 | .B dnsmasq | |
3be34541 | 1438 | clears its cache and then re-loads |
5aabfc78 SK |
1439 | .I /etc/hosts |
1440 | and | |
1441 | .I /etc/ethers | |
824af85b | 1442 | and any file given by --dhcp-hostsfile, --dhcp-optsfile or --addn-hosts. |
5aabfc78 SK |
1443 | The dhcp lease change script is called for all |
1444 | existing DHCP leases. If | |
9e4abcb5 SK |
1445 | .B |
1446 | --no-poll | |
3be34541 SK |
1447 | is set SIGHUP also re-reads |
1448 | .I /etc/resolv.conf. | |
1449 | SIGHUP | |
b49644f3 | 1450 | does NOT re-read the configuration file. |
9e4abcb5 SK |
1451 | .PP |
1452 | When it receives a SIGUSR1, | |
1453 | .B dnsmasq | |
824af85b | 1454 | writes statistics to the system log. It writes the cache size, |
9e4abcb5 SK |
1455 | the number of names which have had to removed from the cache before |
1456 | they expired in order to make room for new names and the total number | |
824af85b SK |
1457 | of names that have been inserted into the cache. For each upstream |
1458 | server it gives the number of queries sent, and the number which | |
1459 | resulted in an error. In | |
9e4abcb5 | 1460 | .B --no-daemon |
5aabfc78 SK |
1461 | mode or when full logging is enabled (-q), a complete dump of the |
1462 | contents of the cache is made. | |
1463 | .PP | |
1464 | When it receives SIGUSR2 and it is logging direct to a file (see | |
1465 | .B --log-facility | |
1466 | ) | |
1467 | .B dnsmasq | |
1468 | will close and reopen the log file. Note that during this operation, | |
1469 | dnsmasq will not be running as root. When it first creates the logfile | |
1470 | dnsmasq changes the ownership of the file to the non-root user it will run | |
1471 | as. Logrotate should be configured to create a new log file with | |
9e038946 | 1472 | the ownership which matches the existing one before sending SIGUSR2. |
5aabfc78 SK |
1473 | If TCP DNS queries are in progress, the old logfile will remain open in |
1474 | child processes which are handling TCP queries and may continue to be | |
1475 | written. There is a limit of 150 seconds, after which all existing TCP | |
1476 | processes will have expired: for this reason, it is not wise to | |
1477 | configure logfile compression for logfiles which have just been | |
1478 | rotated. Using logrotate, the required options are | |
1479 | .B create | |
1480 | and | |
1481 | .B delaycompress. | |
1482 | ||
1483 | ||
9e4abcb5 | 1484 | .PP |
9e4abcb5 SK |
1485 | Dnsmasq is a DNS query forwarder: it it not capable of recursively |
1486 | answering arbitrary queries starting from the root servers but | |
1487 | forwards such queries to a fully recursive upstream DNS server which is | |
1488 | typically provided by an ISP. By default, dnsmasq reads | |
3be34541 SK |
1489 | .I /etc/resolv.conf |
1490 | to discover the IP | |
9e4abcb5 SK |
1491 | addresses of the upstream nameservers it should use, since the |
1492 | information is typically stored there. Unless | |
1493 | .B --no-poll | |
1494 | is used, | |
1495 | .B dnsmasq | |
3be34541 SK |
1496 | checks the modification time of |
1497 | .I /etc/resolv.conf | |
1498 | (or equivalent if | |
9e4abcb5 SK |
1499 | .B \--resolv-file |
1500 | is used) and re-reads it if it changes. This allows the DNS servers to | |
1501 | be set dynamically by PPP or DHCP since both protocols provide the | |
1502 | information. | |
3be34541 SK |
1503 | Absence of |
1504 | .I /etc/resolv.conf | |
1505 | is not an error | |
9e4abcb5 | 1506 | since it may not have been created before a PPP connection exists. Dnsmasq |
3be34541 SK |
1507 | simply keeps checking in case |
1508 | .I /etc/resolv.conf | |
1509 | is created at any | |
9e4abcb5 SK |
1510 | time. Dnsmasq can be told to parse more than one resolv.conf |
1511 | file. This is useful on a laptop, where both PPP and DHCP may be used: | |
3be34541 SK |
1512 | dnsmasq can be set to poll both |
1513 | .I /etc/ppp/resolv.conf | |
1514 | and | |
1515 | .I /etc/dhcpc/resolv.conf | |
1516 | and will use the contents of whichever changed | |
9e4abcb5 SK |
1517 | last, giving automatic switching between DNS servers. |
1518 | .PP | |
1519 | Upstream servers may also be specified on the command line or in | |
b49644f3 | 1520 | the configuration file. These server specifications optionally take a |
9e4abcb5 SK |
1521 | domain name which tells dnsmasq to use that server only to find names |
1522 | in that particular domain. | |
1523 | .PP | |
1524 | In order to configure dnsmasq to act as cache for the host on which it is running, put "nameserver 127.0.0.1" in | |
1525 | .I /etc/resolv.conf | |
1526 | to force local processes to send queries to | |
1527 | dnsmasq. Then either specify the upstream servers directly to dnsmasq | |
1528 | using | |
1529 | .B \--server | |
1530 | options or put their addresses real in another file, say | |
1531 | .I /etc/resolv.dnsmasq | |
1532 | and run dnsmasq with the | |
1533 | .B \-r /etc/resolv.dnsmasq | |
1534 | option. This second technique allows for dynamic update of the server | |
1535 | addresses by PPP or DHCP. | |
f6b7dc47 SK |
1536 | .PP |
1537 | Addresses in /etc/hosts will "shadow" different addresses for the same | |
1538 | names in the upstream DNS, so "mycompany.com 1.2.3.4" in /etc/hosts will ensure that | |
1539 | queries for "mycompany.com" always return 1.2.3.4 even if queries in | |
1540 | the upstream DNS would otherwise return a different address. There is | |
1541 | one exception to this: if the upstream DNS contains a CNAME which | |
1542 | points to a shadowed name, then looking up the CNAME through dnsmasq | |
1543 | will result in the unshadowed address associated with the target of | |
1544 | the CNAME. To work around this, add the CNAME to /etc/hosts so that | |
1545 | the CNAME is shadowed too. | |
1546 | ||
3be34541 | 1547 | .PP |
8ef5ada2 SK |
1548 | The tag system works as follows: For each DHCP request, dnsmasq |
1549 | collects a set of valid tags from active configuration lines which | |
1550 | include set:<tag>, including one from the | |
26128d27 SK |
1551 | .B dhcp-range |
1552 | used to allocate the address, one from any matching | |
1553 | .B dhcp-host | |
9009d746 | 1554 | (and "known" if a dhcp-host matches) |
8ef5ada2 SK |
1555 | The tag "bootp" is set for BOOTP requests, and a tag whose name is the |
1556 | name of the interface on which the request arrived is also set. | |
1557 | ||
1558 | Any configuration lines which includes one or more tag:<tag> contructs | |
1559 | will only be valid if all that tags are matched in the set derived | |
1560 | above. Typically this is dhcp-option. | |
26128d27 | 1561 | .B dhcp-option |
8ef5ada2 | 1562 | which has tags will be used in preference to an untagged |
26128d27 SK |
1563 | .B dhcp-option, |
1564 | provided that _all_ the tags match somewhere in the | |
8ef5ada2 SK |
1565 | set collected as described above. The prefix '!' on a tag means 'not' |
1566 | so --dhcp=option=tag:!purple,3,1.2.3.4 sends the option when the | |
1567 | tag purple is not in the set of valid tags. (If using this in a | |
1568 | command line rather than a configuration file, be sure to escape !, | |
1569 | which is a shell metacharacter) | |
7de060b0 SK |
1570 | |
1571 | When selecting dhcp-options, a tag from dhcp-range is second class | |
1572 | relative to other tags, to make it easy to override options for | |
1573 | individual hosts, so | |
1574 | .B dhcp-range=set:interface1,...... | |
1575 | .B dhcp-host=set:myhost,..... | |
1576 | .B dhcp-option=tag:interface1,option:nis-domain,"domain1" | |
1577 | .B dhcp-option=tag:myhost,option:nis-domain,"domain2" | |
1578 | will set the NIS-domain to domain1 for hosts in the range, but | |
1579 | override that to domain2 for a particular host. | |
1580 | ||
26128d27 | 1581 | .PP |
8ef5ada2 | 1582 | Note that for |
f6b7dc47 | 1583 | .B dhcp-range |
8ef5ada2 SK |
1584 | both tag:<tag> and set:<tag> are allowed, to both select the range in |
1585 | use based on (eg) dhcp-host, and to affect the options sent, based on | |
1586 | the range selected. | |
1587 | ||
1588 | This system evolved from an earlier, more limited one and for backward | |
1589 | compatibility "net:" may be used instead of "tag:" and "set:" may be | |
1590 | omitted. (Except in | |
1591 | .B dhcp-host, | |
1592 | where "net:" may be used instead of "set:".) For the same reason, '#' | |
1593 | may be used instead of '!' to indicate NOT. | |
f6b7dc47 | 1594 | .PP |
3be34541 SK |
1595 | The DHCP server in dnsmasq will function as a BOOTP server also, |
1596 | provided that the MAC address and IP address for clients are given, | |
1597 | either using | |
1598 | .B dhcp-host | |
1599 | configurations or in | |
1600 | .I /etc/ethers | |
1601 | , and a | |
1602 | .B dhcp-range | |
1603 | configuration option is present to activate the DHCP server | |
b8187c80 SK |
1604 | on a particular network. (Setting --bootp-dynamic removes the need for |
1605 | static address mappings.) The filename | |
8ef5ada2 SK |
1606 | parameter in a BOOTP request is used as a tag, |
1607 | as is the tag "bootp", allowing some control over the options returned to | |
3be34541 SK |
1608 | different classes of hosts. |
1609 | ||
8ef5ada2 SK |
1610 | .B dhcp-range |
1611 | may have an interface name supplied as | |
1612 | "interface:<interface-name>". The semantics if this are as follows: | |
1613 | For DHCP, if any other dhcp-range exists _without_ an interface name, | |
1614 | then the interface name is ignored and and dnsmasq behaves as if the | |
1615 | interface parts did not exist, otherwise DHCP is only provided to | |
1616 | interfaces mentioned in dhcp-range | |
1617 | declarations. For DNS, if there are no | |
1618 | .B --interface | |
1619 | or | |
1620 | .B --listen-address | |
1621 | flags, behaviour is unchanged by the interface part. If either of | |
1622 | these flags are present, the interfaces mentioned in | |
1623 | dhcp-ranges are added to the set which get DNS service. | |
1624 | ||
1625 | Similarly, | |
1626 | .B enable-tftp | |
1627 | may take an interface name, which enables TFTP only for a particular | |
1628 | interface, ignoring | |
1629 | .B --interface | |
1630 | or | |
1631 | .B --listen-address | |
1632 | flags. In addition | |
1633 | .B --tftp-secure | |
1634 | and | |
1635 | .B --tftp-unique-root | |
1636 | and | |
1637 | .B --tftp-no-blocksize | |
1638 | are ignored for requests from such interfaces. (A | |
1639 | .B --tftp-root | |
1640 | directive giving a root path and an interface should be | |
1641 | provided too.) | |
1642 | ||
1643 | These rules may seem odd at first sight, but they | |
1644 | allow a single line of the form "dhcp-range=interface:virt0,192.168.0.4,192.168.0.200" | |
1645 | to be added to dnsmasq configuration which then supplies | |
1646 | DHCP and DNS services to that interface, without affecting | |
1647 | what services are supplied to other interfaces and irrespective of | |
1648 | the existance or lack of "interface=<interface>" | |
1649 | lines elsewhere in the dnsmasq configuration. | |
1650 | "enable-tftp=virt0" and "tftp-root=<root>,virt0" do the same job for TFTP. | |
1651 | The idea is | |
1652 | that such a line can be added automatically by libvirt | |
1653 | or equivalent systems, without disturbing any manual | |
1654 | configuration. | |
1655 | ||
5aabfc78 SK |
1656 | .SH EXIT CODES |
1657 | .PP | |
1658 | 0 - Dnsmasq successfully forked into the background, or terminated | |
1659 | normally if backgrounding is not enabled. | |
1660 | .PP | |
1661 | 1 - A problem with configuration was detected. | |
1662 | .PP | |
1663 | 2 - A problem with network access occurred (address in use, attempt | |
1664 | to use privileged ports without permission). | |
1665 | .PP | |
9e038946 | 1666 | 3 - A problem occurred with a filesystem operation (missing |
5aabfc78 SK |
1667 | file/directory, permissions). |
1668 | .PP | |
1669 | 4 - Memory allocation failure. | |
1670 | .PP | |
1671 | 5 - Other miscellaneous problem. | |
1672 | .PP | |
1673 | 11 or greater - a non zero return code was received from the | |
1674 | lease-script process "init" call. The exit code from dnsmasq is the | |
1675 | script's exit code with 10 added. | |
1676 | ||
1b7ecd11 SK |
1677 | .SH LIMITS |
1678 | The default values for resource limits in dnsmasq are generally | |
1679 | conservative, and appropriate for embedded router type devices with | |
1680 | slow processors and limited memory. On more capable hardware, it is | |
1681 | possible to increase the limits, and handle many more clients. The | |
1682 | following applies to dnsmasq-2.37: earlier versions did not scale as well. | |
1683 | ||
1684 | .PP | |
1685 | Dnsmasq is capable of handling DNS and DHCP for at least a thousand | |
8ef5ada2 | 1686 | clients. The DHCP lease times should not be very short (less than one hour). The |
1b7ecd11 SK |
1687 | value of |
1688 | .B --dns-forward-max | |
1689 | can be increased: start with it equal to | |
1690 | the number of clients and increase if DNS seems slow. Note that DNS | |
1691 | performance depends too on the performance of the upstream | |
1692 | nameservers. The size of the DNS cache may be increased: the hard | |
1693 | limit is 10000 names and the default (150) is very low. Sending | |
1694 | SIGUSR1 to dnsmasq makes it log information which is useful for tuning | |
1695 | the cache size. See the | |
1696 | .B NOTES | |
1697 | section for details. | |
1698 | ||
1699 | .PP | |
1700 | The built-in TFTP server is capable of many simultaneous file | |
1701 | transfers: the absolute limit is related to the number of file-handles | |
1702 | allowed to a process and the ability of the select() system call to | |
1703 | cope with large numbers of file handles. If the limit is set too high | |
1704 | using | |
1705 | .B --tftp-max | |
1706 | it will be scaled down and the actual limit logged at | |
1707 | start-up. Note that more transfers are possible when the same file is | |
1708 | being sent than when each transfer sends a different file. | |
1709 | ||
1710 | .PP | |
1711 | It is possible to use dnsmasq to block Web advertising by using a list | |
1712 | of known banner-ad servers, all resolving to 127.0.0.1 or 0.0.0.0, in | |
1713 | .B /etc/hosts | |
1714 | or an additional hosts file. The list can be very long, | |
1715 | dnsmasq has been tested successfully with one million names. That size | |
1716 | file needs a 1GHz processor and about 60Mb of RAM. | |
1717 | ||
1f15b81d SK |
1718 | .SH INTERNATIONALISATION |
1719 | Dnsmasq can be compiled to support internationalisation. To do this, | |
1720 | the make targets "all-i18n" and "install-i18n" should be used instead of | |
1721 | the standard targets "all" and "install". When internationalisation | |
1722 | is compiled in, dnsmasq will produce log messages in the local | |
1723 | language and support internationalised domain names (IDN). Domain | |
1724 | names in /etc/hosts, /etc/ethers and /etc/dnsmasq.conf which contain | |
1725 | non-ASCII characters will be translated to the DNS-internal punycode | |
1726 | representation. Note that | |
1727 | dnsmasq determines both the language for messages and the assumed | |
1728 | charset for configuration | |
1729 | files from the LANG environment variable. This should be set to the system | |
1730 | default value by the script which is responsible for starting | |
1731 | dnsmasq. When editing the configuration files, be careful to do so | |
1732 | using only the system-default locale and not user-specific one, since | |
1733 | dnsmasq has no direct way of determining the charset in use, and must | |
1734 | assume that it is the system default. | |
1735 | ||
9e4abcb5 | 1736 | .SH FILES |
b49644f3 SK |
1737 | .IR /etc/dnsmasq.conf |
1738 | ||
1739 | .IR /usr/local/etc/dnsmasq.conf | |
9e4abcb5 SK |
1740 | |
1741 | .IR /etc/resolv.conf | |
28866e95 SK |
1742 | .IR /var/run/dnsmasq/resolv.conf |
1743 | .IR /etc/ppp/resolv.conf | |
1744 | .IR /etc/dhcpc/resolv.conf | |
9e4abcb5 SK |
1745 | |
1746 | .IR /etc/hosts | |
1747 | ||
3be34541 SK |
1748 | .IR /etc/ethers |
1749 | ||
b49644f3 SK |
1750 | .IR /var/lib/misc/dnsmasq.leases |
1751 | ||
1752 | .IR /var/db/dnsmasq.leases | |
9e4abcb5 SK |
1753 | |
1754 | .IR /var/run/dnsmasq.pid | |
1755 | .SH SEE ALSO | |
9e4abcb5 SK |
1756 | .BR hosts (5), |
1757 | .BR resolver (5) | |
1758 | .SH AUTHOR | |
1759 | This manual page was written by Simon Kelley <simon@thekelleys.org.uk>. | |
1760 | ||
1761 |