diff options
Diffstat (limited to 'man/dnsmasq.8')
| -rw-r--r-- | man/dnsmasq.8 | 356 |
1 files changed, 241 insertions, 115 deletions
diff --git a/man/dnsmasq.8 b/man/dnsmasq.8 index c8913b5..bd99b48 100644 --- a/man/dnsmasq.8 +++ b/man/dnsmasq.8 @@ -30,7 +30,7 @@ DHCPv4 server, and in addition, it includes router advertisements and a neat feature which allows nameing for clients which use DHCPv4 and 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. .PP -Dnsmasq is coded with small embedded systems in mind. It aims for the smallest possible memory footprint compatible with the supported functions, and allows uneeded functions to be omitted from the compiled binary. +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. .SH OPTIONS Note that in general missing parameters are allowed and switch off functions, for instance "--pid-file" disables writing a PID file. On @@ -42,6 +42,13 @@ the configuration file. Read and syntax check configuration file(s). Exit with code 0 if all is OK, or a non-zero code otherwise. Do not start up dnsmasq. .TP +.B \-w, --help +Display all command-line options. +.B --help dhcp +will display known DHCPv4 configuration options, and +.B --help dhcp6 +will display DHCPv6 options. +.TP .B \-h, --no-hosts Don't read the hostnames in /etc/hosts. .TP @@ -60,7 +67,7 @@ in the same way as for DHCP-derived names. Note that this does not apply to domain names in cnames, PTR records, TXT records etc. .TP .B \-T, --local-ttl=<time> -When replying with information from /etc/hosts or the DHCP leases +When replying with information from /etc/hosts or configuration or the DHCP leases file dnsmasq by default sets the time-to-live field to zero, meaning that the requester should not itself cache the information. This is the correct thing to do in almost all situations. This option allows a @@ -68,6 +75,9 @@ time-to-live (in seconds) to be given for these replies. This will reduce the load on the server at the expense of clients using stale data under some circumstances. .TP +.B --dhcp-ttl=<time> +As for --local-ttl, but affects only replies with information from DHCP leases. If both are given, --dhcp-ttl applies for DHCP information, and --local-ttl for others. Setting this to zero eliminates the effect of --local-ttl for DHCP. +.TP .B --neg-ttl=<time> Negative replies from upstream servers normally contain time-to-live information in SOA records which dnsmasq uses for caching. If the @@ -172,8 +182,16 @@ OS: this was the default behaviour in versions prior to 2.43. Do not use ports less than that given as source for outbound DNS queries. Dnsmasq picks random ports as source for outbound queries: when this option is given, the ports used will always to larger -than that specified. Useful for systems behind firewalls. +than that specified. Useful for systems behind firewalls. If not specified, +defaults to 1024. +.TP +.B --max-port=<port> +Use ports lower than that given as source for outbound DNS queries. +Dnsmasq picks random ports as source for outbound queries: +when this option is given, the ports used will always be lower +than that specified. Useful for systems behind firewalls. .TP + .B \-i, --interface=<interface name> Listen only on the specified interface(s). Dnsmasq automatically adds the loopback (local) interface to the list of interfaces to use when @@ -186,12 +204,17 @@ or options are given dnsmasq listens on all available interfaces except any given in .B \--except-interface -options. IP alias interfaces (eg "eth1:0") cannot be used with -.B --interface +options. On Linux, when +.B \--bind-interfaces or -.B --except-interface -options, use --listen-address instead. A simple wildcard, consisting -of a trailing '*', can be used in +.B \--bind-dynamic +are in effect, IP alias interface labels (eg "eth1:0") are checked, rather than +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 +allows control over which of those addresses are accepted. +The same effect is achievable in default mode by using +.B \--listen-address. +A simple wildcard, consisting of a trailing '*', +can be used in .B \--interface and .B \--except-interface @@ -205,7 +228,9 @@ and .B --except-interface options does not matter and that .B --except-interface -options always override the others. +options always override the others. The comments about interface labels for +.B --listen-address +apply here. .TP .B --auth-server=<domain>,<interface>|<ip-address> Enable DNS authoritative mode for queries arriving at an interface or address. Note that the interface or address @@ -215,9 +240,9 @@ or .B --listen-address configuration, indeed .B --auth-server -will overide these and provide a different DNS service on the +will override these and provide a different DNS service on the specified interface. The <domain> is the "glue record". It should -resolve in the global DNS to a A and/or AAAA record which points to +resolve in the global DNS to an A and/or AAAA record which points to the address dnsmasq is listening on. When an interface is specified, it may be qualified with "/4" or "/6" to specify only the IPv4 or IPv6 addresses associated with the interface. @@ -225,7 +250,7 @@ addresses associated with the interface. .B --local-service Accept DNS queries only from hosts whose address is on a local subnet, ie a subnet for which an interface exists on the server. This option -only has effect is there are no --interface --except-interface, +only has effect if there are no --interface --except-interface, --listen-address or --auth-server options. It is intended to be set as a default on installation, to allow unconfigured installations to be useful but also safe from being used for DNS amplification attacks. @@ -272,8 +297,8 @@ option requires non-standard networking APIs and it is only available under Linux. On other platforms it falls-back to --bind-interfaces mode. .TP .B \-y, --localise-queries -Return answers to DNS queries from /etc/hosts which depend on the interface over which the query was -received. If a name in /etc/hosts has more than one address associated with +Return answers to DNS queries from /etc/hosts and --interface-name which depend on the interface over which the query was +received. If a name has more than one address associated with it, and at least one of those addresses is on the same subnet as the interface to which the query was sent, then return only the address(es) on that subnet. This allows for a server to have multiple @@ -284,7 +309,8 @@ attached to. Currently this facility is limited to IPv4. .B \-b, --bogus-priv Bogus private reverse lookups. All reverse lookups for private IP ranges (ie 192.168.x.x, etc) which are not found in /etc/hosts or the DHCP leases file are answered -with "no such domain" rather than being forwarded upstream. +with "no such domain" rather than being forwarded upstream. The +set of prefixes affected is the list given in RFC6303, for IPv4 and IPv6. .TP .B \-V, --alias=[<old-ip>]|[<start-ip>-<end-ip>],<new-ip>[,<mask>] Modify IPv4 addresses returned from upstream nameservers; old-ip is @@ -307,7 +333,7 @@ instead of the correct NXDOMAIN response. This option tells dnsmasq to fake the correct response when it sees this behaviour. As at Sept 2003 the IP address being returned by Verisign is 64.94.110.11 .TP -.B \-B, --ignore-address=<ipaddr> +.B --ignore-address=<ipaddr> Ignore replies to A-record queries which include the specified address. No error is generated, dnsmasq simply continues to listen for another reply. This is useful to defeat blocking strategies which rely on quickly supplying a @@ -405,7 +431,10 @@ xxx.internal.thekelleys.org.uk at 192.168.1.1 then giving the flag .B -S /internal.thekelleys.org.uk/192.168.1.1 will send all queries for internal machines to that nameserver, everything else will go to the -servers in /etc/resolv.conf. An empty domain specification, +servers in /etc/resolv.conf. DNSSEC validation is turned off for such +private nameservers, UNLESS a +.B --trust-anchor +is specified for the domain in question. An empty domain specification, .B // has the special meaning of "unqualified names only" ie names without any dots in them. A non-standard port may be specified as @@ -414,7 +443,7 @@ address using a # character. More than one -S flag is allowed, with repeated domain or ipaddr parts as required. -More specific domains take precendence over less specific domains, so: +More specific domains take precedence over less specific domains, so: .B --server=/google.com/1.2.3.4 .B --server=/www.google.com/2.3.4.5 will send queries for *.google.com to 1.2.3.4, except *www.google.com, @@ -436,17 +465,17 @@ is a synonym for .B server to make configuration files clearer in this case. -IPv6 addresses may include a %interface scope-id, eg +IPv6 addresses may include an %interface scope-id, eg fe80::202:a412:4512:7bbf%eth0. -The optional string after the @ character tells -dnsmasq how to set the source of the queries to this -nameserver. It should be an ip-address, which should belong to the machine on which -dnsmasq is running otherwise this server line will be logged and then -ignored, or an interface name. If an interface name is given, then -queries to the server will be forced via that interface; if an -ip-address is given then the source address of the queries will be set -to that address. +The optional string after the @ character tells dnsmasq how to set the source of +the queries to this nameserver. It can either be an ip-address, an interface +name or both. The ip-address should belong to the machine on which dnsmasq is +running, otherwise this server line will be logged and then ignored. If an +interface name is given, then queries to the server will be forced via that +interface; if an ip-address is given then the source address of the queries will +be set to that address; and if both are given then a combination of ip-address +and interface name will be used to steer requests to the server. The query-port flag is ignored for any servers which have a source address specified but the port may be specified directly as part of the source address. Forcing queries to an interface is not @@ -460,28 +489,36 @@ but provides some syntactic sugar to make specifying address-to-name queries eas is exactly equivalent to .B --server=/3.2.1.in-addr.arpa/192.168.0.1 .TP -.B \-A, --address=/<domain>/[domain/][<ipaddr>] +.B \-A, --address=/<domain>[/<domain>...]/[<ipaddr>] Specify an IP address to return for any host in the given domains. Queries in the domains are never forwarded and always replied to with the specified IP address which may be IPv4 or IPv6. To give -both IPv4 and IPv6 addresses for a domain, use repeated -A flags. +both IPv4 and IPv6 addresses for a domain, use repeated \fB-A\fP flags. +To include multiple IP addresses for a single query, use +\fB--addn-hosts=<path>\fP instead. Note that /etc/hosts and DHCP leases override this for individual names. A common use of this is to redirect the entire doubleclick.net domain to some friendly local web server to avoid banner ads. The -domain specification works in the same was as for --server, with the -additional facility that /#/ matches any domain. Thus ---address=/#/1.2.3.4 will always return 1.2.3.4 for any query not -answered from /etc/hosts or DHCP and not sent to an upstream -nameserver by a more specific --server directive. As for --server, -one or more domains with no address returns a no-such-domain answer, so ---address=/example.com/ is equivalent to --server=/example.com/ and returns -NXDOMAIN for example.com and all its subdomains. -.TP -.B --ipset=/<domain>/[domain/]<ipset>[,<ipset>] -Places the resolved IP addresses of queries for the specified domains -in the specified netfilter ip sets. Domains and subdomains are matched -in the same way as --address. These ip sets must already exist. See -ipset(8) for more details. +domain specification works in the same was as for \fB--server\fP, with +the additional facility that \fB/#/\fP matches any domain. Thus +\fB--address=/#/1.2.3.4\fP will always return \fB1.2.3.4\fP for any +query not answered from \fB/etc/hosts\fP or DHCP and not sent to an +upstream nameserver by a more specific \fB--server\fP directive. As for +\fB--server\fP, one or more domains with no address returns a +no-such-domain answer, so \fB--address=/example.com/\fP is equivalent to +\fB--server=/example.com/\fP and returns NXDOMAIN for example.com and +all its subdomains. +.TP +.B --ipset=/<domain>[/<domain>...]/<ipset>[,<ipset>...] +Places the resolved IP addresses of queries for one or more domains in +the specified Netfilter IP set. If multiple setnames are given, then the +addresses are placed in each of them, subject to the limitations of an +IP set (IPv4 addresses cannot be stored in an IPv6 IP set and vice +versa). Domains and subdomains are matched in the same way as +\fB--address\fP. +These IP sets must already exist. See +.BR ipset (8) +for more details. .TP .B \-m, --mx-host=<mx name>[[,<hostname>],<preference>] Return an MX record named <mx name> pointing to the given hostname (if @@ -519,7 +556,7 @@ zone files: the port, weight and priority numbers are in a different order. More than one SRV record for a given service/domain is allowed, all that match are returned. .TP -.B --host-record=<name>[,<name>....],[<IPv4-address>],[<IPv6-address>] +.B --host-record=<name>[,<name>....],[<IPv4-address>],[<IPv6-address>][,<TTL>] Add A, AAAA and PTR records to the DNS. This adds one or more names to the DNS with associated IPv4 (A) and IPv6 (AAAA) records. A name may appear in more than one @@ -536,6 +573,10 @@ is in effect. Short and long names may appear in the same .B host-record, eg. .B --host-record=laptop,laptop.thekelleys.org,192.168.0.1,1234::100 + +If the time-to-live is given, it overrides the default, which is zero +or the value of --local-ttl. The value is a positive integer and gives +the time-to-live in seconds. .TP .B \-Y, --txt-record=<name>[[,<text>],<text>] Return a TXT DNS record. The value of TXT record is a set of strings, @@ -549,7 +590,7 @@ Return a PTR DNS record. .B --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<regexp>[,<replacement>] Return an NAPTR DNS record, as specified in RFC3403. .TP -.B --cname=<cname>,<target> +.B --cname=<cname>,[<cname>,]<target>[,<TTL>] Return a CNAME record which indicates that <cname> is really <target>. There are significant limitations on the target; it must be a DNS name which is known to dnsmasq from /etc/hosts (or additional @@ -557,7 +598,13 @@ hosts files), from DHCP, from --interface-name or from another .B --cname. If the target does not satisfy this criteria, the whole cname is ignored. The cname must be unique, but it -is permissable to have more than one cname pointing to the same target. +is permissible to have more than one cname pointing to the same target. Indeed +it's possible to declare multiple cnames to a target in a single line, like so: +.B --cname=cname1,cname2,target + +If the time-to-live is given, it overrides the default, which is zero +or the value of -local-ttl. The value is a positive integer and gives +the time-to-live in seconds. .TP .B --dns-rr=<name>,<RR-number>,[<hex data>] Return an arbitrary DNS Resource Record. The number is the type of the @@ -566,7 +613,7 @@ given by the hex data, which may be of the form 01:23:45 or 01 23 45 or 012345 or any mixture of these. .TP .B --interface-name=<name>,<interface>[/4|/6] -Return a DNS record associating the name with the primary address on +Return DNS records associating the name with the address(es) of the given interface. This flag specifies an A or AAAA record for the given name in the same way as an /etc/hosts line, except that the address is not constant, but taken from the given interface. The interface may be @@ -576,25 +623,31 @@ down, not configured or non-existent, an empty record is returned. The matching PTR record is also created, mapping the interface address to the name. More than one name may be associated with an interface address by repeating the flag; in that case the first instance is used -for the reverse address-to-name mapping. +for the reverse address-to-name mapping. Note that a name used in +--interface-name may not appear in /etc/hosts. .TP -.B --synth-domain=<domain>,<address range>[,<prefix>] +.B --synth-domain=<domain>,<address range>[,<prefix>[*]] Create artificial A/AAAA and PTR records for an address range. The -records use the address, with periods (or colons for IPv6) replaced -with dashes. +records either seqential numbers or the address, with periods (or colons for IPv6) replaced with dashes. -An example should make this clearer. -.B --synth-domain=thekelleys.org.uk,192.168.0.0/24,internal- +An examples should make this clearer. First sequential numbers. +.B --synth-domain=thekelleys.org.uk,192.168.0.50,192.168.0.70,internal-* +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. + +Second, +.B --synth-domain=thekelleys.org.uk,192.168.0.0/24,internal- (no *) will result in a query for internal-192-168-0-56.thekelleys.org.uk returning 192.168.0.56 and a reverse query vice versa. The same applies to IPv6, but IPv6 addresses may start with '::' but DNS labels may not start with '-' so in this case if no prefix is configured a zero is added in front of the label. ::1 becomes 0--1. +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 + The address range can be of the form -<ip address>,<ip address> or <ip address>/<netmask> +<ip address>,<ip address> or <ip address>/<netmask> in both forms of the option. .TP -.B --add-mac +.B --add-mac[=base64|text] Add the MAC address of the requestor to DNS queries which are forwarded upstream. This may be used to DNS filtering by the upstream server. The MAC address can only be added if the requestor is on the same @@ -602,19 +655,34 @@ subnet as the dnsmasq server. Note that the mechanism used to achieve this (an E is not yet standardised, so this should be considered experimental. Also note that exposing MAC addresses in this way may have security and privacy implications. The warning about caching -given for --add-subnet applies to --add-mac too. +given for --add-subnet applies to --add-mac too. An alternative encoding of the +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. +.TP +.B --add-cpe-id=<string> +Add an arbitrary identifying string to o DNS queries which are +forwarded upstream. .TP -.B --add-subnet[[=<IPv4 prefix length>],<IPv6 prefix length>] -Add the subnet address of the requestor to the DNS queries which are -forwarded upstream. The amount of the address forwarded depends on the -prefix length parameter: 32 (128 for IPv6) forwards the whole address, -zero forwards none of it but still marks the request so that no -upstream nameserver will add client address information either. The -default is zero for both IPv4 and IPv6. Note that upstream nameservers -may be configured to return different results based on this -information, but the dnsmasq cache does not take account. If a dnsmasq -instance is configured such that different results may be encountered, -caching should be disabled. +.B --add-subnet[[=[<IPv4 address>/]<IPv4 prefix length>][,[<IPv6 address>/]<IPv6 prefix length>]] +Add a subnet address to the DNS queries which are forwarded +upstream. If an address is specified in the flag, it will be used, +otherwise, the address of the requestor will be used. The amount of +the address forwarded depends on the prefix length parameter: 32 (128 +for IPv6) forwards the whole address, zero forwards none of it but +still marks the request so that no upstream nameserver will add client +address information either. The default is zero for both IPv4 and +IPv6. Note that upstream nameservers may be configured to return +different results based on this information, but the dnsmasq cache +does not take account. If a dnsmasq instance is configured such that +different results may be encountered, caching should be disabled. + +For example, +.B --add-subnet=24,96 +will add the /24 and /96 subnets of the requestor for IPv4 and IPv6 requestors, respectively. +.B --add-subnet=1.2.3.4/24 +will add 1.2.3.0/24 for IPv4 requestors and ::/0 for IPv6 requestors. +.B --add-subnet=1.2.3.4/24,1.2.3.4/24 +will add 1.2.3.0/24 for both IPv4 and IPv6 requestors. + .TP .B \-c, --cache-size=<cachesize> Set the size of dnsmasq's cache. The default is 150 names. Setting the cache size to zero disables caching. @@ -644,15 +712,15 @@ permitted to reduce the cache size below the default when DNSSEC is enabled. The nameservers upstream of dnsmasq must be DNSSEC-capable, ie capable of returning DNSSEC records with data. If they are not, then dnsmasq will not be able to determine the trusted status of -answers. In the default mode, this menas that all replies will be +answers. In the default mode, this means that all replies will be marked as untrusted. If .B --dnssec-check-unsigned is set and the upstream servers don't support DNSSEC, then DNS service will be entirely broken. .TP .B --trust-anchor=[<class>],<domain>,<key-tag>,<algorithm>,<digest-type>,<digest> Provide DS records to act a trust anchors for DNSSEC -validation. Typically these will be the DS record(s) for Zone Signing -key(s) of the root zone, +validation. Typically these will be the DS record(s) for Key Signing +key(s) (KSK) of the root zone, but trust anchors for limited domains are also possible. The current root-zone trust anchors may be downloaded from https://data.iana.org/root-anchors/root-anchors.xml .TP @@ -672,10 +740,14 @@ section on DNSSEC signatures are only valid for specified time windows, and should be rejected outside those windows. This generates an interesting chicken-and-egg problem for machines which don't have a hardware real time clock. For these machines to determine the correct time typically requires use of NTP and therefore DNS, but validating DNS requires that the correct time is already known. Setting this flag -removes the time-window checks (but not other DNSSEC validation.) only until the dnsmasq process receives SIGHUP. The intention is +removes the time-window checks (but not other DNSSEC validation.) only until the dnsmasq process receives SIGINT. The intention is that dnsmasq should be started with this flag when the platform determines that reliable time is not currently available. As soon as -reliable time is established, a SIGHUP should be sent to dnsmasq, which enables time checking, and purges the cache of DNS records -which have not been throughly checked. +reliable time is established, a SIGINT should be sent to dnsmasq, which enables time checking, and purges the cache of DNS records +which have not been thoroughly checked. + +Earlier versions of dnsmasq overloaded SIGHUP (which re-reads much configuration) to also enable time validation. + +If dnsmasq is run in debug mode (-d flag) then SIGINT retains its usual meaning of terminating the dnsmasq process. .TP .B --dnssec-timestamp=<path> Enables an alternative way of checking the validity of the system time for DNSSEC (see --dnssec-no-timecheck). In this case, the @@ -696,7 +768,7 @@ a return code of SERVFAIL. Note that setting this may affect DNS behaviour in bad ways, it is not an extra-logging flag and should not be set in production. .TP -.B --auth-zone=<domain>[,<subnet>[/<prefix length>][,<subnet>[/<prefix length>].....]] +.B --auth-zone=<domain>[,<subnet>[/<prefix length>][,<subnet>[/<prefix length>].....][,exclude:<subnet>[/<prefix length>]].....] Define a DNS zone for which dnsmasq acts as authoritative server. Locally defined DNS records which are in the domain will be served. If subnet(s) are given, A and AAAA records must be in one of the specified subnets. @@ -713,6 +785,10 @@ appear in the zone, but RFC1918 IPv4 addresses which should not. Interface-name and address-literal subnet specifications may be used freely in the same --auth-zone declaration. +It's possible to exclude certain IP addresses from responses. It can be +used, to make sure that answers contain only global routeable IP +addresses (by excluding loopback, RFC1918 and ULA addresses). + The subnet(s) are also used to define in-addr.arpa and ip6.arpa domains which are served for reverse-DNS queries. If not specified, the prefix length defaults to 24 for IPv4 and 64 for IPv6. @@ -747,7 +823,7 @@ compiled in and the kernel must have conntrack support included and configured. This option cannot be combined with --query-port. .TP -.B \-F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-addr>[,<end-addr>][,<mode>][,<netmask>[,<broadcast>]][,<lease time>] +.B \-F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-addr>[,<end-addr>|<mode>][,<netmask>[,<broadcast>]][,<lease time>] .TP .B \-F, --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag>,]<start-IPv6addr>[,<end-IPv6addr>|constructor:<interface>][,<mode>][,<prefix-len>][,<lease time>] @@ -779,7 +855,7 @@ For IPv6, the parameters are slightly different: instead of netmask and broadcast address, there is an optional prefix length which must be equal to or larger then the prefix length on the local interface. If not given, this defaults to 64. Unlike the IPv4 case, the prefix length is not -automatically derived from the interface configuration. The mimimum +automatically derived from the interface configuration. The minimum size of the prefix length is 64. 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 @@ -901,7 +977,7 @@ subnets which don't need a pool of dynamically allocated addresses, use the "static" keyword in the dhcp-range declaration. It is allowed to use client identifiers (called client -DUID in IPv6-land rather than +DUID in IPv6-land) rather than hardware addresses to identify hosts by prefixing with 'id:'. Thus: .B --dhcp-host=id:01:02:03:04,..... refers to the host with client identifier 01:02:03:04. It is also @@ -953,6 +1029,8 @@ dhcp-host directive (or one implied by /etc/ethers) then the special tag "known" is set. This allows dnsmasq to be configured to ignore requests from unknown machines using .B --dhcp-ignore=tag:!known +If the host matches only a dhcp-host directive which cannot +be used because it specifies an address on different subnet, the tag "known-othernet" is set. Ethernet addresses (but not client-ids) may have wildcard bytes, so for example .B --dhcp-host=00:20:e0:3b:13:*,ignore @@ -994,22 +1072,21 @@ is given, then read all the files contained in that directory. The advantage of using this option is the same as for --dhcp-hostsfile: the dhcp-optsfile will be re-read when dnsmasq receives SIGHUP. Note that it is possible to encode the information in a +.B --dhcp-boot +flag as DHCP options, using the options names bootfile-name, +server-ip-address and tftp-server. This allows these to be included +in a dhcp-optsfile. .TP .B --dhcp-hostsdir=<path> This is equivalent to dhcp-hostsfile, except for the following. The path MUST be a directory, and not an individual file. Changed or new files within the directory are read automatically, without the need to send SIGHUP. -If a file is deleted for changed after it has been read by dnsmasq, then the -host record it contained will remain until dnsmasq recieves a SIGHUP, or +If a file is deleted or changed after it has been read by dnsmasq, then the +host record it contained will remain until dnsmasq receives a SIGHUP, or is restarted; ie host records are only added dynamically. .TP .B --dhcp-optsdir=<path> This is equivalent to dhcp-optsfile, with the differences noted for --dhcp-hostsdir. -.TP -.B --dhcp-boot -flag as DHCP options, using the options names bootfile-name, -server-ip-address and tftp-server. This allows these to be included -in a dhcp-optsfile. .TP .B \-Z, --read-ethers Read /etc/ethers for information about hosts for the DHCP server. The @@ -1246,7 +1323,7 @@ Perform boolean operations on tags. Any tag appearing as set:<tag> is set if all the tags which appear as tag:<tag> are set, (or unset when tag:!<tag> is used) If no tag:<tag> appears set:<tag> tags are set unconditionally. Any number of set: and tag: forms may appear, in any order. -Tag-if lines ares executed in order, so if the tag in tag:<tag> is a +Tag-if lines are executed in order, so if the tag in tag:<tag> is a tag set by another .B tag-if, the line which sets the tag must precede the one which tests it. @@ -1315,7 +1392,7 @@ functions when supported by a suitable DHCP server. This specifies a boot option which may appear in a PXE boot menu. <CSA> is client system type, only services of the correct type will appear in a menu. The known types are x86PC, PC98, IA64_EFI, Alpha, Arc_x86, -Intel_Lean_Client, IA32_EFI, BC_EFI, Xscale_EFI and X86-64_EFI; an +Intel_Lean_Client, IA32_EFI, X86-64_EFI, Xscale_EFI, BC_EFI, ARM32_EFI and ARM64_EFI; an integer may be used for other types. The parameter after the menu text may be a file name, in which case dnsmasq acts as a boot server and directs the PXE client to download the file by TFTP, @@ -1324,8 +1401,9 @@ either from itself ( must be set for this to work) or another TFTP server if the final server address/name is given. Note that the "layer" -suffix (normally ".0") is supplied by PXE, and should not be added to -the basename. If an integer boot service type, rather than a basename +suffix (normally ".0") is supplied by PXE, and need not be added to +the basename. Alternatively, the basename may be a filename, complete with suffix, in which case +no layer suffix is added. If an integer boot service type, rather than a basename is given, then the PXE client will search for a suitable boot service for that type on the network. This search may be done by broadcast, or direct to a server if its IP address/name is provided. @@ -1416,7 +1494,7 @@ DUID automatically when it is first needed. When given, this option provides dnsmasq the data required to create a DUID-EN type DUID. Note that once set, the DUID is stored in the lease database, so to change between DUID-EN and automatically created DUIDs or vice-versa, the lease database must be -re-intialised. The enterprise-id is assigned by IANA, and the uid is a +re-initialised. The enterprise-id is assigned by IANA, and the uid is a string of hex octets unique to a particular device. .TP .B \-6 --dhcp-script=<path> @@ -1484,6 +1562,8 @@ DHCP relay-agent added any of these options. If the client provides vendor-class, DNSMASQ_VENDOR_CLASS. +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. + For IPv6 only: If the client provides vendor-class, DNSMASQ_VENDOR_CLASS_ID, @@ -1507,8 +1587,8 @@ database. All file descriptors are -closed except stdin, stdout and stderr which are open to /dev/null -(except in debug mode). +closed except stdin, which is open to /dev/null, and stdout and stderr which capture output for logging by dnsmasq. +(In debug mode, stdio, stdout and stderr file are left as those inherited from the invoker of dnsmasq). The script is not invoked concurrently: at most one instance of the script is ever running (dnsmasq waits for an instance of script to exit @@ -1523,11 +1603,11 @@ At dnsmasq startup, the script will be invoked for all existing leases as they are read from the lease file. Expired leases will be called with "del" and others with "old". When dnsmasq receives a HUP signal, the script will be invoked for existing leases -with an "old " event. +with an "old" event. -There are two further actions which may appear as the first argument -to the script, "init" and "tftp". More may be added in the future, so +There are four further actions which may appear as the first argument +to the script, "init", "arp-add", "arp-del" and "tftp". More may be added in the future, so scripts should be written to ignore unknown actions. "init" is described below in .B --leasefile-ro @@ -1535,11 +1615,16 @@ The "tftp" action is invoked when a TFTP file transfer completes: the arguments are the file size in bytes, the address to which the file was sent, and the complete pathname of the file. +The "arp-add" and "arp-del" actions are only called if enabled with +.B --script-arp +They are are supplied with a MAC address and IP address as arguments. "arp-add" indicates +the arrival of a new entry in the ARP or neighbour table, and "arp-del" indicates the deletion of same. + .TP .B --dhcp-luascript=<path> Specify a script written in Lua, to be run when leases are created, destroyed or changed. To use this option, dnsmasq must be compiled -with the correct support. The Lua interpreter is intialised once, when +with the correct support. The Lua interpreter is initialised once, when dnsmasq starts, so that global variables persist between lease events. The Lua code must define a .B lease @@ -1581,10 +1666,24 @@ table holds the tags .B file_name and .B file_size. + +The +.B arp +and +.B arp-old +functions are called only when enabled with +.B --script-arp +and have a table which holds the tags +.B mac_address +and +.B client_address. .TP .B --dhcp-scriptuser 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. -.TP +.TP +.B --script-arp +Enable the "arp" and "arp-old" functions in the dhcp-script and dhcp-luascript. +.TP .B \-9, --leasefile-ro Completely suppress use of the lease database file. The file will not be created, read, or written. Change the way the lease-change @@ -1600,13 +1699,17 @@ option also forces the leasechange script to be called on changes to the client-id and lease length and expiry time. .TP .B --bridge-interface=<interface>,<alias>[,<alias>] -Treat DHCP (v4 and v6) request and IPv6 Router Solicit packets +Treat DHCP (v4 and v6) requests and IPv6 Router Solicit packets arriving at any of the <alias> interfaces as if they had arrived at <interface>. This option allows dnsmasq to provide DHCP and RA service over unaddressed and unbridged Ethernet interfaces, e.g. on an OpenStack compute host where each such interface is a TAP interface to a VM, or as in "old style bridging" on BSD platforms. A trailing '*' wildcard can be used in each <alias>. + +It is permissible to add more than one alias using more than one --bridge-interface option since +--bridge-interface=int1,alias1,alias2 is exactly equivalent to +--bridge-interface=int1,alias1 --bridge-interface=int1,alias2 .TP .B \-s, --domain=<domain>[,<address range>[,local]] Specifies DNS domains for the DHCP server. Domains may be be given @@ -1677,17 +1780,17 @@ creation are handled by a different protocol. When DHCP is in use, only a subset of this is needed, and dnsmasq can handle it, using existing DHCP configuration to provide most data. When RA is enabled, dnsmasq will advertise a prefix for each dhcp-range, with default -router and recursive DNS server as the relevant link-local address on -the machine running dnsmasq. By default, he "managed address" bits are set, and +router as the relevant link-local address on +the machine running dnsmasq. By default, the "managed address" bits are set, and the "use SLAAC" bit is reset. This can be changed for individual subnets with the mode keywords described in .B --dhcp-range. RFC6106 DNS parameters are included in the advertisements. By default, the relevant link-local address of the machine running dnsmasq is sent as recursive DNS server. If provided, the DHCPv6 options dns-server and -domain-search are used for RDNSS and DNSSL. +domain-search are used for the DNS server (RDNSS) and the domain search list (DNSSL). .TP -.B --ra-param=<interface>,[high|low],[[<ra-interval>],<router lifetime>] +.B --ra-param=<interface>,[mtu:<integer>|<interface>|off,][high,|low,]<ra-interval>[,<router lifetime>] Set non-default values for router advertisements sent via an interface. The priority field for the router may be altered from the default of medium with eg @@ -1697,16 +1800,26 @@ The interval between router advertisements may be set (in seconds) with The lifetime of the route may be changed or set to zero, which allows a router to advertise prefixes but not a route via itself. .B --ra-parm=eth0,0,0 -(A value of zero for the interval means the default value.) All three parameters may be set at once. -.B --ra-param=low,60,1200 +(A value of zero for the interval means the default value.) All four parameters may be set at once. +.B --ra-param=eth0,mtu:1280,low,60,1200 + The interface field may include a wildcard. + +The mtu: parameter may be an arbitrary interface name, in which case the MTU value for that interface is used. This is useful +for (eg) advertising the MTU of a WAN interface on the other interfaces of a router. +.TP +.B --dhcp-reply-delay=[tag:<tag>,]<integer> +Delays sending DHCPOFFER and proxydhcp replies for at least the specified number of seconds. +This can be used as workaround for bugs in PXE boot firmware that does not function properly when +receiving an instant reply. +This option takes into account the time already spent waiting (e.g. performing ping check) if any. .TP .B --enable-tftp[=<interface>[,<interface>]] Enable the TFTP server function. This is deliberately limited to that needed to net-boot a client. Only reading is allowed; the tsize and blksize extensions are supported (tsize is only supported in octet mode). Without an argument, the TFTP service is provided to the same set of interfaces as DHCP service. -If the list of interfaces is provided, that defines which interfaces recieve TFTP service. +If the list of interfaces is provided, that defines which interfaces receive TFTP service. .TP .B --tftp-root=<directory>[,<interface>] Look for files to transfer using TFTP relative to the given @@ -1719,12 +1832,16 @@ directory is only used for TFTP requests via that interface. .B --tftp-no-fail Do not abort startup if specified tftp root directories are inaccessible. .TP -.B --tftp-unique-root -Add the IP address of the TFTP client as a path component on the end -of the TFTP-root (in standard dotted-quad format). Only valid if a -tftp-root is set and the directory exists. For instance, if tftp-root is "/tftp" and client -1.2.3.4 requests file "myfile" then the effective path will be -"/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4 exists or /tftp/myfile otherwise. +.B --tftp-unique-root[=ip|mac] +Add the IP or hardware address of the TFTP client as a path component on the end +of the TFTP-root. Only valid if a tftp-root is set and the directory exists. +Defaults to adding IP address (in standard dotted-quad format). +For instance, if tftp-root is "/tftp" and client 1.2.3.4 requests file "myfile" +then the effective path will be "/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4 exists or /tftp/myfile otherwise. +When "=mac" is specified it will append the MAC address instead, using lowercase zero padded digits +separated by dashes, e.g.: 01-02-03-04-aa-bb +Note that resolving MAC addresses is only possible if the client is in the local network or obtained +a DHCP lease from us. .TP .B --tftp-secure Enable TFTP secure mode: without this, any file which is readable by @@ -1755,6 +1872,10 @@ require about (2*n) + 10 descriptors. If .B --tftp-port-range is given, that can affect the number of concurrent connections. .TP +.B --tftp-mtu=<mtu size> +Use size as the ceiling of the MTU supported by the intervening network when +negotiating TFTP blocksize, overriding the MTU setting of the local interface if it is larger. +.TP .B --tftp-no-blocksize Stop the TFTP server from negotiating the "blocksize" option with a client. Some buggy clients request this option but then behave badly @@ -1790,7 +1911,7 @@ A special case of .B --conf-file which differs in two respects. Firstly, only --server and --rev-server are allowed in the configuration file included. Secondly, the file is re-read and the configuration -therein is updated when dnsmasq recieves SIGHUP. +therein is updated when dnsmasq receives SIGHUP. .SH CONFIG FILE At startup, dnsmasq reads .I /etc/dnsmasq.conf, @@ -1870,7 +1991,7 @@ and .PP -Dnsmasq is a DNS query forwarder: it it not capable of recursively +Dnsmasq is a DNS query forwarder: it is not capable of recursively answering arbitrary queries starting from the root servers but forwards such queries to a fully recursive upstream DNS server which is typically provided by an ISP. By default, dnsmasq reads @@ -1939,7 +2060,7 @@ include set:<tag>, including one from the .B dhcp-range used to allocate the address, one from any matching .B dhcp-host -(and "known" if a dhcp-host matches) +(and "known" or "known-othernet" if a dhcp-host matches) The tag "bootp" is set for BOOTP requests, and a tag whose name is the name of the interface on which the request arrived is also set. @@ -2126,7 +2247,12 @@ following data is used to populate the authoritative zone. .B --cname as long as the record name is in the authoritative domain. If the target of the CNAME is unqualified, then it is qualified with the -authoritative zone name. +authoritative zone name. CNAME used in this way (only) may be wildcards, as in + +.nf +.B cname=*.example.com,default.example.com +.fi + .PP IPv4 and IPv6 addresses from /etc/hosts (and .B --addn-hosts @@ -2139,7 +2265,7 @@ provided the address falls into one of the subnets specified in the .PP Addresses of DHCP leases, provided the address falls into one of the subnets specified in the .B --auth-zone. -(If contructed DHCP ranges are is use, which depend on the address dynamically +(If constructed DHCP ranges are is use, which depend on the address dynamically assigned to an interface, then the form of .B --auth-zone which defines subnets by the dynamic address of an interface should |