.TP
.B --hostsdir=<path>
Read all the hosts files contained in the directory. New or changed files
-are read automatically. See \fB--dhcp-hostsdir\fP for details.
+are read automatically and modified and deleted files have removed records
+automatically deleted.
.TP
.B \-E, --expand-hosts
Add the domain to simple names (without a period) in /etc/hosts
.B --auth-ttl=<time>
Set the TTL value returned in answers from the authoritative server.
.TP
+.B --fast-dns-retry=[<initial retry delay in ms>[,<time to continue retries in ms>]]
+Under normal circumstances, dnsmasq relies on DNS clients to do retries; it
+does not generate timeouts itself. Setting this option
+instructs dnsmasq to generate its own retries starting after a delay
+which defaults to 1000ms. If the second parameter is given this controls
+how long the retries will continue for
+otherwise this defaults to 10000ms. Retries are repeated with exponential
+backoff. Using this option increases memory usage and
+network bandwidth.
+.TP
.B \-k, --keep-in-foreground
Do not go into the background at startup but otherwise run as
normal. This is intended for use when dnsmasq is run under daemontools
that using this option will make dnsmasq less secure against DNS
spoofing attacks but it may be faster and use less resources. Setting this option
to zero makes dnsmasq use a single port allocated to it by the
-OS: this was the default behaviour in versions prior to 2.43.
+OS: this was the default behaviour in versions prior to 2.43.
+.TP
+.B --port-limit=<#ports>
+By default, when sending a query via random ports to multiple upstream servers or
+retrying a query dnsmasq will use a single random port for all the tries/retries.
+This option allows a larger number of ports to be used, which can increase robustness
+in certain network configurations. Note that increasing this to more than
+two or three can have security and resource implications and should only
+be done with understanding of those.
.TP
.B --min-port=<port>
Do not use ports less than that given as source for outbound DNS
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
+address(es) on that subnet and return all the available addresses otherwise.
+This allows for a server to have multiple
addresses in /etc/hosts corresponding to each of its interfaces, and
hosts will get the correct address based on which network they are
attached to. Currently this facility is limited to IPv4.
.B \-f, --filterwin2k
Later versions of windows make periodic DNS requests which don't get sensible answers from
the public DNS and can cause problems by triggering dial-on-demand links. This flag turns on an option
-to filter such requests. The requests blocked are for records of types SOA and SRV, and type ANY where the
-requested name has underscores, to catch LDAP requests.
+to filter such requests. The requests blocked are for records of type ANY
+where the requested name has underscores, to catch LDAP requests, and for
+\fBall\fP records of types SOA and SRV.
+.TP
+.B --filter-A
+Remove A records from answers. No IPv4 addresses will be returned.
+.TP
+.B --filter-AAAA
+Remove AAAA records from answers. No IPv6 addresses will be returned.
.TP
.B \-r, --resolv-file=<file>
Read the IP addresses of the upstream nameservers from <file>, instead of
or domain parts, to upstream nameservers. If the name is not known
from /etc/hosts or DHCP then a "not found" answer is returned.
.TP
-.B \-S, --local, --server=[/[<domain>]/[domain/]][<
ipaddr>[#<port>]][@<interface>][@<source-ip>[#<port>]]
-Specify IP address of upstream servers directly. Setting this flag does
+.B \-S, --local, --server=[/[<domain>]/[domain/]][<
server>[#<port>]][@<interface>][@<source-ip>[#<port>]]
+Specify upstream servers directly. Setting this flag does
not suppress reading of /etc/resolv.conf, use \fB--no-resolv\fP to do that. If one or more
optional domains are given, that server is used only for those domains
and they are queried only using the specified server. This is
source address specified but the port may be specified directly as
part of the source address. Forcing queries to an interface is not
implemented on all platforms supported by dnsmasq.
+
+Upstream servers may be specified with a hostname rather than an IP address.
+In this case, dnsmasq will try to use the system resolver to get the IP address
+of a server during startup. If name resolution fails, starting dnsmasq fails, too.
+If the system's configuration is such that the system resolver sends DNS queries
+through the dnsmasq instance which is starting up then this will time-out and fail.
.TP
-.B --rev-server=<ip-address>
/<prefix-len>[,<ipaddr>][#<port>][@<interface>][@<source-ip>[#<port>]]
+.B --rev-server=<ip-address>
[/<prefix-len>][,<server>][#<port>][@<interface>][@<source-ip>[#<port>]]
This is functionally the same as
.B --server,
but provides some syntactic sugar to make specifying address-to-name queries easier. For example
.B --rev-server=1.2.3.0/24,192.168.0.1
is exactly equivalent to
.B --server=/3.2.1.in-addr.arpa/192.168.0.1
+Allowed prefix lengths are 1-32 (IPv4) and 1-128 (IPv6). If the prefix length is omitted, dnsmasq substitutes either 32 (IPv4) or 128 (IPv6).
.TP
.B \-A, --address=/<domain>[/<domain>...]/[<ipaddr>]
Specify an IP address to return for any host in the given domains.
-Queries in the domains are never forwarded and always replied to
+A (or AAAA) 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 \fB--address\fP flags.
-To include multiple IP addresses for a single query, use
-\fB--addn-hosts=<path>\fP instead.
+multiple addresses or both IPv4 and IPv6 addresses for a domain, use repeated \fB--address\fP flags.
Note that /etc/hosts and DHCP leases override this for individual
names. A common use of this is to redirect the entire doubleclick.net
domain to some friendly local web server to avoid banner ads. The
its subdomains. This is partly syntactic sugar for \fB--address=/example.com/0.0.0.0\fP
and \fB--address=/example.com/::\fP but is also more efficient than including both
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.
+
+Note that the behaviour for queries which don't match the specified address literal changed in version 2.86.
+Previous versions, configured with (eg) --address=/example.com/1.2.3.4 and then queried for a RR type other than
+A would return a NoData answer. From 2.86, the query is sent upstream. To restore the pre-2.86 behaviour,
+use the configuration --address=/example.com/1.2.3.4 --local=/example.com/
.TP
.B --ipset=/<domain>[/<domain>...]/<ipset>[,<ipset>...]
Places the resolved IP addresses of queries for one or more domains in
.BR ipset (8)
for more details.
.TP
+.B --nftset=/<domain>[/<domain>...]/[(6|4)#[<family>#]<table>#<set>[,[(6|4)#[<family>#]<table>#<set>]...]
+Similar to the \fB--ipset\fP option, but accepts one or more nftables
+sets to add IP addresses into.
+These sets must already exist. See
+.BR nft (8)
+for more details. The family, table and set are passed directly to the nft. If the spec starts with 4# or 6# then
+only A or AAAA records respectively are added to the set. Since an nftset can hold only IPv4 or IPv6 addresses, this
+avoids errors being logged for addresses of the wrong type.
+.TP
.B --connmark-allowlist-enable[=<mask>]
Enables filtering of incoming DNS queries with associated Linux connection track marks
according to individual allowlists configured via a series of \fB--connmark-allowlist\fP
.TP
.B --dumpmask=<mask>
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
-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.
+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, 0x1000 - DHCPv4, 0x2000 - DHCPv6, 0x4000 - Router advertisement, 0x8000 - TFTP.
.TP
.B --add-mac[=base64|text]
Add the MAC address of the requestor to DNS queries which are
given for \fB--add-subnet\fP applies to \fB--add-mac\fP 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 --strip-mac
+Remove any MAC address information already in downstream queries before forwarding upstream.
+.TP
.B --add-cpe-id=<string>
Add an arbitrary identifying string to DNS queries which are
forwarded upstream.
.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 --umbrella[=deviceid:<deviceid>[,orgid:<orgid>]]
+.B --strip-subnet
+Remove any subnet address already present in a downstream query before forwarding it upstream. If --add-subnet is set this also
+ensures that any downstream-provided subnet is replaced by the one added by dnsmasq. Otherwise, dnsmasq will NOT replace an
+existing subnet in the query.
+.TP
+.B --umbrella[=[deviceid:<deviceid>][,orgid:<orgid>][,assetid:<id>]]
Embeds the requestor's IP address in DNS queries forwarded upstream.
-If device id or organization id are specified, the information is
+If device id or, asset id or organization id are specified, the information is
included in the forwarded queries and may be able to be used in
-filtering policies and reporting. The order of the deviceid and orgid
-attributes is irrelevant, but must be separated by a comma.
+filtering policies and reporting. The order of the id
+attributes is irrelevant, but they must be separated by a comma. Deviceid is
+a sixteen digit hexadecimal number, org and asset ids are decimal numbers.
.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. Note: huge cache size impacts performance.
"no such domain" answers from upstream nameservers and answer
identical queries without forwarding them again.
.TP
+.B --no-round-robin
+Dnsmasq normally permutes the order of A or AAAA records for the same
+name on successive queries, for load-balancing. This turns off that
+behaviour, so that the records are always returned in the order
+that they are received from upstream.
+.TP
+.B --use-stale-cache[=<max TTL excess in s>]
+When set, if a DNS name exists in the cache, but its time-to-live has expired, dnsmasq will return the data anyway. (It attempts to refresh the
+data with an upstream query after returning the stale data.) This can improve speed and reliability. It comes at the expense
+of sometimes returning out-of-date data and less efficient cache utilisation, since old data cannot be flushed when its TTL expires, so the cache becomes
+mostly least-recently-used. To mitigate issues caused by massively outdated DNS replies, the maximum overaging of cached records can be specified in seconds
+(defaulting to not serve anything older than one day). Setting the TTL excess time to zero will serve stale cache data regardless how long it has expired.
+.TP
.B \-0, --dns-forward-max=<queries>
Set the maximum number of concurrent DNS queries. The default value is
150, which should be fine for most setups. The only known situation
tells dnsmasq to advertise the prefix without the on-link (aka L) bit set.
.TP
-.B \-G, --dhcp-host=[<hwaddr>][,id:<client_id>|*][,set:<tag>][tag:<tag>][,<ipaddr>][,<hostname>][,<lease_time>][,ignore]
+.B \-G, --dhcp-host=[<hwaddr>][,id:<client_id>|*][,set:<tag>][,tag:<tag>][,<ipaddr>][,<hostname>][,<lease_time>][,ignore]
Specify per host parameters for the DHCP server. This allows a machine
with a particular hardware address to be always allocated the same
hostname, IP address and lease time. A hostname specified like this
.B --dhcp-host
option, but aliases are possible by using CNAMEs. (See
.B --cname
-).
+). Note that /etc/hosts is NOT used when the DNS server side of dnsmasq
+is disabled by setting the DNS server port to zero.
More than one
.B --dhcp-host
If the host matches only a \fB--dhcp-host\fP directive which cannot
be used because it specifies an address on different subnet, the tag "known-othernet" is set.
-The tag:<tag> construct filters which dhcp-host directives are used. Tagged directives are used in preference to untagged ones.
+The tag:<tag> construct filters which dhcp-host directives are used; more than
+one can be provided, in this case the request must match all of them. Tagged
+directives are used in preference to untagged ones. Note that one of <hwaddr>,
+<client_id> or <hostname> still needs to be specified (can be a wildcard).
Ethernet addresses (but not client-ids) may have
wildcard bytes, so for example
options but can, rarely, confuse old or broken clients. This flag
forces "simple and safe" behaviour to avoid problems in such a case.
.TP
-.B --dhcp-relay=<local address>,<server address>[,<interface]
+.B --dhcp-relay=<local address>[,<server address>[#<server port>]][,<interface]
Configure dnsmasq to do DHCP relay. The local address is an address
allocated to an interface on the host running dnsmasq. All DHCP
requests arriving on that interface will we relayed to a remote DHCP
address to multiple remote servers by using multiple \fB--dhcp-relay\fP
configs with the same local address and different server
addresses. A server address must be an IP literal address, not a
-domain name. In the case of DHCPv6, the server address may be the
-ALL_SERVERS multicast address, ff05::1:3. In this case the interface
-must be given, not be wildcard, and is used to direct the multicast to the
-correct interface to reach the DHCP server.
+domain name. If the server address is omitted, the request will be
+forwarded by broadcast (IPv4) or multicast (IPv6). In this case the interface
+must be given and not be wildcard. The server address may specify a non-standard
+port to relay to. If this is used then \fB--dhcp-proxy\fP should likely also be set,
+otherwise parts of the DHCP conversation which do not pass through the relay
+will be delivered to the wrong port.
Access control for DHCP clients has the same rules as for the DHCP
server, see \fB--interface\fP, \fB--except-interface\fP, etc. The optional
Both DHCPv4 and DHCPv6 relay is supported. It's not possible to relay
DHCPv4 to a DHCPv6 server or vice-versa.
+
+The DHCP relay function for IPv6 includes the ability to snoop
+prefix-delegation from relayed DHCP transactions. See
+.B --dhcp-script
+for details.
.TP
.B \-U, --dhcp-vendorclass=set:<tag>,[enterprise:<IANA-enterprise number>,]<vendor-class>
Map from a vendor-class string to a tag. Most DHCP clients provide a
the length of the lease (in seconds) is stored in
DNSMASQ_LEASE_LENGTH, otherwise the time of lease expiry is stored in
DNSMASQ_LEASE_EXPIRES. The number of seconds until lease expiry is
-always stored in DNSMASQ_TIME_REMAINING.
+always stored in DNSMASQ_TIME_REMAINING.
+
+DNSMASQ_DATA_MISSING is set to "1" during "old" events for existing
+leases generated at startup to indicate that data not stored in the
+persistent lease database will not be present. This comprises everything
+other than IP address, hostname, MAC address, DUID, IAID and lease length
+or expiry time.
If a lease used to have a hostname, which is
removed, an "old" event is generated with the new state of the lease,
.B --log-dhcp
is in effect.
+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.
+
+DNSMASQ_MUD_URL the Manufacturer Usage Description URL if provided by the client. (See RFC8520 for details.)
+
+
For IPv4 only:
DNSMASQ_CLIENT_ID if the host provided a client-id.
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,
with an "old" event.
-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
+There are five further actions which may appear as the first argument
+to the script, "init", "arp-add", "arp-del", "relay-snoop" 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
+
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 "relay-snoop" action is invoked when dnsmasq is configured as a DHCP
+relay for DHCPv6 and it relays a prefx delegation to a client. The arguments
+are the name of the interface where the client is conected, its (link-local)
+address on that interface and the delegated prefix. This information is
+sufficient to install routes to the delegated prefix of a router. See
+.B --dhcp-relay
+for more details on configuring DHCP relay.
+
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
addresses may be allocated from.
.TP
-.B \-s, --domain=<domain>[,<address range>[,local]]
+.B \-s, --domain=<domain>[[,<address range>[,local]]|<interface>]
Specifies DNS domains for the DHCP server. Domains may be be given
unconditionally (without the IP range) or for limited IP ranges. This has two effects;
firstly it causes the DHCP server to return the domain to any hosts
is identical to
.B --domain=thekelleys.org.uk,192.168.0.0/24
.B --local=/thekelleys.org.uk/ --local=/0.168.192.in-addr.arpa/
-The network size must be 8, 16 or 24 for this to be legal.
+
+The address range can also be given as a network interface name, in which case
+all of the subnets currently assigned to the interface are used in matching the
+address. This allows hosts on different physical subnets to be given different
+domains in a way which updates automatically as the interface addresses change.
.TP
.B --dhcp-fqdn
In the default mode, dnsmasq inserts the unqualified names of
which differs in two respects. Firstly, only \fB--server\fP and \fB--rev-server\fP are allowed
in the configuration file included. Secondly, the file is re-read and the configuration
therein is updated when dnsmasq receives SIGHUP.
+.TP
+.B \--conf-script=<file>[ <arg]
+Execute <file>, and treat what it emits to stdout as the contents of a configuration file.
+If the script exits with a non-zero exit code, dnsmasq treats this as a fatal error.
+The script can be passed arguments, space seperated from the filename and each other so, for instance
+.B --conf-dir="/etc/dnsmasq-uncompress-ads /share/ads-domains.gz"
+
+with /etc/dnsmasq-uncompress-ads containing
+
+set -e
+
+zcat ${1} | sed -e "s:^:address=/:" -e "s:$:/:"
+
+exit 0
+
+and /share/ads-domains.gz containing a compressed
+list of ad server domains will save disk space with large ad-server blocklists.
.SH CONFIG FILE
At startup, dnsmasq reads
.I /etc/dnsmasq.conf,
5 - Other miscellaneous problem.
.PP
11 or greater - a non zero return code was received from the
-lease-script process "init" call. The exit code from dnsmasq is the
+lease-script process "init" call or a
+.B \--conf-script
+file. The exit code from dnsmasq is the
script's exit code with 10 added.
.SH LIMITS
projects / platform / upstream / dnsmasq.git / blobdiff