Dnsmasq setup

Installation.

To compile and install dnsmasq, the following command (as root) is enough.

make install

You might want to edit config.h. Dnsmasq has been run on (at least) Linux, uCLinux, AIX 4.1.5, FreeBSD 4.4 OpenBSD and Tru64 4.x Dnsmasq is normally run on a firewall machine (the machine with the modem or other connection to your ISP.) but it can run on any machine with access to the ISPs nameservers. Put the binary in /usr/local/sbin/dnsmasq (running make install will do this) and arrange for it to be started at boot time. Note that dnsmasq needs to run as root, since it binds privileged ports. It will drop root privileges after start-up. Dnsmasq logs problems using the syslog facility as a daemon. It logs debugging information to local0

Configuration.

Configuration for dnsmasq is pretty simple in almost all cases. The program has collected a fair few options as it has developed but most of them are not needed most of the time. A machine which already has a DNS configuration (ie one or more external nameservers in /etc/resolv.conf and any local hosts in /etc/hosts) can be turned into a nameserver simply by running dnsmasq, with no options or configuration at all. Set the IP address of the machine running dnsmasq as the DNS server in all the other machines on your network, and you're done.

With a few option flags, it is possible to make dnsmasq do more clever tricks. Options for dnsmasq can be set either on the command line when starting dnsmasq, or in its configuration file, /etc/dnsmasq.conf.

Making the nameserver machine use dnsmasq.

In the simple configuration described above, processes local to the machine will not use dnsmasq, since they get their information about which nameservers to use from /etc/resolv.conf, which is set to the upstream nameservers. To fix this, simply replace the nameserver in /etc/resolv.conf with the local address 127.0.0.1 and give the address(es) of the upstream nameserver(s) to dnsmasq directly. You can do this using either the server option, or by putting them into another file, and telling dnsmasq about its location with the resolv-file option.

Automatic nameserver configuration.

The two protocols most used for automatic IP network configuration (PPP and DHCP) can determine the IP addresses for nameservers automatically. The daemons can be made to write out a file in the resolv.conf format with the nameservers in which is perfect for dnsmasq to use. When the nameservers change, for instance on dialling into a new ISP using PPP, dnsmasq will automatically re-read this file and begin using the new nameserver(s) completely transparently.

Automatic DNS server configuration with PPP.

Later versions of pppd have an option "usepeerdns" which instructs it to write a file containing the address(es) of the DNS severs in /etc/ppp/resolv.conf. Configure dnsmasq as above with "nameserver 127.0.0.1" in /etc/resolv.conf and run dnsmasq with to option resolv-file=/etc/ppp/resolv.conf.

On Redhat (at least versions 7.1, 7.2 and 7.3) you can set pppd options by adding "PPPOPTIONS=usepeerdns" to /etc/sysconfig/network-scripts/ifcfg-ippp0. In the same file, make sure that "PEERDNS=no" to stop RedHat's network initscripts from copying /etc/ppp/resolv.conf into /etc/resolv.conf.
On SuSE (at least version 8.1, and 8.2) you should use YaST to activate [x] Modify DNS when connected then stop SuSEs network initscripts from copying /etc/ppp/resolv.conf into /etc/resolv.conf by modifying MODIFY_RESOLV_CONF_DYNAMICALLY="no" in /etc/sysconfig/network/config.

Automatic DNS server configuration with DHCP.

You need to get your DHCP client to write the addresse(s) of the DNS servers to a file other than /etc/resolv.conf. For dhcpcd, the dhcpcd.exe script gets run with the addresses of the nameserver(s) in the shell variable $DNS. The following bit of shell script uses that to write a file suitable for dnsmasq.


