Return to dnsmasq.8 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dnsmasq / man

dnsmasq 2.84

    1: .TH DNSMASQ 8 2020-04-05
    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, PXE, router advertisement 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. It can also act as the
   17: authoritative DNS server for one or more domains, allowing local names
   18: to appear in the global DNS. It can be configured to do DNSSEC
   19: validation.
   20: .PP
   21: The dnsmasq DHCP server supports static address assignments and multiple
   22: networks. It automatically
   23: sends a sensible default set of DHCP options, and can be configured to
   24: send any desired set of DHCP options, including vendor-encapsulated
   25: options. It includes a secure, read-only,
   26: TFTP server to allow net/PXE boot of DHCP hosts and also supports BOOTP. The PXE support is full featured, and includes a proxy mode which supplies PXE information to clients whilst DHCP address allocation is done by another server.
   27: .PP
   28: The dnsmasq DHCPv6 server provides the same set of features as the
   29: DHCPv4 server, and in addition, it includes router advertisements and
   30: a neat feature which allows naming for clients which use DHCPv4 and
   31: stateless autoconfiguration only for IPv6 configuration. There is support for doing address allocation (both DHCPv6 and RA) from subnets which are dynamically delegated via DHCPv6 prefix delegation.
   32: .PP
   33: Dnsmasq is coded with small embedded systems in mind. It aims for the smallest possible memory footprint compatible with the supported functions,  and allows unneeded functions to be omitted from the compiled binary.  
   34: .SH OPTIONS
   35: Note that in general missing parameters are allowed and switch off
   36: functions, for instance "--pid-file" disables writing a PID file. On
   37: BSD, unless the GNU getopt library is linked, the long form of the
   38: options does not work on the command line; it is still recognised in
   39: the configuration file.
   40: .TP
   41: .B --test
   42: Read and syntax check configuration file(s). Exit with code 0 if all
   43: is OK, or a non-zero code otherwise. Do not start up dnsmasq.
   44: .TP
   45: .B \-w, --help
   46: Display all command-line options. 
   47: .B --help dhcp 
   48: will display known DHCPv4 configuration options, and 
   49: .B --help dhcp6 
   50: will display DHCPv6 options.
   51: .TP
   52: .B \-h, --no-hosts
   53: Don't read the hostnames in /etc/hosts.
   54: .TP
   55: .B \-H, --addn-hosts=<file>
   56: Additional hosts file. Read the specified file as well as /etc/hosts. If \fB--no-hosts\fP is given, read
   57: only the specified file. This option may be repeated for more than one
   58: additional hosts file. If a directory is given, then read all the files contained in that directory. 
   59: .TP
   60: .B --hostsdir=<path>
   61: Read all the hosts files contained in the directory. New or changed files
   62: are read automatically. See \fB--dhcp-hostsdir\fP for details.
   63: .TP
   64: .B \-E, --expand-hosts
   65: Add the domain to simple names (without a period) in /etc/hosts
   66: in the same way as for DHCP-derived names. Note that this does not
   67: apply to domain names in cnames, PTR records, TXT records etc.
   68: .TP
   69: .B \-T, --local-ttl=<time>
   70: When replying with information from /etc/hosts or configuration or the DHCP leases
   71: file dnsmasq by default sets the time-to-live field to zero, meaning
   72: that the requester should not itself cache the information. This is
   73: the correct thing to do in almost all situations. This option allows a
   74: time-to-live (in seconds) to be given for these replies. This will
   75: reduce the load on the server at the expense of clients using stale
   76: data under some circumstances.
   77: .TP
   78: .B --dhcp-ttl=<time>
   79: As for \fB--local-ttl\fP, but affects only replies with information from DHCP leases. If both are given, \fB--dhcp-ttl\fP applies for DHCP information, and \fB--local-ttl\fP for others. Setting this to zero eliminates the effect of \fB--local-ttl\fP for DHCP.
   80: .TP
   81: .B --neg-ttl=<time>
   82: Negative replies from upstream servers normally contain time-to-live
   83: information in SOA records which dnsmasq uses for caching. If the
   84: replies from upstream servers omit this information, dnsmasq does not
   85: cache the reply. This option gives a default value for time-to-live
   86: (in seconds) which dnsmasq uses to cache negative replies even in 
   87: the absence of an SOA record. 
   88: .TP
   89: .B --max-ttl=<time>
   90: Set a maximum TTL value that will be handed out to clients. The specified
   91: maximum TTL will be given to clients instead of the true TTL value if it is 
   92: lower. The true TTL value is however kept in the cache to avoid flooding 
   93: the upstream DNS servers.
   94: .TP
   95: .B --max-cache-ttl=<time>
   96: Set a maximum TTL value for entries in the cache.
   97: .TP
   98: .B --min-cache-ttl=<time>
   99: Extend short TTL values to the time given when caching them. Note that
  100: artificially extending TTL values is in general a bad idea, do not do it 
  101: unless you have a good reason, and understand what you are doing. 
  102: Dnsmasq limits the value of this option to one hour, unless recompiled.
  103: .TP
  104: .B --auth-ttl=<time>
  105: Set the TTL value returned in answers from the authoritative server.
  106: .TP
  107: .B \-k, --keep-in-foreground
  108: Do not go into the background at startup but otherwise run as
  109: normal. This is intended for use when dnsmasq is run under daemontools
  110: or launchd.
  111: .TP
  112: .B \-d, --no-daemon
  113: Debug mode: don't fork to the background, don't write a pid file,
  114: don't change user id, generate a complete cache dump on receipt on
  115: SIGUSR1, log to stderr as well as syslog, don't fork new processes
  116: to handle TCP queries. Note that this option is for use in debugging
  117: only, to stop dnsmasq daemonising in production, use 
  118: .B --keep-in-foreground.
  119: .TP
  120: .B \-q, --log-queries
  121: Log the results of DNS queries handled by dnsmasq. Enable a full cache dump on receipt of SIGUSR1. If the argument "extra" is supplied, ie
  122: .B --log-queries=extra
  123: then the log has extra information at the start of each line.
  124: This consists of a serial number which ties together the log lines associated with an individual query, and the IP address of the requestor.
  125: .TP
  126: .B \-8, --log-facility=<facility>
  127: Set the facility to which dnsmasq will send syslog entries, this
  128: defaults to DAEMON, and to LOCAL0 when debug mode is in operation. If
  129: the facility given contains at least one '/' character, it is taken to
  130: be a filename, and dnsmasq logs to the given file, instead of
  131: syslog. If the facility is '-' then dnsmasq logs to stderr.
  132: (Errors whilst reading configuration will still go to syslog,
  133: but all output from a successful startup, and all output whilst
  134: running, will go exclusively to the file.) When logging to a file,
  135: dnsmasq will close and reopen the file when it receives SIGUSR2. This 
  136: allows the log file to be rotated without stopping dnsmasq.
  137: .TP
  138: .B --log-async[=<lines>]
  139: Enable asynchronous logging and optionally set the limit on the
  140: number of lines
  141: which will be queued by dnsmasq when writing to the syslog is slow. 
  142: Dnsmasq can log asynchronously: this
  143: allows it to continue functioning without being blocked by syslog, and
  144: allows syslog to use dnsmasq for DNS queries without risking deadlock.
  145: If the queue of log-lines becomes full, dnsmasq will log the
  146: overflow, and the number of messages  lost. The default queue length is
  147: 5, a sane value would be 5-25, and a maximum limit of 100 is imposed.
  148: .TP
  149: .B \-x, --pid-file=<path>
  150: Specify an alternate path for dnsmasq to record its process-id in. Normally /var/run/dnsmasq.pid.
  151: .TP
  152: .B \-u, --user=<username>
  153: Specify the userid to which dnsmasq will change after startup. Dnsmasq must normally be started as root, but it will drop root 
  154: privileges after startup by changing id to another user. Normally this user is "nobody" but that 
  155: can be over-ridden with this switch.
  156: .TP
  157: .B \-g, --group=<groupname> 
  158: Specify the group which dnsmasq will run
  159: as. The default is "dip", if available, to facilitate access to
  160: /etc/ppp/resolv.conf which is not normally world readable.
  161: .TP
  162: .B \-v, --version
  163: Print the version number.
  164: .TP
  165: .B \-p, --port=<port>
  166: Listen on <port> instead of the standard DNS port (53). Setting this
  167: to zero completely disables DNS function, leaving only DHCP and/or TFTP.
  168: .TP
  169: .B \-P, --edns-packet-max=<size>
  170: Specify the largest EDNS.0 UDP packet which is supported by the DNS
  171: forwarder. Defaults to 4096, which is the RFC5625-recommended size.
  172: .TP
  173: .B \-Q, --query-port=<query_port>
  174: Send outbound DNS queries from, and listen for their replies on, the
  175: specific UDP port <query_port> instead of using random ports. NOTE
  176: that using this option will make dnsmasq less secure against DNS
  177: spoofing attacks but it may be faster and use less resources.  Setting this option
  178: to zero makes dnsmasq use a single port allocated to it by the
  179: OS: this was the default behaviour in versions prior to 2.43. 
  180: .TP
  181: .B --min-port=<port>
  182: Do not use ports less than that given as source for outbound DNS
  183: queries. Dnsmasq picks random ports as source for outbound queries:
  184: when this option is given, the ports used will always to larger
  185: than that specified. Useful for systems behind firewalls. If not specified,
  186: defaults to 1024.
  187: .TP
  188: .B --max-port=<port>
  189: Use ports lower than that given as source for outbound DNS queries.
  190: Dnsmasq picks random ports as source for outbound queries:
  191: when this option is given, the ports used will always be lower
  192: than that specified. Useful for systems behind firewalls.
  193: .TP
  194: .B \-i, --interface=<interface name>
  195: Listen only on the specified interface(s). Dnsmasq automatically adds
  196: the loopback (local) interface to the list of interfaces to use when
  197: the
  198: .B \--interface
  199: option  is used. If no
  200: .B \--interface
  201: or
  202: .B \--listen-address
  203: options are given dnsmasq listens on all available interfaces except any
  204: given in
  205: .B \--except-interface
  206: options. On Linux, when
  207: .B \--bind-interfaces
  208: or
  209: .B \--bind-dynamic
  210: are in effect, IP alias interface labels (eg "eth1:0") are checked, rather than
  211: interface names. In the degenerate case when an interface has one address, this amounts to the same thing but when an interface has multiple addresses it
  212: allows control over which of those addresses are accepted.
  213: The same effect is achievable in default mode by using
  214: .B \--listen-address.
  215: A simple wildcard, consisting of a trailing '*',
  216: can be used in
  217: .B \--interface 
  218: and
  219: .B \--except-interface
  220: options. 
  221: .TP
  222: .B \-I, --except-interface=<interface name>
  223: Do not listen on the specified interface. Note that the order of
  224: .B \--listen-address
  225: .B --interface
  226: and
  227: .B --except-interface
  228: options does not matter and that 
  229: .B --except-interface
  230: options always override the others. The comments about interface labels for
  231: .B --listen-address
  232: apply here.
  233: .TP
  234: .B --auth-server=<domain>,[<interface>|<ip-address>...]
  235: Enable DNS authoritative mode for queries arriving at an interface or address. Note that the interface or address
  236: need not be mentioned in 
  237: .B --interface
  238: or 
  239: .B --listen-address
  240: configuration, indeed
  241: .B --auth-server
  242: will override these and provide a different DNS service on the
  243: specified interface. The <domain> is the "glue record". It should
  244: resolve in the global DNS to an A and/or AAAA record which points to
  245: the address dnsmasq is listening on. When an interface is specified,
  246: it may be qualified with "/4" or "/6" to specify only the IPv4 or IPv6
  247: addresses associated with the interface. Since any defined authoritative zones are also available as part of the normal recusive DNS service supplied by dnsmasq, it can make sense to have an --auth-server declaration with no interfaces or address, but simply specifying the primary external nameserver.
  248: .TP
  249: .B --local-service
  250: Accept DNS queries only from hosts whose address is on a local subnet,
  251: ie a subnet for which an interface exists on the server. This option
  252: only has effect if there are no \fB--interface\fP, \fB--except-interface\fP,
  253: \fB--listen-address\fP or \fB--auth-server\fP options. It is intended to be set as
  254: a default on installation, to allow unconfigured installations to be
  255: useful but also safe from being used for DNS amplification attacks.
  256: .TP 
  257: .B \-2, --no-dhcp-interface=<interface name>
  258: Do not provide DHCP or TFTP on the specified interface, but do provide DNS service.
  259: .TP
  260: .B \-a, --listen-address=<ipaddr>
  261: Listen on the given IP address(es). Both 
  262: .B \--interface
  263: and
  264: .B \--listen-address
  265: options may be given, in which case the set of both interfaces and
  266: addresses is used. Note that if no
  267: .B \--interface
  268: option is given, but 
  269: .B \--listen-address
  270: is, dnsmasq will not automatically listen on the loopback
  271: interface. To achieve this, its IP address, 127.0.0.1, must be
  272: explicitly given as a 
  273: .B \--listen-address
  274: option.
  275: .TP
  276: .B \-z, --bind-interfaces
  277: On systems which support it, dnsmasq binds the wildcard address,
  278: even when it is listening on only some interfaces. It then discards
  279: requests that it shouldn't reply to. This has the advantage of 
  280: working even when interfaces come and go and change address. This
  281: option forces dnsmasq to really bind only the interfaces it is
  282: listening on. About the only time when this is useful is when 
  283: running another nameserver (or another instance of dnsmasq) on the
  284: same machine. Setting this option also enables multiple instances of
  285: dnsmasq which provide DHCP service to run in the same machine.
  286: .TP
  287: .B --bind-dynamic
  288: Enable a network mode which is a hybrid between 
  289: .B --bind-interfaces
  290: and the default. Dnsmasq binds the address of individual interfaces,
  291: allowing multiple dnsmasq instances, but if new interfaces or
  292: addresses appear, it automatically listens on those (subject to any
  293: access-control configuration). This makes dynamically created
  294: interfaces work in the same way as the default. Implementing this
  295: option requires non-standard networking APIs and it is only available
  296: under Linux. On other platforms it falls-back to \fB--bind-interfaces\fP mode.
  297: .TP
  298: .B \-y, --localise-queries
  299: Return answers to DNS queries from /etc/hosts and \fB--interface-name\fP which depend on the interface over which the query was
  300: received. If a name has more than one address associated with
  301: it, and at least one of those addresses is on the same subnet as the
  302: interface to which the query was sent, then return only the
  303: address(es) on that subnet. This allows for a server  to have multiple
  304: addresses in /etc/hosts corresponding to each of its interfaces, and
  305: hosts will get the correct address based on which network they are
  306: attached to. Currently this facility is limited to IPv4.
  307: .TP
  308: .B \-b, --bogus-priv
  309: Bogus private reverse lookups. All reverse lookups for private IP ranges (ie 192.168.x.x, etc)
  310: which are not found in /etc/hosts or the DHCP leases file are answered
  311: with "no such domain" rather than being forwarded upstream. The 
  312: set of prefixes affected is the list given in RFC6303, for IPv4 and IPv6.
  313: .TP
  314: .B \-V, --alias=[<old-ip>]|[<start-ip>-<end-ip>],<new-ip>[,<mask>]
  315: Modify IPv4 addresses returned from upstream nameservers; old-ip is
  316: replaced by new-ip. If the optional mask is given then any address
  317: which matches the masked old-ip will be re-written. So, for instance
  318: .B --alias=1.2.3.0,6.7.8.0,255.255.255.0 
  319: will map 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. This is what
  320: Cisco PIX routers call "DNS doctoring". If the old IP is given as
  321: range, then only addresses in the range, rather than a whole subnet,
  322: are re-written. So 
  323: .B --alias=192.168.0.10-192.168.0.40,10.0.0.0,255.255.255.0
  324: maps 192.168.0.10->192.168.0.40 to 10.0.0.10->10.0.0.40
  325: .TP 
  326: .B \-B, --bogus-nxdomain=<ipaddr>
  327: Transform replies which contain the IP address given into "No such
  328: domain" replies. This is intended to counteract a devious move made by
  329: Verisign in September 2003 when they started returning the address of
  330: an advertising web page in response to queries for unregistered names,
  331: instead of the correct NXDOMAIN response. This option tells dnsmasq to
  332: fake the correct response when it sees this behaviour. As at Sept 2003
  333: the IP address being returned by Verisign is 64.94.110.11
  334: .TP 
  335: .B --ignore-address=<ipaddr>
  336: Ignore replies to A-record queries which include the specified address. 
  337: No error is generated, dnsmasq simply continues to listen for another reply. 
  338: This is useful to defeat blocking strategies which rely on quickly supplying a
  339: forged answer to a DNS request for certain domain, before the correct answer can arrive.
  340: .TP
  341: .B \-f, --filterwin2k
  342: Later versions of windows make periodic DNS requests which don't get sensible answers from
  343: the public DNS and can cause problems by triggering dial-on-demand links. This flag turns on an option
  344: to filter such requests. The requests blocked are for records of types SOA and SRV, and type ANY where the 
  345: requested name has underscores, to catch LDAP requests.
  346: .TP
  347: .B \-r, --resolv-file=<file>
  348: Read the IP addresses of the upstream nameservers from <file>, instead of
  349: /etc/resolv.conf. For the format of this file see
  350: .BR resolv.conf (5). 
  351: The only lines relevant to dnsmasq are nameserver ones. Dnsmasq can
  352: be told to poll more than one resolv.conf file, the first file name  specified
  353: overrides the default, subsequent ones add to the list. This is only
  354: allowed when polling; the file with the currently latest modification
  355: time is the one used. 
  356: .TP
  357: .B \-R, --no-resolv
  358: Don't read /etc/resolv.conf. Get upstream servers only from the command
  359: line or the dnsmasq configuration file.
  360: .TP
  361: .B \-1, --enable-dbus[=<service-name>]
  362: Allow dnsmasq configuration to be updated via DBus method calls. The
  363: configuration which can be changed is upstream DNS servers (and
  364: corresponding domains) and cache clear. Requires that dnsmasq has
  365: been built with DBus support. If the service name is given, dnsmasq
  366: provides service at that name, rather than the default which is 
  367: .B uk.org.thekelleys.dnsmasq
  368: .TP 
  369: .B --enable-ubus[=<service-name>]
  370: Enable dnsmasq UBus interface. It sends notifications via UBus on
  371: DHCPACK and DHCPRELEASE events. Furthermore it offers metrics.
  372: Requires that dnsmasq has been built with UBus support. If the service
  373: name is given, dnsmasq provides service at that namespace, rather than
  374: the default which is
  375: .B dnsmasq
  376: .TP
  377: .B \-o, --strict-order
  378: By default, dnsmasq will send queries to any of the upstream servers
  379: it knows about and tries to favour servers that are known to
  380: be up. Setting this flag forces dnsmasq to try each query with each
  381: server strictly in the order they appear in /etc/resolv.conf
  382: .TP
  383: .B --all-servers
  384: By default, when dnsmasq has more than one upstream server available,
  385: it will send queries to just one server. Setting this flag forces
  386: dnsmasq to send all queries to all available servers. The reply from
  387: the server which answers first will be returned to the original requester.
  388: .TP
  389: .B --dns-loop-detect
  390: Enable code to detect DNS forwarding loops; ie the situation where a query sent to one 
  391: of the upstream server eventually returns as a new query to the dnsmasq instance. The
  392: process works by generating TXT queries of the form <hex>.test and sending them to
  393: each upstream server. The hex is a UID which encodes the instance of dnsmasq sending the query
  394: and the upstream server to which it was sent. If the query returns to the server which sent it, then
  395: the upstream server through which it was sent is disabled and this event is logged. Each time the
  396: set of upstream servers changes, the test is re-run on all of them, including ones which
  397: were previously disabled.
  398: .TP
  399: .B --stop-dns-rebind
  400: Reject (and log) addresses from upstream nameservers which are in the
  401: private ranges. This blocks an attack where a browser behind a
  402: firewall is used to probe machines on the local network. For IPv6, the
  403: private range covers the IPv4-mapped addresses in private space plus
  404: all link-local (LL) and site-local (ULA) addresses.
  405: .TP
  406: .B --rebind-localhost-ok
  407: Exempt 127.0.0.0/8 and ::1 from rebinding checks. This address range is
  408: returned by realtime black hole servers, so blocking it may disable
  409: these services.
  410: .TP 
  411: .B  --rebind-domain-ok=[<domain>]|[[/<domain>/[<domain>/]
  412: Do not detect and block dns-rebind on queries to these domains. The
  413: argument may be either a single domain, or multiple domains surrounded
  414: by '/', like the \fB--server\fP syntax, eg.
  415: .B  --rebind-domain-ok=/domain1/domain2/domain3/
  416: .TP
  417: .B \-n, --no-poll
  418: Don't poll /etc/resolv.conf for changes.
  419: .TP
  420: .B --clear-on-reload
  421: Whenever /etc/resolv.conf is re-read or the upstream servers are set
  422: via DBus, clear the DNS cache.
  423: This is useful when new nameservers may have different
  424: data than that held in cache.
  425: .TP
  426: .B \-D, --domain-needed
  427: Tells dnsmasq to never forward A or AAAA queries for plain names, without dots
  428: or domain parts, to upstream nameservers. If the name is not known
  429: from /etc/hosts or DHCP then a "not found" answer is returned.
  430: .TP
  431: .B \-S, --local, --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>]][@<source-ip>|<interface>[#<port>]]
  432: Specify IP address of upstream servers directly. Setting this flag does
  433: not suppress reading of /etc/resolv.conf, use \fB--no-resolv\fP to do that. If one or more
  434: optional domains are given, that server is used only for those domains
  435: and they are queried only using the specified server. This is
  436: intended for private nameservers: if you have a nameserver on your
  437: network which deals with names of the form
  438: xxx.internal.thekelleys.org.uk at 192.168.1.1 then giving  the flag 
  439: .B --server=/internal.thekelleys.org.uk/192.168.1.1
  440: will send all queries for
  441: internal machines to that nameserver, everything else will go to the
  442: servers in /etc/resolv.conf. DNSSEC validation is turned off for such
  443: private nameservers, UNLESS a
  444: .B --trust-anchor
  445: is specified for the domain in question. An empty domain specification,
  446: .B // 
  447: has the special meaning of "unqualified names only" ie names without any
  448: dots in them. A non-standard port may be specified as 
  449: part of the IP
  450: address using a # character.
  451: More than one \fB--server\fP flag is allowed, with
  452: repeated domain or ipaddr parts as required.
  453: 
  454: More specific domains take precedence over less specific domains, so:
  455: .B --server=/google.com/1.2.3.4
  456: .B --server=/www.google.com/2.3.4.5
  457: will send queries for *.google.com to 1.2.3.4, except *www.google.com,
  458: which will go to 2.3.4.5
  459: 
  460: The special server address '#' means, "use the standard servers", so
  461: .B --server=/google.com/1.2.3.4
  462: .B --server=/www.google.com/#
  463: will send queries for *.google.com to 1.2.3.4, except *www.google.com which will
  464: be forwarded as usual.
  465: 
  466: Also permitted is a -S
  467: flag which gives a domain but no IP address; this tells dnsmasq that
  468: a domain is local and it may answer queries from /etc/hosts or DHCP
  469: but should never forward queries on that domain to any upstream
  470: servers.
  471: .B --local
  472: is a synonym for
  473: .B --server
  474: to make configuration files clearer in this case.
  475: 
  476: IPv6 addresses may include an %interface scope-id, eg
  477: fe80::202:a412:4512:7bbf%eth0.
  478: 
  479: The optional string after the @ character tells dnsmasq how to set the source of
  480: the queries to this nameserver. It can either be an ip-address, an interface
  481: name or both. The ip-address should belong to the machine on which dnsmasq is
  482: running, otherwise this server line will be logged and then ignored. If an
  483: interface name is given, then queries to the server will be forced via that
  484: interface; if an ip-address is given then the source address of the queries will
  485: be set to that address; and if both are given then a combination of ip-address
  486: and interface name will be used to steer requests to the server.
  487: The query-port flag is ignored for any servers which have a
  488: source address specified but the port may be specified directly as
  489: part of the source address. Forcing queries to an interface is not
  490: implemented on all platforms supported by dnsmasq.
  491: .TP
  492: .B --rev-server=<ip-address>/<prefix-len>[,<ipaddr>][#<port>][@<source-ip>|<interface>[#<port>]]
  493: This is functionally the same as 
  494: .B --server, 
  495: but provides some syntactic sugar to make specifying address-to-name queries easier. For example
  496: .B --rev-server=1.2.3.0/24,192.168.0.1
  497: is exactly equivalent to 
  498: .B --server=/3.2.1.in-addr.arpa/192.168.0.1
  499: .TP
  500: .B \-A, --address=/<domain>[/<domain>...]/[<ipaddr>]
  501: Specify an IP address to return for any host in the given domains.
  502: Queries in the domains are never forwarded and always replied to
  503: with the specified IP address which may be IPv4 or IPv6. To give
  504: both IPv4 and IPv6 addresses for a domain, use repeated \fB--address\fP flags.
  505: To include multiple IP addresses for a single query, use
  506: \fB--addn-hosts=<path>\fP instead.
  507: Note that /etc/hosts and DHCP leases override this for individual
  508: names. A common use of this is to redirect the entire doubleclick.net
  509: domain to some friendly local web server to avoid banner ads. The
  510: domain specification works in the same was as for \fB--server\fP, with
  511: the additional facility that \fB/#/\fP matches any domain. Thus
  512: \fB--address=/#/1.2.3.4\fP will always return \fB1.2.3.4\fP for any
  513: query not answered from \fB/etc/hosts\fP or DHCP and not sent to an
  514: upstream nameserver by a more specific \fB--server\fP directive. As for
  515: \fB--server\fP, one or more domains with no address returns a
  516: no-such-domain answer, so \fB--address=/example.com/\fP is equivalent to
  517: \fB--server=/example.com/\fP and returns NXDOMAIN for example.com and
  518: all its subdomains. An address specified as '#' translates to the NULL
  519: address of 0.0.0.0 and its IPv6 equivalent of :: so
  520: \fB--address=/example.com/#\fP will return NULL addresses for example.com and
  521: its subdomains. This is partly syntactic sugar for \fB--address=/example.com/0.0.0.0\fP
  522: and \fB--address=/example.com/::\fP but is also more efficient than including both
  523: as separate configuration lines. Note that NULL addresses normally work in the same way as localhost, so beware that clients looking up these names are likely to end up talking to themselves.
  524: .TP
  525: .B --ipset=/<domain>[/<domain>...]/<ipset>[,<ipset>...]
  526: Places the resolved IP addresses of queries for one or more domains in
  527: the specified Netfilter IP set. If multiple setnames are given, then the
  528: addresses are placed in each of them, subject to the limitations of an
  529: IP set (IPv4 addresses cannot be stored in an IPv6 IP set and vice
  530: versa).  Domains and subdomains are matched in the same way as
  531: \fB--address\fP.
  532: These IP sets must already exist. See
  533: .BR ipset (8)
  534: for more details.
  535: .TP
  536: .B \-m, --mx-host=<mx name>[[,<hostname>],<preference>]
  537: Return an MX record named <mx name> pointing to the given hostname (if
  538: given), or
  539: the host specified in the \fB--mx-target\fP switch
  540: or, if that switch is not given, the host on which dnsmasq 
  541: is running. The default is useful for directing mail from systems on a LAN
  542: to a central server. The preference value is optional, and defaults to
  543: 1 if not given. More than one MX record may be given for a host.
  544: .TP 
  545: .B \-t, --mx-target=<hostname>
  546: Specify the default target for the MX record returned by dnsmasq. See
  547: \fB--mx-host\fP.  If \fB--mx-target\fP is given, but not \fB--mx-host\fP, then dnsmasq
  548: returns a MX record containing the MX target for MX queries on the 
  549: hostname of the machine on which dnsmasq is running.
  550: .TP
  551: .B \-e, --selfmx
  552: Return an MX record pointing to itself for each local
  553: machine. Local machines are those in /etc/hosts or with DHCP leases.
  554: .TP 
  555: .B \-L, --localmx
  556: Return an MX record pointing to the host given by \fB--mx-target\fP (or the
  557: machine on which dnsmasq is running) for each
  558: local machine. Local machines are those in /etc/hosts or with DHCP
  559: leases.
  560: .TP
  561: .B \-W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<priority>[,<weight>]]]]
  562: Return a SRV DNS record. See RFC2782 for details. If not supplied, the
  563: domain defaults to that given by
  564: .B --domain.
  565: The default for the target domain is empty, and the default for port
  566: is one and the defaults for 
  567: weight and priority are zero. Be careful if transposing data from BIND
  568: zone files: the port, weight and priority numbers are in a different
  569: order. More than one SRV record for a given service/domain is allowed,
  570: all that match are returned.
  571: .TP
  572: .B --host-record=<name>[,<name>....],[<IPv4-address>],[<IPv6-address>][,<TTL>]
  573: Add A, AAAA and PTR records to the DNS. This adds one or more names to
  574: the DNS with associated IPv4 (A) and IPv6 (AAAA) records. A name may
  575: appear in more than one 
  576: .B --host-record
  577: and therefore be assigned more than one address. Only the first
  578: address creates a PTR record linking the address to the name. This is
  579: the same rule as is used reading hosts-files. 
  580: .B --host-record
  581: options are considered to be read before host-files, so a name
  582: appearing there inhibits PTR-record creation if it appears in
  583: hosts-file also. Unlike hosts-files, names are not expanded, even when
  584: .B --expand-hosts
  585: is in effect. Short and long names may appear in the same 
  586: .B --host-record,
  587: eg. 
  588: .B --host-record=laptop,laptop.thekelleys.org,192.168.0.1,1234::100
  589: 
  590: If the time-to-live is given, it overrides the default, which is zero
  591: or the value of \fB--local-ttl\fP. The value is a positive integer and gives
  592: the time-to-live in seconds.
  593: .TP
  594: .B \-Y, --txt-record=<name>[[,<text>],<text>]
  595: Return a TXT DNS record. The value of TXT record is a set of strings,
  596: so  any number may be included, delimited by commas; use quotes to put
  597: commas into a string. Note that the maximum length of a single string
  598: is 255 characters, longer strings are split into 255 character chunks.
  599: .TP
  600: .B --ptr-record=<name>[,<target>]
  601: Return a PTR DNS record.
  602: .TP
  603: .B --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<regexp>[,<replacement>]
  604: Return an NAPTR DNS record, as specified in RFC3403.
  605: .TP
  606: .B --caa-record=<name>,<flags>,<tag>,<value>
  607: Return a CAA DNS record, as specified in RFC6844.
  608: .TP
  609: .B --cname=<cname>,[<cname>,]<target>[,<TTL>]
  610: Return a CNAME record which indicates that <cname> is really
  611: <target>. There is a significant limitation on the target; it must be a
  612: DNS record which is known to dnsmasq and NOT a DNS record which comes from
  613: an upstream server. The cname must be unique, but it
  614: is permissible to have more than one cname pointing to the same target. Indeed
  615: it's possible to declare multiple cnames to a target in a single line, like so:
  616: .B --cname=cname1,cname2,target
  617: 
  618: If the time-to-live is given, it overrides the default, which is zero
  619: or the value of \fB--local-ttl\fP. The value is a positive integer and gives
  620: the time-to-live in seconds.
  621: .TP
  622: .B --dns-rr=<name>,<RR-number>,[<hex data>]
  623: Return an arbitrary DNS Resource Record. The number is the type of the
  624: record (which is always in the C_IN class). The value of the record is
  625: given by the hex data, which may be of the form 01:23:45 or 01 23 45 or
  626: 012345 or any mixture of these.
  627: .TP
  628: .B --interface-name=<name>,<interface>[/4|/6]
  629: Return DNS records associating the name with the address(es) of
  630: the given interface. This flag specifies an A or AAAA record for the given
  631: name in the same way as an /etc/hosts line, except that the address is
  632: not constant, but taken from the given interface. The interface may be
  633: followed by "/4" or "/6" to specify that only IPv4 or IPv6 addresses
  634: of the interface should be used. If the interface is
  635: down, not configured or non-existent, an empty record is returned. The
  636: matching PTR record is also created, mapping the interface address to
  637: the name. More than one name may be associated with an interface
  638: address by repeating the flag; in that case the first instance is used
  639: for the reverse address-to-name mapping. Note that a name used in 
  640: \fB--interface-name\fP may not appear in /etc/hosts.
  641: .TP
  642: .B --synth-domain=<domain>,<address range>[,<prefix>[*]]
  643: Create artificial A/AAAA and PTR records for an address range. The
  644: records either seqential numbers or the address, with periods (or colons for IPv6) replaced with dashes.
  645: 
  646: An examples should make this clearer. First sequential numbers.
  647: .B --synth-domain=thekelleys.org.uk,192.168.0.50,192.168.0.70,internal-*
  648: results in the name internal-0.thekelleys.org.uk. returning 192.168.0.50, internal-1.thekelleys.org.uk returning 192.168.0.51 and so on. (note the *) The same principle applies to IPv6 addresses (where the numbers may be very large). Reverse lookups from address to name behave as expected.
  649: 
  650: Second, 
  651: .B --synth-domain=thekelleys.org.uk,192.168.0.0/24,internal- (no *)
  652: will result in a query for internal-192-168-0-56.thekelleys.org.uk returning
  653: 192.168.0.56 and a reverse query vice versa. The same applies to IPv6,
  654: but IPv6 addresses may start with '::'
  655: but DNS labels may not start with '-' so in this case if no prefix is
  656: configured a zero is added in front of the label. ::1 becomes 0--1.
  657: 
  658: V4 mapped IPv6 addresses, which have a representation like ::ffff:1.2.3.4 are handled specially, and become like 0--ffff-1-2-3-4
  659: 
  660: The address range can be of the form
  661: <ip address>,<ip address> or <ip address>/<netmask> in both forms of the option.
  662: .TP
  663: .B --dumpfile=<path/to/file>
  664: Specify the location of a pcap-format file which dnsmasq uses to dump copies of network packets for debugging purposes. If the file exists when dnsmasq starts, it is not deleted; new packets are added to the end.
  665: .TP
  666: .B --dumpmask=<mask>
  667: Specify which types of packets should be added to the dumpfile. The argument should be the OR of the bitmasks for each type of packet to be dumped: it can be specified in hex by preceding the number with 0x in  the normal way. Each time a packet is written to the dumpfile, dnsmasq logs the packet sequence and the mask
  668: representing its type. The current types are: 0x0001 - DNS queries from clients 0x0002 DNS replies to clients 0x0004 - DNS queries to upstream 0x0008 - DNS replies from upstream 0x0010 - queries send upstream for DNSSEC validation 0x0020 - replies to queries for DNSSEC validation 0x0040 - replies to client queries which fail DNSSEC validation 0x0080 replies to queries for DNSSEC validation which fail validation.
  669: .TP
  670: .B --add-mac[=base64|text]
  671: Add the MAC address of the requestor to DNS queries which are
  672: forwarded upstream. This may be used to DNS filtering by the upstream
  673: server. The MAC address can only be added if the requestor is on the same
  674: subnet as the dnsmasq server. Note that the mechanism used to achieve this (an EDNS0 option)
  675: is not yet standardised, so this should be considered
  676: experimental. Also note that exposing MAC addresses in this way may
  677: have security and privacy implications. The warning about caching
  678: given for \fB--add-subnet\fP applies to \fB--add-mac\fP too. An alternative encoding of the
  679: MAC, as base64, is enabled by adding the "base64" parameter and a human-readable encoding of hex-and-colons is enabled by added the "text" parameter.
  680: .TP
  681: .B --add-cpe-id=<string>
  682: Add an arbitrary identifying string to DNS queries which are
  683: forwarded upstream.
  684: .TP 
  685: .B --add-subnet[[=[<IPv4 address>/]<IPv4 prefix length>][,[<IPv6 address>/]<IPv6 prefix length>]]
  686: Add a subnet address to the DNS queries which are forwarded
  687: upstream. If an address is specified in the flag, it will be used,
  688: otherwise, the address of the requestor will be used. The amount of
  689: the address forwarded depends on the prefix length parameter: 32 (128
  690: for IPv6) forwards the whole address, zero forwards none of it but
  691: still marks the request so that no upstream nameserver will add client
  692: address information either. The default is zero for both IPv4 and
  693: IPv6. Note that upstream nameservers may be configured to return
  694: different results based on this information, but the dnsmasq cache
  695: does not take account. Caching is therefore disabled for such replies,
  696: unless the subnet address being added is constant.
  697: 
  698: For example,
  699: .B --add-subnet=24,96
  700: will add the /24 and /96 subnets of the requestor for IPv4 and IPv6 requestors, respectively.
  701: .B --add-subnet=1.2.3.4/24
  702: will add 1.2.3.0/24 for IPv4 requestors and ::/0 for IPv6 requestors.
  703: .B --add-subnet=1.2.3.4/24,1.2.3.4/24
  704: will add 1.2.3.0/24 for both IPv4 and IPv6 requestors.
  705: 
  706: .TP
  707: .B \-c, --cache-size=<cachesize>
  708: Set the size of dnsmasq's cache. The default is 150 names. Setting the cache size to zero disables caching. Note: huge cache size impacts performance.
  709: .TP
  710: .B \-N, --no-negcache
  711: Disable negative caching. Negative caching allows dnsmasq to remember
  712: "no such domain" answers from upstream nameservers and answer
  713: identical queries without forwarding them again. 
  714: .TP
  715: .B \-0, --dns-forward-max=<queries>
  716: Set the maximum number of concurrent DNS queries. The default value is
  717: 150, which should be fine for most setups. The only known situation
  718: where this needs to be increased is when using web-server log file
  719: resolvers, which can generate large numbers of concurrent queries.
  720: .TP
  721: .B --dnssec
  722: Validate DNS replies and cache DNSSEC data. When forwarding DNS queries, dnsmasq requests the 
  723: DNSSEC records needed to validate the replies. The replies are validated and the result returned as 
  724: the Authenticated Data bit in the DNS packet. In addition the DNSSEC records are stored in the cache, making 
  725: validation by clients more efficient. Note that validation by clients is the most secure DNSSEC mode, but for
  726: clients unable to do validation, use of the AD bit set by dnsmasq is useful, provided that the network between 
  727: the dnsmasq server and the client is trusted. Dnsmasq must be compiled with HAVE_DNSSEC enabled, and DNSSEC
  728: trust anchors provided, see 
  729: .B --trust-anchor.
  730: Because the DNSSEC validation process uses the cache, it is not
  731: permitted to reduce the cache size below the default when DNSSEC is
  732: enabled. The nameservers upstream of dnsmasq must be DNSSEC-capable,
  733: ie capable of returning DNSSEC records with data. If they are not,
  734: then dnsmasq will not be able to determine the trusted status of
  735: answers and this means that DNS service will be entirely broken.
  736: .TP
  737: .B --trust-anchor=[<class>],<domain>,<key-tag>,<algorithm>,<digest-type>,<digest>
  738: Provide DS records to act a trust anchors for DNSSEC
  739: validation. Typically these will be the DS record(s) for Key Signing
  740: key(s) (KSK) of the root zone,
  741: but trust anchors for limited domains are also possible. The current
  742: root-zone trust anchors may be downloaded from https://data.iana.org/root-anchors/root-anchors.xml 
  743: .TP
  744: .B --dnssec-check-unsigned[=no]
  745: As a default, dnsmasq checks that unsigned DNS replies are
  746: legitimate: this entails possible extra queries even for the majority of DNS
  747: zones which are not, at the moment, signed. If
  748: .B --dnssec-check-unsigned=no
  749: appears in the configuration, then such replies they are assumed to be valid and passed on (without the
  750: "authentic data" bit set, of course). This does not protect against an
  751: attacker forging unsigned replies for signed DNS zones, but it is
  752: fast.
  753: 
  754: Versions of dnsmasq prior to 2.80 defaulted to not checking unsigned replies, and used 
  755: .B --dnssec-check-unsigned
  756: to switch this on. Such configurations will continue to work as before, but those which used the default of no checking will need to be altered to explicitly select no checking. The new default is because switching off checking for unsigned replies is inherently dangerous. Not only does it open the possiblity of forged replies, but it allows everything to appear to be working even when the upstream namesevers do not support DNSSEC, and in this case no DNSSEC validation at all is occurring.
  757: .TP
  758: .B --dnssec-no-timecheck
  759: DNSSEC signatures are only valid for specified time windows, and should be rejected outside those windows. This generates an
  760: interesting chicken-and-egg problem for machines which don't have a hardware real time clock. For these machines to determine the correct 
  761: time typically requires use of NTP and therefore DNS, but validating DNS requires that the correct time is already known. Setting this flag
  762: removes the time-window checks (but not other DNSSEC validation.) only until the dnsmasq process receives SIGINT. The intention is
  763: that dnsmasq should be started with this flag when the platform determines that reliable time is not currently available. As soon as 
  764: reliable time is established, a SIGINT should be sent to dnsmasq, which enables time checking, and purges the cache of DNS records
  765: which have not been thoroughly checked.
  766: 
  767: Earlier versions of dnsmasq overloaded SIGHUP (which re-reads much configuration) to also enable time validation.
  768: 
  769: If dnsmasq is run in debug mode (\fB--no-daemon\fP flag) then SIGINT retains its usual meaning of terminating the dnsmasq process.
  770: .TP
  771: .B --dnssec-timestamp=<path>
  772: Enables an alternative way of checking the validity of the system time for DNSSEC (see \fB--dnssec-no-timecheck\fP). In this case, the
  773: system time is considered to be valid once it becomes later than the timestamp on the specified file. The file is created and 
  774: its timestamp set automatically by dnsmasq. The file must be stored on a persistent filesystem, so that it and its mtime are carried 
  775: over system restarts. The timestamp file is created after dnsmasq has dropped root, so it must be in a location writable by the 
  776: unprivileged user that dnsmasq runs as.
  777: .TP
  778: .B --proxy-dnssec
  779: Copy the DNSSEC Authenticated Data bit from upstream servers to downstream clients.  This is an 
  780: alternative to having dnsmasq validate DNSSEC, but it depends on the security of the network between 
  781: dnsmasq and the upstream servers, and the trustworthiness of the upstream servers. Note that caching the
  782: Authenticated Data bit correctly in all cases is not technically possible. If the AD bit is to be relied upon
  783: when using this option, then the cache should be disabled using --cache-size=0. In most cases, enabling DNSSEC validation
  784: within dnsmasq is a better option. See --dnssec for details.
  785: .TP
  786: .B --dnssec-debug
  787: Set debugging mode for the DNSSEC validation, set the Checking Disabled bit on upstream queries, 
  788: and don't convert replies which do not validate to responses with
  789: a return code of SERVFAIL. Note that
  790: setting this may affect DNS behaviour in bad ways, it is not an
  791: extra-logging flag and should not be set in production.
  792: .TP
  793: .B --auth-zone=<domain>[,<subnet>[/<prefix length>][,<subnet>[/<prefix length>].....][,exclude:<subnet>[/<prefix length>]].....]
  794: Define a DNS zone for which dnsmasq acts as authoritative server. Locally defined DNS records which are in the domain
  795: will be served. If subnet(s) are given, A and AAAA records must be in one of the
  796: specified subnets.
  797: 
  798: As alternative to directly specifying the subnets, it's possible to
  799: give the name of an interface, in which case the subnets implied by
  800: that interface's configured addresses and netmask/prefix-length are
  801: used; this is useful when using constructed DHCP ranges as the actual
  802: address is dynamic and not known when configuring dnsmasq. The
  803: interface addresses may be confined to only IPv6 addresses using
  804: <interface>/6 or to only IPv4 using <interface>/4. This is useful when
  805: an interface has dynamically determined global IPv6 addresses which should
  806: appear in the zone, but RFC1918 IPv4 addresses which should not.
  807: Interface-name and address-literal subnet specifications may be used
  808: freely in the same \fB--auth-zone\fP declaration.
  809: 
  810: It's possible to exclude certain IP addresses from responses. It can be
  811: used, to make sure that answers contain only global routeable IP
  812: addresses (by excluding loopback, RFC1918 and ULA addresses).
  813: 
  814: The subnet(s) are also used to define in-addr.arpa and
  815: ip6.arpa domains which are served for reverse-DNS queries. If not
  816: specified, the prefix length defaults to 24 for IPv4 and 64 for IPv6.
  817: For IPv4 subnets, the prefix length should be have the value 8, 16 or 24
  818: unless you are familiar with RFC 2317 and have arranged the
  819: in-addr.arpa delegation accordingly. Note that if no subnets are
  820: specified, then no reverse queries are answered.
  821: .TP
  822: .B --auth-soa=<serial>[,<hostmaster>[,<refresh>[,<retry>[,<expiry>]]]]
  823: Specify fields in the SOA record associated with authoritative
  824: zones. Note that this is optional, all the values are set to sane defaults.
  825: .TP
  826: .B --auth-sec-servers=<domain>[,<domain>[,<domain>...]]
  827: Specify any secondary servers for a zone for which dnsmasq is
  828: authoritative. These servers must be configured to get zone data from
  829: dnsmasq by zone transfer, and answer queries for the same
  830: authoritative zones as dnsmasq.
  831: .TP
  832: .B --auth-peer=<ip-address>[,<ip-address>[,<ip-address>...]]
  833: Specify the addresses of secondary servers which are allowed to
  834: initiate zone transfer (AXFR) requests for zones for which dnsmasq is
  835: authoritative. If this option is not given but --auth-sec-servers is,
  836: then AXFR requests will be
  837: accepted from any secondary. Specifying
  838: .B --auth-peer
  839: without
  840: .B --auth-sec-servers
  841: enables zone transfer but does not advertise the secondary in NS records returned by dnsmasq.
  842: .TP 
  843: .B --conntrack
  844: Read the Linux connection track mark associated with incoming DNS
  845: queries and set the same mark value on upstream traffic used to answer
  846: those queries. This allows traffic generated by dnsmasq to be
  847: associated with the queries which cause it, useful for bandwidth
  848: accounting and firewalling. Dnsmasq must have conntrack support
  849: compiled in and the kernel must have conntrack support
  850: included and configured. This option cannot be combined with
  851: .B --query-port.
  852: .TP
  853: .B \-F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-addr>[,<end-addr>|<mode>][,<netmask>[,<broadcast>]][,<lease time>]
  854: .TP
  855: .B \-F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-IPv6addr>[,<end-IPv6addr>|constructor:<interface>][,<mode>][,<prefix-len>][,<lease time>]
  856: 
  857: Enable the DHCP server. Addresses will be given out from the range
  858: <start-addr> to <end-addr> and from statically defined addresses given
  859: in 
  860: .B --dhcp-host
  861: options. If the lease time is given, then leases
  862: will be given for that length of time. The lease time is in seconds,
  863: or minutes (eg 45m) or hours (eg 1h) or "infinite". If not given,
  864: the default lease time is one hour for IPv4 and one day for IPv6. The
  865: minimum lease time is two minutes. For IPv6 ranges, the lease time
  866: maybe "deprecated"; this sets the preferred lifetime sent in a DHCP
  867: lease or router advertisement to zero, which causes clients to use
  868: other addresses, if available, for new connections as a prelude to renumbering.
  869: 
  870: This option may be repeated, with different addresses, to enable DHCP
  871: service to more than one network. For directly connected networks (ie,
  872: networks on which the machine running dnsmasq has an interface) the
  873: netmask is optional: dnsmasq will determine it from the interface
  874: configuration. For networks which receive DHCP service via a relay
  875: agent, dnsmasq cannot determine the netmask itself, so it should be
  876: specified, otherwise dnsmasq will have to guess, based on the class (A, B or
  877: C) of the network address. The broadcast address is
  878: always optional. It is always
  879: allowed to have more than one \fB--dhcp-range\fP in a single subnet.
  880: 
  881: For IPv6, the parameters are slightly different: instead of netmask
  882: and broadcast address, there is an optional prefix length which must
  883: be equal to or larger then the prefix length on the local interface. If not
  884: given, this defaults to 64. Unlike the IPv4 case, the prefix length is not
  885: automatically derived from the interface configuration. The minimum
  886: size of the prefix length is 64.
  887: 
  888: IPv6 (only) supports another type of range. In this, the start address and optional end address contain only the network part (ie ::1) and they are followed by
  889: .B constructor:<interface>.
  890: This forms a template which describes how to create ranges, based on the addresses assigned to the interface. For instance
  891: 
  892: .B --dhcp-range=::1,::400,constructor:eth0
  893: 
  894: will look for addresses on
  895: eth0 and then create a range from <network>::1 to <network>::400. If
  896: the interface is assigned more than one network, then the
  897: corresponding ranges will be automatically created, and then
  898: deprecated and finally removed again as the address is deprecated and
  899: then deleted. The interface name may have a final "*" wildcard. Note
  900: that just any address on eth0 will not do: it must not be an
  901: autoconfigured or privacy address, or be deprecated.
  902: 
  903: If a \fB--dhcp-range\fP is only being used for stateless DHCP and/or SLAAC,
  904: then the address can be simply ::
  905: 
  906: .B --dhcp-range=::,constructor:eth0
  907: 
  908: 
  909: The optional 
  910: .B set:<tag> 
  911: sets an alphanumeric label which marks this network so that
  912: DHCP options may be specified on a per-network basis.
  913: When it is prefixed with 'tag:' instead, then its meaning changes from setting
  914: a tag to matching it. Only one tag may be set, but more than one tag
  915: may be matched.
  916: 
  917: The optional <mode> keyword may be 
  918: .B static
  919: which tells dnsmasq to enable DHCP for the network specified, but not
  920: to dynamically allocate IP addresses: only hosts which have static
  921: addresses given via 
  922: .B --dhcp-host
  923: or from /etc/ethers will be served. A static-only subnet with address
  924: all zeros may be used as a "catch-all" address to enable replies to all
  925: Information-request packets on a subnet which is provided with
  926: stateless DHCPv6, ie
  927: .B --dhcp-range=::,static
  928: 
  929: For IPv4, the <mode> may be 
  930: .B proxy
  931: in which case dnsmasq will provide proxy-DHCP on the specified
  932: subnet. (See 
  933: .B --pxe-prompt
  934: and 
  935: .B --pxe-service
  936: for details.)
  937: 
  938: For IPv6, the mode may be some combination of
  939: .B ra-only, slaac, ra-names, ra-stateless, ra-advrouter, off-link.
  940: 
  941: .B ra-only
  942: tells dnsmasq to offer Router Advertisement only on this subnet,
  943: and not DHCP. 
  944: 
  945: .B slaac
  946: tells dnsmasq to offer Router Advertisement on this subnet and to set
  947: the A bit in the router advertisement, so that the client will use
  948: SLAAC addresses. When used with a DHCP range or static DHCP address
  949: this results in the client having both a DHCP-assigned and a SLAAC
  950: address.
  951: 
  952: .B ra-stateless
  953: sends router advertisements with the O and A bits set, and provides a
  954: stateless DHCP service. The client will use a SLAAC address, and use
  955: DHCP for other configuration information.
  956: 
  957: .B ra-names
  958: enables a mode
  959: which gives DNS names to dual-stack hosts which do SLAAC for
  960: IPv6. Dnsmasq uses the host's IPv4 lease to derive the name, network
  961: segment and MAC address and assumes that the host will also have an
  962: IPv6 address calculated using the SLAAC algorithm, on the same network
  963: segment. The address is pinged, and if a reply is received, an AAAA
  964: record is added to the DNS for this IPv6
  965: address. Note that this is only happens for directly-connected
  966: networks, (not one doing DHCP via a relay) and it will not work 
  967: if a host is using privacy extensions. 
  968: .B ra-names
  969: can be combined  with 
  970: .B ra-stateless
  971: and
  972: .B slaac.
  973: 
  974: .B ra-advrouter
  975: enables a mode where router address(es) rather than prefix(es) are included in the advertisements.
  976: This is described in RFC-3775 section 7.2 and is used in mobile IPv6. In this mode the interval option
  977: is also included, as described in RFC-3775 section 7.3.
  978: 
  979: .B off-link
  980: tells dnsmasq to advertise the prefix without the on-link (aka L) bit set.
  981: 
  982: .TP
  983: .B \-G, --dhcp-host=[<hwaddr>][,id:<client_id>|*][,set:<tag>][tag:<tag>][,<ipaddr>][,<hostname>][,<lease_time>][,ignore]
  984: Specify per host parameters for the DHCP server. This allows a machine
  985: with a particular hardware address to be always allocated the same
  986: hostname, IP address and lease time. A hostname specified like this
  987: overrides any supplied by the DHCP client on the machine. It is also
  988: allowable to omit the hardware address and include the hostname, in
  989: which case the IP address and lease times will apply to any machine
  990: claiming that name. For example 
  991: .B --dhcp-host=00:20:e0:3b:13:af,wap,infinite 
  992: tells dnsmasq to give
  993: the machine with hardware address 00:20:e0:3b:13:af the name wap, and
  994: an infinite DHCP lease. 
  995: .B --dhcp-host=lap,192.168.0.199 
  996: tells
  997: dnsmasq to always allocate the machine lap the IP address
  998: 192.168.0.199. 
  999: 
 1000: Addresses allocated like this are not constrained to be
 1001: in the range given by the \fB--dhcp-range\fP option, but they must be in
 1002: the same subnet as some valid dhcp-range.  For
 1003: subnets which don't need a pool of dynamically allocated addresses,
 1004: use the "static" keyword in the \fB--dhcp-range\fP declaration.
 1005: 
 1006: It is allowed to use client identifiers (called client
 1007: DUID in IPv6-land) rather than
 1008: hardware addresses to identify hosts by prefixing with 'id:'. Thus: 
 1009: .B --dhcp-host=id:01:02:03:04,..... 
 1010: refers to the host with client identifier 01:02:03:04. It is also
 1011: allowed to specify the client ID as text, like this:
 1012: .B --dhcp-host=id:clientidastext,..... 
 1013: 
 1014: A single
 1015: .B --dhcp-host
 1016: may contain an IPv4 address or one or more IPv6 addresses, or both. IPv6 addresses must be bracketed by square brackets thus:
 1017: .B --dhcp-host=laptop,[1234::56]
 1018: IPv6 addresses may contain only the host-identifier part:
 1019: .B --dhcp-host=laptop,[::56]
 1020: in which case they act as wildcards in constructed DHCP ranges, with
 1021: the appropriate network part inserted. For IPv6, an address may include a prefix length:
 1022: .B --dhcp-host=laptop,[1234:50/126]
 1023: which (in this case) specifies four addresses, 1234::50 to 1234::53. This (an the ability
 1024: to specify multiple addresses) is useful
 1025: when a host presents either a consistent name or hardware-ID, but varying DUIDs, since it allows
 1026: dnsmasq to honour the static address allocation but assign a different adddress for each DUID. This
 1027: typically occurs when chain netbooting, as each stage of the chain gets in turn allocates an address.
 1028: 
 1029: Note that in IPv6 DHCP, the hardware address may not be
 1030: available, though it normally is for direct-connected clients, or
 1031: clients using DHCP relays which support RFC 6939.
 1032: 
 1033: 
 1034: For DHCPv4, the  special option id:* means "ignore any client-id 
 1035: and use MAC addresses only." This is useful when a client presents a client-id sometimes 
 1036: but not others.
 1037: 
 1038: If a name appears in /etc/hosts, the associated address can be
 1039: allocated to a DHCP lease, but only if a 
 1040: .B --dhcp-host
 1041: option specifying the name also exists. Only one hostname can be
 1042: given in a 
 1043: .B --dhcp-host
 1044: option, but aliases are possible by using CNAMEs. (See 
 1045: .B --cname
 1046: ).
 1047: 
 1048: The special keyword "ignore"
 1049: tells dnsmasq to never offer a DHCP lease to a machine. The machine
 1050: can be specified by hardware address, client ID or hostname, for
 1051: instance
 1052: .B --dhcp-host=00:20:e0:3b:13:af,ignore
 1053: This is
 1054: useful when there is another DHCP server on the network which should
 1055: be used by some machines.
 1056: 
 1057: The set:<tag> construct sets the tag
 1058: whenever this \fB--dhcp-host\fP directive is in use. This can be used to
 1059: selectively send DHCP options just for this host. More than one tag
 1060: can be set in a \fB--dhcp-host\fP directive (but not in other places where
 1061: "set:<tag>" is allowed). When a host matches any
 1062: \fB--dhcp-host\fP directive (or one implied by /etc/ethers) then the special
 1063: tag "known" is set. This allows dnsmasq to be configured to
 1064: ignore requests from unknown machines using
 1065: .B --dhcp-ignore=tag:!known
 1066: If the host matches only a \fB--dhcp-host\fP directive which cannot
 1067: be used because it specifies an address on different subnet, the tag "known-othernet" is set.
 1068: 
 1069: The tag:<tag> construct filters which dhcp-host directives are used. Tagged directives are used in preference to untagged ones.
 1070: 
 1071: Ethernet addresses (but not client-ids) may have
 1072: wildcard bytes, so for example 
 1073: .B --dhcp-host=00:20:e0:3b:13:*,ignore 
 1074: will cause dnsmasq to ignore a range of hardware addresses. Note that
 1075: the "*" will need to be escaped or quoted on a command line, but not
 1076: in the configuration file.
 1077: 
 1078: Hardware addresses normally match any
 1079: network (ARP) type, but it is possible to restrict them to a single
 1080: ARP type by preceding them with the ARP-type (in HEX) and "-". so 
 1081: .B --dhcp-host=06-00:20:e0:3b:13:af,1.2.3.4 
 1082: will only match a
 1083: Token-Ring hardware address, since the ARP-address type for token ring
 1084: is 6. 
 1085: 
 1086: As a special case, in DHCPv4, it is possible to include more than one
 1087: hardware address. eg:
 1088: .B --dhcp-host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2
 1089: This allows an IP address to be associated with
 1090: multiple hardware addresses, and gives dnsmasq permission to abandon a
 1091: DHCP lease to one of the hardware addresses when another one asks for
 1092: a lease. Beware that this is a dangerous thing to do, it will only
 1093: work reliably if only one of the hardware addresses is active at any
 1094: time and there is no way for dnsmasq to enforce this. It is, for instance,
 1095: useful to allocate a stable IP address to a laptop which
 1096: has both wired and wireless interfaces.
 1097: .TP
 1098: .B --dhcp-hostsfile=<path>
 1099: Read DHCP host information from the specified file. If a directory
 1100: is given, then read all the files contained in that directory. The file contains 
 1101: information about one host per line. The format of a line is the same
 1102: as text to the right of '=' in \fB--dhcp-host\fP. The advantage of storing DHCP host information
 1103: in this file is that it can be changed without re-starting dnsmasq:
 1104: the file will be re-read when dnsmasq receives SIGHUP.
 1105: .TP
 1106: .B --dhcp-optsfile=<path>
 1107: Read DHCP option information from the specified file.  If a directory
 1108: is given, then read all the files contained in that directory. The advantage of 
 1109: using this option is the same as for \fB--dhcp-hostsfile\fP: the
 1110: \fB--dhcp-optsfile\fP will be re-read when dnsmasq receives SIGHUP. Note that
 1111: it is possible to encode the information in a
 1112: .B --dhcp-boot
 1113: flag as DHCP options, using the options names bootfile-name,
 1114: server-ip-address and tftp-server. This allows these to be included
 1115: in a \fB--dhcp-optsfile\fP.
 1116: .TP
 1117: .B --dhcp-hostsdir=<path>
 1118: This is equivalent to \fB--dhcp-hostsfile\fP, except for the following. The path MUST be a
 1119: directory, and not an individual file. Changed or new files within
 1120: the directory are read automatically, without the need to send SIGHUP.
 1121: If a file is deleted or changed after it has been read by dnsmasq, then the
 1122: host record it contained will remain until dnsmasq receives a SIGHUP, or 
 1123: is restarted; ie host records are only added dynamically.
 1124: .TP
 1125: .B --dhcp-optsdir=<path>
 1126: This is equivalent to \fB--dhcp-optsfile\fP, with the differences noted for \fB--dhcp-hostsdir\fP.
 1127: .TP 
 1128: .B \-Z, --read-ethers
 1129: Read /etc/ethers for information about hosts for the DHCP server. The
 1130: format of /etc/ethers is a hardware address, followed by either a
 1131: hostname or dotted-quad IP address. When read by dnsmasq these lines
 1132: have exactly the same effect as
 1133: .B --dhcp-host
 1134: options containing the same information. /etc/ethers is re-read when 
 1135: dnsmasq receives SIGHUP. IPv6 addresses are NOT read from /etc/ethers.
 1136: .TP
 1137: .B \-O, --dhcp-option=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<enterprise>,][vendor:[<vendor-class>],][<opt>|option:<opt-name>|option6:<opt>|option6:<opt-name>],[<value>[,<value>]]
 1138: Specify different or extra options to DHCP clients. By default,
 1139: dnsmasq sends some standard options to DHCP clients, the netmask and
 1140: broadcast address are set to the same as the host running dnsmasq, and
 1141: the DNS server and default route are set to the address of the machine
 1142: running dnsmasq. (Equivalent rules apply for IPv6.) If the domain name option has been set, that is sent.
 1143: This configuration allows these defaults to be overridden,
 1144: or other options specified. The option, to be sent may be given as a
 1145: decimal number or as "option:<option-name>" The option numbers are
 1146: specified in RFC2132 and subsequent RFCs. The set of option-names
 1147: known by dnsmasq can be discovered by running "dnsmasq --help dhcp".
 1148: For example, to set the default route option to 
 1149: 192.168.4.4, do 
 1150: .B --dhcp-option=3,192.168.4.4 
 1151: or
 1152: .B --dhcp-option = option:router, 192.168.4.4
 1153: and to set the time-server address to 192.168.0.4, do
 1154: .B --dhcp-option = 42,192.168.0.4 
 1155: or 
 1156: .B --dhcp-option = option:ntp-server, 192.168.0.4
 1157: The special address 0.0.0.0 is taken to mean "the address of the
 1158: machine running dnsmasq". 
 1159: 
 1160: Data types allowed are comma separated
 1161: dotted-quad IPv4 addresses, []-wrapped IPv6 addresses, a decimal number, colon-separated hex digits
 1162: and a text string. If the optional tags are given then
 1163: this option is only sent when all the tags are matched.
 1164: 
 1165: Special processing is done on a text argument for option 119, to
 1166: conform with RFC 3397. Text or dotted-quad IP addresses as arguments
 1167: to option 120 are handled as per RFC 3361. Dotted-quad IP addresses 
 1168: which are followed by a slash and then a netmask size are encoded as
 1169: described in RFC 3442.
 1170: 
 1171: IPv6 options are specified using the 
 1172: .B option6:
 1173: keyword, followed by the option number or option name. The IPv6 option
 1174: name space is disjoint from the IPv4 option name space. IPv6 addresses
 1175: in options must be bracketed with square brackets, eg. 
 1176: .B --dhcp-option=option6:ntp-server,[1234::56]
 1177: For IPv6, [::] means "the global address of
 1178: the machine running dnsmasq", whilst [fd00::] is replaced with the
 1179: ULA, if it exists, and [fe80::] with the link-local address.
 1180: 
 1181: Be careful: no checking is done that the correct type of data for the
 1182: option number is sent, it is quite possible to
 1183: persuade dnsmasq to generate illegal DHCP packets with injudicious use
 1184: of this flag. When the value is a decimal number, dnsmasq must determine how 
 1185: large the data item is. It does this by examining the option number and/or the
 1186: value, but can be overridden by appending a single letter flag as follows:
 1187: b = one byte, s = two bytes, i = four bytes. This is mainly useful with 
 1188: encapsulated vendor class options (see below) where dnsmasq cannot
 1189: determine data size from the  option number. Option data which
 1190: consists solely of periods and digits will be interpreted by dnsmasq
 1191: as an IP address, and inserted into an option as such. To force a
 1192: literal string, use quotes. For instance when using option 66 to send
 1193: a literal IP address as TFTP server name, it is necessary to do
 1194: .B --dhcp-option=66,"1.2.3.4"
 1195: 
 1196: Encapsulated Vendor-class options may also be specified (IPv4 only) using
 1197: \fB--dhcp-option\fP: for instance
 1198: .B --dhcp-option=vendor:PXEClient,1,0.0.0.0 
 1199: sends the encapsulated vendor
 1200: class-specific option "mftp-address=0.0.0.0" to any client whose
 1201: vendor-class matches "PXEClient". The vendor-class matching is
 1202: substring based (see \fB--dhcp-vendorclass\fP for details). If a
 1203: vendor-class option (number 60) is sent by dnsmasq, then that is used 
 1204: for selecting encapsulated options in preference to any sent by the
 1205: client. It is
 1206: possible to omit the vendorclass completely;
 1207: .B --dhcp-option=vendor:,1,0.0.0.0
 1208: in which case the encapsulated option is always sent. 
 1209: 
 1210: Options may be encapsulated (IPv4 only) within other options: for instance
 1211: .B --dhcp-option=encap:175, 190, "iscsi-client0"
 1212: will send option 175, within which is the option 190. If multiple
 1213: options are given which are encapsulated with the same option number
 1214: then they will be correctly combined into one encapsulated option.
 1215: encap: and vendor: are may not both be set in the same \fB--dhcp-option\fP.
 1216: 
 1217: The final variant on encapsulated options is "Vendor-Identifying
 1218: Vendor Options" as specified by RFC3925. These are denoted like this: 
 1219: .B --dhcp-option=vi-encap:2, 10, "text"
 1220: The number in the vi-encap: section is the IANA enterprise number
 1221: used to identify this option. This form of encapsulation is supported
 1222: in IPv6.
 1223:  
 1224: The address 0.0.0.0 is not treated specially in
 1225: encapsulated options.
 1226: .TP
 1227: .B --dhcp-option-force=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<enterprise>,][vendor:[<vendor-class>],]<opt>,[<value>[,<value>]]
 1228: This works in exactly the same way as
 1229: .B --dhcp-option
 1230: except that the option will always be sent, even if the client does
 1231: not ask for it in the parameter request list. This is sometimes
 1232: needed, for example when sending options to PXELinux.
 1233: .TP
 1234: .B --dhcp-no-override
 1235: (IPv4 only) Disable re-use of the DHCP servername and filename fields as extra
 1236: option space. If it can, dnsmasq moves the boot server and filename
 1237: information (from \fB--dhcp-boot\fP) out of their dedicated fields into
 1238: DHCP options. This make extra space available in the DHCP packet for
 1239: options but can, rarely, confuse old or broken clients. This flag
 1240: forces "simple and safe" behaviour to avoid problems in such a case.
 1241: .TP
 1242: .B --dhcp-relay=<local address>,<server address>[,<interface]
 1243: Configure dnsmasq to do DHCP relay. The local address is an address
 1244: allocated to an interface on the host running dnsmasq. All DHCP
 1245: requests arriving on that interface will we relayed to a remote DHCP
 1246: server at the server address. It is possible to relay from a single local
 1247: address to multiple remote servers by using multiple \fB--dhcp-relay\fP
 1248: configs with the same local address and different server
 1249: addresses. A server address must be an IP literal address, not a
 1250: domain name. In the case of DHCPv6, the server address may be the
 1251: ALL_SERVERS multicast address, ff05::1:3. In this case the interface
 1252: must be given, not be wildcard, and is used to direct the multicast to the
 1253: correct interface to reach the DHCP server. 
 1254: 
 1255: Access control for DHCP clients has the same rules as for the DHCP
 1256: server, see \fB--interface\fP, \fB--except-interface\fP, etc. The optional
 1257: interface name in the \fB--dhcp-relay\fP config has a different function: it
 1258: controls on which interface DHCP replies from the server will be
 1259: accepted. This is intended for configurations which have three
 1260: interfaces: one being relayed from, a second connecting the DHCP
 1261: server, and a third untrusted network, typically the wider
 1262: internet. It avoids the possibility of spoof replies arriving via this
 1263: third interface.
 1264: 
 1265: It is allowed to have dnsmasq act as a DHCP server on one set of
 1266: interfaces and relay from a disjoint set of interfaces. Note that
 1267: whilst it is quite possible to write configurations which appear to
 1268: act as a server and a relay on the same interface, this is not
 1269: supported: the relay function will take precedence.
 1270: 
 1271: Both DHCPv4 and DHCPv6 relay is supported. It's not possible to relay
 1272: DHCPv4 to a DHCPv6 server or vice-versa.
 1273: .TP
 1274: .B \-U, --dhcp-vendorclass=set:<tag>,[enterprise:<IANA-enterprise number>,]<vendor-class>
 1275: Map from a vendor-class string to a tag. Most DHCP clients provide a 
 1276: "vendor class" which represents, in some sense, the type of host. This option 
 1277: maps vendor classes to tags, so that DHCP options may be selectively delivered
 1278: to different classes of hosts. For example 
 1279: .B --dhcp-vendorclass=set:printers,Hewlett-Packard JetDirect
 1280: will allow options to be set only for HP printers like so:
 1281: .B --dhcp-option=tag:printers,3,192.168.4.4 
 1282: The vendor-class string is
 1283: substring matched against the vendor-class supplied by the client, to
 1284: allow fuzzy matching. The set: prefix is optional but allowed for
 1285: consistency. 
 1286: 
 1287: Note that in IPv6 only, vendorclasses are namespaced with an 
 1288: IANA-allocated enterprise number. This is given with enterprise:
 1289: keyword and specifies that only vendorclasses matching the specified
 1290: number should be searched.
 1291: .TP
 1292: .B \-j, --dhcp-userclass=set:<tag>,<user-class>
 1293: Map from a user-class string to a tag (with substring
 1294: matching, like vendor classes). Most DHCP clients provide a 
 1295: "user class" which is configurable. This option
 1296: maps user classes to tags, so that DHCP options may be selectively delivered
 1297: to different classes of hosts. It is possible, for instance to use
 1298: this to set a different printer server for hosts in the class
 1299: "accounts" than for hosts in the class "engineering".
 1300: .TP
 1301: .B \-4, --dhcp-mac=set:<tag>,<MAC address>
 1302: Map from a MAC address to a tag. The MAC address may include
 1303: wildcards. For example
 1304: .B --dhcp-mac=set:3com,01:34:23:*:*:*
 1305: will set the tag "3com" for any host whose MAC address matches the pattern.
 1306: .TP
 1307: .B --dhcp-circuitid=set:<tag>,<circuit-id>, --dhcp-remoteid=set:<tag>,<remote-id>
 1308: Map from RFC3046 relay agent options to tags. This data may
 1309: be provided by DHCP relay agents. The circuit-id or remote-id is
 1310: normally given as colon-separated hex, but is also allowed to be a
 1311: simple string. If an exact match is achieved between the circuit or
 1312: agent ID and one provided by a relay agent, the tag is set. 
 1313: 
 1314: .B --dhcp-remoteid
 1315: (but not \fB--dhcp-circuitid\fP) is supported in IPv6.
 1316: .TP
 1317: .B --dhcp-subscrid=set:<tag>,<subscriber-id>
 1318: (IPv4 and IPv6) Map from RFC3993 subscriber-id relay agent options to tags.
 1319: .TP
 1320: .B --dhcp-proxy[=<ip addr>]......
 1321: (IPv4 only) A normal DHCP relay agent is only used to forward the initial parts of
 1322: a DHCP interaction to the DHCP server. Once a client is configured, it
 1323: communicates directly with the server. This is undesirable if the
 1324: relay agent is adding extra information to the DHCP packets, such as
 1325: that used by
 1326: .B --dhcp-circuitid
 1327: and
 1328: .B --dhcp-remoteid.
 1329: A full relay implementation can use the RFC 5107 serverid-override
 1330: option to force the DHCP server to use the relay as a full proxy, with all
 1331: packets passing through it. This flag provides an alternative method
 1332: of doing the same thing, for relays which don't support RFC
 1333: 5107. Given alone, it manipulates the server-id for all interactions
 1334: via relays. If a list of IP addresses is given, only interactions via
 1335: relays at those addresses are affected.
 1336: .TP
 1337: .B --dhcp-match=set:<tag>,<option number>|option:<option name>|vi-encap:<enterprise>[,<value>]
 1338: Without a value, set the tag if the client sends a DHCP
 1339: option of the given number or name. When a value is given, set the tag only if
 1340: the option is sent and matches the value. The value may be of the form
 1341: "01:ff:*:02" in which case the value must match (apart from wildcards)
 1342: but the option sent may have unmatched data past the end of the
 1343: value. The value may also be of the same form as in 
 1344: .B --dhcp-option
 1345: in which case the option sent is treated as an array, and one element
 1346: must match, so
 1347: .B --dhcp-match=set:efi-ia32,option:client-arch,6
 1348: will set the tag "efi-ia32" if the the number 6 appears in the list of
 1349: architectures sent by the client in option 93. (See RFC 4578 for
 1350: details.)  If the value is a string, substring matching is used.
 1351: 
 1352: The special form with vi-encap:<enterprise number> matches against
 1353: vendor-identifying vendor classes for the specified enterprise. Please
 1354: see RFC 3925 for more details of these rare and interesting beasts.
 1355: .TP
 1356: .B --dhcp-name-match=set:<tag>,<name>[*]
 1357: Set the tag if the given name is supplied by a DHCP client. There may be a single trailing wildcard *, which has the usual meaning. Combined with dhcp-ignore or dhcp-ignore-names this gives the ability to ignore certain clients by name, or disallow certain hostnames from being claimed by a client.
 1358: .TP
 1359: .B --tag-if=set:<tag>[,set:<tag>[,tag:<tag>[,tag:<tag>]]]
 1360: Perform boolean operations on tags. Any tag appearing as set:<tag> is set if
 1361: all the tags which appear as tag:<tag> are set, (or unset when tag:!<tag> is used)
 1362: If no tag:<tag> appears set:<tag> tags are set unconditionally.
 1363: Any number of set: and tag: forms may appear, in any order. 
 1364: \fB--tag-if\fP lines are executed in order, so if the tag in tag:<tag> is a
 1365: tag set by another
 1366: .B --tag-if,
 1367: the line which sets the tag must precede the one which tests it.
 1368: .TP
 1369: .B \-J, --dhcp-ignore=tag:<tag>[,tag:<tag>]
 1370: When all the given tags appear in the tag set ignore the host and do
 1371: not allocate it a DHCP lease.
 1372: .TP
 1373: .B --dhcp-ignore-names[=tag:<tag>[,tag:<tag>]]
 1374: When all the given tags appear in the tag set, ignore any hostname
 1375: provided by the host. Note that, unlike \fB--dhcp-ignore\fP, it is permissible
 1376: to supply no tags, in which case DHCP-client supplied hostnames
 1377: are always ignored, and DHCP hosts are added to the DNS using only
 1378: \fB--dhcp-host\fP configuration in dnsmasq and the contents of /etc/hosts and
 1379: /etc/ethers.
 1380: .TP
 1381: .B --dhcp-generate-names=tag:<tag>[,tag:<tag>]
 1382: (IPv4 only) Generate a name for DHCP clients which do not otherwise have one,
 1383: using the MAC address expressed in hex, separated by dashes. Note that
 1384: if a host provides a name, it will be used by preference to this,
 1385: unless 
 1386: .B --dhcp-ignore-names 
 1387: is set.
 1388: .TP
 1389: .B --dhcp-broadcast[=tag:<tag>[,tag:<tag>]]
 1390: (IPv4 only) When all the given tags appear in the tag set, always use broadcast to
 1391: communicate with the host when it is unconfigured. It is permissible
 1392: to supply no tags, in which case this is unconditional. Most DHCP clients which
 1393: need broadcast replies set a flag in their requests so that this
 1394: happens automatically, some old BOOTP clients do not.
 1395: .TP
 1396: .B \-M, --dhcp-boot=[tag:<tag>,]<filename>,[<servername>[,<server address>|<tftp_servername>]]
 1397: (IPv4 only) Set BOOTP options to be returned by the DHCP server. Server name and
 1398: address are optional: if not provided, the name is left empty, and the
 1399: address set to the address of the machine running dnsmasq. If dnsmasq
 1400: is providing a TFTP service (see 
 1401: .B --enable-tftp
 1402: ) then only the filename is required here to enable network booting.
 1403: If the optional tag(s) are given,
 1404: they must match for this configuration to be sent. 
 1405: Instead of an IP address, the TFTP server address can be given as a domain
 1406: name which is looked up in /etc/hosts. This name can be associated in
 1407: /etc/hosts with multiple IP addresses, which are used round-robin.
 1408: This facility can be used to load balance the tftp load among a set of servers.
 1409: .TP
 1410: .B --dhcp-sequential-ip
 1411: Dnsmasq is designed to choose IP addresses for DHCP clients using a
 1412: hash of the client's MAC address. This normally allows a client's
 1413: address to remain stable long-term, even if the client  sometimes allows its DHCP
 1414: lease to expire. In this default mode IP addresses are distributed
 1415: pseudo-randomly over the entire available address range. There are
 1416: sometimes circumstances (typically server deployment) where it is more
 1417: convenient to have IP
 1418: addresses allocated sequentially, starting from the lowest available
 1419: address, and setting this flag enables this mode. Note that in the
 1420: sequential mode, clients which allow a lease to expire are much more
 1421: likely to move IP address; for this reason it should not be generally used.
 1422: .TP
 1423: .B --dhcp-ignore-clid
 1424: Dnsmasq is reading 'client identifier' (RFC 2131) option sent by clients
 1425: (if available) to identify clients. This allow to serve same IP address
 1426: for a host using several interfaces. Use this option to disable 'client identifier'
 1427: reading, i.e. to always identify a host using the MAC address.
 1428: .TP
 1429: .B --pxe-service=[tag:<tag>,]<CSA>,<menu text>[,<basename>|<bootservicetype>][,<server address>|<server_name>]
 1430: Most uses of PXE boot-ROMS simply allow the PXE
 1431: system to obtain an IP address and then download the file specified by
 1432: .B --dhcp-boot
 1433: and execute it. However the PXE system is capable of more complex
 1434: functions when supported by a suitable DHCP server.
 1435: 
 1436: This specifies a boot option which may appear in a PXE boot menu. <CSA> is
 1437: client system type, only services of the correct type will appear in a
 1438: menu. The known types are x86PC, PC98, IA64_EFI, Alpha, Arc_x86,
 1439: Intel_Lean_Client, IA32_EFI,  X86-64_EFI, Xscale_EFI, BC_EFI, ARM32_EFI and ARM64_EFI; an
 1440: integer may be used for other types. The
 1441: parameter after the menu text may be a file name, in which case dnsmasq acts as a
 1442: boot server and directs the PXE client to download the file by TFTP,
 1443: either from itself (
 1444: .B --enable-tftp
 1445: must be set for this to work) or another TFTP server if the final server
 1446: address/name is given.
 1447: Note that the "layer"
 1448: suffix (normally ".0") is supplied by PXE, and need not be added to
 1449: the basename. Alternatively, the basename may be a filename, complete with suffix, in which case
 1450: no layer suffix is added. If an integer boot service type, rather than a basename
 1451: is given, then the PXE client will search for a
 1452: suitable boot service for that type on the network. This search may be done
 1453: by broadcast, or direct to a server if its IP address/name is provided.  
 1454: If no boot service type or filename is provided (or a boot service type of 0 is specified)
 1455: then the menu entry will abort the net boot procedure and
 1456: continue booting from local media. The server address can be given as a domain
 1457: name which is looked up in /etc/hosts. This name can be associated in
 1458: /etc/hosts with multiple IP addresses, which are used round-robin.
 1459: .TP
 1460: .B --pxe-prompt=[tag:<tag>,]<prompt>[,<timeout>]
 1461: Setting this provides a prompt to be displayed after PXE boot. If the
 1462: timeout is given then after the
 1463: timeout has elapsed with no keyboard input, the first available menu
 1464: option will be automatically executed. If the timeout is zero then the first available menu
 1465: item will be executed immediately. If 
 1466: .B --pxe-prompt
 1467: is omitted the system will wait for user input if there are multiple
 1468: items in the menu, but boot immediately if
 1469: there is only one. See
 1470: .B --pxe-service
 1471: for details of menu items.
 1472: 
 1473: Dnsmasq supports PXE "proxy-DHCP", in this case another DHCP server on
 1474: the network is responsible for allocating IP addresses, and dnsmasq
 1475: simply provides the information given in 
 1476: .B --pxe-prompt
 1477: and
 1478: .B --pxe-service
 1479: to allow netbooting. This mode is enabled using the
 1480: .B proxy
 1481: keyword in
 1482: .B --dhcp-range.
 1483: .TP
 1484: .B --dhcp-pxe-vendor=<vendor>[,...]
 1485: According to UEFI and PXE specifications, DHCP packets between PXE clients and
 1486: proxy PXE servers should have 
 1487: .I PXEClient 
 1488: in their vendor-class field. However, the firmware of computers from a few
 1489: vendors is customized to carry a different identifier in that field. This option
 1490: is used to consider such identifiers valid for identifying PXE clients. For 
 1491: instance
 1492: 
 1493: .B --dhcp-pxe-vendor=PXEClient,HW-Client
 1494: 
 1495: will enable dnsmasq to also provide proxy PXE service to those PXE clients with
 1496: .I HW-Client
 1497: in as their identifier.
 1498: >>>>>>> 907def3... pxe: support pxe clients with custom vendor-class
 1499: .TP  
 1500: .B \-X, --dhcp-lease-max=<number>
 1501: Limits dnsmasq to the specified maximum number of DHCP leases. The
 1502: default is 1000. This limit is to prevent DoS attacks from hosts which
 1503: create thousands of leases and use lots of memory in the dnsmasq
 1504: process.
 1505: .TP
 1506: .B \-K, --dhcp-authoritative
 1507: Should be set when dnsmasq is definitely the only DHCP server on a network.
 1508: For DHCPv4, it changes the behaviour from strict RFC compliance so that DHCP requests on
 1509: unknown leases from unknown hosts are not ignored. This allows new hosts
 1510: to get a lease without a tedious timeout under all circumstances. It also 
 1511: allows dnsmasq to rebuild its lease database without each client needing to 
 1512: reacquire a lease, if the database is lost. For DHCPv6 it sets the
 1513: priority in replies to 255 (the maximum) instead of 0 (the minimum).
 1514: .TP
 1515: .B --dhcp-rapid-commit
 1516: Enable DHCPv4 Rapid Commit Option specified in RFC 4039. When enabled, dnsmasq
 1517: will respond to a DHCPDISCOVER message including a Rapid Commit
 1518: option with a DHCPACK including a Rapid Commit option and fully committed
 1519: address and configuration information. Should only be enabled if either the
 1520: server is  the only server for the subnet, or multiple servers are present and they each commit a binding for all clients.
 1521: .TP
 1522: .B --dhcp-alternate-port[=<server port>[,<client port>]]
 1523: (IPv4 only) Change the ports used for DHCP from the default. If this option is
 1524: given alone, without arguments, it changes the ports used for DHCP
 1525: from 67 and 68 to 1067 and 1068. If a single argument is given, that
 1526: port number is used for the server and the port number plus one used
 1527: for the client. Finally, two port numbers allows arbitrary
 1528: specification of both server and client ports for DHCP.
 1529: .TP
 1530: .B \-3, --bootp-dynamic[=<network-id>[,<network-id>]]
 1531: (IPv4 only) Enable dynamic allocation of IP addresses to BOOTP clients. Use this
 1532: with care, since each address allocated to a BOOTP client is leased
 1533: forever, and therefore becomes permanently unavailable for re-use by
 1534: other hosts. if this is given without tags, then it unconditionally
 1535: enables dynamic allocation. With tags, only when the tags are all
 1536: set. It may be repeated with different tag sets. 
 1537: .TP
 1538: .B \-5, --no-ping
 1539: (IPv4 only) By default, the DHCP server will attempt to ensure that an address is
 1540: not in use before allocating it to a host. It does this by sending an
 1541: ICMP echo request (aka "ping") to the address in question. If it gets
 1542: a reply, then the address must already be in use, and another is
 1543: tried. This flag disables this check. Use with caution.
 1544: .TP
 1545: .B --log-dhcp
 1546: Extra logging for DHCP: log all the options sent to DHCP clients and
 1547: the tags used to determine them.
 1548: .TP
 1549: .B --quiet-dhcp, --quiet-dhcp6, --quiet-ra
 1550: Suppress logging of the routine operation of these protocols. Errors and
 1551: problems will still be logged. \fB--quiet-dhcp\fP and quiet-dhcp6 are
 1552: over-ridden by \fB--log-dhcp\fP.
 1553: .TP
 1554: .B \-l, --dhcp-leasefile=<path>
 1555: Use the specified file to store DHCP lease information.
 1556: .TP 
 1557: .B --dhcp-duid=<enterprise-id>,<uid>
 1558: (IPv6 only) Specify the server persistent UID which the DHCPv6 server
 1559: will use. This option is not normally required as dnsmasq creates a
 1560: DUID automatically when it is first needed. When given, this option
 1561: provides dnsmasq the data required to create a DUID-EN type DUID. Note
 1562: that once set, the DUID is stored in the lease database, so to change between DUID-EN and
 1563: automatically created DUIDs or vice-versa, the lease database must be
 1564: re-initialised. The enterprise-id is assigned by IANA, and the uid is a
 1565: string of hex octets unique to a particular device.
 1566: .TP
 1567: .B \-6 --dhcp-script=<path>
 1568: Whenever a new DHCP lease is created, or an old one destroyed, or a
 1569: TFTP file transfer completes, the
 1570: executable specified by this option is run.  <path>
 1571: must be an absolute pathname, no PATH search occurs. 
 1572: The arguments to the process
 1573: are "add", "old" or "del", the MAC
 1574: address of the host (or DUID for IPv6) , the IP address, and the hostname,
 1575: if known. "add" means a lease has been created, "del" means it has
 1576: been destroyed, "old" is a notification of an existing lease when
 1577: dnsmasq starts or a change to MAC address or hostname of an existing
 1578: lease (also, lease length or expiry and client-id, if \fB--leasefile-ro\fP is set
 1579: and lease expiry if \fB--script-on-renewal\fP is set).
 1580: If the MAC address is from a network type other than ethernet,
 1581: it will have the network type prepended, eg "06-01:23:45:67:89:ab" for
 1582: token ring. The process is run as root (assuming that dnsmasq was originally run as
 1583: root) even if dnsmasq is configured to change UID to an unprivileged user.
 1584: 
 1585: The environment is inherited from the invoker of dnsmasq, with some or
 1586: all of the following variables added
 1587: 
 1588: For both IPv4 and IPv6:
 1589: 
 1590: DNSMASQ_DOMAIN if the fully-qualified domain name of the host is
 1591: known, this is set to the  domain part. (Note that the hostname passed
 1592: to the script as an argument is never fully-qualified.)
 1593: 
 1594: If the client provides a hostname, DNSMASQ_SUPPLIED_HOSTNAME
 1595: 
 1596: If the client provides user-classes, DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn 
 1597: 
 1598: If dnsmasq was compiled with HAVE_BROKEN_RTC, then
 1599: the length of the lease (in seconds) is stored in
 1600: DNSMASQ_LEASE_LENGTH, otherwise the time of lease expiry is stored in
 1601: DNSMASQ_LEASE_EXPIRES. The number of seconds until lease expiry is
 1602: always stored in DNSMASQ_TIME_REMAINING. 
 1603: 
 1604: If a lease used to have a hostname, which is
 1605: removed, an "old" event is generated with the new state of the lease, 
 1606: ie no name, and the former name is provided in the environment 
 1607: variable DNSMASQ_OLD_HOSTNAME. 
 1608: 
 1609: DNSMASQ_INTERFACE stores the name of
 1610: the interface on which the request arrived; this is not set for "old"
 1611: actions when dnsmasq restarts. 
 1612: 
 1613: DNSMASQ_RELAY_ADDRESS is set if the client
 1614: used a DHCP relay to contact dnsmasq and the IP address of the relay
 1615: is known. 
 1616: 
 1617: DNSMASQ_TAGS contains all the tags set during the
 1618: DHCP transaction, separated by spaces.
 1619: 
 1620: DNSMASQ_LOG_DHCP is set if
 1621: .B --log-dhcp
 1622: is in effect.
 1623: 
 1624: For IPv4 only:
 1625: 
 1626: DNSMASQ_CLIENT_ID if the host provided a client-id.
 1627: 
 1628: DNSMASQ_CIRCUIT_ID, DNSMASQ_SUBSCRIBER_ID, DNSMASQ_REMOTE_ID if a
 1629: DHCP relay-agent added any of these options.
 1630:  
 1631: If the client provides vendor-class, DNSMASQ_VENDOR_CLASS.
 1632: 
 1633: DNSMASQ_REQUESTED_OPTIONS a string containing the decimal values in the Parameter Request List option, comma separated, if the parameter request list option is provided by the client.
 1634: 
 1635: For IPv6 only:
 1636: 
 1637: If the client provides vendor-class, DNSMASQ_VENDOR_CLASS_ID,
 1638: containing the IANA enterprise id for the class, and
 1639: DNSMASQ_VENDOR_CLASS0..DNSMASQ_VENDOR_CLASSn for the data.
 1640: 
 1641: DNSMASQ_SERVER_DUID containing the DUID of the server: this is the same for
 1642: every call to the script.
 1643: 
 1644: DNSMASQ_IAID containing the IAID for the lease. If the lease is a
 1645: temporary allocation, this is prefixed to 'T'.
 1646: 
 1647: DNSMASQ_MAC containing the MAC address of the client, if known.
 1648: 
 1649: Note that the supplied hostname, vendorclass and userclass data is
 1650: only  supplied for
 1651: "add" actions or "old" actions when a host resumes an existing lease,
 1652: since these data are not held in dnsmasq's lease
 1653: database.
 1654: 
 1655: 
 1656: 
 1657: All file descriptors are
 1658: closed except stdin, which is open to /dev/null, and stdout and stderr which capture output for logging by dnsmasq. 
 1659: (In debug mode, stdio, stdout and stderr file are left as those inherited from the invoker of dnsmasq).
 1660: 
 1661: The script is not invoked concurrently: at most one instance
 1662: of the script is ever running (dnsmasq waits for an instance of script to exit
 1663: before running the next). Changes to the lease database are which
 1664: require the script to be invoked are queued awaiting exit of a running instance.
 1665: If this queueing allows multiple state changes occur to a single
 1666: lease before the script can be run then 
 1667: earlier states are discarded and the current state of that lease is
 1668: reflected when the script finally runs. 
 1669: 
 1670: At dnsmasq startup, the script will be invoked for
 1671: all existing leases as they are read from the lease file. Expired
 1672: leases will be called with "del" and others with "old". When dnsmasq
 1673: receives a HUP signal, the script will be invoked for existing leases
 1674: with an "old" event.
 1675: 
 1676: 
 1677: There are four further actions which may appear as the first argument
 1678: to the script, "init", "arp-add", "arp-del" and "tftp". More may be added in the future, so
 1679: scripts should be written to ignore unknown actions. "init" is
 1680: described below in 
 1681: .B --leasefile-ro
 1682: The "tftp" action is invoked when a TFTP file transfer completes: the
 1683: arguments are the file size in bytes, the address to which the file
 1684: was sent, and the complete pathname of the file.
 1685:  
 1686: The "arp-add" and "arp-del" actions are only called if enabled with
 1687: .B --script-arp
 1688: They are are supplied with a MAC address and IP address as arguments. "arp-add" indicates
 1689: the arrival of a new entry in the ARP or neighbour table, and "arp-del" indicates the deletion of same.
 1690: 
 1691: .TP
 1692: .B --dhcp-luascript=<path>
 1693: Specify a script written in Lua, to be run when leases are created,
 1694: destroyed or changed. To use this option, dnsmasq must be compiled
 1695: with the correct support. The Lua interpreter is initialised once, when
 1696: dnsmasq starts, so that global variables persist between lease
 1697: events. The Lua code must define a
 1698: .B lease
 1699: function, and may provide
 1700: .B init
 1701: and
 1702: .B shutdown
 1703: functions, which are called, without arguments when dnsmasq starts up
 1704: and terminates. It may also provide a 
 1705: .B tftp
 1706: function.
 1707: 
 1708: The 
 1709: .B lease
 1710: function receives the information detailed in 
 1711: .B --dhcp-script. 
 1712: It gets two arguments, firstly the action, which is a string
 1713: containing, "add", "old" or "del", and secondly a table of tag value
 1714: pairs. The tags mostly correspond to the environment variables
 1715: detailed above, for instance the tag "domain" holds the same data as
 1716: the environment variable DNSMASQ_DOMAIN. There are a few extra tags
 1717: which hold the data supplied as arguments to
 1718: .B --dhcp-script. 
 1719: These are 
 1720: .B mac_address, ip_address
 1721: and 
 1722: .B hostname
 1723: for IPv4, and 
 1724: .B client_duid, ip_address
 1725: and 
 1726: .B hostname
 1727: for IPv6.
 1728: 
 1729: The  
 1730: .B tftp
 1731: function is called in the same way as the lease function, and the
 1732: table holds the tags 
 1733: .B destination_address,
 1734: .B file_name
 1735: and 
 1736: .B file_size.
 1737: 
 1738: The 
 1739: .B arp
 1740: and
 1741: .B arp-old
 1742: functions are called only when enabled with
 1743: .B --script-arp
 1744: and have a table which holds the tags
 1745: .B mac_address
 1746: and
 1747: .B client_address.
 1748: .TP
 1749: .B --dhcp-scriptuser
 1750: Specify the user as which to run the lease-change script or Lua script. This defaults to root, but can be changed to another user using this flag. 
 1751: .TP
 1752: .B --script-arp
 1753: Enable the "arp" and "arp-old" functions in the \fB--dhcp-script\fP and \fB--dhcp-luascript\fP.
 1754: .TP
 1755: .B \-9, --leasefile-ro
 1756: Completely suppress use of the lease database file. The file will not
 1757: be created, read, or written. Change the way the lease-change
 1758: script (if one is provided) is called, so that the lease database may
 1759: be maintained in external storage by the script. In addition to the
 1760: invocations  given in 
 1761: .B  --dhcp-script
 1762: the lease-change script is called once, at dnsmasq startup, with the
 1763: single argument "init". When called like this the script should write
 1764: the saved state of the lease database, in dnsmasq leasefile format, to
 1765: stdout and exit with zero exit code. Setting this
 1766: option also forces the leasechange script to be called on changes
 1767: to the client-id and lease length and expiry time.
 1768: .TP
 1769: .B --script-on-renewal
 1770: Call the DHCP script when the lease expiry time changes, for instance when the
 1771: lease is renewed.
 1772: .TP
 1773: .B --bridge-interface=<interface>,<alias>[,<alias>]
 1774: Treat DHCP (v4 and v6) requests and IPv6 Router Solicit packets
 1775: arriving at any of the <alias> interfaces as if they had arrived at
 1776: <interface>.  This option allows dnsmasq to provide DHCP and RA
 1777: service over unaddressed and unbridged Ethernet interfaces, e.g. on an
 1778: OpenStack compute host where each such interface is a TAP interface to
 1779: a VM, or as in "old style bridging" on BSD platforms.  A trailing '*'
 1780: wildcard can be used in each <alias>.
 1781: 
 1782: It is permissible to add more than one alias using more than one \fB--bridge-interface\fP option since
 1783: \fB--bridge-interface=int1,alias1,alias2\fP is exactly equivalent to
 1784: \fB--bridge-interface=int1,alias1 --bridge-interface=int1,alias2\fP
 1785: .TP
 1786: .B --shared-network=<interface>,<addr>
 1787: .PD 0
 1788: .TP
 1789: .B --shared-network=<addr>,<addr>
 1790: .PD 1v
 1791: The DHCP server determines which DHCP ranges are useable for allocating an
 1792: address to a DHCP client based on the network from which the DHCP request arrives,
 1793: and the IP configuration of the server's interface on that network. The shared-network
 1794: option extends the available subnets (and therefore DHCP ranges) beyond the
 1795: subnets configured on the arrival interface.
 1796: 
 1797: The first argument is either the
 1798: name of an interface, or an address that is configured on a local interface, and the
 1799: second argument is an address which defines another subnet on which addresses can be allocated.
 1800: 
 1801: To be useful, there must be a suitable dhcp-range which allows address allocation on this subnet
 1802: and this dhcp-range MUST include the netmask.
 1803: 
 1804: Using shared-network also needs extra
 1805: consideration of routing. Dnsmasq does not have the usual information that it uses to
 1806: determine the default route, so the default route option (or other routing) MUST be
 1807: configured manually. The client must have a route to the server: if the two-address form
 1808: of shared-network is used, this needs to be to the first specified address. If the interface,address
 1809: form is used, there must be a route to all of the addresses configured on the interface.
 1810: 
 1811: The two-address form of shared-network is also usable with a DHCP relay: the first address
 1812: is the address of the relay and the second, as before, specifies an extra subnet which
 1813: addresses may be allocated from.
 1814: 
 1815: .TP
 1816: .B \-s, --domain=<domain>[,<address range>[,local]]
 1817: Specifies DNS domains for the DHCP server. Domains may be be given 
 1818: unconditionally (without the IP range) or for limited IP ranges. This has two effects;
 1819: firstly it causes the DHCP server to return the domain to any hosts
 1820: which request it, and secondly it sets the domain which it is legal
 1821: for DHCP-configured hosts to claim. The intention is to constrain
 1822: hostnames so that an untrusted host on the LAN cannot advertise 
 1823: its name via DHCP as e.g. "microsoft.com" and capture traffic not 
 1824: meant for it. If no domain suffix is specified, then any DHCP
 1825: hostname with a domain part (ie with a period) will be disallowed 
 1826: and logged. If suffix is specified, then hostnames with a domain 
 1827: part are allowed, provided the domain part matches the suffix. In
 1828: addition, when a suffix is set then hostnames without a domain
 1829: part have the suffix added as an optional domain part. Eg on my network I can set 
 1830: .B --domain=thekelleys.org.uk
 1831: and have a machine whose DHCP hostname is "laptop". The IP address for that machine is available from 
 1832: .B dnsmasq
 1833: both as "laptop" and "laptop.thekelleys.org.uk". If the domain is
 1834: given as "#" then the domain is read from the first "search" directive
 1835: in /etc/resolv.conf (or equivalent).
 1836: 
 1837: The address range can be of the form
 1838: <ip address>,<ip address> or <ip address>/<netmask> or just a single
 1839: <ip address>. See 
 1840: .B --dhcp-fqdn
 1841: which can change the behaviour of dnsmasq with domains.
 1842: 
 1843: If the address range is given as ip-address/network-size, then a
 1844: additional flag "local" may be supplied which has the effect of adding
 1845: \fB--local\fP declarations for forward and reverse DNS queries. Eg.
 1846: .B --domain=thekelleys.org.uk,192.168.0.0/24,local
 1847: is identical to
 1848: .B --domain=thekelleys.org.uk,192.168.0.0/24
 1849: .B --local=/thekelleys.org.uk/ --local=/0.168.192.in-addr.arpa/
 1850: The network size must be 8, 16 or 24 for this to be legal.
 1851: .TP
 1852: .B --dhcp-fqdn
 1853: In the default mode, dnsmasq inserts the unqualified names of
 1854: DHCP clients into the DNS. For this reason, the names must be unique,
 1855: even if two clients which have the same name are in different
 1856: domains. If a second DHCP client appears which has the same name as an
 1857: existing client, the name is transferred to the new client. If 
 1858: .B --dhcp-fqdn
 1859: is set, this behaviour changes: the unqualified name is no longer
 1860: put in the DNS, only the qualified name. Two DHCP clients with the
 1861: same name may both keep the name, provided that the domain part is
 1862: different (ie the fully qualified names differ.) To ensure that all
 1863: names have a domain part, there must be at least 
 1864: .B --domain 
 1865: without an address specified when 
 1866: .B --dhcp-fqdn 
 1867: is set.
 1868: .TP
 1869: .B --dhcp-client-update
 1870: Normally, when giving a DHCP lease, dnsmasq sets flags in the FQDN
 1871: option to tell the client not to attempt a DDNS update with its name
 1872: and IP address. This is because the name-IP pair is automatically
 1873: added into dnsmasq's DNS view. This flag suppresses that behaviour,
 1874: this is useful, for instance, to allow Windows clients to update
 1875: Active Directory servers. See RFC 4702 for details. 
 1876: .TP
 1877: .B --enable-ra
 1878: Enable dnsmasq's IPv6 Router Advertisement feature. DHCPv6 doesn't
 1879: handle complete network configuration in the same way as DHCPv4. Router
 1880: discovery and (possibly) prefix discovery for autonomous address
 1881: creation are handled by a different protocol. When DHCP is in use,
 1882: only a subset of this is needed, and dnsmasq can handle it, using
 1883: existing DHCP configuration to provide most data. When RA is enabled,
 1884: dnsmasq will advertise a prefix for each \fB--dhcp-range\fP, with default
 1885: router  as the relevant link-local address on 
 1886: the machine running dnsmasq. By default, the "managed address" bits are set, and
 1887: the "use SLAAC" bit is reset. This can be changed for individual
 1888: subnets with the mode keywords described in
 1889: .B --dhcp-range.
 1890: RFC6106 DNS parameters are included in the advertisements. By default,
 1891: the relevant link-local address of the machine running dnsmasq is sent
 1892: as recursive DNS server. If provided, the DHCPv6 options dns-server and
 1893: domain-search are used for the DNS server (RDNSS) and the domain search list (DNSSL).
 1894: .TP
 1895: .B --ra-param=<interface>,[mtu:<integer>|<interface>|off,][high,|low,]<ra-interval>[,<router lifetime>]
 1896: Set non-default values for router advertisements sent via an
 1897: interface. The priority field for the router may be altered from the
 1898: default of medium with eg
 1899: .B --ra-param=eth0,high.
 1900: The interval between router advertisements may be set (in seconds) with 
 1901: .B --ra-param=eth0,60.
 1902: The lifetime of the route may be changed or set to zero, which allows
 1903: a router to advertise prefixes but not a route via itself. 
 1904: .B --ra-param=eth0,0,0
 1905: (A value of zero for the interval means the default value.) All four parameters may be set at once.
 1906: .B --ra-param=eth0,mtu:1280,low,60,1200
 1907: 
 1908: The interface field may include a wildcard.
 1909: 
 1910: The mtu: parameter may be an arbitrary interface name, in which case the MTU value for that interface is used. This is useful
 1911: for (eg) advertising the MTU of a WAN interface on the other interfaces of a router.
 1912: .TP
 1913: .B --dhcp-reply-delay=[tag:<tag>,]<integer>
 1914: Delays sending DHCPOFFER and PROXYDHCP replies for at least the specified number of seconds.
 1915: This can be used as workaround for bugs in PXE boot firmware that does not function properly when
 1916: receiving an instant reply.
 1917: This option takes into account the time already spent waiting (e.g. performing ping check) if any.
 1918: .TP
 1919: .B --enable-tftp[=<interface>[,<interface>]]
 1920: Enable the TFTP server function. This is deliberately limited to that
 1921: needed to net-boot a client. Only reading is allowed; the tsize and
 1922: blksize extensions are supported (tsize is only supported in octet
 1923: mode). Without an argument, the TFTP service is provided to the same set of interfaces as DHCP service. 
 1924: If the list of interfaces is provided, that defines which interfaces receive TFTP service.
 1925: .TP
 1926: .B --tftp-root=<directory>[,<interface>]
 1927: Look for files to transfer using TFTP relative to the given
 1928: directory. When this is set, TFTP paths which include ".." are
 1929: rejected, to stop clients getting outside the specified root.
 1930: Absolute paths (starting with /) are allowed, but they must be within
 1931: the tftp-root. If the optional interface argument is given, the
 1932: directory is only used for TFTP requests via that interface.
 1933: .TP
 1934: .B --tftp-no-fail
 1935: Do not abort startup if specified tftp root directories are inaccessible.
 1936: .TP
 1937: .B --tftp-unique-root[=ip|mac]
 1938: Add the IP or hardware address of the TFTP client as a path component on the end
 1939: of the TFTP-root. Only valid if a \fB--tftp-root\fP is set and the directory exists.
 1940: Defaults to adding IP address (in standard dotted-quad format).
 1941: For instance, if \fB--tftp-root\fP is "/tftp" and client 1.2.3.4 requests file "myfile"
 1942: then the effective path will be "/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4 exists or /tftp/myfile otherwise.
 1943: When "=mac" is specified it will append the MAC address instead, using lowercase zero padded digits
 1944: separated by dashes, e.g.: 01-02-03-04-aa-bb
 1945: Note that resolving MAC addresses is only possible if the client is in the local network or obtained
 1946: a DHCP lease from us.
 1947: .TP
 1948: .B --tftp-secure
 1949: Enable TFTP secure mode: without this, any file which is readable by
 1950: the dnsmasq process under normal unix access-control rules is
 1951: available via TFTP. When the \fB--tftp-secure\fP flag is given, only files
 1952: owned by the user running the dnsmasq process are accessible. If
 1953: dnsmasq is being run as root, different rules apply: \fB--tftp-secure\fP
 1954: has no effect, but only files which have the world-readable bit set
 1955: are accessible. It is not recommended to run dnsmasq as root with TFTP
 1956: enabled, and certainly not without specifying \fB--tftp-root\fP. Doing so
 1957: can expose any world-readable file on the server to any host on the net. 
 1958: .TP
 1959: .B --tftp-lowercase
 1960: Convert filenames in TFTP requests to all lowercase. This is useful
 1961: for requests from Windows machines, which have case-insensitive
 1962: filesystems and tend to play fast-and-loose with case in filenames.
 1963: Note that dnsmasq's tftp server always converts "\\" to "/" in filenames.
 1964: .TP
 1965: .B --tftp-max=<connections>
 1966: Set the maximum number of concurrent TFTP connections allowed. This
 1967: defaults to 50. When serving a large number of TFTP connections,
 1968: per-process file descriptor limits may be encountered. Dnsmasq needs
 1969: one file descriptor for each concurrent TFTP connection and one
 1970: file descriptor per unique file (plus a few others). So serving the
 1971: same file simultaneously to n clients will use require about n + 10 file
 1972: descriptors, serving different files simultaneously to n clients will
 1973: require about (2*n) + 10 descriptors. If 
 1974: .B --tftp-port-range
 1975: is given, that can affect the number of concurrent connections.
 1976: .TP
 1977: .B --tftp-mtu=<mtu size>
 1978: Use size as the ceiling of the MTU supported by the intervening network when 
 1979: negotiating TFTP blocksize, overriding the MTU setting of the local interface  if it is larger.
 1980: .TP
 1981: .B --tftp-no-blocksize
 1982: Stop the TFTP server from negotiating the "blocksize" option with a
 1983: client. Some buggy clients request this option but then behave badly
 1984: when it is granted.
 1985: .TP
 1986: .B --tftp-port-range=<start>,<end>
 1987: A TFTP server listens on a well-known port (69) for connection initiation,
 1988: but it also uses a dynamically-allocated port for each
 1989: connection. Normally these are allocated by the OS, but this option
 1990: specifies a range of ports for use by TFTP transfers. This can be
 1991: useful when TFTP has to traverse a firewall. The start of the range
 1992: cannot be lower than 1025 unless dnsmasq is running as root. The number
 1993: of concurrent TFTP connections is limited by the size of the port range. 
 1994: .TP
 1995: .B --tftp-single-port
 1996: Run in a mode where the TFTP server uses ONLY the well-known port (69) for its end
 1997: of the TFTP transfer. This allows TFTP to work when there in NAT is the path between client and server. Note that
 1998: this is not strictly compliant with the RFCs specifying the TFTP protocol: use at your own risk.
 1999: .TP
 2000: .B \-C, --conf-file=<file>
 2001: Specify a configuration file. The presence of this option stops dnsmasq from reading the default configuration
 2002: file (normally /etc/dnsmasq.conf). Multiple files may be specified by repeating the option
 2003: either on the command line or in configuration files. A
 2004: filename of "-" causes dnsmasq to read configuration from stdin.
 2005: .TP
 2006: .B \-7, --conf-dir=<directory>[,<file-extension>......],
 2007: Read all the files in the given directory as configuration
 2008: files. If extension(s) are given, any files which end in those
 2009: extensions are skipped. Any files whose names end in ~ or start with . or start and end
 2010: with # are always skipped. If the extension starts with * then only files 
 2011: which have that extension are loaded. So
 2012: .B --conf-dir=/path/to/dir,*.conf
 2013: loads all files with the suffix .conf in /path/to/dir. This flag may be given on the command
 2014: line or in a configuration file. If giving it on the command line, be sure to
 2015: escape * characters. Files are loaded in alphabetical order of filename.
 2016: .TP
 2017: .B --servers-file=<file>
 2018: A special case of 
 2019: .B --conf-file
 2020: which differs in two respects. Firstly, only \fB--server\fP and \fB--rev-server\fP are allowed
 2021: in the configuration file included. Secondly, the file is re-read and the configuration
 2022: therein is updated when dnsmasq receives SIGHUP.
 2023: .SH CONFIG FILE
 2024: At startup, dnsmasq reads
 2025: .I /etc/dnsmasq.conf,
 2026: if it exists. (On
 2027: FreeBSD, the file is 
 2028: .I /usr/local/etc/dnsmasq.conf
 2029: ) (but see the 
 2030: .B \--conf-file
 2031: and
 2032: .B \--conf-dir
 2033: options.) The format of this
 2034: file consists of one option per line, exactly as the long options detailed 
 2035: in the OPTIONS section but without the leading "--". Lines starting with # are comments and ignored. For
 2036: options which may only be specified once, the configuration file overrides 
 2037: the command line.  Quoting is allowed in a config file:
 2038: between " quotes the special meanings of ,:. and # are removed and the
 2039: following escapes are allowed: \\\\ \\" \\t \\e \\b \\r and \\n. The later 
 2040: corresponding to tab, escape, backspace, return and newline.
 2041: .SH NOTES
 2042: When it receives a SIGHUP, 
 2043: .B dnsmasq 
 2044: clears its cache and then re-loads 
 2045: .I /etc/hosts
 2046: and 
 2047: .I /etc/ethers 
 2048: and any file given by \fB--dhcp-hostsfile\fP, \fB--dhcp-hostsdir\fP, \fB--dhcp-optsfile\fP,
 2049: \fB--dhcp-optsdir\fP, \fB--addn-hosts\fP or \fB--hostsdir\fP.
 2050: The DHCP lease change script is called for all
 2051: existing DHCP leases. If 
 2052: .B
 2053: --no-poll
 2054: is set SIGHUP also re-reads
 2055: .I /etc/resolv.conf.
 2056: SIGHUP
 2057: does NOT re-read the configuration file.
 2058: .PP
 2059: When it receives a SIGUSR1,
 2060: .B dnsmasq 
 2061: writes statistics to the system log. It writes the cache size,
 2062: the number of names which have had to removed from the cache before
 2063: they expired in order to make room for new names and the total number
 2064: of names that have been inserted into the cache. The number of cache hits and 
 2065: misses and the number of authoritative queries answered are also given. For each upstream
 2066: server it gives the number of queries sent, and the number which
 2067: resulted in an error. In 
 2068: .B --no-daemon
 2069: mode or when full logging is enabled (\fB--log-queries\fP), a complete dump of the
 2070: contents of the cache is made. 
 2071: 
 2072: The cache statistics are also available in the DNS as answers to 
 2073: queries of class CHAOS and type TXT in domain bind. The domain names are cachesize.bind, insertions.bind, evictions.bind, 
 2074: misses.bind, hits.bind, auth.bind and servers.bind. An example command to query this, using the 
 2075: .B dig
 2076: utility would be
 2077: 
 2078: dig +short chaos txt cachesize.bind
 2079: 
 2080: .PP 
 2081: When it receives SIGUSR2 and it is logging direct to a file (see
 2082: .B --log-facility
 2083: ) 
 2084: .B dnsmasq
 2085: will close and reopen the log file. Note that during this operation,
 2086: dnsmasq will not be running as root. When it first creates the logfile
 2087: dnsmasq changes the ownership of the file to the non-root user it will run
 2088: as. Logrotate should be configured to create a new log file with
 2089: the ownership which matches the existing one before sending SIGUSR2.
 2090: If TCP DNS queries are in progress, the old logfile will remain open in
 2091: child processes which are handling TCP queries and may continue to be
 2092: written. There is a limit of 150 seconds, after which all existing TCP
 2093: processes will have expired: for this reason, it is not wise to
 2094: configure logfile compression for logfiles which have just been
 2095: rotated. Using logrotate, the required options are 
 2096: .B create 
 2097: and
 2098: .B delaycompress.
 2099: 
 2100:  
 2101: .PP
 2102: Dnsmasq is a DNS query forwarder: it is not capable of recursively
 2103: answering arbitrary queries starting from the root servers but
 2104: forwards such queries to a fully recursive upstream DNS server which is
 2105: typically provided by an ISP. By default, dnsmasq reads
 2106: .I /etc/resolv.conf
 2107: to discover the IP
 2108: addresses of the upstream nameservers it should use, since the
 2109: information is typically stored there. Unless
 2110: .B --no-poll
 2111: is used,
 2112: .B dnsmasq
 2113: checks the modification time of
 2114: .I /etc/resolv.conf
 2115: (or equivalent if 
 2116: .B \--resolv-file 
 2117: is used) and re-reads it if it changes. This allows the DNS servers to
 2118: be set dynamically by PPP or DHCP since both protocols provide the
 2119: information.
 2120: Absence of
 2121: .I /etc/resolv.conf
 2122: is not an error
 2123: since it may not have been created before a PPP connection exists. Dnsmasq 
 2124: simply keeps checking in case
 2125: .I /etc/resolv.conf 
 2126: is created at any
 2127: time. Dnsmasq can be told to parse more than one resolv.conf
 2128: file. This is useful on a laptop, where both PPP and DHCP may be used:
 2129: dnsmasq can be set to poll both 
 2130: .I /etc/ppp/resolv.conf 
 2131: and
 2132: .I /etc/dhcpc/resolv.conf 
 2133: and will use the contents of whichever changed
 2134: last, giving automatic switching between DNS servers.
 2135: .PP
 2136: Upstream servers may also be specified on the command line or in
 2137: the configuration file. These server specifications optionally take a
 2138: domain name which tells dnsmasq to use that server only to find names
 2139: in that particular domain.
 2140: .PP
 2141: In order to configure dnsmasq to act as cache for the host on which it is running, put "nameserver 127.0.0.1" in
 2142: .I /etc/resolv.conf
 2143: to force local processes to send queries to
 2144: dnsmasq. Then either specify the upstream servers directly to dnsmasq
 2145: using 
 2146: .B \--server
 2147: options or put their addresses real in another file, say
 2148: .I /etc/resolv.dnsmasq
 2149: and run dnsmasq with the 
 2150: .B \--resolv-file /etc/resolv.dnsmasq
 2151: option. This second technique allows for dynamic update of the server
 2152: addresses by PPP or DHCP.
 2153: .PP
 2154: Addresses in /etc/hosts will "shadow" different addresses for the same
 2155: names in the upstream DNS, so "mycompany.com 1.2.3.4" in /etc/hosts will ensure that
 2156: queries for "mycompany.com" always return 1.2.3.4 even if queries in
 2157: the upstream DNS would otherwise return a different address. There is
 2158: one exception to this: if the upstream DNS contains a CNAME which
 2159: points to a shadowed name, then looking up the CNAME through dnsmasq
 2160: will result in the unshadowed address associated with the target of
 2161: the CNAME. To work around this, add the CNAME to /etc/hosts so that
 2162: the CNAME is shadowed too.
 2163: 
 2164: .PP
 2165: The tag system works as follows: For each DHCP request, dnsmasq
 2166: collects a set of valid tags from active configuration lines which
 2167: include set:<tag>, including one from the 
 2168: .B --dhcp-range
 2169: used to allocate the address, one from any matching 
 2170: .B --dhcp-host
 2171: (and "known" or "known-othernet" if a \fB--dhcp-host\fP matches)
 2172: The tag "bootp" is set for BOOTP requests, and a tag whose name is the 
 2173: name of the interface on which the request arrived is also set.
 2174: 
 2175: Any configuration lines which include one or more tag:<tag> constructs
 2176: will only be valid if all that tags are matched in the set derived
 2177: above. Typically this is \fB--dhcp-option\fP.
 2178: .B --dhcp-option
 2179: which has tags will be used in preference  to an untagged 
 2180: .B --dhcp-option,
 2181: provided that _all_ the tags match somewhere in the
 2182: set collected as described above. The prefix '!' on a tag means 'not'
 2183: so \fB--dhcp-option=tag:!purple,3,1.2.3.4\fP sends the option when the
 2184: tag purple is not in the set of valid tags. (If using this in a
 2185: command line rather than a configuration file, be sure to escape !,
 2186: which is a shell metacharacter)
 2187: 
 2188: When selecting \fB--dhcp-options\fP, a tag from \fB--dhcp-range\fP is second class
 2189: relative to other tags, to make it easy to override options for
 2190: individual hosts, so 
 2191: .B --dhcp-range=set:interface1,......
 2192: .B --dhcp-host=set:myhost,.....
 2193: .B --dhcp-option=tag:interface1,option:nis-domain,"domain1"
 2194: .B --dhcp-option=tag:myhost,option:nis-domain,"domain2"
 2195: will set the NIS-domain to domain1 for hosts in the range, but
 2196: override that to domain2 for a particular host.
 2197: 
 2198: .PP
 2199: Note that for 
 2200: .B --dhcp-range
 2201: both tag:<tag> and set:<tag> are allowed, to both select the range in
 2202: use based on (eg) \fB--dhcp-host\fP, and to affect the options sent, based on
 2203: the range selected.
 2204: 
 2205: This system evolved from an earlier, more limited one and for backward
 2206: compatibility "net:" may be used instead of "tag:" and "set:" may be
 2207: omitted. (Except in 
 2208: .B --dhcp-host,
 2209: where "net:" may be used instead of "set:".) For the same reason, '#'
 2210: may be used instead of '!' to indicate NOT.
 2211: .PP 
 2212: The DHCP server in dnsmasq will function as a BOOTP server also,
 2213: provided that the MAC address and IP address for clients are given,
 2214: either using 
 2215: .B --dhcp-host
 2216: configurations or in
 2217: .I /etc/ethers
 2218: , and a
 2219: .B --dhcp-range
 2220: configuration option is present to activate the DHCP server
 2221: on a particular network. (Setting \fB--bootp-dynamic\fP removes the need for
 2222: static address mappings.) The filename
 2223: parameter in a BOOTP request is used as a tag,
 2224: as is the tag "bootp", allowing some control over the options returned to
 2225: different classes of hosts.
 2226: 
 2227: .SH AUTHORITATIVE CONFIGURATION
 2228: Configuring dnsmasq to act as an authoritative DNS server is
 2229: complicated by the fact that it involves configuration of external DNS
 2230: servers to provide delegation. We will walk through three scenarios of
 2231: increasing complexity. Prerequisites for all of these scenarios
 2232: are a globally accessible IP address, an A or AAAA record pointing to that address,
 2233: and an external DNS server capable of doing delegation of the zone in
 2234: question. For the first part of this explanation, we will call the A (or AAAA) record
 2235: for the globally accessible address server.example.com, and the zone
 2236: for which dnsmasq is authoritative our.zone.com.
 2237: 
 2238: The simplest configuration consists of two lines of dnsmasq configuration; something like
 2239: 
 2240: .nf
 2241: .B --auth-server=server.example.com,eth0
 2242: .B --auth-zone=our.zone.com,1.2.3.0/24
 2243: .fi
 2244: 
 2245: and two records in the external DNS
 2246: 
 2247: .nf
 2248: server.example.com       A    192.0.43.10
 2249: our.zone.com            NS    server.example.com
 2250: .fi
 2251: 
 2252: eth0 is the external network interface on which dnsmasq is listening,
 2253: and has (globally accessible) address 192.0.43.10. 
 2254: 
 2255: Note that the external IP address may well be dynamic (ie assigned
 2256: from an ISP by DHCP or PPP) If so, the A record must be linked to this
 2257: dynamic assignment by one of the usual dynamic-DNS systems.
 2258: 
 2259: A more complex, but practically useful configuration has the address
 2260: record for the globally accessible IP address residing in the
 2261: authoritative zone which dnsmasq is serving, typically at the root. Now
 2262: we have
 2263: 
 2264: .nf
 2265: .B --auth-server=our.zone.com,eth0
 2266: .B --auth-zone=our.zone.com,1.2.3.0/24
 2267: .fi
 2268: 
 2269: .nf
 2270: our.zone.com             A    1.2.3.4
 2271: our.zone.com            NS    our.zone.com
 2272: .fi
 2273: 
 2274: The A record for our.zone.com has now become a glue record, it solves
 2275: the chicken-and-egg problem of finding the IP address of the
 2276: nameserver for our.zone.com when the A record is within that
 2277: zone. Note that this is the only role of this record: as dnsmasq is
 2278: now authoritative from our.zone.com it too must provide this
 2279: record. If the external address is static, this can be done with an
 2280: .B /etc/hosts 
 2281: entry or 
 2282: .B --host-record.
 2283: 
 2284: .nf
 2285: .B --auth-server=our.zone.com,eth0
 2286: .B --host-record=our.zone.com,1.2.3.4
 2287: .B --auth-zone=our.zone.com,1.2.3.0/24
 2288: .fi
 2289: 
 2290: If the external address is dynamic, the address
 2291: associated with our.zone.com must be derived from the address of the
 2292: relevant interface. This is done using 
 2293: .B --interface-name
 2294: Something like:
 2295: 
 2296: .nf
 2297: .B --auth-server=our.zone.com,eth0
 2298: .B --interface-name=our.zone.com,eth0
 2299: .B --auth-zone=our.zone.com,1.2.3.0/24,eth0
 2300: .fi
 2301: 
 2302: (The "eth0" argument in \fB--auth-zone\fP adds the subnet containing eth0's
 2303: dynamic address to the zone, so that the \fB--interface-name\fP returns the
 2304: address in outside queries.)
 2305: 
 2306: Our final configuration builds on that above, but also adds a
 2307: secondary DNS server. This is another DNS server which learns the DNS data
 2308: for the zone by doing zones transfer, and acts as a backup should
 2309: the primary server become inaccessible. The configuration of the
 2310: secondary is beyond the scope of this man-page, but the extra
 2311: configuration of dnsmasq is simple:
 2312: 
 2313: .nf
 2314: .B --auth-sec-servers=secondary.myisp.com
 2315: .fi
 2316: 
 2317: and
 2318: 
 2319: .nf
 2320: our.zone.com           NS    secondary.myisp.com
 2321: .fi
 2322: 
 2323: Adding auth-sec-servers enables zone transfer in dnsmasq, to allow the
 2324: secondary to collect the DNS data. If you wish to restrict this data
 2325: to particular hosts then
 2326: 
 2327: .nf
 2328: .B --auth-peer=<IP address of secondary>
 2329: .fi
 2330: 
 2331: will do so.
 2332: 
 2333: Dnsmasq acts as an authoritative server for  in-addr.arpa and
 2334: ip6.arpa domains associated with the subnets given in \fB--auth-zone\fP
 2335: declarations, so reverse (address to name) lookups can be simply
 2336: configured with a suitable NS record, for instance in this example,
 2337: where we allow 1.2.3.0/24 addresses.
 2338: 
 2339: .nf
 2340:  3.2.1.in-addr.arpa  NS    our.zone.com
 2341: .fi
 2342: 
 2343: Note that at present, reverse (in-addr.arpa and ip6.arpa) zones are
 2344: not available in zone transfers, so there is no point arranging
 2345: secondary servers for reverse lookups.
 2346: 
 2347: .PP
 2348: When dnsmasq is configured to act as an authoritative server, the
 2349: following data is used to populate the authoritative zone.
 2350: .PP
 2351: .B --mx-host, --srv-host, --dns-rr, --txt-record, --naptr-record, --caa-record,
 2352: as long as the record names are in the authoritative domain.
 2353: .PP
 2354: .B --cname
 2355: as long as the record name is in  the authoritative domain. If the
 2356: target of the CNAME is unqualified, then it  is qualified with the
 2357: authoritative zone name. CNAME used in this way (only) may be wildcards, as in
 2358: 
 2359: .nf
 2360: .B --cname=*.example.com,default.example.com
 2361: .fi
 2362: 
 2363: .PP
 2364: IPv4 and IPv6 addresses from /etc/hosts (and 
 2365: .B --addn-hosts
 2366: ) and
 2367: .B --host-record
 2368: and 
 2369: .B --interface-name
 2370: provided the address falls into one of the subnets specified in the
 2371: .B --auth-zone.
 2372: .PP
 2373: Addresses of DHCP leases, provided the address falls into one of the subnets specified in the
 2374: .B --auth-zone.
 2375: (If constructed DHCP ranges are is use, which depend on the address dynamically 
 2376: assigned to an interface, then the form of
 2377: .B --auth-zone
 2378: which defines subnets by the dynamic address of an interface should
 2379: be used to ensure this condition is met.)
 2380: .PP 
 2381: In the default mode, where a DHCP lease
 2382: has an unqualified name, and possibly a qualified name constructed
 2383: using 
 2384: .B --domain
 2385: then the name in the authoritative zone is constructed from the
 2386: unqualified name and the zone's domain. This may or may not equal
 2387: that specified by 
 2388: .B --domain.
 2389: If 
 2390: .B --dhcp-fqdn
 2391: is set, then the fully qualified names associated with DHCP leases are
 2392: used, and must match the zone's domain.
 2393:  
 2394: 
 2395: 
 2396: .SH EXIT CODES
 2397: 0 - Dnsmasq successfully forked into the background, or terminated
 2398: normally if backgrounding is not enabled.
 2399: .PP
 2400: 1 - A problem with configuration was detected.
 2401: .PP
 2402: 2 - A problem with network access occurred (address in use, attempt
 2403: to use privileged ports without permission).
 2404: .PP
 2405: 3 - A problem occurred with a filesystem operation (missing
 2406: file/directory, permissions).
 2407: .PP
 2408: 4 - Memory allocation failure.
 2409: .PP
 2410: 5 - Other miscellaneous problem.
 2411: .PP
 2412: 11 or greater - a non zero return code was received from the
 2413: lease-script process "init" call. The exit code from dnsmasq is the
 2414: script's exit code with 10 added. 
 2415: 
 2416: .SH LIMITS
 2417: The default values for resource limits in dnsmasq are generally
 2418: conservative, and appropriate for embedded router type devices with
 2419: slow processors and limited memory. On more capable hardware, it is
 2420: possible to increase the limits, and handle many more clients. The
 2421: following applies to dnsmasq-2.37: earlier versions did not scale as well.
 2422:  
 2423: .PP
 2424: Dnsmasq is capable of handling DNS and DHCP for at least a thousand
 2425: clients. The DHCP lease times should not be very short (less than one hour). The
 2426: value of 
 2427: .B --dns-forward-max 
 2428: can be increased: start with it equal to
 2429: the number of clients and increase if DNS seems slow. Note that DNS
 2430: performance depends too on the performance of the upstream
 2431: nameservers. The size of the DNS cache may be increased: the hard
 2432: limit is 10000 names and the default (150) is very low. Sending
 2433: SIGUSR1 to dnsmasq makes it log information which is useful for tuning
 2434: the cache size. See the 
 2435: .B NOTES
 2436: section for details.
 2437: 
 2438: .PP
 2439: The built-in TFTP server is capable of many simultaneous file
 2440: transfers: the absolute limit is related to the number of file-handles
 2441: allowed to a process and the ability of the select() system call to
 2442: cope with large numbers of file handles. If the limit is set too high
 2443: using 
 2444: .B --tftp-max
 2445: it will be scaled down and the actual limit logged at
 2446: start-up. Note that more transfers are possible when the same file is
 2447: being sent than when each transfer sends a different file.
 2448: 
 2449: .PP
 2450: It is possible to use dnsmasq to block Web advertising by using a list
 2451: of known banner-ad servers, all resolving to 127.0.0.1 or 0.0.0.0, in
 2452: .B /etc/hosts 
 2453: or an additional hosts file. The list can be very long, 
 2454: dnsmasq has been tested successfully with one million names. That size
 2455: file needs a 1GHz processor and about 60Mb of RAM.
 2456: 
 2457: .SH INTERNATIONALISATION
 2458: Dnsmasq can be compiled to support internationalisation. To do this,
 2459: the make targets "all-i18n" and "install-i18n" should be used instead of
 2460: the standard targets "all" and "install". When internationalisation
 2461: is compiled in, dnsmasq will produce log messages in the local
 2462: language and support internationalised domain names (IDN). Domain
 2463: names in /etc/hosts, /etc/ethers and /etc/dnsmasq.conf which contain
 2464: non-ASCII characters will be translated to the DNS-internal punycode
 2465: representation. Note that
 2466: dnsmasq determines both the language for messages and the assumed
 2467: charset for configuration
 2468: files from the LANG environment variable. This should be set to the system
 2469: default value by the script which is responsible for starting
 2470: dnsmasq. When editing the configuration files, be careful to do so
 2471: using only the system-default locale and not user-specific one, since
 2472: dnsmasq has no direct way of determining the charset in use, and must
 2473: assume that it is the system default. 
 2474:  
 2475: .SH FILES
 2476: .IR /etc/dnsmasq.conf 
 2477: 
 2478: .IR /usr/local/etc/dnsmasq.conf
 2479: 
 2480: .IR /etc/resolv.conf
 2481: .IR /var/run/dnsmasq/resolv.conf
 2482: .IR /etc/ppp/resolv.conf
 2483: .IR /etc/dhcpc/resolv.conf
 2484: 
 2485: .IR /etc/hosts
 2486: 
 2487: .IR /etc/ethers
 2488: 
 2489: .IR /var/lib/misc/dnsmasq.leases 
 2490: 
 2491: .IR /var/db/dnsmasq.leases
 2492: 
 2493: .IR /var/run/dnsmasq.pid
 2494: .SH SEE ALSO
 2495: .BR hosts (5), 
 2496: .BR resolver (5)
 2497: .SH AUTHOR
 2498: This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.
 2499: 
 2500: