DNSMASQ(8)

NAME
dnsmasq - A caching DNS forwarder.

SYNOPSIS
dnsmasq [OPTION]...

DESCRIPTION
dnsmasq is a lightweight DNS forwarder. It 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 into the cache at startup so that local hostnames which do not appear in the global DNS can be resolved. It can also read hostnames from a DHCP leases file so that local hosts which have addresses allocated by DHCP can be named.

dnsmasq supports IPv6.

dnsmasq is lightweight and easy to configure. It is intended as be run on small router/firewalls and provide a DNS service to a LAN.

OPTIONS
Note that in general missing parameters are allowed and switch off functions, for instance "--resolv-file=" disables all use of /etc/resolv.conf.

-h, --no-hosts
    Don't read the hostnames in /etc/hosts.

-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.

-q, --log-queries
    Log the results of DNS queries handled by dnsmasq. Enable a full cache dump on receipt of SIGUSR1.

-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 priviledges after startup by changing id to another user. Normally this user is "nobody" but that can be over-ridden with this switch. Note that dnsmasq changes its group 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). Useful mainly for debugging.

-i, --interface=<interface name>
    Listen only on the specified interface. More than one interface may be specified. Dnsmasq always listens on the loopback (local) interface. If no -i flags are given, dnsmasq listens on all available interfaces unless overridden by -a flags.

-a, --listen-address
    Listen only on the given IP address. As with -i more than one address may be specified. Unlike -i the loopback interface is not special: if dnsmasq is to listen on the loopback interface, it's IP, 127.0.0.1, must be explicitly given. If no -a flags are given, dnsmasq listens on all available interfaces unless overridden by -i flags.

-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/resolv.conf or the DHCP leases file are resolved to the IP address in dotted-quad form.

-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.

-o, --strict-order
    By default, dnsmasq will send queries to any of the upstream servers it knows about and tries to favour servers to 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

-n, --no-poll
    Don't poll /etc/resolv.conf for changes.

-S, --server=/<domain>/<ipaddr>
    Specify IP address of upsream severs directly. Setting this flag does not suppress reading of /etc/resolv.conf, use -R to do that. If the optional /domain/ is given, that server is used only for that domain and that domain is 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. More than one -S flag is allowed, with repeated domain or ipaddr parts as required.

-m, --mx-host=<mx name>
    Return an MX record named <mx name> pointing to the host specified in the --mx-target switch or, if that switch is not given, the host on which dnsmasq is running. This is useful for directing mail from systems on a LAN to a central server.

-t, --mx-target=<hostname>
    Specify target for the MX record returned by dnsmasq. See --mx-host. Note that to turn on the MX function, at least one of --mx-record and --mx-target must be set. If only one of --mx-record and --mx-target is set, the other defaults to 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 the DHCP leases file.

-c, --cache-size=<cachesize>
    Set the size of dnsmasq's cache. The default is 150 names. Setting the cache size to zero disables caching.

-l, --dhcp-lease=<path>
    Read DHCP leases from the specified lease file. The file is of the format created by the ISC dhcp daemon: see dhcpd.leases(5) for details. Dnsmasq will re-read the file as it changes. Any host which sets the "hostname" or "client-hostname" option will have that name inserted into dnsmasq's cache.

-s, --domain-suffix=<domain>
    Specifies the domain which hosts read from the DHCP leases file must have to be legal. The intention is to constrain hostnames so that an untrusted host on the LAN cannot advertise it's 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-suffix=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".

CONFIG FILE
At startup, dnsmasq reads /etc/dnsmasq.conf, if it exists. The format of this file consists of one option per line, exactly as the long options detailed in the OPTIONS section. Lines starting with # are comments and ignored. For options which may only be specified once, /etc/dnsmasq.conf overrides the command line. Use the --conf-file option to specify a different configuration file.

NOTES
When it receives a SIGHUP, dnsmasq clears its cache and then re-loads /etc/hosts and /etc/resolv.conf. It does NOT re-read /etc/dnsmasq.conf.

When it receives a SIGUSR1, dnsmasq writes cache 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 have been inserted into the cache. In --no-daemon mode or when full logging is enabled (-q), a complete dump of the contents of the cache is made to stdout.

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.

Upstream servers may also be specified on the command line or in /etc/dnsmasq.conf. 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.

FILES
/etc/dnsmasq.conf /etc/resolv.conf /etc/hosts /var/lib/dhcp/dhcp.leases /var/run/dnsmasq.pid

SEE ALSO
dhcp.leases(5), hosts(5), resolver(5)

AUTHOR
This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.