import of dnsmasq-2.40.tar.gz

man/dnsmasq.8

@@ -6,8 +6,8 @@ dnsmasq \- A lightweight DHCP and caching DNS server.
 .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.
+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
@@ -73,7 +73,9 @@ the facilty 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.) 
+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
@@ -252,7 +254,7 @@ 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>[#<port>]]]
-Specify IP address of upstream severs directly. Setting this flag does
+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
@@ -364,8 +366,7 @@ Set the size of dnsmasq's cache. The default is 150 names. Setting the cache siz
 .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. This flag disables
-negative caching.
+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
@@ -441,9 +442,12 @@ instance
 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.
+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 
@@ -456,6 +460,13 @@ ARP type by preceding them with the ARP-type (in HEX) and "-". so
 will only match a
 Token-Ring hardware address, since the ARP-address type for token ring
 is 6.
+.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 \-Z, --read-ethers
 Read /etc/ethers for information about hosts for the DHCP server. The
@@ -463,7 +474,8 @@ 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.
+options containing the same information. /etc/ethers is re-read when 
+dnsmasq receives SIGHUP.
 .TP
 .B \-O, --dhcp-option=[<network-id>,[<network-id>,]][vendor:[<vendor-class>],][<opt>|option:<opt-name>],[<value>[,<value>]]
 Specify different or extra options to DHCP clients. By default,
@@ -577,7 +589,7 @@ 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-name[=<network-id>[,<network-id>]]
+.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 permissable
@@ -660,7 +672,9 @@ 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. If a lease used to have a hostname, which is
+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.
@@ -672,7 +686,9 @@ 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.
+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 \-9, --leasefile-ro
 Completely suppress use of the lease database file. The file will not
@@ -726,8 +742,15 @@ 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 readble by
+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
@@ -783,8 +806,12 @@ corresponding to tab, bell, backspace, return and newline.
 When it receives a SIGHUP, 
 .B dnsmasq 
 clears its cache and then re-loads 
-.I /etc/hosts and /etc/ethers.
-If 
+.I /etc/hosts
+and 
+.I /etc/ethers 
+and any file given by --dhcp-hostsfile.
+The dhcp lease change script is called for all
+existing DHCP leases. If 
 .B
 --no-poll
 is set SIGHUP also re-reads
@@ -799,7 +826,29 @@ 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. In 
 .B --no-daemon
-mode or when full logging is enabled (-q), a complete dump of the contents of the cache is made.
+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 exising 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
@@ -903,6 +952,27 @@ parameter in a BOOTP request is matched against netids in
 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 occured 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