echo -n >|/etc/dhcpc/resolv.conf
dnsservs=${DNS//,/ }
for serv in $dnsservs; do
    echo "nameserver $serv" >>/etc/dhcpc/resolv.conf
done

Remember to give dhcpcd the -R flag to stop it overwriting /etc/resolv.conf.

For other DHCP clients it should be possible to achieve the same effect.

DHCP and PPP.

On a laptop which may potentially connect via a modem and PPP or ethernet and DHCP it is possible to combine both of the above configurations. Running dnsmasq with the flags resolv-file=/etc/ppp/resolv.conf resolv-file=/etc/dhcpc/resolv.conf makes it poll both files and use whichever was updated last. The result is automatic switching between DNS servers.

Integration with DHCP.

Dnsmasq reads /etc/hosts so that the names of local machines are available in DNS. This is fine when you give all your local machines static IP addresses which can go in /etc/hosts, but it doesn't work when local machines are configured via DHCP, since the IP address allocated to machine is not fixed. Dnsmasq comes with an integrated DHCP daemon to solve this problem.

The dnsmasq DHCP daemon allocates addresses to hosts on the network and tries to determine their names. If it succeeds it add the name and address pair to the DNS. There are basically two ways to associate a name with a DHCP-configured machine; either the machine knows its name which it gets a DHCP lease, or dnsmasq gives it a name, based on the MAC address of its ethernet card. For the former to work, a machine needs to know its name when it requests a DHCP lease. For dhcpcd, the -h option specifies this. The names may be anything as far as DHCP is concerned, but dnsmasq adds some limitations. By default the names must no have a domain part, ie they must just be a alphanumeric name, without any dots. This is a security feature to stop a machine on your network telling DHCP that its name is "www.microsoft.com" and thereby grabbing traffic which shouldn't go to it. A domain part is only allowed by dnsmasq in DHCP machine names if the domain-suffix option is set, the domain part must match the suffix.

As an aside, make sure not to tell DHCP to set the hostname when it obtains a lease (in dhcpcd that's the -H flag.) This is not reliable since the DHCP server gets the hostname from DNS which in this case is dnsmasq. There is a race condition because the host's name in the DNS may change as a result of it getting a DHCP lease, but this does not propagate before the name is looked up. The net effect may be that the host believes it is called something different to its name in the DNS. To be safe, set the hostname on a machine locally, and pass the same name to DHCP when requesting a lease.

Setting up a mailhub.

If you generate mail on the machines attached to your private network, you may be interested in the MX record feature of dnsmasq. This allows you to have all the machines on your network use your firewall or another machine as a "smarthost" and deliver mail to it. The details of how to set this up are highly dependent on your mailer, system and distribution. The only thing that's relevant to dnsmasq is that the mailer needs to be able to interrogate the DNS and find an MX record for your mailhub.

By giving dnsmasq the mx-host option you instruct dnsmasq to serve an MX record for the specified address. By default the MX record points to the machine on which dnsmasq is running, so mail delivered to that name will get sent to the mailer on your firewall machine. You can have the MX record point to another machine by using the mx-target option.

In some cases it's useful for all local machines to see an MX record pointing at themselves: this allows mailers which insist on an MX record and don't fall back to A records to deliver mail within the machine. These MX records are enabled using the selfmx option.

Using special servers.

Dnsmasq has the ability to direct DNS queries for certain domains to specific upstream nameservers. This feature was added for use with VPNs but it is fully general. The scenario is this: you have a standard internet connection via an ISP, and dnsmasq is configured to forward queries to the ISP's nameservers, then you make a VPN connection into your companies network, giving access to hosts inside the company firewall. You have access, but since many of the internal hosts aren't visible on the public internet, your company doesn't publish them to the public DNS and you can't get their IP address from the ISP nameservers. The solution is to use the companies nameserver for private domains within the company, and dnsmasq allows this. Assuming that internal company machines are all in the domain internal.myco.com and the companies nameserver is at 192.168.10.1 then the option server=/internal.myco.com/192.168.10.1 will direct all queries in the internal domain to the correct nameserver. You can specify more than one domain in each server option. If there is more than one nameserver just include as many server options as is needed to specify them all.

Local domains.

Sometimes people have local domains which they do not want forwarded to upstream servers. This is accomodated by using server options without the server IP address. To make things clearer local is a synonym for server. For example the option local=/localnet/ ensures that any domain name query which ends in .localnet will be answered if possible from /etc/hosts or DHCP, but never sent to an upstream server.

Defeating wildcards in top level domains.

In September 2003 Verisign installed a wildcard record in the .com and .net top level domains. The effect of this is that queries for unregistered .com and .net names now return the address of Verisign's sitefinder service, rather than a "no such domain" response. To restore the correct behaviour, you can tell dnsmasq the address of the sitefinder host and have it substitute an NXDOMAIN reply when it sees that address. The sitefinder address is currently 64.94.110.11, so giving the option bogus-nxdomain=64.94.110.11 will enable this facility for Verisign. If other TLDs do that same thing you can add the correct addresses for them too. See the dnsmasq FAQ for more details on the bogus-nxdomain option.

Other configuration details.

By default dnsmasq offers DNS service on all the configured interfaces of a host. It's likely that you don't (for instance) want to offer a DNS service to the world via an interface connected to ADSL or cable-modem so dnsmasq allows you to specify which interfaces it will listen on. Use either the interface or address options to do this.

The filterwin2k option makes dnsmasq ignore certain DNS requests which are made by Windows boxen every few minutes. The requests generally don't get sensible answers in the global DNS and cause trouble by triggering dial-on-demand internet links.

Sending SIGHUP to the dnsmasq process will cause it to empty its cache and then re-load /etc/hosts and /etc/resolv.conf.

Sending SIGUSR1 (killall -10 dnsmasq) to the dnsmasq process will cause to to write cache usage statisticss to the log, typically /var/log/syslog or /var/log/messages.

The log-queries option tells dnsmasq to verbosely log the queries it is handling and causes SIGUSR1 to trigger a complete dump of the contents of the cache to the syslog.

For a complete listing of options please take a look at the manpage dnsmasq(8).