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