--test Read and syntax check configuration files.
Exit with code 0 if all is OK, or a non-zero code otherwise.
Do not start up dnsmasq.
| -v --version Raspian buster 5/24/20Dnsmasq version 2.80 Copyright (c) 2000-2018 Simon Kelley
Compile time options:
IPv6 GNU-getopt DBus i18n IDN DHCP DHCPv6 no-Lua TFTP
conntrack ipset auth DNSSEC loop-detect inotify dumpfile
| -w --help
Display command-line options.
--help dhcp displays DHCPv4 configuration options,
--help dhcp6 displays DHCPv6 options.
|
-h --no-hosts Don't read /etc/hosts .
| -H --addn-hosts=hfile
Additional hosts file.
If --no-hosts is given, read only hfile
May be repeated
If a directory is given, then read all the files in that directory.
| --hostsdir=path
Read all the hosts files contained in the directory. New or changed files are read automatically. See --dhcp-hostsdir
-E --expand-hosts
Add the domain to simple names (without a period) in /etc/hosts in the same way as for DHCP-derived names. Note that this
does not apply to domain names in cnames, PTR records, TXT records etc.
|
-T --local-ttl=time
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 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.
| --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 to zero eliminates the effect of --local-ttl for DHCP.
| --neg-ttl=time
Negative replies from upstream servers normally contain time-to-live information in SOA records which dnsmasq uses for
caching. If the replies from upstream servers omit this information, dnsmasq does not cache the reply. This option gives a
default value for time-to-live (in seconds) which dnsmasq uses to cache negative replies even in the absence of an SOA
record.
| --max-ttl=time
Set a maximum TTL value that will be handed out to clients. The specified maximum TTL will be given to clients instead of
the true TTL value if it is lower. The true TTL value is however kept in the cache to avoid flooding the upstream DNS
servers.
| --max-cache-ttl=time
Set a maximum TTL value for entries in the cache.
| --min-cache-ttl=time
Extend short TTL values to the time given when caching them. Note that artificially extending TTL values is in general a
bad idea, do not do it unless you have a good reason, and understand what you are doing. Dnsmasq limits the value of this
option to one hour, unless recompiled.
| --auth-ttl=time
Set the TTL value returned in answers from the authoritative server.
| -k --keep-in-foreground
Do not go into the background at startup but otherwise run as normal. This is intended for use when dnsmasq is run under
daemontools or launchd.
| -d --no-daemon
Debug mode: don't fork to the background, don't write a pid file, don't change user id, generate a complete cache dump on
receipt on SIGUSR1, log to stderr as well as syslog, don't fork new processes to handle TCP queries. Note that this option
is for use in debugging only, to stop dnsmasq daemonising in production, use --keep-in-foreground.
| -q --log-queries
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 --log-queries=extra then the log has extra information at the start of each line. This consists of a se-
rial number which ties together the log lines associated with an individual query, and the IP address of the requestor.
| -8 --log-facility=facility
Set the facility to which dnsmasq will send syslog entries, this defaults to DAEMON, and to LOCAL0 when debug mode is in
operation. If the facility given contains at least one '/' character, it is taken to be a filename, and dnsmasq logs to
the given file, instead of syslog. If the facility is '-' then dnsmasq logs to stderr. (Errors whilst reading configura-
tion will still go to syslog, but all output from a successful startup, and all output whilst running, will go exclusively
to the file.) When logging to a file, dnsmasq will close and reopen the file when it receives SIGUSR2. This allows the log
file to be rotated without stopping dnsmasq.
| --log-async[=]
Enable asynchronous logging and optionally set the limit on the number of lines which will be queued by dnsmasq when writ-
ing to the syslog is slow. Dnsmasq can log asynchronously: this allows it to continue functioning without being blocked
by syslog, and allows syslog to use dnsmasq for DNS queries without risking deadlock. If the queue of log-lines becomes
full, dnsmasq will log the overflow, and the number of messages lost. The default queue length is 5, a sane value would
be 5-25, and a maximum limit of 100 is imposed.
| -x --pid-file=path
Specify an alternate path for dnsmasq to record its process-id in. Normally /var/run/dnsmasq.pid.
| -u --user=username
Specify the userid to which dnsmasq will change after startup. Dnsmasq must normally be started as root, but it will drop
root privileges after startup by changing id to another user. Normally this user is "nobody" but that can be over-ridden
with this switch.
| -g --group=groupname
Specify the group which dnsmasq will run as. The default is "dip", if available, to facilitate access to /etc/ppp/re-
solv.conf which is not normally world readable.
| -p --port=port
Listen on instead of the standard DNS port (53). Setting to zero completely disables DNS function, leaving
only DHCP and/or TFTP.
-P --edns-packet-max=size
Specify the largest EDNS.0 UDP packet which is supported by the DNS forwarder. Defaults to 4096, which is the RFC5625-rec-
ommended size.
| -Q --query-port=query_port
Send outbound DNS queries from, and listen for their replies on, the specific UDP port instead of using ran-
dom ports. NOTE that using this option will make dnsmasq less secure against DNS spoofing attacks but it may be faster and
use less resources. Setting 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.
--min-port=port
Do not use ports less than that given as source for outbound DNS queries. Dnsmasq picks random ports as source for out-
bound queries: when this option is given, the ports used will always to larger than that specified. Useful for systems be-
hind firewalls. If not specified, defaults to 1024.
| --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.
| -i --interface=interface name
Listen only on the specified interface(s). Dnsmasq automatically adds the loopback (local) interface to the list of inter-
faces to use when the --interface option is used. If no --interface or --listen-address options are given dnsmasq listens
on all available interfaces except any given in --except-interface options. On Linux, when --bind-interfaces or --bind-dy-
namic 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 al-
lows control over which of those addresses are accepted. The same effect is achievable in default mode by using --listen-
address. A simple wildcard, consisting of a trailing '*', can be used in --interface and --except-interface options.
| -I --except-interface=interface name
Do not listen on the specified interface. Note that the order of --listen-address --interface and --except-interface op-
tions does not matter and that --except-interface options always override the others. The comments about interface labels
for --listen-address apply here.
| --auth-server=,[|...]
Enable DNS authoritative mode for queries arriving at an interface or address. Note that the interface or address need not
be mentioned in --interface or --listen-address configuration, indeed --auth-server will override these and provide a dif-
ferent DNS service on the specified interface. The is the "glue record". It should 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. 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 glue record.
--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 if there are no --interface --except-interface, --listen-address or --auth-server op-
tions. 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.
| -2 --no-dhcp-interface=interface name
Do not provide DHCP or TFTP on the specified interface, but do provide DNS service.
| -a --listen-address=ipaddr
Listen on the given IP address(es). Both --interface and --listen-address options may be given, in which case the set of
both interfaces and addresses is used. Note that if no --interface option is given, but --listen-address is, dnsmasq will
not automatically listen on the loopback interface. To achieve this, its IP address, 127.0.0.1, must be explicitly given
as a --listen-address option.
| -z --bind-interfaces
dnsmasq binds the wildcard address, even when it is listening on only some interfaces. It
then discards requests that it shouldn't reply to. This has the advantage of working even when interfaces come and go and
change address. This option forces dnsmasq to really bind only the interfaces it is listening on. About the only time when
this is useful is when running another nameserver (or another instance of dnsmasq) on the same machine. Setting this
also enables multiple instances of dnsmasq which provide DHCP service to run in the same machine.
| --bind-dynamic
Enable a network mode which is a hybrid between --bind-interfaces and the default. Dnsmasq binds the address of individual
interfaces, allowing multiple dnsmasq instances, but if new interfaces or addresses appear, it automatically listens on
those (subject to any access-control configuration). This makes dynamically created interfaces work in the same way as the
default. Implementing this option requires non-standard networking APIs and it is only available under Linux. On other
platforms it falls-back to --bind-interfaces mode.
| -y --localise-queries
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 sub-
net as the interface to which the query was sent, then return only the address(es) on that subnet. This allows for a
server to have multiple addresses in /etc/hosts corresponding to each of its interfaces, and hosts will get the correct
address based on which network they are attached to. Currently this facility is limited to IPv4.
| -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. The set of
prefixes affected is the list given in RFC6303, for IPv4 and IPv6.
| -V --alias=[]|[-],[,]
Modify IPv4 addresses returned from upstream nameservers; old-ip is replaced by new-ip. If the optional mask is given then
any address which matches the masked old-ip will be re-written. So, for instance --alias=1.2.3.0,6.7.8.0,255.255.255.0
will map 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. This is what Cisco PIX routers call "DNS doctoring". If the old IP
is given as range, then only addresses in the range, rather than a whole subnet, are re-written. So
--alias=192.168.0.10-192.168.0.40,10.0.0.0,255.255.255.0 maps 192.168.0.10->192.168.0.40 to 10.0.0.10->10.0.0.40
| -B --bogus-nxdomain=ipaddr
Transform replies which contain the IP address given into "No such domain" replies. This is intended to counteract a devi-
ous move made by Verisign in September 2003 when they started returning the address of an advertising web page in response
to queries for unregistered names, instead of the correct NXDOMAIN response. This option tells dnsmasq to fake the correct
response when it sees this behaviour. As at Sept 2003 the IP address being returned by Verisign is 64.94.110.11
| --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 forged answer
to a DNS request for certain domain, before the correct answer can arrive.
| -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.
| -r --resolv-file=file
Read the IP addresses of the upstream nameservers from , instead of /etc/resolv.conf. For the format of this file
see resolv.conf(5). The only lines relevant to dnsmasq are nameserver ones. Dnsmasq can be told to poll more than one re-
solv.conf file, the first file name specified overrides the default, subsequent ones add to the list. This is only al-
lowed when polling; the file with the currently latest modification time is the one used.
-R --no-resolv
Don't read /etc/resolv.conf. Get upstream servers only from the command line or the dnsmasq configuration file.
| -1 --enable-dbus[=]
Allow dnsmasq configuration to be updated via DBus method calls. The configuration which can be changed is upstream DNS
servers (and corresponding domains) and cache clear. Requires that dnsmasq has been built with DBus support. If the ser-
vice name is given, dnsmasq provides service at that name, rather than the default which is uk.org.thekelleys.dnsmasq
| --enable-ubus
Enable dnsmasq UBus interface. It sends notifications via UBus on DHCPACK and DHCPRELEASE events. Furthermore it offers
metrics. Requires that dnsmasq has been built with UBus support.
| -o --strict-order
By default, dnsmasq will send queries to any of the upstream servers it knows about and tries to favour servers that are
known to be up. Setting this flag forces dnsmasq to try each query with each server strictly in the order they appear in
/etc/resolv.conf
| --all-servers
By default, when dnsmasq has more than one upstream server available, it will send queries to just one server. Setting
this flag forces dnsmasq to send all queries to all available servers. The reply from the server which answers first will
be returned to the original requester.
| --dns-loop-detect
Enable code to detect DNS forwarding loops; ie the situation where a query sent to one of the upstream server eventually
returns as a new query to the dnsmasq instance. The process works by generating TXT queries of the form .test and
sending them to each upstream server. The hex is a UID which encodes the instance of dnsmasq sending the query and the up-
stream server to which it was sent. If the query returns to the server which sent it, then the upstream server through
which it was sent is disabled and this event is logged. Each time the set of upstream servers changes, the test is re-run
on all of them, including ones which were previously disabled.
--stop-dns-rebind
Reject (and log) addresses from upstream nameservers which are in the private IP ranges. This blocks an attack where a
browser behind a firewall is used to probe machines on the local network.
| --rebind-localhost-ok
Exempt 127.0.0.0/8 from rebinding checks. This address range is returned by realtime black hole servers, so blocking it
may disable these services.
| --rebind-domain-ok=[]|[[//[/]
Do not detect and block dns-rebind on queries to these domains. The argument may be either a single domain, or multiple
domains surrounded by '/', like the --server syntax, eg. --rebind-domain-ok=/domain1/domain2/domain3/
| -n --no-poll
Don't poll /etc/resolv.conf for changes.
| --clear-on-reload
Whenever /etc/resolv.conf is re-read or the upstream servers are set via DBus, clear the DNS cache. This is useful when
new nameservers may have different data than that held in cache.
| -D --domain-needed
Tells dnsmasq to never forward A or AAAA queries for plain names, without dots or domain parts, to upstream nameservers.
If the name is not known from /etc/hosts or DHCP then a "not found" answer is returned.
| -S --local, --server=[/[]/[domain/]][[#][@|[#]]
Specify IP address of upstream servers directly. Setting this flag does not suppress reading of /etc/resolv.conf, use
--no-resolv to do that. If one or more optional domains are given, that server is used only for those domains and they are
queried only using the specified server. This is intended for private nameservers: if you have a nameserver on your net-
work which deals with names of the form xxx.internal.thekelleys.org.uk at 192.168.1.1 then giving the flag --server=/in-
ternal.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. DNSSEC validation is turned off for such private nameservers, UNLESS a --trust-an-
chor is specified for the domain in question. An empty domain specification, // has the special meaning of "unqualified
names only" ie names without any dots in them. A non-standard port may be specified as part of the IP address using a #
character. More than one --server flag is allowed, with repeated domain or ipaddr parts as required.
More specific domains take precedence over less specific domains, so: --server=/google.com/1.2.3.4
--server=/www.google.com/2.3.4.5 will send queries for *.google.com to 1.2.3.4, except *www.google.com, which will go to
2.3.4.5
The special server address '#' means, "use the standard servers", so --server=/google.com/1.2.3.4
--server=/www.google.com/# will send queries for *.google.com to 1.2.3.4, except *www.google.com which will be forwarded
as usual.
Also permitted is a -S flag which gives a domain but no IP address; this tells dnsmasq that a domain is local and it may
answer queries from /etc/hosts or DHCP but should never forward queries on that domain to any upstream servers. --local
is a synonym for --server to make configuration files clearer in this case.
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 can
either be an ip-address, an interface name or both. The ip-address should belong to the machine on which dnsmasq is run-
ning, 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 implemented on all platforms sup-
ported by dnsmasq.
| --rev-server=/,[#][@|[#]]
This is functionally the same as --server, but provides some syntactic sugar to make specifying address-to-name queries
easier. For example --rev-server=1.2.3.0/24,192.168.0.1 is exactly equivalent to --server=/3.2.1.in-addr.arpa/192.168.0.1
| -A --address=/[/...]/[]
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 --address flags. To include multiple IP addresses for a single query, use --addn-hosts= instead. Note
that /etc/hosts and DHCP leases override this for individual names. A common use of this is to redirect the entire dou-
bleclick.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 --ad-
dress=/example.com/ is equivalent to --server=/example.com/ and returns NXDOMAIN for example.com and all its subdomains.
An address specified as '#' translates to the NULL address of 0.0.0.0 and its IPv6 equivalent of :: so --address=/exam-
ple.com/# will return NULL addresses for example.com and its subdomains. This is partly syntactic sugar for --address=/ex-
ample.com/0.0.0.0 and --address=/example.com/:: but is also more efficient than including both as seperate 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.
--ipset=/[/...]/[,...]
Places the resolved IP addresses of queries for one or more domains in the specified Netfilter IP set. If multiple set-
names 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 --address.
These IP sets must already exist. See ipset(8) for more details.
|
Mail server
| -m --mx-host=[[,],]
Return an MX record named pointing to the given hostname (if given), or the host specified in the --mx-target
switch or, if that switch is not given, the host on which dnsmasq is running. The default is useful for directing mail
from systems on a LAN to a central server. The preference value is optional, and defaults to 1 if not given. More than one
MX record may be given for a host.
-t --mx-target=hostname
Specify the default target for the MX record returned by dnsmasq. See --mx-host. If --mx-target is given, but not --mx-
host, then dnsmasq returns a MX record containing the MX target for MX queries on the hostname of the machine on which
dnsmasq is running.
| -e --selfmx
Return an MX record pointing to itself for each local machine. Local machines are those in /etc/hosts or with DHCP leases.
| -L --localmx
Return an MX record pointing to the host given by --mx-target (or the machine on which dnsmasq is running) for each local
machine. Local machines are those in /etc/hosts or with DHCP leases.
|
-W --srv-host=<_service>.<_prot>.[],[[,[,[,]]]]
Return a SRV DNS record. See RFC2782 for details. If not supplied, the domain defaults to that given by --domain. The de-
fault for the target domain is empty, and the default for port is one and the defaults for weight and priority are zero.
Be careful if transposing data from BIND zone files: the port, weight and priority numbers are in a different order. More
than one SRV record for a given service/domain is allowed, all that match are returned.
| --host-record=[, | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |