San Mehat | ffd6872 | 2010-01-20 09:56:15 -0800 | [diff] [blame] | 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 |
| 9 | is a lightweight DNS, TFTP and DHCP server. It is intended to provide |
| 10 | coupled DNS and DHCP service to a LAN. |
| 11 | .PP |
| 12 | Dnsmasq accepts DNS queries and either answers them from a small, local, |
| 13 | cache or forwards them to a real, recursive, DNS server. It loads the |
| 14 | contents of /etc/hosts so that local hostnames |
| 15 | which do not appear in the global DNS can be resolved and also answers |
| 16 | DNS queries for DHCP configured hosts. |
| 17 | .PP |
| 18 | The dnsmasq DHCP server supports static address assignments and multiple |
| 19 | networks. It automatically |
| 20 | sends a sensible default set of DHCP options, and can be configured to |
| 21 | send any desired set of DHCP options, including vendor-encapsulated |
| 22 | options. It includes a secure, read-only, |
| 23 | TFTP server to allow net/PXE boot of DHCP hosts and also supports BOOTP. |
| 24 | .PP |
| 25 | Dnsmasq |
| 26 | supports IPv6 for DNS, but not DHCP. |
| 27 | .SH OPTIONS |
| 28 | Note that in general missing parameters are allowed and switch off |
| 29 | functions, for instance "--pid-file" disables writing a PID file. On |
| 30 | BSD, unless the GNU getopt library is linked, the long form of the |
| 31 | options does not work on the command line; it is still recognised in |
| 32 | the configuration file. |
| 33 | .TP |
| 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 |
| 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 |
| 43 | only the specified file. This option may be repeated for more than one |
| 44 | additional hosts file. If a directory is given, then read all the files contained in that directory. |
| 45 | .TP |
| 46 | .B \-E, --expand-hosts |
| 47 | Add the domain to simple names (without a period) in /etc/hosts |
| 48 | in the same way as for DHCP-derived names. Note that this does not |
| 49 | apply to domain names in cnames, PTR records, TXT records etc. |
| 50 | .TP |
| 51 | .B \-T, --local-ttl=<time> |
| 52 | When replying with information from /etc/hosts or the DHCP leases |
| 53 | file dnsmasq by default sets the time-to-live field to zero, meaning |
| 54 | that the requestor should not itself cache the information. This is |
| 55 | the correct thing to do in almost all situations. This option allows a |
| 56 | time-to-live (in seconds) to be given for these replies. This will |
| 57 | reduce the load on the server at the expense of clients using stale |
| 58 | data under some circumstances. |
| 59 | .TP |
| 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 |
| 68 | .B \-k, --keep-in-foreground |
| 69 | Do not go into the background at startup but otherwise run as |
| 70 | normal. This is intended for use when dnsmasq is run under daemontools |
| 71 | or launchd. |
| 72 | .TP |
| 73 | .B \-d, --no-daemon |
| 74 | Debug mode: don't fork to the background, don't write a pid file, |
| 75 | don't change user id, generate a complete cache dump on receipt on |
| 76 | SIGUSR1, log to stderr as well as syslog, don't fork new processes |
| 77 | to handle TCP queries. |
| 78 | .TP |
| 79 | .B \-q, --log-queries |
| 80 | Log the results of DNS queries handled by dnsmasq. Enable a full cache dump on receipt of SIGUSR1. |
| 81 | .TP |
| 82 | .B \-8, --log-facility=<facility> |
| 83 | Set the facility to which dnsmasq will send syslog entries, this |
| 84 | defaults to DAEMON, and to LOCAL0 when debug mode is in operation. If |
| 85 | the facility given contains at least one '/' character, it is taken to |
| 86 | be a filename, and dnsmasq logs to the given file, instead of |
| 87 | syslog. (Errors whilst reading configuration will still go to syslog, |
| 88 | but all output from a successful startup, and all output whilst |
| 89 | running, will go exclusively to the file.) When logging to a file, |
| 90 | dnsmasq will close and reopen the file when it receives SIGUSR2. This |
| 91 | allows the log file to be rotated without stopping dnsmasq. |
| 92 | .TP |
| 93 | .B --log-async[=<lines>] |
| 94 | Enable asynchronous logging and optionally set the limit on the |
| 95 | number of lines |
| 96 | which will be queued by dnsmasq when writing to the syslog is slow. |
| 97 | Dnsmasq can log asynchronously: this |
| 98 | allows it to continue functioning without being blocked by syslog, and |
| 99 | allows syslog to use dnsmasq for DNS queries without risking deadlock. |
| 100 | If the queue of log-lines becomes full, dnsmasq will log the |
| 101 | overflow, and the number of messages lost. The default queue length is |
| 102 | 5, a sane value would be 5-25, and a maximum limit of 100 is imposed. |
| 103 | .TP |
| 104 | .B \-x, --pid-file=<path> |
| 105 | Specify an alternate path for dnsmasq to record its process-id in. Normally /var/run/dnsmasq.pid. |
| 106 | .TP |
| 107 | .B \-u, --user=<username> |
| 108 | Specify the userid to which dnsmasq will change after startup. Dnsmasq must normally be started as root, but it will drop root |
| 109 | privileges after startup by changing id to another user. Normally this user is "nobody" but that |
| 110 | can be over-ridden with this switch. |
| 111 | .TP |
| 112 | .B \-g, --group=<groupname> |
| 113 | Specify the group which dnsmasq will run |
| 114 | as. The defaults to "dip", if available, to facilitate access to |
| 115 | /etc/ppp/resolv.conf which is not normally world readable. |
| 116 | .TP |
| 117 | .B \-v, --version |
| 118 | Print the version number. |
| 119 | .TP |
| 120 | .B \-p, --port=<port> |
| 121 | Listen on <port> instead of the standard DNS port (53). Setting this |
| 122 | to zero completely disables DNS function, leaving only DHCP and/or TFTP. |
| 123 | .TP |
| 124 | .B \-P, --edns-packet-max=<size> |
| 125 | Specify the largest EDNS.0 UDP packet which is supported by the DNS |
| 126 | forwarder. Defaults to 1280, which is the RFC2671-recommended maximum |
| 127 | for ethernet. |
| 128 | .TP |
| 129 | .B \-Q, --query-port=<query_port> |
| 130 | Send outbound DNS queries from, and listen for their replies on, the |
| 131 | specific UDP port <query_port> instead of using random ports. NOTE |
| 132 | that using this option will make dnsmasq less secure against DNS |
| 133 | spoofing attacks but it may be faster and use less resources. Setting this option |
| 134 | to zero makes dnsmasq use a single port allocated to it by the |
| 135 | OS: this was the default behaviour in versions prior to 2.43. |
| 136 | .TP |
| 137 | .B --min-port=<port> |
| 138 | Do not use ports less than that given as source for outbound DNS |
| 139 | queries. Dnsmasq picks random ports as source for outbound queries: |
| 140 | when this option is given, the ports used will always to larger |
| 141 | than that specified. Useful for systems behind firewalls. |
| 142 | .TP |
| 143 | .B \-i, --interface=<interface name> |
| 144 | Listen only on the specified interface(s). Dnsmasq automatically adds |
| 145 | the loopback (local) interface to the list of interfaces to use when |
| 146 | the |
| 147 | .B \--interface |
| 148 | option is used. If no |
| 149 | .B \--interface |
| 150 | or |
| 151 | .B \--listen-address |
| 152 | options are given dnsmasq listens on all available interfaces except any |
| 153 | given in |
| 154 | .B \--except-interface |
| 155 | options. IP alias interfaces (eg "eth1:0") cannot be used with |
| 156 | .B --interface |
| 157 | or |
| 158 | .B --except-interface |
| 159 | options, use --listen-address instead. |
| 160 | .TP |
| 161 | .B \-I, --except-interface=<interface name> |
| 162 | Do not listen on the specified interface. Note that the order of |
| 163 | .B \--listen-address |
| 164 | .B --interface |
| 165 | and |
| 166 | .B --except-interface |
| 167 | options does not matter and that |
| 168 | .B --except-interface |
| 169 | options always override the others. |
| 170 | .TP |
| 171 | .B \-2, --no-dhcp-interface=<interface name> |
| 172 | Do not provide DHCP or TFTP on the specified interface, but do provide DNS service. |
| 173 | .TP |
| 174 | .B \-a, --listen-address=<ipaddr> |
| 175 | Listen on the given IP address(es). Both |
| 176 | .B \--interface |
| 177 | and |
| 178 | .B \--listen-address |
| 179 | options may be given, in which case the set of both interfaces and |
| 180 | addresses is used. Note that if no |
| 181 | .B \--interface |
| 182 | option is given, but |
| 183 | .B \--listen-address |
| 184 | is, dnsmasq will not automatically listen on the loopback |
| 185 | interface. To achieve this, its IP address, 127.0.0.1, must be |
| 186 | explicitly given as a |
| 187 | .B \--listen-address |
| 188 | option. |
| 189 | .TP |
| 190 | .B \-z, --bind-interfaces |
| 191 | On systems which support it, dnsmasq binds the wildcard address, |
| 192 | even when it is listening on only some interfaces. It then discards |
| 193 | requests that it shouldn't reply to. This has the advantage of |
| 194 | working even when interfaces come and go and change address. This |
| 195 | option forces dnsmasq to really bind only the interfaces it is |
| 196 | listening on. About the only time when this is useful is when |
| 197 | running another nameserver (or another instance of dnsmasq) on the |
| 198 | same machine. Setting this option also enables multiple instances of |
| 199 | dnsmasq which provide DHCP service to run in the same machine. |
| 200 | .TP |
| 201 | .B \-y, --localise-queries |
| 202 | Return answers to DNS queries from /etc/hosts which depend on the interface over which the query was |
| 203 | received. If a name in /etc/hosts has more than one address associated with |
| 204 | it, and at least one of those addresses is on the same subnet as the |
| 205 | interface to which the query was sent, then return only the |
| 206 | address(es) on that subnet. This allows for a server to have multiple |
| 207 | addresses in /etc/hosts corresponding to each of its interfaces, and |
| 208 | hosts will get the correct address based on which network they are |
| 209 | attached to. Currently this facility is limited to IPv4. |
| 210 | .TP |
| 211 | .B \-b, --bogus-priv |
| 212 | Bogus private reverse lookups. All reverse lookups for private IP ranges (ie 192.168.x.x, etc) |
| 213 | which are not found in /etc/hosts or the DHCP leases file are answered |
| 214 | with "no such domain" rather than being forwarded upstream. |
| 215 | .TP |
| 216 | .B \-V, --alias=[<old-ip>]|[<start-ip>-<end-ip>],<new-ip>[,<mask>] |
| 217 | Modify IPv4 addresses returned from upstream nameservers; old-ip is |
| 218 | replaced by new-ip. If the optional mask is given then any address |
| 219 | which matches the masked old-ip will be re-written. So, for instance |
| 220 | .B --alias=1.2.3.0,6.7.8.0,255.255.255.0 |
| 221 | will map 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. This is what |
| 222 | Cisco PIX routers call "DNS doctoring". If the old IP is given as |
| 223 | range, then only addresses in the range, rather than a whole subnet, |
| 224 | are re-written. So |
| 225 | .B --alias=192.168.0.10-192.168.0.40,10.0.0.0,255.255.255.0 |
| 226 | maps 192.168.0.10->192.168.0.40 to 10.0.0.10->10.0.0.40 |
| 227 | .TP |
| 228 | .B \-B, --bogus-nxdomain=<ipaddr> |
| 229 | Transform replies which contain the IP address given into "No such |
| 230 | domain" replies. This is intended to counteract a devious move made by |
| 231 | Verisign in September 2003 when they started returning the address of |
| 232 | an advertising web page in response to queries for unregistered names, |
| 233 | instead of the correct NXDOMAIN response. This option tells dnsmasq to |
| 234 | fake the correct response when it sees this behaviour. As at Sept 2003 |
| 235 | the IP address being returned by Verisign is 64.94.110.11 |
| 236 | .TP |
| 237 | .B \-f, --filterwin2k |
| 238 | Later versions of windows make periodic DNS requests which don't get sensible answers from |
| 239 | the public DNS and can cause problems by triggering dial-on-demand links. This flag turns on an option |
| 240 | to filter such requests. The requests blocked are for records of types SOA and SRV, and type ANY where the |
| 241 | requested name has underscores, to catch LDAP requests. |
| 242 | .TP |
| 243 | .B \-r, --resolv-file=<file> |
| 244 | Read the IP addresses of the upstream nameservers from <file>, instead of |
| 245 | /etc/resolv.conf. For the format of this file see |
| 246 | .BR resolv.conf (5) |
| 247 | the only lines relevant to dnsmasq are nameserver ones. Dnsmasq can |
| 248 | be told to poll more than one resolv.conf file, the first file name specified |
| 249 | overrides the default, subsequent ones add to the list. This is only |
| 250 | allowed when polling; the file with the currently latest modification |
| 251 | time is the one used. |
| 252 | .TP |
| 253 | .B \-R, --no-resolv |
| 254 | Don't read /etc/resolv.conf. Get upstream servers only from the command |
| 255 | line or the dnsmasq configuration file. |
| 256 | .TP |
| 257 | .B \-1, --enable-dbus |
| 258 | Allow dnsmasq configuration to be updated via DBus method calls. The |
| 259 | configuration which can be changed is upstream DNS servers (and |
| 260 | corresponding domains) and cache clear. Requires that dnsmasq has |
| 261 | been built with DBus support. |
| 262 | .TP |
| 263 | .B \-o, --strict-order |
| 264 | By default, dnsmasq will send queries to any of the upstream servers |
| 265 | it knows about and tries to favour servers that are known to |
| 266 | be up. Setting this flag forces dnsmasq to try each query with each |
| 267 | server strictly in the order they appear in /etc/resolv.conf |
| 268 | .TP |
| 269 | .B --all-servers |
| 270 | By default, when dnsmasq has more than one upstream server available, |
| 271 | it will send queries to just one server. Setting this flag forces |
| 272 | dnsmasq to send all queries to all available servers. The reply from |
| 273 | the server which answers first will be returned to the original requestor. |
| 274 | .TP |
| 275 | .B --stop-dns-rebind |
| 276 | Reject (and log) addresses from upstream nameservers which are in the |
| 277 | private IP ranges. This blocks an attack where a browser behind a |
| 278 | firewall is used to probe machines on the local network. |
| 279 | .TP |
| 280 | .B \-n, --no-poll |
| 281 | Don't poll /etc/resolv.conf for changes. |
| 282 | .TP |
| 283 | .B --clear-on-reload |
| 284 | Whenever /etc/resolv.conf is re-read, clear the DNS cache. |
| 285 | This is useful when new nameservers may have different |
| 286 | data than that held in cache. |
| 287 | .TP |
| 288 | .B \-D, --domain-needed |
| 289 | Tells dnsmasq to never forward queries for plain names, without dots |
| 290 | or domain parts, to upstream nameservers. If the name is not known |
| 291 | from /etc/hosts or DHCP then a "not found" answer is returned. |
| 292 | .TP |
| 293 | .B \-S, --local, --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>][@<source-ip>|<interface>[#<port>]] |
| 294 | Specify IP address of upstream servers directly. Setting this flag does |
| 295 | not suppress reading of /etc/resolv.conf, use -R to do that. If one or |
| 296 | more |
| 297 | optional domains are given, that server is used only for those domains |
| 298 | and they are queried only using the specified server. This is |
| 299 | intended for private nameservers: if you have a nameserver on your |
| 300 | network which deals with names of the form |
| 301 | xxx.internal.thekelleys.org.uk at 192.168.1.1 then giving the flag |
| 302 | .B -S /internal.thekelleys.org.uk/192.168.1.1 |
| 303 | will send all queries for |
| 304 | internal machines to that nameserver, everything else will go to the |
| 305 | servers in /etc/resolv.conf. An empty domain specification, |
| 306 | .B // |
| 307 | has the special meaning of "unqualified names only" ie names without any |
| 308 | dots in them. A non-standard port may be specified as |
| 309 | part of the IP |
| 310 | address using a # character. |
| 311 | More than one -S flag is allowed, with |
| 312 | repeated domain or ipaddr parts as required. |
| 313 | |
| 314 | Also permitted is a -S |
| 315 | flag which gives a domain but no IP address; this tells dnsmasq that |
| 316 | a domain is local and it may answer queries from /etc/hosts or DHCP |
| 317 | but should never forward queries on that domain to any upstream |
| 318 | servers. |
| 319 | .B local |
| 320 | is a synonym for |
| 321 | .B server |
| 322 | to make configuration files clearer in this case. |
| 323 | |
| 324 | The optional string after the @ character tells |
| 325 | dnsmasq how to set the source of the queries to this |
| 326 | nameserver. It should be an ip-address, which should belong to the machine on which |
| 327 | dnsmasq is running otherwise this server line will be logged and then |
| 328 | ignored, or an interface name. If an interface name is given, then |
| 329 | queries to the server will be forced via that interface; if an |
| 330 | ip-address is given then the source address of the queries will be set |
| 331 | to that address. |
| 332 | The query-port flag is ignored for any servers which have a |
| 333 | source address specified but the port may be specified directly as |
| 334 | part of the source address. Forcing queries to an interface is not |
| 335 | implemented on all platforms supported by dnsmasq. |
| 336 | .TP |
| 337 | .B \-A, --address=/<domain>/[domain/]<ipaddr> |
| 338 | Specify an IP address to return for any host in the given domains. |
| 339 | Queries in the domains are never forwarded and always replied to |
| 340 | with the specified IP address which may be IPv4 or IPv6. To give |
| 341 | both IPv4 and IPv6 addresses for a domain, use repeated -A flags. |
| 342 | Note that /etc/hosts and DHCP leases override this for individual |
| 343 | names. A common use of this is to redirect the entire doubleclick.net |
| 344 | domain to some friendly local web server to avoid banner ads. The |
| 345 | domain specification works in the same was as for --server, with the |
| 346 | additional facility that /#/ matches any domain. Thus |
| 347 | --address=/#/1.2.3.4 will always return 1.2.3.4 for any query not |
| 348 | answered from /etc/hosts or DHCP and not sent to an upstream |
| 349 | nameserver by a more specific --server directive. |
| 350 | .TP |
| 351 | .B \-m, --mx-host=<mx name>[[,<hostname>],<preference>] |
| 352 | Return an MX record named <mx name> pointing to the given hostname (if |
| 353 | given), or |
| 354 | the host specified in the --mx-target switch |
| 355 | or, if that switch is not given, the host on which dnsmasq |
| 356 | is running. The default is useful for directing mail from systems on a LAN |
| 357 | to a central server. The preference value is optional, and defaults to |
| 358 | 1 if not given. More than one MX record may be given for a host. |
| 359 | .TP |
| 360 | .B \-t, --mx-target=<hostname> |
| 361 | Specify the default target for the MX record returned by dnsmasq. See |
| 362 | --mx-host. If --mx-target is given, but not --mx-host, then dnsmasq |
| 363 | returns a MX record containing the MX target for MX queries on the |
| 364 | hostname of the machine on which dnsmasq is running. |
| 365 | .TP |
| 366 | .B \-e, --selfmx |
| 367 | Return an MX record pointing to itself for each local |
| 368 | machine. Local machines are those in /etc/hosts or with DHCP leases. |
| 369 | .TP |
| 370 | .B \-L, --localmx |
| 371 | Return an MX record pointing to the host given by mx-target (or the |
| 372 | machine on which dnsmasq is running) for each |
| 373 | local machine. Local machines are those in /etc/hosts or with DHCP |
| 374 | leases. |
| 375 | .TP |
| 376 | .B \-W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<priority>[,<weight>]]]] |
| 377 | Return a SRV DNS record. See RFC2782 for details. If not supplied, the |
| 378 | domain defaults to that given by |
| 379 | .B --domain. |
| 380 | The default for the target domain is empty, and the default for port |
| 381 | is one and the defaults for |
| 382 | weight and priority are zero. Be careful if transposing data from BIND |
| 383 | zone files: the port, weight and priority numbers are in a different |
| 384 | order. More than one SRV record for a given service/domain is allowed, |
| 385 | all that match are returned. |
| 386 | .TP |
| 387 | .B \-Y, --txt-record=<name>[[,<text>],<text>] |
| 388 | Return a TXT DNS record. The value of TXT record is a set of strings, |
| 389 | so any number may be included, split by commas. |
| 390 | .TP |
| 391 | .B --ptr-record=<name>[,<target>] |
| 392 | Return a PTR DNS record. |
| 393 | .TP |
| 394 | .B --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<regexp>[,<replacement>] |
| 395 | Return an NAPTR DNS record, as specified in RFC3403. |
| 396 | .TP |
| 397 | .B --cname=<cname>,<target> |
| 398 | Return a CNAME record which indicates that <cname> is really |
| 399 | <target>. There are significant limitations on the target; it must be a |
| 400 | DNS name which is known to dnsmasq from /etc/hosts (or additional |
| 401 | hosts files) or from DHCP. If the target does not satisfy this |
| 402 | criteria, the whole cname is ignored. The cname must be unique, but it |
| 403 | is permissable to have more than one cname pointing to the same target. |
| 404 | .TP |
| 405 | .B --interface-name=<name>,<interface> |
| 406 | Return a DNS record associating the name with the primary address on |
| 407 | the given interface. This flag specifies an A record for the given |
| 408 | name in the same way as an /etc/hosts line, except that the address is |
| 409 | not constant, but taken from the given interface. If the interface is |
| 410 | down, not configured or non-existent, an empty record is returned. The |
| 411 | matching PTR record is also created, mapping the interface address to |
| 412 | the name. More than one name may be associated with an interface |
| 413 | address by repeating the flag; in that case the first instance is used |
| 414 | for the reverse address-to-name mapping. |
| 415 | .TP |
| 416 | .B \-c, --cache-size=<cachesize> |
| 417 | Set the size of dnsmasq's cache. The default is 150 names. Setting the cache size to zero disables caching. |
| 418 | .TP |
| 419 | .B \-N, --no-negcache |
| 420 | Disable negative caching. Negative caching allows dnsmasq to remember |
| 421 | "no such domain" answers from upstream nameservers and answer |
| 422 | identical queries without forwarding them again. |
| 423 | .TP |
| 424 | .B \-0, --dns-forward-max=<queries> |
| 425 | Set the maximum number of concurrent DNS queries. The default value is |
| 426 | 150, which should be fine for most setups. The only known situation |
| 427 | where this needs to be increased is when using web-server log file |
| 428 | resolvers, which can generate large numbers of concurrent queries. |
| 429 | .TP |
| 430 | .B \-F, --dhcp-range=[[net:]network-id,]<start-addr>,<end-addr>[[,<netmask>],<broadcast>][,<lease time>] |
| 431 | Enable the DHCP server. Addresses will be given out from the range |
| 432 | <start-addr> to <end-addr> and from statically defined addresses given |
| 433 | in |
| 434 | .B dhcp-host |
| 435 | options. If the lease time is given, then leases |
| 436 | will be given for that length of time. The lease time is in seconds, |
| 437 | or minutes (eg 45m) or hours (eg 1h) or "infinite". If not given, |
| 438 | the default lease time is one hour. The |
| 439 | minimum lease time is two minutes. This |
| 440 | option may be repeated, with different addresses, to enable DHCP |
| 441 | service to more than one network. For directly connected networks (ie, |
| 442 | networks on which the machine running dnsmasq has an interface) the |
| 443 | netmask is optional. It is, however, required for networks which |
| 444 | receive DHCP service via a relay agent. The broadcast address is |
| 445 | always optional. It is always |
| 446 | allowed to have more than one dhcp-range in a single subnet. The optional |
| 447 | network-id is a alphanumeric label which marks this network so that |
| 448 | dhcp options may be specified on a per-network basis. |
| 449 | When it is prefixed with 'net:' then its meaning changes from setting |
| 450 | a tag to matching it. Only one tag may be set, but more than one tag may be matched. |
| 451 | The end address may be replaced by the keyword |
| 452 | .B static |
| 453 | which tells dnsmasq to enable DHCP for the network specified, but not |
| 454 | to dynamically allocate IP addresses: only hosts which have static |
| 455 | addresses given via |
| 456 | .B dhcp-host |
| 457 | or from /etc/ethers will be served. The end address may be replaced by |
| 458 | the keyword |
| 459 | .B proxy |
| 460 | in which case dnsmasq will provide proxy-DHCP on the specified |
| 461 | subnet. (See |
| 462 | .B pxe-prompt |
| 463 | and |
| 464 | .B pxe-service |
| 465 | for details.) |
| 466 | .TP |
| 467 | .B \-G, --dhcp-host=[<hwaddr>][,id:<client_id>|*][,net:<netid>][,<ipaddr>][,<hostname>][,<lease_time>][,ignore] |
| 468 | Specify per host parameters for the DHCP server. This allows a machine |
| 469 | with a particular hardware address to be always allocated the same |
| 470 | hostname, IP address and lease time. A hostname specified like this |
| 471 | overrides any supplied by the DHCP client on the machine. It is also |
| 472 | allowable to ommit the hardware address and include the hostname, in |
| 473 | which case the IP address and lease times will apply to any machine |
| 474 | claiming that name. For example |
| 475 | .B --dhcp-host=00:20:e0:3b:13:af,wap,infinite |
| 476 | tells dnsmasq to give |
| 477 | the machine with hardware address 00:20:e0:3b:13:af the name wap, and |
| 478 | an infinite DHCP lease. |
| 479 | .B --dhcp-host=lap,192.168.0.199 |
| 480 | tells |
| 481 | dnsmasq to always allocate the machine lap the IP address |
| 482 | 192.168.0.199. Addresses allocated like this are not constrained to be |
| 483 | in the range given by the --dhcp-range option, but they must be on the |
| 484 | network being served by the DHCP server. It is allowed to use client identifiers rather than |
| 485 | hardware addresses to identify hosts by prefixing with 'id:'. Thus: |
| 486 | .B --dhcp-host=id:01:02:03:04,..... |
| 487 | refers to the host with client identifier 01:02:03:04. It is also |
| 488 | allowed to specify the client ID as text, like this: |
| 489 | .B --dhcp-host=id:clientidastext,..... |
| 490 | |
| 491 | The special option id:* means "ignore any client-id |
| 492 | and use MAC addresses only." This is useful when a client presents a client-id sometimes |
| 493 | but not others. |
| 494 | |
| 495 | If a name appears in /etc/hosts, the associated address can be |
| 496 | allocated to a DHCP lease, but only if a |
| 497 | .B --dhcp-host |
| 498 | option specifying the name also exists. The special keyword "ignore" |
| 499 | tells dnsmasq to never offer a DHCP lease to a machine. The machine |
| 500 | can be specified by hardware address, client ID or hostname, for |
| 501 | instance |
| 502 | .B --dhcp-host=00:20:e0:3b:13:af,ignore |
| 503 | This is |
| 504 | useful when there is another DHCP server on the network which should |
| 505 | be used by some machines. |
| 506 | |
| 507 | The net:<network-id> sets the network-id tag |
| 508 | whenever this dhcp-host directive is in use. This can be used to |
| 509 | selectively send DHCP options just for this host. When a host matches any |
| 510 | dhcp-host directive (or one implied by /etc/ethers) then the special |
| 511 | network-id tag "known" is set. This allows dnsmasq to be configured to |
| 512 | ignore requests from unknown machines using |
| 513 | .B --dhcp-ignore=#known |
| 514 | Ethernet addresses (but not client-ids) may have |
| 515 | wildcard bytes, so for example |
| 516 | .B --dhcp-host=00:20:e0:3b:13:*,ignore |
| 517 | will cause dnsmasq to ignore a range of hardware addresses. Note that |
| 518 | the "*" will need to be escaped or quoted on a command line, but not |
| 519 | in the configuration file. |
| 520 | |
| 521 | Hardware addresses normally match any |
| 522 | network (ARP) type, but it is possible to restrict them to a single |
| 523 | ARP type by preceding them with the ARP-type (in HEX) and "-". so |
| 524 | .B --dhcp-host=06-00:20:e0:3b:13:af,1.2.3.4 |
| 525 | will only match a |
| 526 | Token-Ring hardware address, since the ARP-address type for token ring |
| 527 | is 6. |
| 528 | |
| 529 | As a special case, it is possible to include more than one |
| 530 | hardware address. eg: |
| 531 | .B --dhcp-host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2 |
| 532 | This allows an IP address to be associated with |
| 533 | multiple hardware addresses, and gives dnsmasq permission to abandon a |
| 534 | DHCP lease to one of the hardware addresses when another one asks for |
| 535 | a lease. Beware that this is a dangerous thing to do, it will only |
| 536 | work reliably if only one of the hardware addresses is active at any |
| 537 | time and there is no way for dnsmasq to enforce this. It is, for instance, |
| 538 | useful to allocate a stable IP address to a laptop which |
| 539 | has both wired and wireless interfaces. |
| 540 | .TP |
| 541 | .B --dhcp-hostsfile=<file> |
| 542 | Read DHCP host information from the specified file. The file contains |
| 543 | information about one host per line. The format of a line is the same |
| 544 | as text to the right of '=' in --dhcp-host. The advantage of storing DHCP host information |
| 545 | in this file is that it can be changed without re-starting dnsmasq: |
| 546 | the file will be re-read when dnsmasq receives SIGHUP. |
| 547 | .TP |
| 548 | .B --dhcp-optsfile=<file> |
| 549 | Read DHCP option information from the specified file. The advantage of |
| 550 | using this option is the same as for --dhcp-hostsfile: the |
| 551 | dhcp-optsfile will be re-read when dnsmasq receives SIGHUP. Note that |
| 552 | it is possible to encode the information in a |
| 553 | .B --dhcp-boot |
| 554 | flag as DHCP options, using the options names bootfile-name, |
| 555 | server-ip-address and tftp-server. This allows these to be included |
| 556 | in a dhcp-optsfile. |
| 557 | .TP |
| 558 | .B \-Z, --read-ethers |
| 559 | Read /etc/ethers for information about hosts for the DHCP server. The |
| 560 | format of /etc/ethers is a hardware address, followed by either a |
| 561 | hostname or dotted-quad IP address. When read by dnsmasq these lines |
| 562 | have exactly the same effect as |
| 563 | .B --dhcp-host |
| 564 | options containing the same information. /etc/ethers is re-read when |
| 565 | dnsmasq receives SIGHUP. |
| 566 | .TP |
| 567 | .B \-O, --dhcp-option=[<network-id>,[<network-id>,]][encap:<opt>,][vendor:[<vendor-class>],][<opt>|option:<opt-name>],[<value>[,<value>]] |
| 568 | Specify different or extra options to DHCP clients. By default, |
| 569 | dnsmasq sends some standard options to DHCP clients, the netmask and |
| 570 | broadcast address are set to the same as the host running dnsmasq, and |
| 571 | the DNS server and default route are set to the address of the machine |
| 572 | running dnsmasq. If the domain name option has been set, that is sent. |
| 573 | This configuration allows these defaults to be overridden, |
| 574 | or other options specified. The option, to be sent may be given as a |
| 575 | decimal number or as "option:<option-name>" The option numbers are |
| 576 | specified in RFC2132 and subsequent RFCs. The set of option-names |
| 577 | known by dnsmasq can be discovered by running "dnsmasq --help dhcp". |
| 578 | For example, to set the default route option to |
| 579 | 192.168.4.4, do |
| 580 | .B --dhcp-option=3,192.168.4.4 |
| 581 | or |
| 582 | .B --dhcp-option = option:router, 192.168.4.4 |
| 583 | and to set the time-server address to 192.168.0.4, do |
| 584 | .B --dhcp-option = 42,192.168.0.4 |
| 585 | or |
| 586 | .B --dhcp-option = option:ntp-server, 192.168.0.4 |
| 587 | The special address 0.0.0.0 is taken to mean "the address of the |
| 588 | machine running dnsmasq". Data types allowed are comma separated |
| 589 | dotted-quad IP addresses, a decimal number, colon-separated hex digits |
| 590 | and a text string. If the optional network-ids are given then |
| 591 | this option is only sent when all the network-ids are matched. |
| 592 | |
| 593 | Special processing is done on a text argument for option 119, to |
| 594 | conform with RFC 3397. Text or dotted-quad IP addresses as arguments |
| 595 | to option 120 are handled as per RFC 3361. Dotted-quad IP addresses |
| 596 | which are followed by a slash and then a netmask size are encoded as |
| 597 | described in RFC 3442. |
| 598 | |
| 599 | Be careful: no checking is done that the correct type of data for the |
| 600 | option number is sent, it is quite possible to |
| 601 | persuade dnsmasq to generate illegal DHCP packets with injudicious use |
| 602 | of this flag. When the value is a decimal number, dnsmasq must determine how |
| 603 | large the data item is. It does this by examining the option number and/or the |
| 604 | value, but can be overridden by appending a single letter flag as follows: |
| 605 | b = one byte, s = two bytes, i = four bytes. This is mainly useful with |
| 606 | encapsulated vendor class options (see below) where dnsmasq cannot |
| 607 | determine data size from the option number. Option data which |
| 608 | consists solely of periods and digits will be interpreted by dnsmasq |
| 609 | as an IP address, and inserted into an option as such. To force a |
| 610 | literal string, use quotes. For instance when using option 66 to send |
| 611 | a literal IP address as TFTP server name, it is necessary to do |
| 612 | .B --dhcp-option=66,"1.2.3.4" |
| 613 | |
| 614 | Encapsulated Vendor-class options may also be specified using |
| 615 | --dhcp-option: for instance |
| 616 | .B --dhcp-option=vendor:PXEClient,1,0.0.0.0 |
| 617 | sends the encapsulated vendor |
| 618 | class-specific option "mftp-address=0.0.0.0" to any client whose |
| 619 | vendor-class matches "PXEClient". The vendor-class matching is |
| 620 | substring based (see --dhcp-vendorclass for details). If a |
| 621 | vendor-class option (number 60) is sent by dnsmasq, then that is used |
| 622 | for selecting encapsulated options in preference to any sent by the |
| 623 | client. It is |
| 624 | possible to omit the vendorclass completely; |
| 625 | .B --dhcp-option=vendor:,1,0.0.0.0 |
| 626 | in which case the encapsulated option is always sent. |
| 627 | |
| 628 | Options may be encapsulated within other options: for instance |
| 629 | .B --dhcp-option=encap:175, 190, "iscsi-client0" |
| 630 | will send option 175, within which is the option 190. If multiple |
| 631 | options are given which are encapsulated with the same option number |
| 632 | then they will be correctly combined into one encapsulated option. |
| 633 | encap: and vendor: are may not both be set in the same dhcp-option. |
| 634 | |
| 635 | The address 0.0.0.0 is not treated specially in |
| 636 | encapsulated options. |
| 637 | .TP |
| 638 | .B --dhcp-option-force=[<network-id>,[<network-id>,]][encap:<opt>,][vendor:[<vendor-class>],]<opt>,[<value>[,<value>]] |
| 639 | This works in exactly the same way as |
| 640 | .B --dhcp-option |
| 641 | except that the option will always be sent, even if the client does |
| 642 | not ask for it in the parameter request list. This is sometimes |
| 643 | needed, for example when sending options to PXELinux. |
| 644 | .TP |
| 645 | .B --dhcp-no-override |
| 646 | Disable re-use of the DHCP servername and filename fields as extra |
| 647 | option space. If it can, dnsmasq moves the boot server and filename |
| 648 | information (from dhcp-boot) out of their dedicated fields into |
| 649 | DHCP options. This make extra space available in the DHCP packet for |
| 650 | options but can, rarely, confuse old or broken clients. This flag |
| 651 | forces "simple and safe" behaviour to avoid problems in such a case. |
| 652 | .TP |
| 653 | .B \-U, --dhcp-vendorclass=<network-id>,<vendor-class> |
| 654 | Map from a vendor-class string to a network id tag. Most DHCP clients provide a |
| 655 | "vendor class" which represents, in some sense, the type of host. This option |
| 656 | maps vendor classes to tags, so that DHCP options may be selectively delivered |
| 657 | to different classes of hosts. For example |
| 658 | .B dhcp-vendorclass=printers,Hewlett-Packard JetDirect |
| 659 | will allow options to be set only for HP printers like so: |
| 660 | .B --dhcp-option=printers,3,192.168.4.4 |
| 661 | The vendor-class string is |
| 662 | substring matched against the vendor-class supplied by the client, to |
| 663 | allow fuzzy matching. |
| 664 | .TP |
| 665 | .B \-j, --dhcp-userclass=<network-id>,<user-class> |
| 666 | Map from a user-class string to a network id tag (with substring |
| 667 | matching, like vendor classes). Most DHCP clients provide a |
| 668 | "user class" which is configurable. This option |
| 669 | maps user classes to tags, so that DHCP options may be selectively delivered |
| 670 | to different classes of hosts. It is possible, for instance to use |
| 671 | this to set a different printer server for hosts in the class |
| 672 | "accounts" than for hosts in the class "engineering". |
| 673 | .TP |
| 674 | .B \-4, --dhcp-mac=<network-id>,<MAC address> |
| 675 | Map from a MAC address to a network-id tag. The MAC address may include |
| 676 | wildcards. For example |
| 677 | .B --dhcp-mac=3com,01:34:23:*:*:* |
| 678 | will set the tag "3com" for any host whose MAC address matches the pattern. |
| 679 | .TP |
| 680 | .B --dhcp-circuitid=<network-id>,<circuit-id>, --dhcp-remoteid=<network-id>,<remote-id> |
| 681 | Map from RFC3046 relay agent options to network-id tags. This data may |
| 682 | be provided by DHCP relay agents. The circuit-id or remote-id is |
| 683 | normally given as colon-separated hex, but is also allowed to be a |
| 684 | simple string. If an exact match is achieved between the circuit or |
| 685 | agent ID and one provided by a relay agent, the network-id tag is set. |
| 686 | .TP |
| 687 | .B --dhcp-subscrid=<network-id>,<subscriber-id> |
| 688 | Map from RFC3993 subscriber-id relay agent options to network-id tags. |
| 689 | .TP |
| 690 | .B --dhcp-match=<network-id>,<option number>|option:<option name>[,<value>] |
| 691 | Without a value, set the network-id tag if the client sends a DHCP |
| 692 | option of the given number or name. When a value is given, set the tag only if |
| 693 | the option is sent and matches the value. The value may be of the form |
| 694 | "01:ff:*:02" in which case the value must match (apart from widcards) |
| 695 | but the option sent may have unmatched data past the end of the |
| 696 | value. The value may also be of the same form as in |
| 697 | .B dhcp-option |
| 698 | in which case the option sent is treated as an array, and one element |
| 699 | must match, so |
| 700 | |
| 701 | --dhcp-match=efi-ia32,option:client-arch,6 |
| 702 | |
| 703 | will set the tag "efi-ia32" if the the number 6 appears in the list of |
| 704 | architectures sent by the client in option 93. (See RFC 4578 for |
| 705 | details.) If the value is a string, substring matching is used. |
| 706 | .TP |
| 707 | .B \-J, --dhcp-ignore=<network-id>[,<network-id>] |
| 708 | When all the given network-ids match the set of network-ids derived |
| 709 | from the net, host, vendor and user classes, ignore the host and do |
| 710 | not allocate it a DHCP lease. |
| 711 | .TP |
| 712 | .B --dhcp-ignore-names[=<network-id>[,<network-id>]] |
| 713 | When all the given network-ids match the set of network-ids derived |
| 714 | from the net, host, vendor and user classes, ignore any hostname |
| 715 | provided by the host. Note that, unlike dhcp-ignore, it is permissible |
| 716 | to supply no netid tags, in which case DHCP-client supplied hostnames |
| 717 | are always ignored, and DHCP hosts are added to the DNS using only |
| 718 | dhcp-host configuration in dnsmasq and the contents of /etc/hosts and |
| 719 | /etc/ethers. |
| 720 | .TP |
| 721 | .B --dhcp-broadcast=<network-id>[,<network-id>] |
| 722 | When all the given network-ids match the set of network-ids derived |
| 723 | from the net, host, vendor and user classes, always use broadcast to |
| 724 | communicate with the host when it is unconfigured. Most DHCP clients which |
| 725 | need broadcast replies set a flag in their requests so that this |
| 726 | happens automatically, some old BOOTP clients do not. |
| 727 | .TP |
| 728 | .B \-M, --dhcp-boot=[net:<network-id>,]<filename>,[<servername>[,<server address>]] |
| 729 | Set BOOTP options to be returned by the DHCP server. Server name and |
| 730 | address are optional: if not provided, the name is left empty, and the |
| 731 | address set to the address of the machine running dnsmasq. If dnsmasq |
| 732 | is providing a TFTP service (see |
| 733 | .B --enable-tftp |
| 734 | ) then only the filename is required here to enable network booting. |
| 735 | If the optional network-id(s) are given, |
| 736 | they must match for this configuration to be sent. Note that |
| 737 | network-ids are prefixed by "net:" to distinguish them. |
| 738 | .TP |
| 739 | .B --pxe-service=[net:<network-id>,]<CSA>,<menu text>,<basename>|<bootservicetype>[,<server address>] |
| 740 | Most uses of PXE boot-ROMS simply allow the PXE |
| 741 | system to obtain an IP address and then download the file specified by |
| 742 | .B dhcp-boot |
| 743 | and execute it. However the PXE system is capable of more complex |
| 744 | functions when supported by a suitable DHCP server. |
| 745 | |
| 746 | This specifies a boot option which may appear in a PXE boot menu. <CSA> is |
| 747 | client system type, only services of the correct type will appear in a |
| 748 | menu. The known types are x86PC, PC98, IA64_EFI, Alpha, Arc_x86, |
| 749 | Intel_Lean_Client, IA32_EFI, BC_EFI, Xscale_EFI and X86-64_EFI; an |
| 750 | integer may be used for other types. The |
| 751 | parameter after the menu text may be a file name, in which case dnsmasq acts as a |
| 752 | boot server and directs the PXE client to download the file by TFTP, |
| 753 | either from itself ( |
| 754 | .B enable-tftp |
| 755 | must be set for this to work) or another TFTP server if the final IP |
| 756 | address is given. |
| 757 | Note that the "layer" |
| 758 | suffix (normally ".0") is supplied by PXE, and should not be added to |
| 759 | the basename. If an integer boot service type, rather than a basename |
| 760 | is given, then the PXE client will search for a |
| 761 | suitable boot service for that type on the network. This search may be done |
| 762 | by multicast or broadcast, or direct to a server if its IP address is provided. A boot service |
| 763 | type of 0 is special, and will abort the net boot procedure and |
| 764 | continue booting from local media. |
| 765 | .TP |
| 766 | .B --pxe-prompt=[net:<network-id>,]<prompt>[,<timeout>] |
| 767 | Setting this provides a prompt to be displayed after PXE boot. If the |
| 768 | timeout is given then after the |
| 769 | timeout has elapsed with no keyboard input, the first available menu |
| 770 | option will be automatically executed. If the timeout is zero then the first available menu |
| 771 | item will be executed immediately. If |
| 772 | .B pxe-prompt |
| 773 | is ommitted the system will wait for user input if there are multiple |
| 774 | items in the menu, but boot immediately if |
| 775 | there is only one. See |
| 776 | .B pxe-service |
| 777 | for details of menu items. |
| 778 | |
| 779 | Dnsmasq supports PXE "proxy-DHCP", in this case another DHCP server on |
| 780 | the network is responsible for allocating IP addresses, and dnsmasq |
| 781 | simply provides the information given in |
| 782 | .B pxe-prompt |
| 783 | and |
| 784 | .B pxe-service |
| 785 | to allow netbooting. This mode is enabled using the |
| 786 | .B proxy |
| 787 | keyword in |
| 788 | .B dhcp-range. |
| 789 | .TP |
| 790 | .B \-X, --dhcp-lease-max=<number> |
| 791 | Limits dnsmasq to the specified maximum number of DHCP leases. The |
| 792 | default is 150. This limit is to prevent DoS attacks from hosts which |
| 793 | create thousands of leases and use lots of memory in the dnsmasq |
| 794 | process. |
| 795 | .TP |
| 796 | .B \-K, --dhcp-authoritative |
| 797 | Should be set when dnsmasq is definitely the only DHCP server on a network. |
| 798 | It changes the behaviour from strict RFC compliance so that DHCP requests on |
| 799 | unknown leases from unknown hosts are not ignored. This allows new hosts |
| 800 | to get a lease without a tedious timeout under all circumstances. It also |
| 801 | allows dnsmasq to rebuild its lease database without each client needing to |
| 802 | reacquire a lease, if the database is lost. |
| 803 | .TP |
| 804 | .B --dhcp-alternate-port[=<server port>[,<client port>]] |
| 805 | Change the ports used for DHCP from the default. If this option is |
| 806 | given alone, without arguments, it changes the ports used for DHCP |
| 807 | from 67 and 68 to 1067 and 1068. If a single argument is given, that |
| 808 | port number is used for the server and the port number plus one used |
| 809 | for the client. Finally, two port numbers allows arbitrary |
| 810 | specification of both server and client ports for DHCP. |
| 811 | .TP |
| 812 | .B \-3, --bootp-dynamic[=<network-id>[,<network-id>]] |
| 813 | Enable dynamic allocation of IP addresses to BOOTP clients. Use this |
| 814 | with care, since each address allocated to a BOOTP client is leased |
| 815 | forever, and therefore becomes permanently unavailable for re-use by |
| 816 | other hosts. if this is given without tags, then it unconditionally |
| 817 | enables dynamic allocation. With tags, only when the tags are all |
| 818 | set. It may be repeated with different tag sets. |
| 819 | .TP |
| 820 | .B \-5, --no-ping |
| 821 | By default, the DHCP server will attempt to ensure that an address in |
| 822 | not in use before allocating it to a host. It does this by sending an |
| 823 | ICMP echo request (aka "ping") to the address in question. If it gets |
| 824 | a reply, then the address must already be in use, and another is |
| 825 | tried. This flag disables this check. Use with caution. |
| 826 | .TP |
| 827 | .B --log-dhcp |
| 828 | Extra logging for DHCP: log all the options sent to DHCP clients and |
| 829 | the netid tags used to determine them. |
| 830 | .TP |
| 831 | .B \-l, --dhcp-leasefile=<path> |
| 832 | Use the specified file to store DHCP lease information. |
| 833 | .TP |
| 834 | .B \-6 --dhcp-script=<path> |
| 835 | Whenever a new DHCP lease is created, or an old one destroyed, the |
| 836 | executable specified by this option is run. The arguments to the process |
| 837 | are "add", "old" or "del", the MAC |
| 838 | address of the host, the IP address, and the hostname, |
| 839 | if known. "add" means a lease has been created, "del" means it has |
| 840 | been destroyed, "old" is a notification of an existing lease when |
| 841 | dnsmasq starts or a change to MAC address or hostname of an existing |
| 842 | lease (also, lease length or expiry and client-id, if leasefile-ro is set). |
| 843 | If the MAC address is from a network type other than ethernet, |
| 844 | it will have the network type prepended, eg "06-01:23:45:67:89:ab" for |
| 845 | token ring. The process is run as root (assuming that dnsmasq was originally run as |
| 846 | root) even if dnsmasq is configured to change UID to an unprivileged user. |
| 847 | The environment is inherited from the invoker of dnsmasq, and if the |
| 848 | host provided a client-id, this is stored in the environment variable |
| 849 | DNSMASQ_CLIENT_ID. If the fully-qualified domain name of the host is |
| 850 | known, the domain part is stored in DNSMASQ_DOMAIN. |
| 851 | If the client provides vendor-class, hostname or user-class, |
| 852 | these are provided in DNSMASQ_VENDOR_CLASS |
| 853 | DNSMASQ_SUPPLIED_HOSTNAME and |
| 854 | DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn variables, but only for |
| 855 | "add" actions or "old" actions when a host resumes an existing lease, |
| 856 | since these data are not held in dnsmasq's lease |
| 857 | database. If dnsmasq was compiled with HAVE_BROKEN_RTC, then |
| 858 | the length of the lease (in seconds) is stored in |
| 859 | DNSMASQ_LEASE_LENGTH, otherwise the time of lease expiry is stored in |
| 860 | DNSMASQ_LEASE_EXPIRES. The number of seconds until lease expiry is |
| 861 | always stored in DNSMASQ_TIME_REMAINING. |
| 862 | If a lease used to have a hostname, which is |
| 863 | removed, an "old" event is generated with the new state of the lease, |
| 864 | ie no name, and the former name is provided in the environment |
| 865 | variable DNSMASQ_OLD_HOSTNAME. DNSMASQ_INTERFACE stores the name of |
| 866 | the interface on which the request arrived; this is not set for "old" |
| 867 | actions when dnsmasq restarts. DNSMASQ_RELAY_ADDRESS is set if the client |
| 868 | used a DHCP relay to contact dnsmasq and the IP address of the relay is known. |
| 869 | All file descriptors are |
| 870 | closed except stdin, stdout and stderr which are open to /dev/null |
| 871 | (except in debug mode). |
| 872 | The script is not invoked concurrently: if subsequent lease |
| 873 | changes occur, the script is not invoked again until any existing |
| 874 | invocation exits. At dnsmasq startup, the script will be invoked for |
| 875 | all existing leases as they are read from the lease file. Expired |
| 876 | leases will be called with "del" and others with "old". <path> |
| 877 | must be an absolute pathname, no PATH search occurs. When dnsmasq |
| 878 | receives a HUP signal, the script will be invoked for existing leases |
| 879 | with an "old " event. |
| 880 | .TP |
| 881 | .B --dhcp-scriptuser |
| 882 | Specify the user as which to run the lease-change script. This defaults to root, but can be changed to another user using this flag. |
| 883 | .TP |
| 884 | .B \-9, --leasefile-ro |
| 885 | Completely suppress use of the lease database file. The file will not |
| 886 | be created, read, or written. Change the way the lease-change |
| 887 | script (if one is provided) is called, so that the lease database may |
| 888 | be maintained in external storage by the script. In addition to the |
| 889 | invocations given in |
| 890 | .B --dhcp-script |
| 891 | the lease-change script is called once, at dnsmasq startup, with the |
| 892 | single argument "init". When called like this the script should write |
| 893 | the saved state of the lease database, in dnsmasq leasefile format, to |
| 894 | stdout and exit with zero exit code. Setting this |
| 895 | option also forces the leasechange script to be called on changes |
| 896 | to the client-id and lease length and expiry time. |
| 897 | .TP |
| 898 | .B --bridge-interface=<interface>,<alias>[,<alias>] |
| 899 | Treat DHCP request packets arriving at any of the <alias> interfaces |
| 900 | as if they had arrived at <interface>. This option is necessary when |
| 901 | using "old style" bridging on BSD platforms, since |
| 902 | packets arrive at tap interfaces which don't have an IP address. |
| 903 | .TP |
| 904 | .B \-s, --domain=<domain>[,<address range>] |
| 905 | Specifies DNS domains for the DHCP server. Domains may be be given |
| 906 | unconditionally (without the IP range) or for limited IP ranges. This has two effects; |
| 907 | firstly it causes the DHCP server to return the domain to any hosts |
| 908 | which request it, and secondly it sets the domain which it is legal |
| 909 | for DHCP-configured hosts to claim. The intention is to constrain |
| 910 | hostnames so that an untrusted host on the LAN cannot advertise |
| 911 | its name via dhcp as e.g. "microsoft.com" and capture traffic not |
| 912 | meant for it. If no domain suffix is specified, then any DHCP |
| 913 | hostname with a domain part (ie with a period) will be disallowed |
| 914 | and logged. If suffix is specified, then hostnames with a domain |
| 915 | part are allowed, provided the domain part matches the suffix. In |
| 916 | addition, when a suffix is set then hostnames without a domain |
| 917 | part have the suffix added as an optional domain part. Eg on my network I can set |
| 918 | .B --domain=thekelleys.org.uk |
| 919 | and have a machine whose DHCP hostname is "laptop". The IP address for that machine is available from |
| 920 | .B dnsmasq |
| 921 | both as "laptop" and "laptop.thekelleys.org.uk". If the domain is |
| 922 | given as "#" then the domain is read from the first "search" directive |
| 923 | in /etc/resolv.conf (or equivalent). The address range can be of the form |
| 924 | <ip address>,<ip address> or <ip address>/<netmask> or just a single |
| 925 | <ip address>. See |
| 926 | .B --dhcp-fqdn |
| 927 | which can change the behaviour of dnsmasq with domains. |
| 928 | .TP |
| 929 | .B --dhcp-fqdn |
| 930 | In the default mode, dnsmasq inserts the unqualified names of |
| 931 | DHCP clients into the DNS. For this reason, the names must be unique, |
| 932 | even if two clients which have the same name are in different |
| 933 | domains. If a second DHCP client appears which has the same name as an |
| 934 | existing client, the name is transfered to the new client. If |
| 935 | .B --dhcp-fqdn |
| 936 | is set, this behaviour changes: the unqualified name is no longer |
| 937 | put in the DNS, only the qualified name. Two DHCP clients with the |
| 938 | same name may both keep the name, provided that the domain part is |
| 939 | different (ie the fully qualified names differ.) To ensure that all |
| 940 | names have a domain part, there must be at least |
| 941 | .B --domain |
| 942 | without an address specified when |
| 943 | .B --dhcp-fqdn |
| 944 | is set. |
| 945 | .TP |
| 946 | .B --enable-tftp |
| 947 | Enable the TFTP server function. This is deliberately limited to that |
| 948 | needed to net-boot a client. Only reading is allowed; the tsize and |
| 949 | blksize extensions are supported (tsize is only supported in octet mode). |
| 950 | .TP |
| 951 | .B --tftp-root=<directory> |
| 952 | Look for files to transfer using TFTP relative to the given |
| 953 | directory. When this is set, TFTP paths which include ".." are |
| 954 | rejected, to stop clients getting outside the specified root. |
| 955 | Absolute paths (starting with /) are allowed, but they must be within |
| 956 | the tftp-root. |
| 957 | .TP |
| 958 | .B --tftp-unique-root |
| 959 | Add the IP address of the TFTP client as a path component on the end |
| 960 | of the TFTP-root (in standard dotted-quad format). Only valid if a |
| 961 | tftp-root is set and the directory exists. For instance, if tftp-root is "/tftp" and client |
| 962 | 1.2.3.4 requests file "myfile" then the effective path will be |
| 963 | "/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4 exists or /tftp/myfile otherwise. |
| 964 | .TP |
| 965 | .B --tftp-secure |
| 966 | Enable TFTP secure mode: without this, any file which is readable by |
| 967 | the dnsmasq process under normal unix access-control rules is |
| 968 | available via TFTP. When the --tftp-secure flag is given, only files |
| 969 | owned by the user running the dnsmasq process are accessible. If |
| 970 | dnsmasq is being run as root, different rules apply: --tftp-secure |
| 971 | has no effect, but only files which have the world-readable bit set |
| 972 | are accessible. It is not recommended to run dnsmasq as root with TFTP |
| 973 | enabled, and certainly not without specifying --tftp-root. Doing so |
| 974 | can expose any world-readable file on the server to any host on the net. |
| 975 | .TP |
| 976 | .B --tftp-max=<connections> |
| 977 | Set the maximum number of concurrent TFTP connections allowed. This |
| 978 | defaults to 50. When serving a large number of TFTP connections, |
| 979 | per-process file descriptor limits may be encountered. Dnsmasq needs |
| 980 | one file descriptor for each concurrent TFTP connection and one |
| 981 | file descriptor per unique file (plus a few others). So serving the |
| 982 | same file simultaneously to n clients will use require about n + 10 file |
| 983 | descriptors, serving different files simultaneously to n clients will |
| 984 | require about (2*n) + 10 descriptors. If |
| 985 | .B --tftp-port-range |
| 986 | is given, that can affect the number of concurrent connections. |
| 987 | .TP |
| 988 | .B --tftp-no-blocksize |
| 989 | Stop the TFTP server from negotiating the "blocksize" option with a |
| 990 | client. Some buggy clients request this option but then behave badly |
| 991 | when it is granted. |
| 992 | .TP |
| 993 | .B --tftp-port-range=<start>,<end> |
| 994 | A TFTP server listens on a well-known port (69) for connection initiation, |
| 995 | but it also uses a dynamically-allocated port for each |
| 996 | connection. Normally these are allocated by the OS, but this option |
| 997 | specifies a range of ports for use by TFTP transfers. This can be |
| 998 | useful when TFTP has to traverse a firewall. The start of the range |
| 999 | cannot be lower than 1025 unless dnsmasq is running as root. The number |
| 1000 | of concurrent TFTP connections is limited by the size of the port range. |
| 1001 | .TP |
| 1002 | .B \-C, --conf-file=<file> |
| 1003 | Specify a different configuration file. The conf-file option is also allowed in |
| 1004 | configuration files, to include multiple configuration files. |
| 1005 | .TP |
| 1006 | .B \-7, --conf-dir=<directory>[,<file-extension>......] |
| 1007 | Read all the files in the given directory as configuration |
| 1008 | files. If extension(s) are given, any files which end in those |
| 1009 | extensions are skipped. Any files whose names end in ~ or start with . or start and end |
| 1010 | with # are always skipped. This flag may be given on the command |
| 1011 | line or in a configuration file. |
| 1012 | .SH CONFIG FILE |
| 1013 | At startup, dnsmasq reads |
| 1014 | .I /etc/dnsmasq.conf, |
| 1015 | if it exists. (On |
| 1016 | FreeBSD, the file is |
| 1017 | .I /usr/local/etc/dnsmasq.conf |
| 1018 | ) (but see the |
| 1019 | .B \-C |
| 1020 | and |
| 1021 | .B \-7 |
| 1022 | options.) The format of this |
| 1023 | file consists of one option per line, exactly as the long options detailed |
| 1024 | in the OPTIONS section but without the leading "--". Lines starting with # are comments and ignored. For |
| 1025 | options which may only be specified once, the configuration file overrides |
| 1026 | the command line. Quoting is allowed in a config file: |
| 1027 | between " quotes the special meanings of ,:. and # are removed and the |
| 1028 | following escapes are allowed: \\\\ \\" \\t \\e \\b \\r and \\n. The later |
| 1029 | corresponding to tab, escape, backspace, return and newline. |
| 1030 | .SH NOTES |
| 1031 | When it receives a SIGHUP, |
| 1032 | .B dnsmasq |
| 1033 | clears its cache and then re-loads |
| 1034 | .I /etc/hosts |
| 1035 | and |
| 1036 | .I /etc/ethers |
| 1037 | and any file given by --dhcp-hostsfile, --dhcp-optsfile or --addn-hosts. |
| 1038 | The dhcp lease change script is called for all |
| 1039 | existing DHCP leases. If |
| 1040 | .B |
| 1041 | --no-poll |
| 1042 | is set SIGHUP also re-reads |
| 1043 | .I /etc/resolv.conf. |
| 1044 | SIGHUP |
| 1045 | does NOT re-read the configuration file. |
| 1046 | .PP |
| 1047 | When it receives a SIGUSR1, |
| 1048 | .B dnsmasq |
| 1049 | writes statistics to the system log. It writes the cache size, |
| 1050 | the number of names which have had to removed from the cache before |
| 1051 | they expired in order to make room for new names and the total number |
| 1052 | of names that have been inserted into the cache. For each upstream |
| 1053 | server it gives the number of queries sent, and the number which |
| 1054 | resulted in an error. In |
| 1055 | .B --no-daemon |
| 1056 | mode or when full logging is enabled (-q), a complete dump of the |
| 1057 | contents of the cache is made. |
| 1058 | .PP |
| 1059 | When it receives SIGUSR2 and it is logging direct to a file (see |
| 1060 | .B --log-facility |
| 1061 | ) |
| 1062 | .B dnsmasq |
| 1063 | will close and reopen the log file. Note that during this operation, |
| 1064 | dnsmasq will not be running as root. When it first creates the logfile |
| 1065 | dnsmasq changes the ownership of the file to the non-root user it will run |
| 1066 | as. Logrotate should be configured to create a new log file with |
| 1067 | the ownership which matches the existing one before sending SIGUSR2. |
| 1068 | If TCP DNS queries are in progress, the old logfile will remain open in |
| 1069 | child processes which are handling TCP queries and may continue to be |
| 1070 | written. There is a limit of 150 seconds, after which all existing TCP |
| 1071 | processes will have expired: for this reason, it is not wise to |
| 1072 | configure logfile compression for logfiles which have just been |
| 1073 | rotated. Using logrotate, the required options are |
| 1074 | .B create |
| 1075 | and |
| 1076 | .B delaycompress. |
| 1077 | |
| 1078 | |
| 1079 | .PP |
| 1080 | Dnsmasq is a DNS query forwarder: it it not capable of recursively |
| 1081 | answering arbitrary queries starting from the root servers but |
| 1082 | forwards such queries to a fully recursive upstream DNS server which is |
| 1083 | typically provided by an ISP. By default, dnsmasq reads |
| 1084 | .I /etc/resolv.conf |
| 1085 | to discover the IP |
| 1086 | addresses of the upstream nameservers it should use, since the |
| 1087 | information is typically stored there. Unless |
| 1088 | .B --no-poll |
| 1089 | is used, |
| 1090 | .B dnsmasq |
| 1091 | checks the modification time of |
| 1092 | .I /etc/resolv.conf |
| 1093 | (or equivalent if |
| 1094 | .B \--resolv-file |
| 1095 | is used) and re-reads it if it changes. This allows the DNS servers to |
| 1096 | be set dynamically by PPP or DHCP since both protocols provide the |
| 1097 | information. |
| 1098 | Absence of |
| 1099 | .I /etc/resolv.conf |
| 1100 | is not an error |
| 1101 | since it may not have been created before a PPP connection exists. Dnsmasq |
| 1102 | simply keeps checking in case |
| 1103 | .I /etc/resolv.conf |
| 1104 | is created at any |
| 1105 | time. Dnsmasq can be told to parse more than one resolv.conf |
| 1106 | file. This is useful on a laptop, where both PPP and DHCP may be used: |
| 1107 | dnsmasq can be set to poll both |
| 1108 | .I /etc/ppp/resolv.conf |
| 1109 | and |
| 1110 | .I /etc/dhcpc/resolv.conf |
| 1111 | and will use the contents of whichever changed |
| 1112 | last, giving automatic switching between DNS servers. |
| 1113 | .PP |
| 1114 | Upstream servers may also be specified on the command line or in |
| 1115 | the configuration file. These server specifications optionally take a |
| 1116 | domain name which tells dnsmasq to use that server only to find names |
| 1117 | in that particular domain. |
| 1118 | .PP |
| 1119 | In order to configure dnsmasq to act as cache for the host on which it is running, put "nameserver 127.0.0.1" in |
| 1120 | .I /etc/resolv.conf |
| 1121 | to force local processes to send queries to |
| 1122 | dnsmasq. Then either specify the upstream servers directly to dnsmasq |
| 1123 | using |
| 1124 | .B \--server |
| 1125 | options or put their addresses real in another file, say |
| 1126 | .I /etc/resolv.dnsmasq |
| 1127 | and run dnsmasq with the |
| 1128 | .B \-r /etc/resolv.dnsmasq |
| 1129 | option. This second technique allows for dynamic update of the server |
| 1130 | addresses by PPP or DHCP. |
| 1131 | .PP |
| 1132 | Addresses in /etc/hosts will "shadow" different addresses for the same |
| 1133 | names in the upstream DNS, so "mycompany.com 1.2.3.4" in /etc/hosts will ensure that |
| 1134 | queries for "mycompany.com" always return 1.2.3.4 even if queries in |
| 1135 | the upstream DNS would otherwise return a different address. There is |
| 1136 | one exception to this: if the upstream DNS contains a CNAME which |
| 1137 | points to a shadowed name, then looking up the CNAME through dnsmasq |
| 1138 | will result in the unshadowed address associated with the target of |
| 1139 | the CNAME. To work around this, add the CNAME to /etc/hosts so that |
| 1140 | the CNAME is shadowed too. |
| 1141 | |
| 1142 | .PP |
| 1143 | The network-id system works as follows: For each DHCP request, dnsmasq |
| 1144 | collects a set of valid network-id tags, one from the |
| 1145 | .B dhcp-range |
| 1146 | used to allocate the address, one from any matching |
| 1147 | .B dhcp-host |
| 1148 | (and "known" if a dhcp-host matches) |
| 1149 | the tag "bootp" for BOOTP requests, a tag whose name is the |
| 1150 | name if the interface on which the request arrived, |
| 1151 | and possibly many from matching vendor classes and user |
| 1152 | classes sent by the DHCP client. Any |
| 1153 | .B dhcp-option |
| 1154 | which has network-id tags will be used in preference to an untagged |
| 1155 | .B dhcp-option, |
| 1156 | provided that _all_ the tags match somewhere in the |
| 1157 | set collected as described above. The prefix '#' on a tag means 'not' |
| 1158 | so --dhcp=option=#purple,3,1.2.3.4 sends the option when the |
| 1159 | network-id tag purple is not in the set of valid tags. |
| 1160 | .PP |
| 1161 | If the network-id in a |
| 1162 | .B dhcp-range |
| 1163 | is prefixed with 'net:' then its meaning changes from setting a |
| 1164 | tag to matching it. Thus if there is more than dhcp-range on a subnet, |
| 1165 | and one is tagged with a network-id which is set (for instance |
| 1166 | from a vendorclass option) then hosts which set the netid tag will be |
| 1167 | allocated addresses in the tagged range. |
| 1168 | .PP |
| 1169 | The DHCP server in dnsmasq will function as a BOOTP server also, |
| 1170 | provided that the MAC address and IP address for clients are given, |
| 1171 | either using |
| 1172 | .B dhcp-host |
| 1173 | configurations or in |
| 1174 | .I /etc/ethers |
| 1175 | , and a |
| 1176 | .B dhcp-range |
| 1177 | configuration option is present to activate the DHCP server |
| 1178 | on a particular network. (Setting --bootp-dynamic removes the need for |
| 1179 | static address mappings.) The filename |
| 1180 | parameter in a BOOTP request is matched against netids in |
| 1181 | .B dhcp-option |
| 1182 | configurations, as is the tag "bootp", allowing some control over the options returned to |
| 1183 | different classes of hosts. |
| 1184 | |
| 1185 | .SH EXIT CODES |
| 1186 | .PP |
| 1187 | 0 - Dnsmasq successfully forked into the background, or terminated |
| 1188 | normally if backgrounding is not enabled. |
| 1189 | .PP |
| 1190 | 1 - A problem with configuration was detected. |
| 1191 | .PP |
| 1192 | 2 - A problem with network access occurred (address in use, attempt |
| 1193 | to use privileged ports without permission). |
| 1194 | .PP |
| 1195 | 3 - A problem occurred with a filesystem operation (missing |
| 1196 | file/directory, permissions). |
| 1197 | .PP |
| 1198 | 4 - Memory allocation failure. |
| 1199 | .PP |
| 1200 | 5 - Other miscellaneous problem. |
| 1201 | .PP |
| 1202 | 11 or greater - a non zero return code was received from the |
| 1203 | lease-script process "init" call. The exit code from dnsmasq is the |
| 1204 | script's exit code with 10 added. |
| 1205 | |
| 1206 | .SH LIMITS |
| 1207 | The default values for resource limits in dnsmasq are generally |
| 1208 | conservative, and appropriate for embedded router type devices with |
| 1209 | slow processors and limited memory. On more capable hardware, it is |
| 1210 | possible to increase the limits, and handle many more clients. The |
| 1211 | following applies to dnsmasq-2.37: earlier versions did not scale as well. |
| 1212 | |
| 1213 | .PP |
| 1214 | Dnsmasq is capable of handling DNS and DHCP for at least a thousand |
| 1215 | clients. Clearly to do this the value of |
| 1216 | .B --dhcp-lease-max |
| 1217 | must be increased, |
| 1218 | and lease times should not be very short (less than one hour). The |
| 1219 | value of |
| 1220 | .B --dns-forward-max |
| 1221 | can be increased: start with it equal to |
| 1222 | the number of clients and increase if DNS seems slow. Note that DNS |
| 1223 | performance depends too on the performance of the upstream |
| 1224 | nameservers. The size of the DNS cache may be increased: the hard |
| 1225 | limit is 10000 names and the default (150) is very low. Sending |
| 1226 | SIGUSR1 to dnsmasq makes it log information which is useful for tuning |
| 1227 | the cache size. See the |
| 1228 | .B NOTES |
| 1229 | section for details. |
| 1230 | |
| 1231 | .PP |
| 1232 | The built-in TFTP server is capable of many simultaneous file |
| 1233 | transfers: the absolute limit is related to the number of file-handles |
| 1234 | allowed to a process and the ability of the select() system call to |
| 1235 | cope with large numbers of file handles. If the limit is set too high |
| 1236 | using |
| 1237 | .B --tftp-max |
| 1238 | it will be scaled down and the actual limit logged at |
| 1239 | start-up. Note that more transfers are possible when the same file is |
| 1240 | being sent than when each transfer sends a different file. |
| 1241 | |
| 1242 | .PP |
| 1243 | It is possible to use dnsmasq to block Web advertising by using a list |
| 1244 | of known banner-ad servers, all resolving to 127.0.0.1 or 0.0.0.0, in |
| 1245 | .B /etc/hosts |
| 1246 | or an additional hosts file. The list can be very long, |
| 1247 | dnsmasq has been tested successfully with one million names. That size |
| 1248 | file needs a 1GHz processor and about 60Mb of RAM. |
| 1249 | |
| 1250 | .SH INTERNATIONALISATION |
| 1251 | Dnsmasq can be compiled to support internationalisation. To do this, |
| 1252 | the make targets "all-i18n" and "install-i18n" should be used instead of |
| 1253 | the standard targets "all" and "install". When internationalisation |
| 1254 | is compiled in, dnsmasq will produce log messages in the local |
| 1255 | language and support internationalised domain names (IDN). Domain |
| 1256 | names in /etc/hosts, /etc/ethers and /etc/dnsmasq.conf which contain |
| 1257 | non-ASCII characters will be translated to the DNS-internal punycode |
| 1258 | representation. Note that |
| 1259 | dnsmasq determines both the language for messages and the assumed |
| 1260 | charset for configuration |
| 1261 | files from the LANG environment variable. This should be set to the system |
| 1262 | default value by the script which is responsible for starting |
| 1263 | dnsmasq. When editing the configuration files, be careful to do so |
| 1264 | using only the system-default locale and not user-specific one, since |
| 1265 | dnsmasq has no direct way of determining the charset in use, and must |
| 1266 | assume that it is the system default. |
| 1267 | |
| 1268 | .SH FILES |
| 1269 | .IR /etc/dnsmasq.conf |
| 1270 | |
| 1271 | .IR /usr/local/etc/dnsmasq.conf |
| 1272 | |
| 1273 | .IR /etc/resolv.conf |
| 1274 | |
| 1275 | .IR /etc/hosts |
| 1276 | |
| 1277 | .IR /etc/ethers |
| 1278 | |
| 1279 | .IR /var/lib/misc/dnsmasq.leases |
| 1280 | |
| 1281 | .IR /var/db/dnsmasq.leases |
| 1282 | |
| 1283 | .IR /var/run/dnsmasq.pid |
| 1284 | .SH SEE ALSO |
| 1285 | .BR hosts (5), |
| 1286 | .BR resolver (5) |
| 1287 | .SH AUTHOR |
| 1288 | This manual page was written by Simon Kelley <simon@thekelleys.org.uk>. |
| 1289 | |
| 1290 | |