dnsmasq
A lightweight DHCP and caching DNS server.
Synopsis
dnsmasq
[OPTION]...
add an example, a script, a trick and tips
examples
source
What do I need to make Linux host names resolvable on LAN?
I use Avahi and nss-mdns to make each system resolve as
<hostname>.local
on my home LAN. Simply make
sure that Avahi is started and port 5353 is open on each system
so they can hear mDNS announcements.
source
dns:unknown:/bin/dnsmasq -d
source
OpenWRT based gateway with dnsmasq and internal server with bind
I ran into this issue myself recently.
Most likely you have rebind protection set to "on" in the config.
If so, you should allow RFC1918 responses for that domain:
--rebind-domain-ok=/mydomain1.com/domain2.com/domain3.com/
This fixed the issue for me. Hope it helps.
If not, take a look at the dnsmasq release notes, there were some
regression bugs reported in versions 2.5x-2.6x. 2.62 and 2.65
seem the most stable (I use v62). Try to upgrade and see if it
fixes the issue.
source
dnsmasq without altering /etc/hosts file manually
Try setting a domain with domain example.org
.
dnsmasq also has a hook to call a script
dhcp-script=foo.sh
. The arguments sent to the script
are "add" or "del", then the MAC address, the IP address and
finally the hostname.
It should be relatively easy to quickly create a script that
updates the hosts file.
source
Replacing stock dnsmasq with optware dnsmasq
I found the answers to my problems. May be useful to someone
else:
-
"There are always 2 processes running for each dhcp network.
The subprocess is because dnsmasq setuids to nobody to run
the external script specified in --dhcp-script. This is
expected behavior." src:
answers.launchpad.net/nova/+question/181398
-
As one of the processes was nobody; during boot up, user
'nobody' was not initialized. Added these two lines to
/opt/etc/init.d/S56dnsmasq:
grep -q nobody /etc/group || echo "nobody:x:99:" >>
/etc/group
grep -q nobody /etc/passwd || echo
"nobody:x:99:99:nobody:/var:/bin/false" >> /etc/passwd
Works like a charm!
source
linux dnsmasq: how do I increase the ttl?
I don't think you can, not easily. The TTL is set by Google's
nameservers and they like it low for loadbalancing purposes.
It's possible that increasing the cache size could help, but for
super-short TTLs like Google's it probably won't.
Unofficially, there are a couple of patches to
provide a TTL-override functionality. I found these on the
dnsmasq-discuss mailing list, so if you feel
like rolling your own, try them out (you might check the mailing
list archives for patches against more recent versions):
source
Debian 6 Internet connection sharing aka IP masquerade not working
It seems you've set the wrong interface to perform
MASQUERADE
for. You state you want to 'share' the
internet connection of the laptop provided by a wireless
connection (probably wlan0
on your machine) to a
wired connection (seems to be eth0
on your machine).
However, your POSTROUTING
chain rule is configured
for eth0
instead of wlan0
(thev value
in the out
column is relevant here).
Try changing the script you mention to read like this:
# set wan interface such as eth1 or ppp0
SHARE_IF="wlan0"
It then uses that interface to set your iptabels rule correctly
in these lines:
echo "Setting ${SHARE_IF} as router interface..."
$IPT --table nat --append POSTROUTING --out-interface ${SHARE_IF} -j MASQUERADE
source
Verify dnsmasq configuration
AFAIK dnsmasq will normally log to the syslog service. By default
it uses facility DAEMON.
FWIW: "It works for me" (in Fedora 18 / 19).
If you aren't seeing any messages I'd suggest verifying your
syslog configuration. Or, a more emperical approach, try
something like "grep -c dnsmasq /var/log/*".
See also the detailed description of logging in the manual page
here: http://www.thekelleys.org.uk/dnsmasq/docs/dnsmasq-man.html
There are some other possibilities for logging mentioned there
that can effect its behaviour e.g. if facility contains a '/'
character.
Are other subsystems (sys-)logging correctly? Can you cause
syslog to log a message by using the 'logger' command?
HTH!
Robb.
description
dnsmasq
is a lightweight DNS, TFTP and DHCP server. It is intended
to provide coupled DNS and DHCP service to a LAN.
Dnsmasq accepts
DNS queries and either answers them from a small, local,
cache or forwards them to a real, recursive, DNS server. It
loads the contents of /etc/hosts so that local hostnames
which do not appear in the global DNS can be resolved and
also answers DNS queries for DHCP configured hosts.
The dnsmasq
DHCP server supports static address assignments and multiple
networks. It automatically sends a sensible default set of
DHCP options, and can be configured to send any desired set
of DHCP options, including vendor-encapsulated options. It
includes a secure, read-only, TFTP server to allow net/PXE
boot of DHCP hosts and also supports BOOTP.
Dnsmasq
supports IPv6 for all functions and a minimal
router-advertisement daemon.
options
Note that in
general missing parameters are allowed and switch off
functions, for instance "--pid-file" disables
writing a PID file. On BSD, unless the GNU getopt library is
linked, the long form of the options does not work on the
command line; it is still recognised in the configuration
file.
--test
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.
-h, --no-hosts
Don’t read the hostnames
in /etc/hosts.
-H,
--addn-hosts=<file>
Additional hosts file. Read the
specified file as well as /etc/hosts. If -h is given, read
only the specified file. This option may be repeated for
more than one additional hosts file. If a directory is
given, then read all the files contained in that
directory.
-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 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.
--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.
-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 -k.
-q,
--log-queries
Log the results of DNS queries
handled by dnsmasq. Enable a full cache dump on receipt of
SIGUSR1.
-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 configuration 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[=<lines>]
Enable asynchronous logging and
optionally set the limit on the number of lines which will
be queued by dnsmasq when writing 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 defaults to "dip", if available,
to facilitate access to /etc/ppp/resolv.conf which is not
normally world readable.
-v, --version
Print the version number.
-p,
--port=<port>
Listen on <port> instead
of the standard DNS port (53). Setting this 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-recommended size.
-Q,
--query-port=<query_port>
Send outbound DNS queries from,
and listen for their replies on, the specific UDP port
<query_port> instead of using random 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 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.
--min-port=<port>
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.
-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 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. IP alias interfaces
(eg "eth1:0") cannot be used with
--interface or --except-interface options, use
--listen-address instead.
-I,
--except-interface=<interface name>
Do not listen on the specified
interface. Note that the order of --listen-address
--interface and --except-interface options does
not matter and that --except-interface options always
override the others.
-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
On systems which support it,
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
option 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 which depend on the interface over which the
query was received. If a name in /etc/hosts 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 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.
-V,
--alias=[<old-ip>]|[<start-ip>-<end-ip>],<new-ip>[,<mask>]
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 devious 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
-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 <file>, 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 resolv.conf file, the first file name specified
overrides the default, subsequent ones add to the list. This
is only allowed 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[=<service-name>]
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 service name is given,
dnsmasq provides service at that name, rather than the
default which is uk.org.thekelleys.dnsmasq
-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.
--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=[<domain>]|[[/<domain>/[<domain>/]
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, 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>]/[domain/]][<ipaddr>[#<port>][@<source-ip>|<interface>[#<port>]]
Specify IP address of upstream
servers directly. Setting this flag does not suppress
reading of /etc/resolv.conf, use -R to do that. If one or
more optional domains are given, that server is used only
for those domains and they are queried only using the
specified server. This is intended for private nameservers:
if you have a nameserver on your network which deals with
names of the form xxx.internal.thekelleys.org.uk at
192.168.1.1 then giving the flag -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, // 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 -S flag is
allowed, with repeated domain or ipaddr parts as
required.
More specific
domains take precendence 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 a %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 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 supported by dnsmasq.
-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. 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.
-m, --mx-host=<mx
name>[[,<hostname>],<preference>]
Return an MX record named
<mx name> 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>.[<domain>],[<target>[,<port>[,<priority>[,<weight>]]]]
Return a SRV DNS record. See
RFC2782 for details. If not supplied, the domain defaults to
that given by --domain. The default 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=<name>[,<name>....][<IPv4-address>],[<IPv6-address>]
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 host-record and therefore be
assigned more than one address. Only the first address
creates a PTR record linking the address to the name. This
is the same rule as is used reading hosts-files.
host-record options are considered to be read before
host-files, so a name appearing there inhibits PTR-record
creation if it appears in hosts-file also. Unlike
hosts-files, names are not expanded, even when
expand-hosts is in effect. Short and long names may
appear in the same host-record, eg.
--host-record=laptop,laptop.thekelleys.org,192.168.0.1,1234::100
-Y,
--txt-record=<name>[[,<text>],<text>]
Return a TXT DNS record. The
value of TXT record is a set of strings, so any number may
be included, delimited by commas; use quotes to put commas
into a string. Note that the maximum length of a single
string is 255 characters, longer strings are split into 255
character chunks.
--ptr-record=<name>[,<target>]
Return a PTR DNS record.
--naptr-record=<name>,<order>,<preference>,<flags>,<service>,<regexp>[,<replacement>]
Return an NAPTR DNS record, as
specified in RFC3403.
--cname=<cname>,<target>
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 hosts files), from DHCP or from another
--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.
--dns-rr=<name>,<RR-number>,[<hex
data>]
Return an arbitrary DNS
Resource Record. The number is the type of the record (which
is always in the C_IN class). The value of the record is
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.
--interface-name=<name>,<interface>
Return a DNS record associating
the name with the primary address on the given interface.
This flag specifies an A 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. If the
interface is 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.
--add-mac
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
subnet as the dnsmasq server. Note that the mechanism used
to achieve this (an EDNS0 option) 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.
-c,
--cache-size=<cachesize>
Set the size of dnsmasq’s
cache. The default is 150 names. Setting the cache size to
zero disables caching.
-N,
--no-negcache
Disable negative caching.
Negative caching allows dnsmasq to remember "no such
domain" answers from upstream nameservers and answer
identical queries without forwarding them again.
-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
where this needs to be increased is when using web-server
log file resolvers, which can generate large numbers of
concurrent queries.
--proxy-dnssec
A resolver on a client machine
can do DNSSEC validation in two ways: it can perform the
cryptograhic operations on the reply it receives, or it can
rely on the upstream recursive nameserver to do the
validation and set a bit in the reply if it succeeds.
Dnsmasq is not a DNSSEC validator, so it cannot perform the
validation role of the recursive nameserver, but it can pass
through the validation results from its own upstream
nameservers. This option enables this behaviour. You should
only do this if you trust all the configured upstream
nameservers and the network between you and them. If
you use the first DNSSEC mode, validating resolvers in
clients, this option is not required. Dnsmasq always returns
all the data needed for a client to do validation
itself.
--conntrack
Read the Linux connection track
mark associated with incoming DNS queries and set the same
mark value on upstream traffic used to answer those queries.
This allows traffic generated by dnsmasq to be associated
with the queries which cause it, useful for bandwidth
accounting and firewalling. Dnsmasq must have conntrack
support compiled in and the kernel must have conntrack
support included and configured. This option cannot be
combined with --query-port.
-F,
--dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag],]<start-addr>[,<end-addr>][,<mode>][,<netmask>[,<broadcast>]][,<lease
time>]
-F,
--dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag],]<start-IPv6addr>[,<end-IPv6addr>][,<mode>][,<prefix-len>][,<lease
time>]
Enable the DHCP
server. Addresses will be given out from the range
<start-addr> to <end-addr> and from statically
defined addresses given in dhcp-host options. If the
lease time is given, then leases will be given for that
length of time. The lease time is in seconds, or minutes (eg
45m) or hours (eg 1h) or "infinite". If not given,
the default lease time is one hour. The minimum lease time
is two minutes. For IPv6 ranges, the lease time maybe
"deprecated"; this sets the preferred lifetime
sent in a DHCP lease or router advertisement to zero, which
causes clients to use other addresses, if available, for new
connections as a prelude to renumbering.
This option may
be repeated, with different addresses, to enable DHCP
service to more than one network. For directly connected
networks (ie, networks on which the machine running dnsmasq
has an interface) the netmask is optional: dnsmasq will
determine it from the interface configuration. For networks
which receive DHCP service via a relay agent, dnsmasq cannot
determine the netmask itself, so it should be specified,
otherwise dnsmasq will have to guess, based on the class (A,
B or C) of the network address. The broadcast address is
always optional. It is always allowed to have more than one
dhcp-range in a single subnet.
For IPv6, the
parameters are slightly different: instead of netmask and
broadcast address, there is an optional prefix length. If
not given, this defaults to 64. Unlike the IPv4 case, the
prefix length is not automatically derived from the
interface configuration. The mimimum size of the prefix
length is 64.
The optional
set:<tag> sets an alphanumeric label which
marks this network so that dhcp options may be specified on
a per-network basis. When it is prefixed with
’tag:’ instead, then its meaning changes from
setting a tag to matching it. Only one tag may be set, but
more than one tag may be matched.
The optional
<mode> keyword may be static which tells
dnsmasq to enable DHCP for the network specified, but not to
dynamically allocate IP addresses: only hosts which have
static addresses given via dhcp-host or from
/etc/ethers will be served. A static-only subnet with
address all zeros may be used as a "catch-all"
address to enable replies to all Information-request packets
on a subnet which is provided with stateless DHCPv6, ie
--dhcp=range=::,static
For IPv4, the
<mode> may be proxy in which case dnsmasq will
provide proxy-DHCP on the specified subnet. (See
pxe-prompt and pxe-service for details.)
For IPv6, the
mode may be some combination of ra-only, slaac, ra-names,
ra-stateless.
ra-only
tells dnsmasq to offer Router Advertisement only on this
subnet, and not DHCP.
slaac
tells dnsmasq to offer Router Advertisement on this subnet
and to set the A bit in the router advertisement, so that
the client will use SLAAC addresses. When used with a DHCP
range or static DHCP address this results in the client
having both a DHCP-assigned and a SLAAC address.
ra-stateless
sends router advertisements with the O and A bits set, and
provides a stateless DHCP service. The client will use a
SLAAC address, and use DHCP for other configuration
information.
ra-names
enables a mode which gives DNS names to dual-stack hosts
which do SLAAC for IPv6. Dnsmasq uses the host’s IPv4
lease to derive the name, network segment and MAC address
and assumes that the host will also have an IPv6 address
calculated using the SLAAC algorithm, on the same network
segment. The address is pinged, and if a reply is received,
an AAAA record is added to the DNS for this IPv6 address.
Note that this is only happens for directly-connected
networks, (not one doing DHCP via a relay) and it will not
work if a host is using privacy extensions. ra-names
can be combined with ra-stateless and
slaac.
-G,
--dhcp-host=[<hwaddr>][,id:<client_id>|*][,set:<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
overrides any supplied by the DHCP client on the machine. It
is also allowable to omit the hardware address and include
the hostname, in which case the IP address and lease times
will apply to any machine claiming that name. For example
--dhcp-host=00:20:e0:3b:13:af,wap,infinite tells
dnsmasq to give the machine with hardware address
00:20:e0:3b:13:af the name wap, and an infinite DHCP lease.
--dhcp-host=lap,192.168.0.199 tells dnsmasq to always
allocate the machine lap the IP address 192.168.0.199.
Addresses
allocated like this are not constrained to be in the range
given by the --dhcp-range option, but they must be in the
same subnet as some valid dhcp-range. For 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 rather than hardware addresses to
identify hosts by prefixing with ’id:’. Thus:
--dhcp-host=id:01:02:03:04,..... refers to the host
with client identifier 01:02:03:04. It is also allowed to
specify the client ID as text, like this:
--dhcp-host=id:clientidastext,.....
A single
dhcp-host may contain an IPv4 address or an IPv6
address, or both. IPv6 addresses must be bracketed by square
brackets thus: --dhcp-host=laptop,[1234::56] Note
that in IPv6 DHCP, the hardware address is not normally
available, so a client must be identified by client-id
(called client DUID in IPv6-land) or hostname.
The special
option id:* means "ignore any client-id and use MAC
addresses only." This is useful when a client presents
a client-id sometimes but not others.
If a name
appears in /etc/hosts, the associated address can be
allocated to a DHCP lease, but only if a --dhcp-host
option specifying the name also exists. Only one hostname
can be given in a dhcp-host option, but aliases are
possible by using CNAMEs. (See --cname ).
The special
keyword "ignore" tells dnsmasq to never offer a
DHCP lease to a machine. The machine can be specified by
hardware address, client ID or hostname, for instance
--dhcp-host=00:20:e0:3b:13:af,ignore This is useful
when there is another DHCP server on the network which
should be used by some machines.
The
set:<tag> contruct sets the tag whenever this
dhcp-host directive is in use. This can be used to
selectively send DHCP options just for this host. More than
one tag can be set in a dhcp-host directive (but not in
other places where "set:<tag>" is allowed).
When a host matches any 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 --dhcp-ignore=tag:!known
Ethernet addresses (but not client-ids) may have wildcard
bytes, so for example
--dhcp-host=00:20:e0:3b:13:*,ignore will cause
dnsmasq to ignore a range of hardware addresses. Note that
the "*" will need to be escaped or quoted on a
command line, but not in the configuration file.
Hardware
addresses normally match any network (ARP) type, but it is
possible to restrict them to a single ARP type by preceding
them with the ARP-type (in HEX) and "-". so
--dhcp-host=06-00:20:e0:3b:13:af,1.2.3.4 will only
match a Token-Ring hardware address, since the ARP-address
type for token ring is 6.
As a special
case, in DHCPv4, it is possible to include more than one
hardware address. eg:
--dhcp-host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2
This allows an IP address to be associated with multiple
hardware addresses, and gives dnsmasq permission to abandon
a DHCP lease to one of the hardware addresses when another
one asks for a lease. Beware that this is a dangerous thing
to do, it will only work reliably if only one of the
hardware addresses is active at any time and there is no way
for dnsmasq to enforce this. It is, for instance, useful to
allocate a stable IP address to a laptop which has both
wired and wireless interfaces.
--dhcp-hostsfile=<path>
Read DHCP host information from
the specified file. If a directory is given, then read all
the files contained in that directory. The file contains
information about one host per line. The format of a line is
the same as text to the right of ’=’ in
--dhcp-host. The advantage of storing DHCP host information
in this file is that it can be changed without re-starting
dnsmasq: the file will be re-read when dnsmasq receives
SIGHUP.
--dhcp-optsfile=<path>
Read DHCP option information
from the specified file. If a directory 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
--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.
-Z,
--read-ethers
Read /etc/ethers for
information about hosts for the DHCP server. The format of
/etc/ethers is a hardware address, followed by either a
hostname or dotted-quad IP address. When read by dnsmasq
these lines have exactly the same effect as
--dhcp-host options containing the same information.
/etc/ethers is re-read when dnsmasq receives SIGHUP. IPv6
addresses are NOT read from /etc/ethers.
-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>]]
Specify different or extra
options to DHCP clients. By default, dnsmasq sends some
standard options to DHCP clients, the netmask and broadcast
address are set to the same as the host running dnsmasq, and
the DNS server and default route are set to the address of
the machine running dnsmasq. (Equivalent rules apply for
IPv6.) If the domain name option has been set, that is sent.
This configuration allows these defaults to be overridden,
or other options specified. The option, to be sent may be
given as a decimal number or as
"option:<option-name>" The option numbers
are specified in RFC2132 and subsequent RFCs. The set of
option-names known by dnsmasq can be discovered by running
"dnsmasq --help dhcp". For example, to set the
default route option to 192.168.4.4, do
--dhcp-option=3,192.168.4.4 or --dhcp-option =
option:router, 192.168.4.4 and to set the time-server
address to 192.168.0.4, do --dhcp-option =
42,192.168.0.4 or --dhcp-option = option:ntp-server,
192.168.0.4 The special address 0.0.0.0 (or [::] for
DHCPv6) is taken to mean "the address of the machine
running dnsmasq". Data types allowed are comma
separated dotted-quad IP addresses, a decimal number,
colon-separated hex digits and a text string. If the
optional tags are given then this option is only sent when
all the tags are matched.
Special
processing is done on a text argument for option 119, to
conform with RFC 3397. Text or dotted-quad IP addresses as
arguments to option 120 are handled as per RFC 3361.
Dotted-quad IP addresses which are followed by a slash and
then a netmask size are encoded as described in RFC
3442.
IPv6 options
are specified using the option6: keyword, followed by
the option number or option name. The IPv6 option name space
is disjoint from the IPv4 option name space. IPv6 addresses
in options must be bracketed with square brackets, eg.
--dhcp-option=option6:ntp-server,[1234::56]
Be careful: no
checking is done that the correct type of data for the
option number is sent, it is quite possible to persuade
dnsmasq to generate illegal DHCP packets with injudicious
use of this flag. When the value is a decimal number,
dnsmasq must determine how large the data item is. It does
this by examining the option number and/or the value, but
can be overridden by appending a single letter flag as
follows: b = one byte, s = two bytes, i = four bytes. This
is mainly useful with encapsulated vendor class options (see
below) where dnsmasq cannot determine data size from the
option number. Option data which consists solely of periods
and digits will be interpreted by dnsmasq as an IP address,
and inserted into an option as such. To force a literal
string, use quotes. For instance when using option 66 to
send a literal IP address as TFTP server name, it is
necessary to do
--dhcp-option=66,"1.2.3.4"
Encapsulated
Vendor-class options may also be specified (IPv4 only) using
--dhcp-option: for instance
--dhcp-option=vendor:PXEClient,1,0.0.0.0 sends the
encapsulated vendor class-specific option
"mftp-address=0.0.0.0" to any client whose
vendor-class matches "PXEClient". The vendor-class
matching is substring based (see --dhcp-vendorclass for
details). If a vendor-class option (number 60) is sent by
dnsmasq, then that is used for selecting encapsulated
options in preference to any sent by the client. It is
possible to omit the vendorclass completely;
--dhcp-option=vendor:,1,0.0.0.0 in which case the
encapsulated option is always sent.
Options may be
encapsulated (IPv4 only) within other options: for instance
--dhcp-option=encap:175, 190, iscsi-client0 will send
option 175, within which is the option 190. If multiple
options are given which are encapsulated with the same
option number then they will be correctly combined into one
encapsulated option. encap: and vendor: are may not both be
set in the same dhcp-option.
The final
variant on encapsulated options is "Vendor-Identifying
Vendor Options" as specified by RFC3925. These are
denoted like this: --dhcp-option=vi-encap:2, 10, text
The number in the vi-encap: section is the IANA enterprise
number used to identify this option. This form of
encapsulation is supported in IPv6.
The address
0.0.0.0 is not treated specially in encapsulated
options.
--dhcp-option-force=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<enterprise>,][vendor:[<vendor-class>],]<opt>,[<value>[,<value>]]
This works in exactly the same
way as --dhcp-option except that the option will
always be sent, even if the client does not ask for it in
the parameter request list. This is sometimes needed, for
example when sending options to PXELinux.
--dhcp-no-override
(IPv4 only) Disable re-use of
the DHCP servername and filename fields as extra option
space. If it can, dnsmasq moves the boot server and filename
information (from dhcp-boot) out of their dedicated fields
into DHCP options. This make extra space available in the
DHCP packet for options but can, rarely, confuse old or
broken clients. This flag forces "simple and safe"
behaviour to avoid problems in such a case.
-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 "vendor
class" which represents, in some sense, the type of
host. This option maps vendor classes to tags, so that DHCP
options may be selectively delivered to different classes of
hosts. For example
dhcp-vendorclass=set:printers,Hewlett-Packard
JetDirect will allow options to be set only for HP
printers like so:
--dhcp-option=tag:printers,3,192.168.4.4 The
vendor-class string is substring matched against the
vendor-class supplied by the client, to allow fuzzy
matching. The set: prefix is optional but allowed for
consistency.
Note that in
IPv6 only, vendorclasses are namespaced with an
IANA-allocated enterprise number. This is given with
enterprise: keyword and specifies that only vendorclasses
matching the specified number should be searched.
-j,
--dhcp-userclass=set:<tag>,<user-class>
Map from a user-class string to
a tag (with substring matching, like vendor classes). Most
DHCP clients provide a "user class" which is
configurable. This option maps user classes to tags, so that
DHCP options may be selectively delivered to different
classes of hosts. It is possible, for instance to use this
to set a different printer server for hosts in the class
"accounts" than for hosts in the class
"engineering".
-4,
--dhcp-mac=set:<tag>,<MAC address>
(IPv4 only) Map from a MAC
address to a tag. The MAC address may include wildcards. For
example --dhcp-mac=set:3com,01:34:23:*:*:* will set
the tag "3com" for any host whose MAC address
matches the pattern.
--dhcp-circuitid=set:<tag>,<circuit-id>,
--dhcp-remoteid=set:<tag>,<remote-id>
Map from RFC3046 relay agent
options to tags. This data may be provided by DHCP relay
agents. The circuit-id or remote-id is normally given as
colon-separated hex, but is also allowed to be a simple
string. If an exact match is achieved between the circuit or
agent ID and one provided by a relay agent, the tag is
set.
dhcp-remoteid
(but not dhcp-circuitid) is supported in IPv6.
--dhcp-subscrid=set:<tag>,<subscriber-id>
(IPv4 and IPv6) Map from
RFC3993 subscriber-id relay agent options to tags.
--dhcp-proxy[=<ip
addr>]......
(IPv4 only) A normal DHCP relay
agent is only used to forward the initial parts of a DHCP
interaction to the DHCP server. Once a client is configured,
it communicates directly with the server. This is
undesirable if the relay agent is addding extra information
to the DHCP packets, such as that used by
dhcp-circuitid and dhcp-remoteid. A full relay
implementation can use the RFC 5107 serverid-override option
to force the DHCP server to use the relay as a full proxy,
with all packets passing through it. This flag provides an
alternative method of doing the same thing, for relays which
don’t support RFC 5107. Given alone, it manipulates
the server-id for all interactions via relays. If a list of
IP addresses is given, only interactions via relays at those
addresses are affected.
--dhcp-match=set:<tag>,<option
number>|option:<option
name>|vi-encap:<enterprise>[,<value>]
Without a value, set the tag if
the client sends a DHCP option of the given number or name.
When a value is given, set the tag only if the option is
sent and matches the value. The value may be of the form
"01:ff:*:02" in which case the value must match
(apart from widcards) but the option sent may have unmatched
data past the end of the value. The value may also be of the
same form as in dhcp-option in which case the option
sent is treated as an array, and one element must match,
so
--dhcp-match=set:efi-ia32,option:client-arch,6
will set the
tag "efi-ia32" if the the number 6 appears in the
list of architectures sent by the client in option 93. (See
RFC 4578 for details.) If the value is a string, substring
matching is used.
The special
form with vi-encap:<enterpise number> matches against
vendor-identifying vendor classes for the specified
enterprise. Please see RFC 3925 for more details of these
rare and interesting beasts.
--tag-if=set:<tag>[,set:<tag>[,tag:<tag>[,tag:<tag>]]]
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 set by another tag-if, the line which sets the
tag must precede the one which tests it.
-J,
--dhcp-ignore=tag:<tag>[,tag:<tag>]
When all the given tags appear
in the tag set ignore the host and do not allocate it a DHCP
lease.
--dhcp-ignore-names[=tag:<tag>[,tag:<tag>]]
When all the given tags appear
in the tag set, ignore any hostname provided by the host.
Note that, unlike dhcp-ignore, it is permissible to supply
no tags, in which case DHCP-client supplied hostnames are
always ignored, and DHCP hosts are added to the DNS using
only dhcp-host configuration in dnsmasq and the contents of
/etc/hosts and /etc/ethers.
--dhcp-generate-names=tag:<tag>[,tag:<tag>]
(IPv4 only) Generate a name for
DHCP clients which do not otherwise have one, using the MAC
address expressed in hex, seperated by dashes. Note that if
a host provides a name, it will be used by preference to
this, unless --dhcp-ignore-names is set.
--dhcp-broadcast[=tag:<tag>[,tag:<tag>]]
(IPv4 only) When all the given
tags appear in the tag set, always use broadcast to
communicate with the host when it is unconfigured. It is
permissible to supply no tags, in which case this is
unconditional. Most DHCP clients which need broadcast
replies set a flag in their requests so that this happens
automatically, some old BOOTP clients do not.
-M,
--dhcp-boot=[tag:<tag>,]<filename>,[<servername>[,<server
address>|<tftp_servername>]]
(IPv4 only) Set BOOTP options
to be returned by the DHCP server. Server name and address
are optional: if not provided, the name is left empty, and
the address set to the address of the machine running
dnsmasq. If dnsmasq is providing a TFTP service (see
--enable-tftp ) then only the filename is required
here to enable network booting. If the optional tag(s) are
given, they must match for this configuration to be sent.
Instead of an IP address, the TFTP server address can be
given as a domain name which is looked up in /etc/hosts.
This name can be associated in /etc/hosts with multiple IP
addresses, which are used round-robin. This facility can be
used to load balance the tftp load among a set of
servers.
--dhcp-sequential-ip
Dnsmasq is designed to choose
IP addresses for DHCP clients using a hash of the
client’s MAC address. This normally allows a
client’s address to remain stable long-term, even if
the client sometimes allows its DHCP lease to expire. In
this default mode IP addresses are distributed
pseudo-randomly over the entire available address range.
There are sometimes circumstances (typically server
deployment) where it is more convenient to have IP addresses
allocated sequentially, starting from the lowest available
address, and setting this flag enables this mode. Note that
in the sequential mode, clients which allow a lease to
expire are much more likely to move IP address; for this
reason it should not be generally used.
--pxe-service=[tag:<tag>,]<CSA>,<menu
text>[,<basename>|<bootservicetype>][,<server
address>|<server_name>]
Most uses of PXE boot-ROMS
simply allow the PXE system to obtain an IP address and then
download the file specified by dhcp-boot and execute
it. However the PXE system is capable of more complex
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 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, either from itself ( enable-tftp 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 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. If no
boot service type or filename is provided (or a boot service
type of 0 is specified) then the menu entry will abort the
net boot procedure and continue booting from local media.
The server address can be given as a domain name which is
looked up in /etc/hosts. This name can be associated in
/etc/hosts with multiple IP addresses, which are used
round-robin.
--pxe-prompt=[tag:<tag>,]<prompt>[,<timeout>]
Setting this provides a prompt
to be displayed after PXE boot. If the timeout is given then
after the timeout has elapsed with no keyboard input, the
first available menu option will be automatically executed.
If the timeout is zero then the first available menu item
will be executed immediately. If pxe-prompt is
ommitted the system will wait for user input if there are
multiple items in the menu, but boot immediately if there is
only one. See pxe-service for details of menu
items.
Dnsmasq
supports PXE "proxy-DHCP", in this case another
DHCP server on the network is responsible for allocating IP
addresses, and dnsmasq simply provides the information given
in pxe-prompt and pxe-service to allow
netbooting. This mode is enabled using the proxy
keyword in dhcp-range.
-X,
--dhcp-lease-max=<number>
Limits dnsmasq to the specified
maximum number of DHCP leases. The default is 1000. This
limit is to prevent DoS attacks from hosts which create
thousands of leases and use lots of memory in the dnsmasq
process.
-K,
--dhcp-authoritative
(IPv4 only) Should be set when
dnsmasq is definitely the only DHCP server on a network. It
changes the behaviour from strict RFC compliance so that
DHCP requests on unknown leases from unknown hosts are not
ignored. This allows new hosts to get a lease without a
tedious timeout under all circumstances. It also allows
dnsmasq to rebuild its lease database without each client
needing to reacquire a lease, if the database is lost.
--dhcp-alternate-port[=<server
port>[,<client port>]]
(IPv4 only) Change the ports
used for DHCP from the default. If this option is given
alone, without arguments, it changes the ports used for DHCP
from 67 and 68 to 1067 and 1068. If a single argument is
given, that port number is used for the server and the port
number plus one used for the client. Finally, two port
numbers allows arbitrary specification of both server and
client ports for DHCP.
-3,
--bootp-dynamic[=<network-id>[,<network-id>]]
(IPv4 only) Enable dynamic
allocation of IP addresses to BOOTP clients. Use this with
care, since each address allocated to a BOOTP client is
leased forever, and therefore becomes permanently
unavailable for re-use by other hosts. if this is given
without tags, then it unconditionally enables dynamic
allocation. With tags, only when the tags are all set. It
may be repeated with different tag sets.
-5, --no-ping
(IPv4 only) By default, the
DHCP server will attempt to ensure that an address in not in
use before allocating it to a host. It does this by sending
an ICMP echo request (aka "ping") to the address
in question. If it gets a reply, then the address must
already be in use, and another is tried. This flag disables
this check. Use with caution.
--log-dhcp
Extra logging for DHCP: log all
the options sent to DHCP clients and the tags used to
determine them.
-l,
--dhcp-leasefile=<path>
Use the specified file to store
DHCP lease information.
--dhcp-duid=<enterprise-id>,<uid>
(IPv6 only) Specify the server
persistent UID which the DHCPv6 server will use. This option
is not normally required as dnsmasq creates a 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 string of hex octets
unique to a particular device.
-6
--dhcp-script=<path>
Whenever a new DHCP lease is
created, or an old one destroyed, or a TFTP file transfer
completes, the executable specified by this option is run.
<path> must be an absolute pathname, no PATH search
occurs. The arguments to the process are "add",
"old" or "del", the MAC address of the
host (or DUID for IPv6) , the IP address, and the hostname,
if known. "add" means a lease has been created,
"del" means it has been destroyed, "old"
is a notification of an existing lease when dnsmasq starts
or a change to MAC address or hostname of an existing lease
(also, lease length or expiry and client-id, if leasefile-ro
is set). If the MAC address is from a network type other
than ethernet, it will have the network type prepended, eg
"06-01:23:45:67:89:ab" for token ring. The process
is run as root (assuming that dnsmasq was originally run as
root) even if dnsmasq is configured to change UID to an
unprivileged user.
The environment
is inherited from the invoker of dnsmasq, with some or all
of the following variables added
For both IPv4
and IPv6:
DNSMASQ_DOMAIN
if the fully-qualified domain name of the host is known,
this is set to the domain part. (Note that the hostname
passed to the script as an argument is never
fully-qualified.)
If the client
provides a hostname, DNSMASQ_SUPPLIED_HOSTNAME
If the client
provides user-classes,
DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn
If dnsmasq was
compiled with HAVE_BROKEN_RTC, then the length of the lease
(in seconds) is stored in DNSMASQ_LEASE_LENGTH, otherwise
the time of lease expiry is stored in DNSMASQ_LEASE_EXPIRES.
The number of seconds until lease expiry is always stored in
DNSMASQ_TIME_REMAINING.
If a lease used
to have a hostname, which is removed, an "old"
event is generated with the new state of the lease, ie no
name, and the former name is provided in the environment
variable DNSMASQ_OLD_HOSTNAME.
DNSMASQ_INTERFACE
stores the name of the interface on which the request
arrived; this is not set for "old" actions when
dnsmasq restarts.
DNSMASQ_RELAY_ADDRESS
is set if the client used a DHCP relay to contact dnsmasq
and the IP address of the relay is known.
DNSMASQ_TAGS
contains all the tags set during the DHCP transaction,
separated by spaces.
DNSMASQ_LOG_DHCP
is set if --log-dhcp is in effect.
For IPv4
only:
DNSMASQ_CLIENT_ID
if the host provided a client-id.
If the client
provides vendor-class, DNSMASQ_VENDOR_CLASS.
For IPv6
only:
If the client
provides vendor-class, DNSMASQ_VENDOR_CLASS_ID, containing
the IANA enterprise id for the class, and
DNSMASQ_VENDOR_CLASS0..DNSMASQ_VENDOR_CLASSn for the
data.
DNSMASQ_SERVER_DUID
containing the DUID of the server: this is the same for
every call to the script.
DNSMASQ_IAID
containing the IAID for the lease. If the lease is a
temporary allocation, this is prefixed to
’T’.
Note that the
supplied hostname, vendorclass and userclass data is only
supplied for "add" actions or "old"
actions when a host resumes an existing lease, since these
data are not held in dnsmasq’s lease database.
All file
descriptors are closed except stdin, stdout and stderr which
are open to /dev/null (except in debug mode).
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 before running the next). Changes to the lease database
are which require the script to be invoked are queued
awaiting exit of a running instance. If this queueing allows
multiple state changes occur to a single lease before the
script can be run then earlier states are discarded and the
current state of that lease is reflected when the script
finally runs.
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.
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 scripts should be written to
ignore unknown actions. "init" is described below
in --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.
--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 dnsmasq starts, so that global variables persist
between lease events. The Lua code must define a
lease function, and may provide init and
shutdown functions, which are called, without
arguments when dnsmasq starts up and terminates. It may also
provide a tftp function.
The
lease function receives the information detailed in
--dhcp-script. It gets two arguments, firstly the
action, which is a string containing, "add",
"old" or "del", and secondly a table of
tag value pairs. The tags mostly correspond to the
environment variables detailed above, for instance the tag
"domain" holds the same data as the environment
variable DNSMASQ_DOMAIN. There are a few extra tags which
hold the data supplied as arguments to --dhcp-script.
These are mac_address, ip_address and hostname
for IPv4, and client_duid, ip_address and
hostname for IPv6.
The tftp
function is called in the same way as the lease function,
and the table holds the tags destination_address,
file_name and file_size.
--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.
-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 script (if one is
provided) is called, so that the lease database may be
maintained in external storage by the script. In addition to
the invocations given in --dhcp-script the
lease-change script is called once, at dnsmasq startup, with
the single argument "init". When called like this
the script should write the saved state of the lease
database, in dnsmasq leasefile format, to stdout and exit
with zero exit code. Setting this option also forces the
leasechange script to be called on changes to the client-id
and lease length and expiry time.
--bridge-interface=<interface>,<alias>[,<alias>]
Treat DHCP request packets
arriving at any of the <alias> interfaces as if they
had arrived at <interface>. This option is necessary
when using "old style" bridging on BSD platforms,
since packets arrive at tap interfaces which don’t
have an IP address.
-s,
--domain=<domain>[,<address
range>[,local]]
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 which request it, and secondly it sets
the domain which it is legal for DHCP-configured hosts to
claim. The intention is to constrain hostnames so that an
untrusted host on the LAN cannot advertise its name via dhcp
as e.g. "microsoft.com" and capture traffic not
meant for it. If no domain suffix is specified, then any
DHCP hostname with a domain part (ie with a period) will be
disallowed and logged. If suffix is specified, then
hostnames with a domain part are allowed, provided the
domain part matches the suffix. In addition, when a suffix
is set then hostnames without a domain part have the suffix
added as an optional domain part. Eg on my network I can set
--domain=thekelleys.org.uk and have a machine whose
DHCP hostname is "laptop". The IP address for that
machine is available from dnsmasq both as
"laptop" and "laptop.thekelleys.org.uk".
If the domain is given as "#" then the domain is
read from the first "search" directive in
/etc/resolv.conf (or equivalent).
The address
range can be of the form <ip address>,<ip
address> or <ip address>/<netmask> or just a
single <ip address>. See --dhcp-fqdn which can
change the behaviour of dnsmasq with domains.
If the address
range is given as ip-address/network-size, then a additional
flag "local" may be supplied which has the effect
of adding --local declarations for forward and reverse DNS
queries. Eg.
--domain=thekelleys.org.uk,192.168.0.0/24,local is
identical to
--domain=thekelleys.org.uk,192.168.0.0/24
--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.
--dhcp-fqdn
In the default mode, dnsmasq
inserts the unqualified names of DHCP clients into the DNS.
For this reason, the names must be unique, even if two
clients which have the same name are in different domains.
If a second DHCP client appears which has the same name as
an existing client, the name is transfered to the new
client. If --dhcp-fqdn is set, this behaviour
changes: the unqualified name is no longer put in the DNS,
only the qualified name. Two DHCP clients with the same name
may both keep the name, provided that the domain part is
different (ie the fully qualified names differ.) To ensure
that all names have a domain part, there must be at least
--domain without an address specified when
--dhcp-fqdn is set.
--dhcp-client-update
Normally, when giving a DHCP
lease, dnsmasq sets flags in the FQDN option to tell the
client not to attempt a DDNS update with its name and IP
address. This is because the name-IP pair is automatically
added into dnsmasq’s DNS view. This flag suppresses
that behaviour, this is useful, for instance, to allow
Windows clients to update Active Directory servers. See RFC
4702 for details.
--enable-ra
Enable dnsmasq’s IPv6
Router Advertisement feature. DHCPv6 doesn’t handle
complete network configuration in the same way as DHCPv4.
Router discovery and (possibly) prefix discovery for
autonomous address 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
the "use SLAAC" bit is reset. This can be changed
for individual subnets with the mode keywords described in
--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.
--enable-tftp
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).
--tftp-root=<directory>[,<interface>]
Look for files to transfer
using TFTP relative to the given directory. When this is
set, TFTP paths which include ".." are rejected,
to stop clients getting outside the specified root. Absolute
paths (starting with /) are allowed, but they must be within
the tftp-root. If the optional interface argument is given,
the directory is only used for TFTP requests via that
interface.
--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.
--tftp-secure
Enable TFTP secure mode:
without this, any file which is readable by the dnsmasq
process under normal unix access-control rules is available
via TFTP. When the --tftp-secure flag is given, only files
owned by the user running the dnsmasq process are
accessible. If dnsmasq is being run as root, different rules
apply: --tftp-secure has no effect, but only files which
have the world-readable bit set are accessible. It is not
recommended to run dnsmasq as root with TFTP enabled, and
certainly not without specifying --tftp-root. Doing so can
expose any world-readable file on the server to any host on
the net.
--tftp-lowercase
Convert filenames in TFTP
requests to all lowercase. This is useful for requests from
Windows machines, which have case-insensitive filesystems
and tend to play fast-and-loose with case in filenames. Note
that dnsmasq’s tftp server always converts
"\" to "/" in filenames.
--tftp-max=<connections>
Set the maximum number of
concurrent TFTP connections allowed. This defaults to 50.
When serving a large number of TFTP connections, per-process
file descriptor limits may be encountered. Dnsmasq needs one
file descriptor for each concurrent TFTP connection and one
file descriptor per unique file (plus a few others). So
serving the same file simultaneously to n clients will use
require about n + 10 file descriptors, serving different
files simultaneously to n clients will require about (2*n) +
10 descriptors. If --tftp-port-range is given, that
can affect the number of concurrent connections.
--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
when it is granted.
--tftp-port-range=<start>,<end>
A TFTP server listens on a
well-known port (69) for connection initiation, but it also
uses a dynamically-allocated port for each connection.
Normally these are allocated by the OS, but this option
specifies a range of ports for use by TFTP transfers. This
can be useful when TFTP has to traverse a firewall. The
start of the range cannot be lower than 1025 unless dnsmasq
is running as root. The number of concurrent TFTP
connections is limited by the size of the port range.
-C,
--conf-file=<file>
Specify a different
configuration file. The conf-file option is also allowed in
configuration files, to include multiple configuration
files. A filename of "-" causes dnsmasq to read
configuration from stdin.
-7,
--conf-dir=<directory>[,<file-extension>......]
Read all the files in the given
directory as configuration files. If extension(s) are given,
any files which end in those extensions are skipped. Any
files whose names end in ~ or start with . or start and end
with # are always skipped. This flag may be given on the
command line or in a configuration file.
config file
At startup, dnsmasq reads /etc/dnsmasq.conf, if it exists.
(On FreeBSD, the file is /usr/local/etc/dnsmasq.conf )
(but see the -C and -7 options.) The format of this
file consists of one option per line, exactly as the long options
detailed in the OPTIONS section but without the leading "--".
Lines starting with # are comments and ignored. For options which
may only be specified once, the configuration file overrides the
command line. Quoting is allowed in a config file: between "
quotes the special meanings of ,:. and # are removed and the
following escapes are allowed: \\ \" \t \e \b \r and \n. The
later corresponding to tab, escape, backspace, return and
newline.
exit codes
0 - Dnsmasq successfully forked into the background, or
terminated normally if backgrounding is not enabled.
1 - A problem with configuration was detected.
2 - A problem with network access occurred (address in use,
attempt to use privileged ports without permission).
3 - A problem occurred with a filesystem operation (missing
file/directory, permissions).
4 - Memory allocation failure.
5 - Other miscellaneous problem.
11 or greater - a non zero return code was received from the
lease-script process "init" call. The exit code from dnsmasq is
the script’s exit code with 10 added.
files
/etc/dnsmasq.conf
/usr/local/etc/dnsmasq.conf
/etc/resolv.conf /var/run/dnsmasq/resolv.conf
/etc/ppp/resolv.conf /etc/dhcpc/resolv.conf
/etc/hosts
/etc/ethers
/var/lib/misc/dnsmasq.leases
/var/db/dnsmasq.leases
/var/run/dnsmasq.pid
internationalisation
Dnsmasq can be compiled to support internationalisation. To do
this, the make targets "all-i18n" and "install-i18n" should be
used instead of the standard targets "all" and "install". When
internationalisation is compiled in, dnsmasq will produce log
messages in the local language and support internationalised
domain names (IDN). Domain names in /etc/hosts, /etc/ethers and
/etc/dnsmasq.conf which contain non-ASCII characters will be
translated to the DNS-internal punycode representation. Note that
dnsmasq determines both the language for messages and the assumed
charset for configuration files from the LANG environment
variable. This should be set to the system default value by the
script which is responsible for starting dnsmasq. When editing
the configuration files, be careful to do so using only the
system-default locale and not user-specific one, since dnsmasq
has no direct way of determining the charset in use, and must
assume that it is the system default.
limits
The default values for resource limits in dnsmasq are generally
conservative, and appropriate for embedded router type devices
with slow processors and limited memory. On more capable
hardware, it is possible to increase the limits, and handle many
more clients. The following applies to dnsmasq-2.37: earlier
versions did not scale as well.
Dnsmasq is capable of handling DNS and DHCP for at least a
thousand clients. The DHCP lease times should not be very short
(less than one hour). The value of --dns-forward-max can
be increased: start with it equal to the number of clients and
increase if DNS seems slow. Note that DNS performance depends too
on the performance of the upstream nameservers. The size of the
DNS cache may be increased: the hard limit is 10000 names and the
default (150) is very low. Sending SIGUSR1 to dnsmasq makes it
log information which is useful for tuning the cache size. See
the NOTES section for details.
The built-in TFTP server is capable of many simultaneous file
transfers: the absolute limit is related to the number of
file-handles allowed to a process and the ability of the select()
system call to cope with large numbers of file handles. If the
limit is set too high using --tftp-max it will be scaled
down and the actual limit logged at start-up. Note that more
transfers are possible when the same file is being sent than when
each transfer sends a different file.
It is possible to use dnsmasq to block Web advertising by using a
list of known banner-ad servers, all resolving to 127.0.0.1 or
0.0.0.0, in /etc/hosts or an additional hosts file. The
list can be very long, dnsmasq has been tested successfully with
one million names. That size file needs a 1GHz processor and
about 60Mb of RAM.
notes
When it receives a SIGHUP, dnsmasq clears its cache and
then re-loads /etc/hosts and /etc/ethers and any
file given by --dhcp-hostsfile, --dhcp-optsfile or --addn-hosts.
The dhcp lease change script is called for all existing DHCP
leases. If --no-poll is set SIGHUP also re-reads
/etc/resolv.conf. SIGHUP does NOT re-read the
configuration file.
When it receives a SIGUSR1, dnsmasq writes statistics to
the system log. It writes the cache size, the number of names
which have had to removed from the cache before they expired in
order to make room for new names and the total number of names
that have been inserted into the cache. For each upstream server
it gives the number of queries sent, and the number which
resulted in an error. In --no-daemon mode or when full
logging is enabled (-q), a complete dump of the contents of the
cache is made.
When it receives SIGUSR2 and it is logging direct to a file (see
--log-facility ) dnsmasq will close and reopen the
log file. Note that during this operation, dnsmasq will not be
running as root. When it first creates the logfile dnsmasq
changes the ownership of the file to the non-root user it will
run as. Logrotate should be configured to create a new log file
with the ownership which matches the existing one before sending
SIGUSR2. If TCP DNS queries are in progress, the old logfile will
remain open in child processes which are handling TCP queries and
may continue to be written. There is a limit of 150 seconds,
after which all existing TCP processes will have expired: for
this reason, it is not wise to configure logfile compression for
logfiles which have just been rotated. Using logrotate, the
required options are create and delaycompress.
Dnsmasq is a DNS query forwarder: it it 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 /etc/resolv.conf to discover the IP
addresses of the upstream nameservers it should use, since the
information is typically stored there. Unless --no-poll is
used, dnsmasq checks the modification time of
/etc/resolv.conf (or equivalent if --resolv-file is
used) and re-reads it if it changes. This allows the DNS servers
to be set dynamically by PPP or DHCP since both protocols provide
the information. Absence of /etc/resolv.conf is not an
error since it may not have been created before a PPP connection
exists. Dnsmasq simply keeps checking in case
/etc/resolv.conf is created at any time. Dnsmasq can be
told to parse more than one resolv.conf file. This is useful on a
laptop, where both PPP and DHCP may be used: dnsmasq can be set
to poll both /etc/ppp/resolv.conf and
/etc/dhcpc/resolv.conf and will use the contents of
whichever changed last, giving automatic switching between DNS
servers.
Upstream servers may also be specified on the command line or in
the configuration file. These server specifications optionally
take a domain name which tells dnsmasq to use that server only to
find names in that particular domain.
In order to configure dnsmasq to act as cache for the host on
which it is running, put "nameserver 127.0.0.1" in
/etc/resolv.conf to force local processes to send queries
to dnsmasq. Then either specify the upstream servers directly to
dnsmasq using --server options or put their addresses real
in another file, say /etc/resolv.dnsmasq and run dnsmasq
with the -r /etc/resolv.dnsmasq option. This second
technique allows for dynamic update of the server addresses by
PPP or DHCP.
Addresses in /etc/hosts will "shadow" different addresses for the
same names in the upstream DNS, so "mycompany.com 1.2.3.4" in
/etc/hosts will ensure that queries for "mycompany.com" always
return 1.2.3.4 even if queries in the upstream DNS would
otherwise return a different address. There is one exception to
this: if the upstream DNS contains a CNAME which points to a
shadowed name, then looking up the CNAME through dnsmasq will
result in the unshadowed address associated with the target of
the CNAME. To work around this, add the CNAME to /etc/hosts so
that the CNAME is shadowed too.
The tag system works as follows: For each DHCP request, dnsmasq
collects a set of valid tags from active configuration lines
which include set:<tag>, including one from the
dhcp-range used to allocate the address, one from any
matching dhcp-host (and "known" 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.
Any configuration lines which includes one or more
tag:<tag> contructs will only be valid if all that tags are
matched in the set derived above. Typically this is dhcp-option.
dhcp-option which has tags will be used in preference to
an untagged dhcp-option, provided that _all_ the tags
match somewhere in the set collected as described above. The
prefix ’!’ on a tag means ’not’ so
--dhcp=option=tag:!purple,3,1.2.3.4 sends the option when the tag
purple is not in the set of valid tags. (If using this in a
command line rather than a configuration file, be sure to escape
!, which is a shell metacharacter)
When selecting dhcp-options, a tag from dhcp-range is second
class relative to other tags, to make it easy to override options
for individual hosts, so dhcp-range=set:interface1,......
dhcp-host=set:myhost,.....
dhcp-option=tag:interface1,option:nis-domain,"domain1"
dhcp-option=tag:myhost,option:nis-domain,"domain2" will set
the NIS-domain to domain1 for hosts in the range, but override
that to domain2 for a particular host.
Note that for dhcp-range both tag:<tag> and
set:<tag> are allowed, to both select the range in use
based on (eg) dhcp-host, and to affect the options sent, based on
the range selected.
This system evolved from an earlier, more limited one and for
backward compatibility "net:" may be used instead of "tag:" and
"set:" may be omitted. (Except in dhcp-host, where "net:"
may be used instead of "set:".) For the same reason, ’#’ may be
used instead of ’!’ to indicate NOT.
The DHCP server in dnsmasq will function as a BOOTP server also,
provided that the MAC address and IP address for clients are
given, either using dhcp-host configurations or in
/etc/ethers , and a dhcp-range configuration option
is present to activate the DHCP server on a particular network.
(Setting --bootp-dynamic removes the need for static address
mappings.) The filename parameter in a BOOTP request is used as a
tag, as is the tag "bootp", allowing some control over the
options returned to different classes of hosts.
see also
hosts,
resolver
author
This manual
page was written by Simon Kelley
<simon[:at:]thekelleys.org[:dot:]uk>.