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 should be run on your firewall machine (the machine with the modem or other connection to your ISP.) 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 priviliges after start-up. Dnsmasq logs problems using the syslog facility as a daemon.

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

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.

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 integrates with the ISC DHCP daemon to solve this problem.

The DHCP daemon stores information about the names and addresses of the hosts it controls in a leases file. This is stored at /var/lib/dhcp/dhcpd.leases or somewhere similar. Simply tell dnsmasq to monitor this file using the dhcp-lease option and it will extract the names and addresses of all the current hosts and add them to the DNS. For this to work, each machines 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 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. If there is more than one nameserver or more than one domain, just include as many server options as is needed to specify them all.

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