dnsmasq: Direct import of version 2.51
Signed-off-by: San Mehat <san@google.com>
diff --git a/man/dnsmasq.8 b/man/dnsmasq.8
new file mode 100755
index 0000000..a5eac63
--- /dev/null
+++ b/man/dnsmasq.8
@@ -0,0 +1,1290 @@
+.TH DNSMASQ 8
+.SH NAME
+dnsmasq \- A lightweight DHCP and caching DNS server.
+.SH SYNOPSIS
+.B dnsmasq
+.I [OPTION]...
+.SH "DESCRIPTION"
+.BR dnsmasq
+is a lightweight DNS, TFTP and DHCP server. It is intended to provide
+coupled DNS and DHCP service to a LAN.
+.PP
+Dnsmasq accepts DNS queries and either answers them from a small, local,
+cache or forwards them to a real, recursive, DNS server. It loads the
+contents of /etc/hosts so that local hostnames
+which do not appear in the global DNS can be resolved and also answers
+DNS queries for DHCP configured hosts.
+.PP
+The dnsmasq DHCP server supports static address assignments and multiple
+networks. It automatically
+sends a sensible default set of DHCP options, and can be configured to
+send any desired set of DHCP options, including vendor-encapsulated
+options. It includes a secure, read-only,
+TFTP server to allow net/PXE boot of DHCP hosts and also supports BOOTP.
+.PP
+Dnsmasq
+supports IPv6 for DNS, but not DHCP.
+.SH OPTIONS
+Note that in general missing parameters are allowed and switch off
+functions, for instance "--pid-file" disables writing a PID file. On
+BSD, unless the GNU getopt library is linked, the long form of the
+options does not work on the command line; it is still recognised in
+the configuration file.
+.TP
+.B --test
+Read and syntax check configuration file(s). Exit with code 0 if all
+is OK, or a non-zero code otherwise. Do not start up dnsmasq.
+.TP
+.B \-h, --no-hosts
+Don't read the hostnames in /etc/hosts.
+.TP
+.B \-H, --addn-hosts=<file>
+Additional hosts file. Read the specified file as well as /etc/hosts. If -h is given, read
+only the specified file. This option may be repeated for more than one
+additional hosts file. If a directory is given, then read all the files contained in that directory.
+.TP
+.B \-E, --expand-hosts
+Add the domain to simple names (without a period) in /etc/hosts
+in the same way as for DHCP-derived names. Note that this does not
+apply to domain names in cnames, PTR records, TXT records etc.
+.TP
+.B \-T, --local-ttl=<time>
+When replying with information from /etc/hosts or the DHCP leases
+file dnsmasq by default sets the time-to-live field to zero, meaning
+that the requestor should not itself cache the information. This is
+the correct thing to do in almost all situations. This option allows a
+time-to-live (in seconds) to be given for these replies. This will
+reduce the load on the server at the expense of clients using stale
+data under some circumstances.
+.TP
+.B --neg-ttl=<time>
+Negative replies from upstream servers normally contain time-to-live
+information in SOA records which dnsmasq uses for caching. If the
+replies from upstream servers omit this information, dnsmasq does not
+cache the reply. This option gives a default value for time-to-live
+(in seconds) which dnsmasq uses to cache negative replies even in
+the absence of an SOA record.
+.TP
+.B \-k, --keep-in-foreground
+Do not go into the background at startup but otherwise run as
+normal. This is intended for use when dnsmasq is run under daemontools
+or launchd.
+.TP
+.B \-d, --no-daemon
+Debug mode: don't fork to the background, don't write a pid file,
+don't change user id, generate a complete cache dump on receipt on
+SIGUSR1, log to stderr as well as syslog, don't fork new processes
+to handle TCP queries.
+.TP
+.B \-q, --log-queries
+Log the results of DNS queries handled by dnsmasq. Enable a full cache dump on receipt of SIGUSR1.
+.TP
+.B \-8, --log-facility=<facility>
+Set the facility to which dnsmasq will send syslog entries, this
+defaults to DAEMON, and to LOCAL0 when debug mode is in operation. If
+the facility given contains at least one '/' character, it is taken to
+be a filename, and dnsmasq logs to the given file, instead of
+syslog. (Errors whilst reading configuration will still go to syslog,
+but all output from a successful startup, and all output whilst
+running, will go exclusively to the file.) When logging to a file,
+dnsmasq will close and reopen the file when it receives SIGUSR2. This
+allows the log file to be rotated without stopping dnsmasq.
+.TP
+.B --log-async[=<lines>]
+Enable asynchronous logging and optionally set the limit on the
+number of lines
+which will be queued by dnsmasq when writing to the syslog is slow.
+Dnsmasq can log asynchronously: this
+allows it to continue functioning without being blocked by syslog, and
+allows syslog to use dnsmasq for DNS queries without risking deadlock.
+If the queue of log-lines becomes full, dnsmasq will log the
+overflow, and the number of messages lost. The default queue length is
+5, a sane value would be 5-25, and a maximum limit of 100 is imposed.
+.TP
+.B \-x, --pid-file=<path>
+Specify an alternate path for dnsmasq to record its process-id in. Normally /var/run/dnsmasq.pid.
+.TP
+.B \-u, --user=<username>
+Specify the userid to which dnsmasq will change after startup. Dnsmasq must normally be started as root, but it will drop root
+privileges after startup by changing id to another user. Normally this user is "nobody" but that
+can be over-ridden with this switch.
+.TP
+.B \-g, --group=<groupname>
+Specify the group which dnsmasq will run
+as. The defaults to "dip", if available, to facilitate access to
+/etc/ppp/resolv.conf which is not normally world readable.
+.TP
+.B \-v, --version
+Print the version number.
+.TP
+.B \-p, --port=<port>
+Listen on <port> instead of the standard DNS port (53). Setting this
+to zero completely disables DNS function, leaving only DHCP and/or TFTP.
+.TP
+.B \-P, --edns-packet-max=<size>
+Specify the largest EDNS.0 UDP packet which is supported by the DNS
+forwarder. Defaults to 1280, which is the RFC2671-recommended maximum
+for ethernet.
+.TP
+.B \-Q, --query-port=<query_port>
+Send outbound DNS queries from, and listen for their replies on, the
+specific UDP port <query_port> instead of using random ports. NOTE
+that using this option will make dnsmasq less secure against DNS
+spoofing attacks but it may be faster and use less resources. Setting this option
+to zero makes dnsmasq use a single port allocated to it by the
+OS: this was the default behaviour in versions prior to 2.43.
+.TP
+.B --min-port=<port>
+Do not use ports less than that given as source for outbound DNS
+queries. Dnsmasq picks random ports as source for outbound queries:
+when this option is given, the ports used will always to larger
+than that specified. Useful for systems behind firewalls.
+.TP
+.B \-i, --interface=<interface name>
+Listen only on the specified interface(s). Dnsmasq automatically adds
+the loopback (local) interface to the list of interfaces to use when
+the
+.B \--interface
+option is used. If no
+.B \--interface
+or
+.B \--listen-address
+options are given dnsmasq listens on all available interfaces except any
+given in
+.B \--except-interface
+options. IP alias interfaces (eg "eth1:0") cannot be used with
+.B --interface
+or
+.B --except-interface
+options, use --listen-address instead.
+.TP
+.B \-I, --except-interface=<interface name>
+Do not listen on the specified interface. Note that the order of
+.B \--listen-address
+.B --interface
+and
+.B --except-interface
+options does not matter and that
+.B --except-interface
+options always override the others.
+.TP
+.B \-2, --no-dhcp-interface=<interface name>
+Do not provide DHCP or TFTP on the specified interface, but do provide DNS service.
+.TP
+.B \-a, --listen-address=<ipaddr>
+Listen on the given IP address(es). Both
+.B \--interface
+and
+.B \--listen-address
+options may be given, in which case the set of both interfaces and
+addresses is used. Note that if no
+.B \--interface
+option is given, but
+.B \--listen-address
+is, dnsmasq will not automatically listen on the loopback
+interface. To achieve this, its IP address, 127.0.0.1, must be
+explicitly given as a
+.B \--listen-address
+option.
+.TP
+.B \-z, --bind-interfaces
+On systems which support it, dnsmasq binds the wildcard address,
+even when it is listening on only some interfaces. It then discards
+requests that it shouldn't reply to. This has the advantage of
+working even when interfaces come and go and change address. This
+option forces dnsmasq to really bind only the interfaces it is
+listening on. About the only time when this is useful is when
+running another nameserver (or another instance of dnsmasq) on the
+same machine. Setting this option also enables multiple instances of
+dnsmasq which provide DHCP service to run in the same machine.
+.TP
+.B \-y, --localise-queries
+Return answers to DNS queries from /etc/hosts which depend on the interface over which the query was
+received. If a name in /etc/hosts has more than one address associated with
+it, and at least one of those addresses is on the same subnet as the
+interface to which the query was sent, then return only the
+address(es) on that subnet. This allows for a server to have multiple
+addresses in /etc/hosts corresponding to each of its interfaces, and
+hosts will get the correct address based on which network they are
+attached to. Currently this facility is limited to IPv4.
+.TP
+.B \-b, --bogus-priv
+Bogus private reverse lookups. All reverse lookups for private IP ranges (ie 192.168.x.x, etc)
+which are not found in /etc/hosts or the DHCP leases file are answered
+with "no such domain" rather than being forwarded upstream.
+.TP
+.B \-V, --alias=[<old-ip>]|[<start-ip>-<end-ip>],<new-ip>[,<mask>]
+Modify IPv4 addresses returned from upstream nameservers; old-ip is
+replaced by new-ip. If the optional mask is given then any address
+which matches the masked old-ip will be re-written. So, for instance
+.B --alias=1.2.3.0,6.7.8.0,255.255.255.0
+will map 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. This is what
+Cisco PIX routers call "DNS doctoring". If the old IP is given as
+range, then only addresses in the range, rather than a whole subnet,
+are re-written. So
+.B --alias=192.168.0.10-192.168.0.40,10.0.0.0,255.255.255.0
+maps 192.168.0.10->192.168.0.40 to 10.0.0.10->10.0.0.40
+.TP
+.B \-B, --bogus-nxdomain=<ipaddr>
+Transform replies which contain the IP address given into "No such
+domain" replies. This is intended to counteract a devious move made by
+Verisign in September 2003 when they started returning the address of
+an advertising web page in response to queries for unregistered names,
+instead of the correct NXDOMAIN response. This option tells dnsmasq to
+fake the correct response when it sees this behaviour. As at Sept 2003
+the IP address being returned by Verisign is 64.94.110.11
+.TP
+.B \-f, --filterwin2k
+Later versions of windows make periodic DNS requests which don't get sensible answers from
+the public DNS and can cause problems by triggering dial-on-demand links. This flag turns on an option
+to filter such requests. The requests blocked are for records of types SOA and SRV, and type ANY where the
+requested name has underscores, to catch LDAP requests.
+.TP
+.B \-r, --resolv-file=<file>
+Read the IP addresses of the upstream nameservers from <file>, instead of
+/etc/resolv.conf. For the format of this file see
+.BR resolv.conf (5)
+the only lines relevant to dnsmasq are nameserver ones. Dnsmasq can
+be told to poll more than one resolv.conf file, the first file name specified
+overrides the default, subsequent ones add to the list. This is only
+allowed when polling; the file with the currently latest modification
+time is the one used.
+.TP
+.B \-R, --no-resolv
+Don't read /etc/resolv.conf. Get upstream servers only from the command
+line or the dnsmasq configuration file.
+.TP
+.B \-1, --enable-dbus
+Allow dnsmasq configuration to be updated via DBus method calls. The
+configuration which can be changed is upstream DNS servers (and
+corresponding domains) and cache clear. Requires that dnsmasq has
+been built with DBus support.
+.TP
+.B \-o, --strict-order
+By default, dnsmasq will send queries to any of the upstream servers
+it knows about and tries to favour servers that are known to
+be up. Setting this flag forces dnsmasq to try each query with each
+server strictly in the order they appear in /etc/resolv.conf
+.TP
+.B --all-servers
+By default, when dnsmasq has more than one upstream server available,
+it will send queries to just one server. Setting this flag forces
+dnsmasq to send all queries to all available servers. The reply from
+the server which answers first will be returned to the original requestor.
+.TP
+.B --stop-dns-rebind
+Reject (and log) addresses from upstream nameservers which are in the
+private IP ranges. This blocks an attack where a browser behind a
+firewall is used to probe machines on the local network.
+.TP
+.B \-n, --no-poll
+Don't poll /etc/resolv.conf for changes.
+.TP
+.B --clear-on-reload
+Whenever /etc/resolv.conf is re-read, clear the DNS cache.
+This is useful when new nameservers may have different
+data than that held in cache.
+.TP
+.B \-D, --domain-needed
+Tells dnsmasq to never forward queries for plain names, without dots
+or domain parts, to upstream nameservers. If the name is not known
+from /etc/hosts or DHCP then a "not found" answer is returned.
+.TP
+.B \-S, --local, --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>][@<source-ip>|<interface>[#<port>]]
+Specify IP address of upstream servers directly. Setting this flag does
+not suppress reading of /etc/resolv.conf, use -R to do that. If one or
+more
+optional domains are given, that server is used only for those domains
+and they are queried only using the specified server. This is
+intended for private nameservers: if you have a nameserver on your
+network which deals with names of the form
+xxx.internal.thekelleys.org.uk at 192.168.1.1 then giving the flag
+.B -S /internal.thekelleys.org.uk/192.168.1.1
+will send all queries for
+internal machines to that nameserver, everything else will go to the
+servers in /etc/resolv.conf. An empty domain specification,
+.B //
+has the special meaning of "unqualified names only" ie names without any
+dots in them. A non-standard port may be specified as
+part of the IP
+address using a # character.
+More than one -S flag is allowed, with
+repeated domain or ipaddr parts as required.
+
+Also permitted is a -S
+flag which gives a domain but no IP address; this tells dnsmasq that
+a domain is local and it may answer queries from /etc/hosts or DHCP
+but should never forward queries on that domain to any upstream
+servers.
+.B local
+is a synonym for
+.B server
+to make configuration files clearer in this case.
+
+The optional string after the @ character tells
+dnsmasq how to set the source of the queries to this
+nameserver. It should be an ip-address, which should belong to the machine on which
+dnsmasq is running otherwise this server line will be logged and then
+ignored, or an interface name. If an interface name is given, then
+queries to the server will be forced via that interface; if an
+ip-address is given then the source address of the queries will be set
+to that address.
+The query-port flag is ignored for any servers which have a
+source address specified but the port may be specified directly as
+part of the source address. Forcing queries to an interface is not
+implemented on all platforms supported by dnsmasq.
+.TP
+.B \-A, --address=/<domain>/[domain/]<ipaddr>
+Specify an IP address to return for any host in the given domains.
+Queries in the domains are never forwarded and always replied to
+with the specified IP address which may be IPv4 or IPv6. To give
+both IPv4 and IPv6 addresses for a domain, use repeated -A flags.
+Note that /etc/hosts and DHCP leases override this for individual
+names. A common use of this is to redirect the entire doubleclick.net
+domain to some friendly local web server to avoid banner ads. The
+domain specification works in the same was as for --server, with the
+additional facility that /#/ matches any domain. Thus
+--address=/#/1.2.3.4 will always return 1.2.3.4 for any query not
+answered from /etc/hosts or DHCP and not sent to an upstream
+nameserver by a more specific --server directive.
+.TP
+.B \-m, --mx-host=<mx name>[[,<hostname>],<preference>]
+Return an MX record named <mx name> pointing to the given hostname (if
+given), or
+the host specified in the --mx-target switch
+or, if that switch is not given, the host on which dnsmasq
+is running. The default is useful for directing mail from systems on a LAN
+to a central server. The preference value is optional, and defaults to
+1 if not given. More than one MX record may be given for a host.
+.TP
+.B \-t, --mx-target=<hostname>
+Specify the default target for the MX record returned by dnsmasq. See
+--mx-host. If --mx-target is given, but not --mx-host, then dnsmasq
+returns a MX record containing the MX target for MX queries on the
+hostname of the machine on which dnsmasq is running.
+.TP
+.B \-e, --selfmx
+Return an MX record pointing to itself for each local
+machine. Local machines are those in /etc/hosts or with DHCP leases.
+.TP
+.B \-L, --localmx
+Return an MX record pointing to the host given by mx-target (or the
+machine on which dnsmasq is running) for each
+local machine. Local machines are those in /etc/hosts or with DHCP
+leases.
+.TP
+.B \-W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<priority>[,<weight>]]]]
+Return a SRV DNS record. See RFC2782 for details. If not supplied, the
+domain defaults to that given by
+.B --domain.
+The default for the target domain is empty, and the default for port
+is one and the defaults for
+weight and priority are zero. Be careful if transposing data from BIND
+zone files: the port, weight and priority numbers are in a different
+order. More than one SRV record for a given service/domain is allowed,
+all that match are returned.
+.TP
+.B \-Y, --txt-record=<name>[[,<text>],<text>]
+Return a TXT DNS record. The value of TXT record is a set of strings,
+so any number may be included, split by commas.
+.TP
+.B --ptr-record=<name>[,<target>]
+Return a PTR DNS record.
+.TP
+.B --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<regexp>[,<replacement>]
+Return an NAPTR DNS record, as specified in RFC3403.
+.TP
+.B --cname=<cname>,<target>
+Return a CNAME record which indicates that <cname> is really
+<target>. There are significant limitations on the target; it must be a
+DNS name which is known to dnsmasq from /etc/hosts (or additional
+hosts files) or from DHCP. If the target does not satisfy this
+criteria, the whole cname is ignored. The cname must be unique, but it
+is permissable to have more than one cname pointing to the same target.
+.TP
+.B --interface-name=<name>,<interface>
+Return a DNS record associating the name with the primary address on
+the given interface. This flag specifies an A record for the given
+name in the same way as an /etc/hosts line, except that the address is
+not constant, but taken from the given interface. If the interface is
+down, not configured or non-existent, an empty record is returned. The
+matching PTR record is also created, mapping the interface address to
+the name. More than one name may be associated with an interface
+address by repeating the flag; in that case the first instance is used
+for the reverse address-to-name mapping.
+.TP
+.B \-c, --cache-size=<cachesize>
+Set the size of dnsmasq's cache. The default is 150 names. Setting the cache size to zero disables caching.
+.TP
+.B \-N, --no-negcache
+Disable negative caching. Negative caching allows dnsmasq to remember
+"no such domain" answers from upstream nameservers and answer
+identical queries without forwarding them again.
+.TP
+.B \-0, --dns-forward-max=<queries>
+Set the maximum number of concurrent DNS queries. The default value is
+150, which should be fine for most setups. The only known situation
+where this needs to be increased is when using web-server log file
+resolvers, which can generate large numbers of concurrent queries.
+.TP
+.B \-F, --dhcp-range=[[net:]network-id,]<start-addr>,<end-addr>[[,<netmask>],<broadcast>][,<lease time>]
+Enable the DHCP server. Addresses will be given out from the range
+<start-addr> to <end-addr> and from statically defined addresses given
+in
+.B dhcp-host
+options. If the lease time is given, then leases
+will be given for that length of time. The lease time is in seconds,
+or minutes (eg 45m) or hours (eg 1h) or "infinite". If not given,
+the default lease time is one hour. The
+minimum lease time is two minutes. This
+option may be repeated, with different addresses, to enable DHCP
+service to more than one network. For directly connected networks (ie,
+networks on which the machine running dnsmasq has an interface) the
+netmask is optional. It is, however, required for networks which
+receive DHCP service via a relay agent. The broadcast address is
+always optional. It is always
+allowed to have more than one dhcp-range in a single subnet. The optional
+network-id is a alphanumeric label which marks this network so that
+dhcp options may be specified on a per-network basis.
+When it is prefixed with 'net:' then its meaning changes from setting
+a tag to matching it. Only one tag may be set, but more than one tag may be matched.
+The end address may be replaced by the keyword
+.B static
+which tells dnsmasq to enable DHCP for the network specified, but not
+to dynamically allocate IP addresses: only hosts which have static
+addresses given via
+.B dhcp-host
+or from /etc/ethers will be served. The end address may be replaced by
+the keyword
+.B proxy
+in which case dnsmasq will provide proxy-DHCP on the specified
+subnet. (See
+.B pxe-prompt
+and
+.B pxe-service
+for details.)
+.TP
+.B \-G, --dhcp-host=[<hwaddr>][,id:<client_id>|*][,net:<netid>][,<ipaddr>][,<hostname>][,<lease_time>][,ignore]
+Specify per host parameters for the DHCP server. This allows a machine
+with a particular hardware address to be always allocated the same
+hostname, IP address and lease time. A hostname specified like this
+overrides any supplied by the DHCP client on the machine. It is also
+allowable to ommit the hardware address and include the hostname, in
+which case the IP address and lease times will apply to any machine
+claiming that name. For example
+.B --dhcp-host=00:20:e0:3b:13:af,wap,infinite
+tells dnsmasq to give
+the machine with hardware address 00:20:e0:3b:13:af the name wap, and
+an infinite DHCP lease.
+.B --dhcp-host=lap,192.168.0.199
+tells
+dnsmasq to always allocate the machine lap the IP address
+192.168.0.199. Addresses allocated like this are not constrained to be
+in the range given by the --dhcp-range option, but they must be on the
+network being served by the DHCP server. It is allowed to use client identifiers rather than
+hardware addresses to identify hosts by prefixing with 'id:'. Thus:
+.B --dhcp-host=id:01:02:03:04,.....
+refers to the host with client identifier 01:02:03:04. It is also
+allowed to specify the client ID as text, like this:
+.B --dhcp-host=id:clientidastext,.....
+
+The special option id:* means "ignore any client-id
+and use MAC addresses only." This is useful when a client presents a client-id sometimes
+but not others.
+
+If a name appears in /etc/hosts, the associated address can be
+allocated to a DHCP lease, but only if a
+.B --dhcp-host
+option specifying the name also exists. The special keyword "ignore"
+tells dnsmasq to never offer a DHCP lease to a machine. The machine
+can be specified by hardware address, client ID or hostname, for
+instance
+.B --dhcp-host=00:20:e0:3b:13:af,ignore
+This is
+useful when there is another DHCP server on the network which should
+be used by some machines.
+
+The net:<network-id> sets the network-id tag
+whenever this dhcp-host directive is in use. This can be used to
+selectively send DHCP options just for this host. When a host matches any
+dhcp-host directive (or one implied by /etc/ethers) then the special
+network-id tag "known" is set. This allows dnsmasq to be configured to
+ignore requests from unknown machines using
+.B --dhcp-ignore=#known
+Ethernet addresses (but not client-ids) may have
+wildcard bytes, so for example
+.B --dhcp-host=00:20:e0:3b:13:*,ignore
+will cause dnsmasq to ignore a range of hardware addresses. Note that
+the "*" will need to be escaped or quoted on a command line, but not
+in the configuration file.
+
+Hardware addresses normally match any
+network (ARP) type, but it is possible to restrict them to a single
+ARP type by preceding them with the ARP-type (in HEX) and "-". so
+.B --dhcp-host=06-00:20:e0:3b:13:af,1.2.3.4
+will only match a
+Token-Ring hardware address, since the ARP-address type for token ring
+is 6.
+
+As a special case, it is possible to include more than one
+hardware address. eg:
+.B --dhcp-host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2
+This allows an IP address to be associated with
+multiple hardware addresses, and gives dnsmasq permission to abandon a
+DHCP lease to one of the hardware addresses when another one asks for
+a lease. Beware that this is a dangerous thing to do, it will only
+work reliably if only one of the hardware addresses is active at any
+time and there is no way for dnsmasq to enforce this. It is, for instance,
+useful to allocate a stable IP address to a laptop which
+has both wired and wireless interfaces.
+.TP
+.B --dhcp-hostsfile=<file>
+Read DHCP host information from the specified file. The file contains
+information about one host per line. The format of a line is the same
+as text to the right of '=' in --dhcp-host. The advantage of storing DHCP host information
+in this file is that it can be changed without re-starting dnsmasq:
+the file will be re-read when dnsmasq receives SIGHUP.
+.TP
+.B --dhcp-optsfile=<file>
+Read DHCP option information from the specified file. The advantage of
+using this option is the same as for --dhcp-hostsfile: the
+dhcp-optsfile will be re-read when dnsmasq receives SIGHUP. Note that
+it is possible to encode the information in a
+.B --dhcp-boot
+flag as DHCP options, using the options names bootfile-name,
+server-ip-address and tftp-server. This allows these to be included
+in a dhcp-optsfile.
+.TP
+.B \-Z, --read-ethers
+Read /etc/ethers for information about hosts for the DHCP server. The
+format of /etc/ethers is a hardware address, followed by either a
+hostname or dotted-quad IP address. When read by dnsmasq these lines
+have exactly the same effect as
+.B --dhcp-host
+options containing the same information. /etc/ethers is re-read when
+dnsmasq receives SIGHUP.
+.TP
+.B \-O, --dhcp-option=[<network-id>,[<network-id>,]][encap:<opt>,][vendor:[<vendor-class>],][<opt>|option:<opt-name>],[<value>[,<value>]]
+Specify different or extra options to DHCP clients. By default,
+dnsmasq sends some standard options to DHCP clients, the netmask and
+broadcast address are set to the same as the host running dnsmasq, and
+the DNS server and default route are set to the address of the machine
+running dnsmasq. If the domain name option has been set, that is sent.
+This configuration allows these defaults to be overridden,
+or other options specified. The option, to be sent may be given as a
+decimal number or as "option:<option-name>" The option numbers are
+specified in RFC2132 and subsequent RFCs. The set of option-names
+known by dnsmasq can be discovered by running "dnsmasq --help dhcp".
+For example, to set the default route option to
+192.168.4.4, do
+.B --dhcp-option=3,192.168.4.4
+or
+.B --dhcp-option = option:router, 192.168.4.4
+and to set the time-server address to 192.168.0.4, do
+.B --dhcp-option = 42,192.168.0.4
+or
+.B --dhcp-option = option:ntp-server, 192.168.0.4
+The special address 0.0.0.0 is taken to mean "the address of the
+machine running dnsmasq". Data types allowed are comma separated
+dotted-quad IP addresses, a decimal number, colon-separated hex digits
+and a text string. If the optional network-ids are given then
+this option is only sent when all the network-ids are matched.
+
+Special processing is done on a text argument for option 119, to
+conform with RFC 3397. Text or dotted-quad IP addresses as arguments
+to option 120 are handled as per RFC 3361. Dotted-quad IP addresses
+which are followed by a slash and then a netmask size are encoded as
+described in RFC 3442.
+
+Be careful: no checking is done that the correct type of data for the
+option number is sent, it is quite possible to
+persuade dnsmasq to generate illegal DHCP packets with injudicious use
+of this flag. When the value is a decimal number, dnsmasq must determine how
+large the data item is. It does this by examining the option number and/or the
+value, but can be overridden by appending a single letter flag as follows:
+b = one byte, s = two bytes, i = four bytes. This is mainly useful with
+encapsulated vendor class options (see below) where dnsmasq cannot
+determine data size from the option number. Option data which
+consists solely of periods and digits will be interpreted by dnsmasq
+as an IP address, and inserted into an option as such. To force a
+literal string, use quotes. For instance when using option 66 to send
+a literal IP address as TFTP server name, it is necessary to do
+.B --dhcp-option=66,"1.2.3.4"
+
+Encapsulated Vendor-class options may also be specified using
+--dhcp-option: for instance
+.B --dhcp-option=vendor:PXEClient,1,0.0.0.0
+sends the encapsulated vendor
+class-specific option "mftp-address=0.0.0.0" to any client whose
+vendor-class matches "PXEClient". The vendor-class matching is
+substring based (see --dhcp-vendorclass for details). If a
+vendor-class option (number 60) is sent by dnsmasq, then that is used
+for selecting encapsulated options in preference to any sent by the
+client. It is
+possible to omit the vendorclass completely;
+.B --dhcp-option=vendor:,1,0.0.0.0
+in which case the encapsulated option is always sent.
+
+Options may be encapsulated within other options: for instance
+.B --dhcp-option=encap:175, 190, "iscsi-client0"
+will send option 175, within which is the option 190. If multiple
+options are given which are encapsulated with the same option number
+then they will be correctly combined into one encapsulated option.
+encap: and vendor: are may not both be set in the same dhcp-option.
+
+The address 0.0.0.0 is not treated specially in
+encapsulated options.
+.TP
+.B --dhcp-option-force=[<network-id>,[<network-id>,]][encap:<opt>,][vendor:[<vendor-class>],]<opt>,[<value>[,<value>]]
+This works in exactly the same way as
+.B --dhcp-option
+except that the option will always be sent, even if the client does
+not ask for it in the parameter request list. This is sometimes
+needed, for example when sending options to PXELinux.
+.TP
+.B --dhcp-no-override
+Disable re-use of the DHCP servername and filename fields as extra
+option space. If it can, dnsmasq moves the boot server and filename
+information (from dhcp-boot) out of their dedicated fields into
+DHCP options. This make extra space available in the DHCP packet for
+options but can, rarely, confuse old or broken clients. This flag
+forces "simple and safe" behaviour to avoid problems in such a case.
+.TP
+.B \-U, --dhcp-vendorclass=<network-id>,<vendor-class>
+Map from a vendor-class string to a network id tag. Most DHCP clients provide a
+"vendor class" which represents, in some sense, the type of host. This option
+maps vendor classes to tags, so that DHCP options may be selectively delivered
+to different classes of hosts. For example
+.B dhcp-vendorclass=printers,Hewlett-Packard JetDirect
+will allow options to be set only for HP printers like so:
+.B --dhcp-option=printers,3,192.168.4.4
+The vendor-class string is
+substring matched against the vendor-class supplied by the client, to
+allow fuzzy matching.
+.TP
+.B \-j, --dhcp-userclass=<network-id>,<user-class>
+Map from a user-class string to a network id tag (with substring
+matching, like vendor classes). Most DHCP clients provide a
+"user class" which is configurable. This option
+maps user classes to tags, so that DHCP options may be selectively delivered
+to different classes of hosts. It is possible, for instance to use
+this to set a different printer server for hosts in the class
+"accounts" than for hosts in the class "engineering".
+.TP
+.B \-4, --dhcp-mac=<network-id>,<MAC address>
+Map from a MAC address to a network-id tag. The MAC address may include
+wildcards. For example
+.B --dhcp-mac=3com,01:34:23:*:*:*
+will set the tag "3com" for any host whose MAC address matches the pattern.
+.TP
+.B --dhcp-circuitid=<network-id>,<circuit-id>, --dhcp-remoteid=<network-id>,<remote-id>
+Map from RFC3046 relay agent options to network-id tags. This data may
+be provided by DHCP relay agents. The circuit-id or remote-id is
+normally given as colon-separated hex, but is also allowed to be a
+simple string. If an exact match is achieved between the circuit or
+agent ID and one provided by a relay agent, the network-id tag is set.
+.TP
+.B --dhcp-subscrid=<network-id>,<subscriber-id>
+Map from RFC3993 subscriber-id relay agent options to network-id tags.
+.TP
+.B --dhcp-match=<network-id>,<option number>|option:<option name>[,<value>]
+Without a value, set the network-id tag if the client sends a DHCP
+option of the given number or name. When a value is given, set the tag only if
+the option is sent and matches the value. The value may be of the form
+"01:ff:*:02" in which case the value must match (apart from widcards)
+but the option sent may have unmatched data past the end of the
+value. The value may also be of the same form as in
+.B dhcp-option
+in which case the option sent is treated as an array, and one element
+must match, so
+
+--dhcp-match=efi-ia32,option:client-arch,6
+
+will set the tag "efi-ia32" if the the number 6 appears in the list of
+architectures sent by the client in option 93. (See RFC 4578 for
+details.) If the value is a string, substring matching is used.
+.TP
+.B \-J, --dhcp-ignore=<network-id>[,<network-id>]
+When all the given network-ids match the set of network-ids derived
+from the net, host, vendor and user classes, ignore the host and do
+not allocate it a DHCP lease.
+.TP
+.B --dhcp-ignore-names[=<network-id>[,<network-id>]]
+When all the given network-ids match the set of network-ids derived
+from the net, host, vendor and user classes, ignore any hostname
+provided by the host. Note that, unlike dhcp-ignore, it is permissible
+to supply no netid tags, in which case DHCP-client supplied hostnames
+are always ignored, and DHCP hosts are added to the DNS using only
+dhcp-host configuration in dnsmasq and the contents of /etc/hosts and
+/etc/ethers.
+.TP
+.B --dhcp-broadcast=<network-id>[,<network-id>]
+When all the given network-ids match the set of network-ids derived
+from the net, host, vendor and user classes, always use broadcast to
+communicate with the host when it is unconfigured. Most DHCP clients which
+need broadcast replies set a flag in their requests so that this
+happens automatically, some old BOOTP clients do not.
+.TP
+.B \-M, --dhcp-boot=[net:<network-id>,]<filename>,[<servername>[,<server address>]]
+Set BOOTP options to be returned by the DHCP server. Server name and
+address are optional: if not provided, the name is left empty, and the
+address set to the address of the machine running dnsmasq. If dnsmasq
+is providing a TFTP service (see
+.B --enable-tftp
+) then only the filename is required here to enable network booting.
+If the optional network-id(s) are given,
+they must match for this configuration to be sent. Note that
+network-ids are prefixed by "net:" to distinguish them.
+.TP
+.B --pxe-service=[net:<network-id>,]<CSA>,<menu text>,<basename>|<bootservicetype>[,<server address>]
+Most uses of PXE boot-ROMS simply allow the PXE
+system to obtain an IP address and then download the file specified by
+.B dhcp-boot
+and execute it. However the PXE system is capable of more complex
+functions when supported by a suitable DHCP server.
+
+This specifies a boot option which may appear in a PXE boot menu. <CSA> is
+client system type, only services of the correct type will appear in a
+menu. The known types are x86PC, PC98, IA64_EFI, Alpha, Arc_x86,
+Intel_Lean_Client, IA32_EFI, BC_EFI, Xscale_EFI and X86-64_EFI; an
+integer may be used for other types. The
+parameter after the menu text may be a file name, in which case dnsmasq acts as a
+boot server and directs the PXE client to download the file by TFTP,
+either from itself (
+.B enable-tftp
+must be set for this to work) or another TFTP server if the final IP
+address is given.
+Note that the "layer"
+suffix (normally ".0") is supplied by PXE, and should not be added to
+the basename. If an integer boot service type, rather than a basename
+is given, then the PXE client will search for a
+suitable boot service for that type on the network. This search may be done
+by multicast or broadcast, or direct to a server if its IP address is provided. A boot service
+type of 0 is special, and will abort the net boot procedure and
+continue booting from local media.
+.TP
+.B --pxe-prompt=[net:<network-id>,]<prompt>[,<timeout>]
+Setting this provides a prompt to be displayed after PXE boot. If the
+timeout is given then after the
+timeout has elapsed with no keyboard input, the first available menu
+option will be automatically executed. If the timeout is zero then the first available menu
+item will be executed immediately. If
+.B pxe-prompt
+is ommitted the system will wait for user input if there are multiple
+items in the menu, but boot immediately if
+there is only one. See
+.B pxe-service
+for details of menu items.
+
+Dnsmasq supports PXE "proxy-DHCP", in this case another DHCP server on
+the network is responsible for allocating IP addresses, and dnsmasq
+simply provides the information given in
+.B pxe-prompt
+and
+.B pxe-service
+to allow netbooting. This mode is enabled using the
+.B proxy
+keyword in
+.B dhcp-range.
+.TP
+.B \-X, --dhcp-lease-max=<number>
+Limits dnsmasq to the specified maximum number of DHCP leases. The
+default is 150. This limit is to prevent DoS attacks from hosts which
+create thousands of leases and use lots of memory in the dnsmasq
+process.
+.TP
+.B \-K, --dhcp-authoritative
+Should be set when dnsmasq is definitely the only DHCP server on a network.
+It changes the behaviour from strict RFC compliance so that DHCP requests on
+unknown leases from unknown hosts are not ignored. This allows new hosts
+to get a lease without a tedious timeout under all circumstances. It also
+allows dnsmasq to rebuild its lease database without each client needing to
+reacquire a lease, if the database is lost.
+.TP
+.B --dhcp-alternate-port[=<server port>[,<client port>]]
+Change the ports used for DHCP from the default. If this option is
+given alone, without arguments, it changes the ports used for DHCP
+from 67 and 68 to 1067 and 1068. If a single argument is given, that
+port number is used for the server and the port number plus one used
+for the client. Finally, two port numbers allows arbitrary
+specification of both server and client ports for DHCP.
+.TP
+.B \-3, --bootp-dynamic[=<network-id>[,<network-id>]]
+Enable dynamic allocation of IP addresses to BOOTP clients. Use this
+with care, since each address allocated to a BOOTP client is leased
+forever, and therefore becomes permanently unavailable for re-use by
+other hosts. if this is given without tags, then it unconditionally
+enables dynamic allocation. With tags, only when the tags are all
+set. It may be repeated with different tag sets.
+.TP
+.B \-5, --no-ping
+By default, the DHCP server will attempt to ensure that an address in
+not in use before allocating it to a host. It does this by sending an
+ICMP echo request (aka "ping") to the address in question. If it gets
+a reply, then the address must already be in use, and another is
+tried. This flag disables this check. Use with caution.
+.TP
+.B --log-dhcp
+Extra logging for DHCP: log all the options sent to DHCP clients and
+the netid tags used to determine them.
+.TP
+.B \-l, --dhcp-leasefile=<path>
+Use the specified file to store DHCP lease information.
+.TP
+.B \-6 --dhcp-script=<path>
+Whenever a new DHCP lease is created, or an old one destroyed, the
+executable specified by this option is run. The arguments to the process
+are "add", "old" or "del", the MAC
+address of the host, the IP address, and the hostname,
+if known. "add" means a lease has been created, "del" means it has
+been destroyed, "old" is a notification of an existing lease when
+dnsmasq starts or a change to MAC address or hostname of an existing
+lease (also, lease length or expiry and client-id, if leasefile-ro is set).
+If the MAC address is from a network type other than ethernet,
+it will have the network type prepended, eg "06-01:23:45:67:89:ab" for
+token ring. The process is run as root (assuming that dnsmasq was originally run as
+root) even if dnsmasq is configured to change UID to an unprivileged user.
+The environment is inherited from the invoker of dnsmasq, and if the
+host provided a client-id, this is stored in the environment variable
+DNSMASQ_CLIENT_ID. If the fully-qualified domain name of the host is
+known, the domain part is stored in DNSMASQ_DOMAIN.
+If the client provides vendor-class, hostname or user-class,
+ these are provided in DNSMASQ_VENDOR_CLASS
+DNSMASQ_SUPPLIED_HOSTNAME and
+DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn variables, but only for
+"add" actions or "old" actions when a host resumes an existing lease,
+since these data are not held in dnsmasq's lease
+database. If dnsmasq was compiled with HAVE_BROKEN_RTC, then
+the length of the lease (in seconds) is stored in
+DNSMASQ_LEASE_LENGTH, otherwise the time of lease expiry is stored in
+DNSMASQ_LEASE_EXPIRES. The number of seconds until lease expiry is
+always stored in DNSMASQ_TIME_REMAINING.
+If a lease used to have a hostname, which is
+removed, an "old" event is generated with the new state of the lease,
+ie no name, and the former name is provided in the environment
+variable DNSMASQ_OLD_HOSTNAME. DNSMASQ_INTERFACE stores the name of
+the interface on which the request arrived; this is not set for "old"
+actions when dnsmasq restarts. DNSMASQ_RELAY_ADDRESS is set if the client
+used a DHCP relay to contact dnsmasq and the IP address of the relay is known.
+All file descriptors are
+closed except stdin, stdout and stderr which are open to /dev/null
+(except in debug mode).
+The script is not invoked concurrently: if subsequent lease
+changes occur, the script is not invoked again until any existing
+invocation exits. At dnsmasq startup, the script will be invoked for
+all existing leases as they are read from the lease file. Expired
+leases will be called with "del" and others with "old". <path>
+must be an absolute pathname, no PATH search occurs. When dnsmasq
+receives a HUP signal, the script will be invoked for existing leases
+with an "old " event.
+.TP
+.B --dhcp-scriptuser
+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.
+.TP
+.B \-9, --leasefile-ro
+Completely suppress use of the lease database file. The file will not
+be created, read, or written. Change the way the lease-change
+script (if one is provided) is called, so that the lease database may
+be maintained in external storage by the script. In addition to the
+invocations given in
+.B --dhcp-script
+the lease-change script is called once, at dnsmasq startup, with the
+single argument "init". When called like this the script should write
+the saved state of the lease database, in dnsmasq leasefile format, to
+stdout and exit with zero exit code. Setting this
+option also forces the leasechange script to be called on changes
+to the client-id and lease length and expiry time.
+.TP
+.B --bridge-interface=<interface>,<alias>[,<alias>]
+Treat DHCP request packets arriving at any of the <alias> interfaces
+as if they had arrived at <interface>. This option is necessary when
+using "old style" bridging on BSD platforms, since
+packets arrive at tap interfaces which don't have an IP address.
+.TP
+.B \-s, --domain=<domain>[,<address range>]
+Specifies DNS domains for the DHCP server. Domains may be be given
+unconditionally (without the IP range) or for limited IP ranges. This has two effects;
+firstly it causes the DHCP server to return the domain to any hosts
+which request it, and secondly it sets the domain which it is legal
+for DHCP-configured hosts to claim. The intention is to constrain
+hostnames so that an untrusted host on the LAN cannot advertise
+its name via dhcp as e.g. "microsoft.com" and capture traffic not
+meant for it. If no domain suffix is specified, then any DHCP
+hostname with a domain part (ie with a period) will be disallowed
+and logged. If suffix is specified, then hostnames with a domain
+part are allowed, provided the domain part matches the suffix. In
+addition, when a suffix is set then hostnames without a domain
+part have the suffix added as an optional domain part. Eg on my network I can set
+.B --domain=thekelleys.org.uk
+and have a machine whose DHCP hostname is "laptop". The IP address for that machine is available from
+.B dnsmasq
+both as "laptop" and "laptop.thekelleys.org.uk". If the domain is
+given as "#" then the domain is read from the first "search" directive
+in /etc/resolv.conf (or equivalent). The address range can be of the form
+<ip address>,<ip address> or <ip address>/<netmask> or just a single
+<ip address>. See
+.B --dhcp-fqdn
+which can change the behaviour of dnsmasq with domains.
+.TP
+.B --dhcp-fqdn
+In the default mode, dnsmasq inserts the unqualified names of
+DHCP clients into the DNS. For this reason, the names must be unique,
+even if two clients which have the same name are in different
+domains. If a second DHCP client appears which has the same name as an
+existing client, the name is transfered to the new client. If
+.B --dhcp-fqdn
+is set, this behaviour changes: the unqualified name is no longer
+put in the DNS, only the qualified name. Two DHCP clients with the
+same name may both keep the name, provided that the domain part is
+different (ie the fully qualified names differ.) To ensure that all
+names have a domain part, there must be at least
+.B --domain
+without an address specified when
+.B --dhcp-fqdn
+is set.
+.TP
+.B --enable-tftp
+Enable the TFTP server function. This is deliberately limited to that
+needed to net-boot a client. Only reading is allowed; the tsize and
+blksize extensions are supported (tsize is only supported in octet mode).
+.TP
+.B --tftp-root=<directory>
+Look for files to transfer using TFTP relative to the given
+directory. When this is set, TFTP paths which include ".." are
+rejected, to stop clients getting outside the specified root.
+Absolute paths (starting with /) are allowed, but they must be within
+the tftp-root.
+.TP
+.B --tftp-unique-root
+Add the IP address of the TFTP client as a path component on the end
+of the TFTP-root (in standard dotted-quad format). Only valid if a
+tftp-root is set and the directory exists. For instance, if tftp-root is "/tftp" and client
+1.2.3.4 requests file "myfile" then the effective path will be
+"/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4 exists or /tftp/myfile otherwise.
+.TP
+.B --tftp-secure
+Enable TFTP secure mode: without this, any file which is readable by
+the dnsmasq process under normal unix access-control rules is
+available via TFTP. When the --tftp-secure flag is given, only files
+owned by the user running the dnsmasq process are accessible. If
+dnsmasq is being run as root, different rules apply: --tftp-secure
+has no effect, but only files which have the world-readable bit set
+are accessible. It is not recommended to run dnsmasq as root with TFTP
+enabled, and certainly not without specifying --tftp-root. Doing so
+can expose any world-readable file on the server to any host on the net.
+.TP
+.B --tftp-max=<connections>
+Set the maximum number of concurrent TFTP connections allowed. This
+defaults to 50. When serving a large number of TFTP connections,
+per-process file descriptor limits may be encountered. Dnsmasq needs
+one file descriptor for each concurrent TFTP connection and one
+file descriptor per unique file (plus a few others). So serving the
+same file simultaneously to n clients will use require about n + 10 file
+descriptors, serving different files simultaneously to n clients will
+require about (2*n) + 10 descriptors. If
+.B --tftp-port-range
+is given, that can affect the number of concurrent connections.
+.TP
+.B --tftp-no-blocksize
+Stop the TFTP server from negotiating the "blocksize" option with a
+client. Some buggy clients request this option but then behave badly
+when it is granted.
+.TP
+.B --tftp-port-range=<start>,<end>
+A TFTP server listens on a well-known port (69) for connection initiation,
+but it also uses a dynamically-allocated port for each
+connection. Normally these are allocated by the OS, but this option
+specifies a range of ports for use by TFTP transfers. This can be
+useful when TFTP has to traverse a firewall. The start of the range
+cannot be lower than 1025 unless dnsmasq is running as root. The number
+of concurrent TFTP connections is limited by the size of the port range.
+.TP
+.B \-C, --conf-file=<file>
+Specify a different configuration file. The conf-file option is also allowed in
+configuration files, to include multiple configuration files.
+.TP
+.B \-7, --conf-dir=<directory>[,<file-extension>......]
+Read all the files in the given directory as configuration
+files. If extension(s) are given, any files which end in those
+extensions are skipped. Any files whose names end in ~ or start with . or start and end
+with # are always skipped. This flag may be given on the command
+line or in a configuration file.
+.SH CONFIG FILE
+At startup, dnsmasq reads
+.I /etc/dnsmasq.conf,
+if it exists. (On
+FreeBSD, the file is
+.I /usr/local/etc/dnsmasq.conf
+) (but see the
+.B \-C
+and
+.B \-7
+options.) The format of this
+file consists of one option per line, exactly as the long options detailed
+in the OPTIONS section but without the leading "--". Lines starting with # are comments and ignored. For
+options which may only be specified once, the configuration file overrides
+the command line. Quoting is allowed in a config file:
+between " quotes the special meanings of ,:. and # are removed and the
+following escapes are allowed: \\\\ \\" \\t \\e \\b \\r and \\n. The later
+corresponding to tab, escape, backspace, return and newline.
+.SH NOTES
+When it receives a SIGHUP,
+.B dnsmasq
+clears its cache and then re-loads
+.I /etc/hosts
+and
+.I /etc/ethers
+and any file given by --dhcp-hostsfile, --dhcp-optsfile or --addn-hosts.
+The dhcp lease change script is called for all
+existing DHCP leases. If
+.B
+--no-poll
+is set SIGHUP also re-reads
+.I /etc/resolv.conf.
+SIGHUP
+does NOT re-read the configuration file.
+.PP
+When it receives a SIGUSR1,
+.B dnsmasq
+writes statistics to the system log. It writes the cache size,
+the number of names which have had to removed from the cache before
+they expired in order to make room for new names and the total number
+of names that have been inserted into the cache. For each upstream
+server it gives the number of queries sent, and the number which
+resulted in an error. In
+.B --no-daemon
+mode or when full logging is enabled (-q), a complete dump of the
+contents of the cache is made.
+.PP
+When it receives SIGUSR2 and it is logging direct to a file (see
+.B --log-facility
+)
+.B dnsmasq
+will close and reopen the log file. Note that during this operation,
+dnsmasq will not be running as root. When it first creates the logfile
+dnsmasq changes the ownership of the file to the non-root user it will run
+as. Logrotate should be configured to create a new log file with
+the ownership which matches the existing one before sending SIGUSR2.
+If TCP DNS queries are in progress, the old logfile will remain open in
+child processes which are handling TCP queries and may continue to be
+written. There is a limit of 150 seconds, after which all existing TCP
+processes will have expired: for this reason, it is not wise to
+configure logfile compression for logfiles which have just been
+rotated. Using logrotate, the required options are
+.B create
+and
+.B delaycompress.
+
+
+.PP
+Dnsmasq is a DNS query forwarder: it it not capable of recursively
+answering arbitrary queries starting from the root servers but
+forwards such queries to a fully recursive upstream DNS server which is
+typically provided by an ISP. By default, dnsmasq reads
+.I /etc/resolv.conf
+to discover the IP
+addresses of the upstream nameservers it should use, since the
+information is typically stored there. Unless
+.B --no-poll
+is used,
+.B dnsmasq
+checks the modification time of
+.I /etc/resolv.conf
+(or equivalent if
+.B \--resolv-file
+is used) and re-reads it if it changes. This allows the DNS servers to
+be set dynamically by PPP or DHCP since both protocols provide the
+information.
+Absence of
+.I /etc/resolv.conf
+is not an error
+since it may not have been created before a PPP connection exists. Dnsmasq
+simply keeps checking in case
+.I /etc/resolv.conf
+is created at any
+time. Dnsmasq can be told to parse more than one resolv.conf
+file. This is useful on a laptop, where both PPP and DHCP may be used:
+dnsmasq can be set to poll both
+.I /etc/ppp/resolv.conf
+and
+.I /etc/dhcpc/resolv.conf
+and will use the contents of whichever changed
+last, giving automatic switching between DNS servers.
+.PP
+Upstream servers may also be specified on the command line or in
+the configuration file. These server specifications optionally take a
+domain name which tells dnsmasq to use that server only to find names
+in that particular domain.
+.PP
+In order to configure dnsmasq to act as cache for the host on which it is running, put "nameserver 127.0.0.1" in
+.I /etc/resolv.conf
+to force local processes to send queries to
+dnsmasq. Then either specify the upstream servers directly to dnsmasq
+using
+.B \--server
+options or put their addresses real in another file, say
+.I /etc/resolv.dnsmasq
+and run dnsmasq with the
+.B \-r /etc/resolv.dnsmasq
+option. This second technique allows for dynamic update of the server
+addresses by PPP or DHCP.
+.PP
+Addresses in /etc/hosts will "shadow" different addresses for the same
+names in the upstream DNS, so "mycompany.com 1.2.3.4" in /etc/hosts will ensure that
+queries for "mycompany.com" always return 1.2.3.4 even if queries in
+the upstream DNS would otherwise return a different address. There is
+one exception to this: if the upstream DNS contains a CNAME which
+points to a shadowed name, then looking up the CNAME through dnsmasq
+will result in the unshadowed address associated with the target of
+the CNAME. To work around this, add the CNAME to /etc/hosts so that
+the CNAME is shadowed too.
+
+.PP
+The network-id system works as follows: For each DHCP request, dnsmasq
+collects a set of valid network-id tags, one from the
+.B dhcp-range
+used to allocate the address, one from any matching
+.B dhcp-host
+(and "known" if a dhcp-host matches)
+the tag "bootp" for BOOTP requests, a tag whose name is the
+name if the interface on which the request arrived,
+and possibly many from matching vendor classes and user
+classes sent by the DHCP client. Any
+.B dhcp-option
+which has network-id tags will be used in preference to an untagged
+.B dhcp-option,
+provided that _all_ the tags match somewhere in the
+set collected as described above. The prefix '#' on a tag means 'not'
+so --dhcp=option=#purple,3,1.2.3.4 sends the option when the
+network-id tag purple is not in the set of valid tags.
+.PP
+If the network-id in a
+.B dhcp-range
+is prefixed with 'net:' then its meaning changes from setting a
+tag to matching it. Thus if there is more than dhcp-range on a subnet,
+and one is tagged with a network-id which is set (for instance
+from a vendorclass option) then hosts which set the netid tag will be
+allocated addresses in the tagged range.
+.PP
+The DHCP server in dnsmasq will function as a BOOTP server also,
+provided that the MAC address and IP address for clients are given,
+either using
+.B dhcp-host
+configurations or in
+.I /etc/ethers
+, and a
+.B dhcp-range
+configuration option is present to activate the DHCP server
+on a particular network. (Setting --bootp-dynamic removes the need for
+static address mappings.) The filename
+parameter in a BOOTP request is matched against netids in
+.B dhcp-option
+configurations, as is the tag "bootp", allowing some control over the options returned to
+different classes of hosts.
+
+.SH EXIT CODES
+.PP
+0 - Dnsmasq successfully forked into the background, or terminated
+normally if backgrounding is not enabled.
+.PP
+1 - A problem with configuration was detected.
+.PP
+2 - A problem with network access occurred (address in use, attempt
+to use privileged ports without permission).
+.PP
+3 - A problem occurred with a filesystem operation (missing
+file/directory, permissions).
+.PP
+4 - Memory allocation failure.
+.PP
+5 - Other miscellaneous problem.
+.PP
+11 or greater - a non zero return code was received from the
+lease-script process "init" call. The exit code from dnsmasq is the
+script's exit code with 10 added.
+
+.SH LIMITS
+The default values for resource limits in dnsmasq are generally
+conservative, and appropriate for embedded router type devices with
+slow processors and limited memory. On more capable hardware, it is
+possible to increase the limits, and handle many more clients. The
+following applies to dnsmasq-2.37: earlier versions did not scale as well.
+
+.PP
+Dnsmasq is capable of handling DNS and DHCP for at least a thousand
+clients. Clearly to do this the value of
+.B --dhcp-lease-max
+must be increased,
+and lease times should not be very short (less than one hour). The
+value of
+.B --dns-forward-max
+can be increased: start with it equal to
+the number of clients and increase if DNS seems slow. Note that DNS
+performance depends too on the performance of the upstream
+nameservers. The size of the DNS cache may be increased: the hard
+limit is 10000 names and the default (150) is very low. Sending
+SIGUSR1 to dnsmasq makes it log information which is useful for tuning
+the cache size. See the
+.B NOTES
+section for details.
+
+.PP
+The built-in TFTP server is capable of many simultaneous file
+transfers: the absolute limit is related to the number of file-handles
+allowed to a process and the ability of the select() system call to
+cope with large numbers of file handles. If the limit is set too high
+using
+.B --tftp-max
+it will be scaled down and the actual limit logged at
+start-up. Note that more transfers are possible when the same file is
+being sent than when each transfer sends a different file.
+
+.PP
+It is possible to use dnsmasq to block Web advertising by using a list
+of known banner-ad servers, all resolving to 127.0.0.1 or 0.0.0.0, in
+.B /etc/hosts
+or an additional hosts file. The list can be very long,
+dnsmasq has been tested successfully with one million names. That size
+file needs a 1GHz processor and about 60Mb of RAM.
+
+.SH INTERNATIONALISATION
+Dnsmasq can be compiled to support internationalisation. To do this,
+the make targets "all-i18n" and "install-i18n" should be used instead of
+the standard targets "all" and "install". When internationalisation
+is compiled in, dnsmasq will produce log messages in the local
+language and support internationalised domain names (IDN). Domain
+names in /etc/hosts, /etc/ethers and /etc/dnsmasq.conf which contain
+non-ASCII characters will be translated to the DNS-internal punycode
+representation. Note that
+dnsmasq determines both the language for messages and the assumed
+charset for configuration
+files from the LANG environment variable. This should be set to the system
+default value by the script which is responsible for starting
+dnsmasq. When editing the configuration files, be careful to do so
+using only the system-default locale and not user-specific one, since
+dnsmasq has no direct way of determining the charset in use, and must
+assume that it is the system default.
+
+.SH FILES
+.IR /etc/dnsmasq.conf
+
+.IR /usr/local/etc/dnsmasq.conf
+
+.IR /etc/resolv.conf
+
+.IR /etc/hosts
+
+.IR /etc/ethers
+
+.IR /var/lib/misc/dnsmasq.leases
+
+.IR /var/db/dnsmasq.leases
+
+.IR /var/run/dnsmasq.pid
+.SH SEE ALSO
+.BR hosts (5),
+.BR resolver (5)
+.SH AUTHOR
+This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.
+
+