1<HTML> 2<HEAD> 3<TITLE> Configuring Dnsmasq.</TITLE> 4</HEAD> 5<BODY BGCOLOR="WHITE"> 6<H1 ALIGN=center>Dnsmasq setup</H1> 7<H2>Installation.</H2> 8To compile and install dnsmasq, the following command (as root) is enough. 9 10<PRE> 11make install 12</PRE> 13 14You might want to edit config.h. Dnsmasq has 15been run on (at least) Linux, uCLinux, AIX 4.1.5, FreeBSD 4.4 OpenBSD and Tru64 4.x 16 17Dnsmasq should be run on your firewall machine (the machine with the modem or other connection to your ISP.) 18 19Put the binary in <TT>/usr/local/sbin/dnsmasq</TT> (running <TT>make install</TT> will do this) and arrange for it 20to be started at boot time. 21 22Note that dnsmasq needs to run as root, since it binds privileged ports. It will drop root priviliges after start-up. Dnsmasq 23logs problems using the syslog facility as a daemon. 24<P> 25<H2>Configuration.</H2> 26Configuration for dnsmasq is pretty simple in almost all cases. The 27program has collected a fair few options as it has developed but most of them 28are not needed most of the time. A machine which already has a DNS 29configuration (ie one or more external nameservers in <TT>/etc/resolv.conf</TT> 30and any local hosts in <TT>/etc/hosts</TT>) can be turned into a nameserver 31simply by running dnsmasq, with no options or configuration at 32all. Set the IP address of the machine running dnsmasq as the DNS 33server in all the other machines on your network, and your're done. 34<P> 35With a few option flags, it is possible to make dnsmasq do more clever 36tricks. Options for dnsmasq can be set either on the command line 37when starting dnsmasq, or in its configuration file, <TT>/etc/dnsmasq.conf</TT>. 38 39<h2>Making the nameserver machine use dnsmasq.</h2> 40In the simple configuration described above, processes local to the 41machine will not use dnsmasq, since they get their information about 42which nameservers to use from /etc/resolv.conf, which is set to the 43upstream nameservers. To fix this, simply replace the nameserver in 44<TT>/etc/resolv.conf</TT> with the local address 127.0.0.1 and give the 45address(es) of the upstream nameserver(s) to dnsmasq directly. You can 46do this using either the <TT>server</TT> option, or by putting them into 47another file, and telling dnsmasq about its location with 48the <TT>resolv-file</TT> option. 49 50<h2>Automatic nameserver configuration.</h2> 51The two protocols most used for automatic IP network configuration 52(PPP and DHCP) can determine the IP addresses for nameservers automatically. 53The daemons can be made to write out a file in the resolv.conf format with the 54nameservers in which is perfect for dnsmasq to use. When the 55nameservers change, for instance on dialling into a new ISP using PPP, 56dnsmasq will automatically re-read this file and begin using the new 57nameserver(s) completely transparently. 58 59<h3>Automatic DNS server configuration with PPP.</h3> 60Later versions of pppd have an option "usepeerdns" which instructs it to write a file containing 61the address(es) of the DNS severs in <TT>/etc/ppp/resolv.conf</TT>. Configure dnsmasq 62as above with "nameserver 127.0.0.1" in <TT>/etc/resolv.conf</TT> and run dnsmasq 63with to option <TT>resolv-file=/etc/ppp/resolv.conf</TT>. 64<P> 65On Redhat (at least versions 7.1, 7.2 and 7.3) you can set pppd 66options by adding "PPPOPTIONS=usepeerdns" to 67<TT>/etc/sysconfig/network-scripts/ifcfg-ippp0</TT>. In the same file, make sure 68that "PEERDNS=no" to stop RedHat's network initscripts from copying 69<TT>/etc/ppp/resolv.conf</TT> into <TT>/etc/resolv.conf</TT>. 70 71 72<h3>Automatic DNS server configuration with DHCP.</h3> 73You need to get your DHCP client to write the addresse(s) of the DNS 74servers to a file other than <TT>/etc/resolv.conf</TT>. For dhcpcd, the 75<TT>dhcpcd.exe</TT> script gets run with the addresses of the nameserver(s) in 76the shell variable <TT>$DNS</TT>. The following bit of shell script 77uses that to write a file suitable for dnsmasq. 78<PRE> 79 80echo -n >|/etc/dhcpc/resolv.conf 81dnsservs=${DNS/,/ } 82for serv in $dnsservs; do 83 echo "nameserver $serv" >>/etc/dhcpc/resolv.conf 84done 85 86</PRE> 87 88Remember to give dhcpcd the <TT>-R</TT> flag to stop it overwriting 89<TT>/etc/resolv.conf</TT>. 90 91<P> 92For other DHCP clients it should be possible to achieve the same effect. 93 94<H2> Integration with DHCP.</H2> 95Dnsmasq reads <TT>/etc/hosts</TT> so that the names of local machines are 96available in DNS. This is fine when you give all your local machines 97static IP addresses which can go in <TT>/etc/hosts</TT>, but it doesn't work 98when local machines are configured via DHCP, since the IP address 99allocated to machine is not fixed. Dnsmasq integrates with the ISC 100DHCP daemon to solve this problem. 101<P> 102The DHCP daemon stores information about the names and addresses of 103the hosts it controls in a leases file. This is stored at 104<TT>/var/lib/dhcp/dhcpd.leases</TT> or somewhere similar. Simply tell dnsmasq 105to monitor this file using the <TT>dhcp-lease</TT> option and it will extract 106the names and addresses of all the current hosts and add them to the 107DNS. For this to work, each machines needs to know its name when it 108requests a DHCP lease. For dhcpcd, the -h option specifies this. The 109names may be anything as far as DHCP is concerned, but dnsmasq adds 110some limitations. By default the names must no have a domain part, ie 111they must just be a alphanumeric name, without any dots. This is a 112security feature to stop a machine on your network telling DHCP that 113its name is "www.microsoft.com" and thereby grabbing traffic which 114shouldn't go to it. A domain part is only allowed by dnsmasq in DHCP machine names 115if the <TT>domain-suffix</TT> option is set, the domain part must match the 116suffix. 117<P> 118As an aside, make sure not to tell DHCP to set the hostname when it 119obtains a lease (in dhcpcd that's the -H flag.) 120This is not reliable since the DHCP server gets the 121hostname from DNS which in this case is dnsmasq. There is a race 122condition because the the host's name in the DNS may change as a 123result of it getting a DHCP lease, but this does not propagate before 124the name is looked up. THe net effect may be that the host believes it 125is called something different to its name in the DNS. To be safe, set 126the hostname on a machine locally, and pass the same name to DHCP when 127requesting a lease. 128<P> 129<H2>Setting up a mailhub.</H2> 130If you generate mail on the machines attached to your private network, you may 131 be interested in the MX record feature of dnsmasq. This allows you to have all 132 the machines on your network use your firewall or another machine as a "smarthost" and 133deliver mail to it. The details of how to set this up are highly dependent on 134your mailer, system and distribution. The only thing that's relevant to dnsmasq is that the mailer 135needs to be able to interrogate the DNS and find an MX record for your mailhub. 136<P> 137By giving dnsmasq the <TT>mx-host</TT> option 138you instruct dnsmasq to serve an MX record for the specified address. 139By default the MX record 140points to the machine on which dnsmasq is running, so mail delivered to that 141name will get sent to the mailer on your firewall machine. You can 142have the MX record point to another machine by using the <TT>mx-target</TT> 143option. 144<P> 145In some cases it's useful for all local machines to see an MX record 146pointing at themselves: this allows mailers which insist on an MX record and 147don't fall back to A records to deliver mail within the 148machine. These MX records are enabled using the <TT>selfmx</TT> option. 149 150<H2>Using special servers.</H2> 151Dnsmasq has the ability to direct DNS queries for certain domains to 152specific upstream nameservers. This feature was added for use with 153VPNs but it is fully general. The scenario is this: you have a 154standard internet connection via an ISP, and dnsmasq is configured to 155forward queries to the ISP's nameservers, then you make a VPN 156connection into your companies network, giving access to hosts inside 157the company firewall. You have access, but since many of the internal hosts 158aren't visible on the public internet, your company doesn't publish 159them to the public DNS and you can't get their IP address from the ISP 160nameservers. The solution is to use the companies nameserver for 161private domains within the company, and dnsmasq allows this. Assuming 162that internal company machines are all in the domain internal.myco.com 163and the companies nameserver is at 192.168.10.1 then the option 164<TT>server=/internal.myco.com/192.168.10.1</TT> will direct all 165queries in the internal domain to the correct nameserver. If there is 166more than one nameserver or more than one domain, just include as many 167<TT>server</TT> options as is needed to specify them all. 168 169<H2>Other configuration details.</H2> 170By default dnsmasq offers DNS service on all the configured interfaces 171of a host. It's likely that you don't (for instance) want to offer a 172DNS service to the world via an interface connected to ADSL or 173cable-modem so dnsmasq allows you to specify which interfaces it will 174listen on. Use either the <TT>interface</TT> or <TT>address</TT> options to do this. 175<P> 176The <TT>filterwin2k</TT> option makes dnsmasq ignore certain DNS requests which 177are made by Windows boxen every few minutes. The requests generally 178don't get sensible answers in the global DNS and cause trouble by 179triggering dial-on-demand internet links. 180<P> 181Sending SIGHUP to the dnsmasq process will cause it to empty its cache and 182then re-load <TT>/etc/hosts</TT> and <TT>/etc/resolv.conf</TT>. 183<P> Sending SIGUSR1 (killall -10 dnsmasq) to the dnsmasq process will 184cause to to write cache usage statisticss to the log, typically 185<TT>/var/log/syslog</TT> or <TT>/var/log/messages</TT>. 186<P> The <TT>log-queries</TT> option tells dnsmasq to verbosely log the queries 187it is handling and causes SIGUSR1 to trigger a complete dump of the 188contents of the cache to the syslog. 189 190<P>For a complete listing of options please take a look at the manpage 191dnsmasq(8). 192