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 is normally run on a firewall machine (the machine with the 18modem or other connection to your ISP.) but it can run on any machine 19with access to the ISPs nameservers. 20 21Put the binary in <TT>/usr/local/sbin/dnsmasq</TT> (running <TT>make install</TT> will do this) and arrange for it 22to be started at boot time. 23 24Note that dnsmasq needs to run as root, since it binds privileged ports. It will drop root privileges after start-up. Dnsmasq 25logs problems using the syslog facility as a daemon. It logs debugging 26information to local0 27<P> 28<H2>Configuration.</H2> 29Configuration for dnsmasq is pretty simple in almost all cases. The 30program has collected a fair few options as it has developed but most of them 31are not needed most of the time. A machine which already has a DNS 32configuration (ie one or more external nameservers in <TT>/etc/resolv.conf</TT> 33and any local hosts in <TT>/etc/hosts</TT>) can be turned into a nameserver 34simply by running dnsmasq, with no options or configuration at 35all. Set the IP address of the machine running dnsmasq as the DNS 36server in all the other machines on your network, and you're done. 37<P> 38With a few option flags, it is possible to make dnsmasq do more clever 39tricks. Options for dnsmasq can be set either on the command line 40when starting dnsmasq, or in its configuration file, <TT>/etc/dnsmasq.conf</TT>. 41 42<h2>Making the nameserver machine use dnsmasq.</h2> 43In the simple configuration described above, processes local to the 44machine will not use dnsmasq, since they get their information about 45which nameservers to use from /etc/resolv.conf, which is set to the 46upstream nameservers. To fix this, simply replace the nameserver in 47<TT>/etc/resolv.conf</TT> with the local address 127.0.0.1 and give the 48address(es) of the upstream nameserver(s) to dnsmasq directly. You can 49do this using either the <TT>server</TT> option, or by putting them into 50another file, and telling dnsmasq about its location with 51the <TT>resolv-file</TT> option. 52 53<h2>Automatic nameserver configuration.</h2> 54The two protocols most used for automatic IP network configuration 55(PPP and DHCP) can determine the IP addresses for nameservers automatically. 56The daemons can be made to write out a file in the resolv.conf format with the 57nameservers in which is perfect for dnsmasq to use. When the 58nameservers change, for instance on dialling into a new ISP using PPP, 59dnsmasq will automatically re-read this file and begin using the new 60nameserver(s) completely transparently. 61 62<h3>Automatic DNS server configuration with PPP.</h3> 63Later versions of pppd have an option "usepeerdns" which instructs it to write a file containing 64the address(es) of the DNS severs in <TT>/etc/ppp/resolv.conf</TT>. Configure dnsmasq 65as above with "nameserver 127.0.0.1" in <TT>/etc/resolv.conf</TT> and run dnsmasq 66with to option <TT>resolv-file=/etc/ppp/resolv.conf</TT>. 67<P> 68On Redhat (at least versions 7.1, 7.2 and 7.3) you can set pppd 69options by adding "PPPOPTIONS=usepeerdns" to 70<TT>/etc/sysconfig/network-scripts/ifcfg-ippp0</TT>. In the same file, make sure 71that "PEERDNS=no" to stop RedHat's network initscripts from copying 72<TT>/etc/ppp/resolv.conf</TT> into <TT>/etc/resolv.conf</TT>.<BR> 73 74On SuSE (at least version 8.1, and 8.2) you should use YaST to activate 75<TT>[x] Modify DNS when connected</TT> then stop SuSEs network initscripts 76from copying <TT>/etc/ppp/resolv.conf</TT> into <TT>/etc/resolv.conf</TT> 77by modifying MODIFY_RESOLV_CONF_DYNAMICALLY="no" in <TT>/etc/sysconfig/network/config</TT>. 78 79 80<h3>Automatic DNS server configuration with DHCP.</h3> 81You need to get your DHCP client to write the addresse(s) of the DNS 82servers to a file other than <TT>/etc/resolv.conf</TT>. For dhcpcd, the 83<TT>dhcpcd.exe</TT> script gets run with the addresses of the nameserver(s) in 84the shell variable <TT>$DNS</TT>. The following bit of shell script 85uses that to write a file suitable for dnsmasq. 86<PRE> 87 88echo -n >|/etc/dhcpc/resolv.conf 89dnsservs=${DNS//,/ } 90for serv in $dnsservs; do 91 echo "nameserver $serv" >>/etc/dhcpc/resolv.conf 92done 93 94</PRE> 95 96Remember to give dhcpcd the <TT>-R</TT> flag to stop it overwriting 97<TT>/etc/resolv.conf</TT>. 98 99<P> 100For other DHCP clients it should be possible to achieve the same effect. 101 102<h3> DHCP and PPP.</h3> 103On a laptop which may potentially connect via a modem and PPP or 104ethernet and DHCP it is possible to combine both of the above 105configurations. Running dnsmasq with the flags 106<TT>resolv-file=/etc/ppp/resolv.conf resolv-file=/etc/dhcpc/resolv.conf</TT> 107makes it poll <B>both</B> files and use whichever was updated 108last. The result is automatic switching between DNS servers. 109</H3> 110 111<H2> Integration with DHCP.</H2> 112Dnsmasq reads <TT>/etc/hosts</TT> so that the names of local machines are 113available in DNS. This is fine when you give all your local machines 114static IP addresses which can go in <TT>/etc/hosts</TT>, but it doesn't work 115when local machines are configured via DHCP, since the IP address 116allocated to machine is not fixed. Dnsmasq comes with an integrated 117DHCP daemon to solve this problem. 118<P> 119The dnsmasq DHCP daemon allocates addresses to hosts on the network and tries 120to determine their names. If it succeeds it add the name and address 121pair to the DNS. There are basically two ways to associate a name with 122a DHCP-configured machine; either the machine knows its name which it 123gets a DHCP lease, or dnsmasq gives it a name, based on the MAC 124address of its ethernet card. For the former to work, a machine needs to know its name when it 125requests a DHCP lease. For dhcpcd, the -h option specifies this. The 126names may be anything as far as DHCP is concerned, but dnsmasq adds 127some limitations. By default the names must no have a domain part, ie 128they must just be a alphanumeric name, without any dots. This is a 129security feature to stop a machine on your network telling DHCP that 130its name is "www.microsoft.com" and thereby grabbing traffic which 131shouldn't go to it. A domain part is only allowed by dnsmasq in DHCP machine names 132if the <TT>domain-suffix</TT> option is set, the domain part must match the 133suffix. 134<P> 135As an aside, make sure not to tell DHCP to set the hostname when it 136obtains a lease (in dhcpcd that's the -H flag.) 137This is not reliable since the DHCP server gets the 138hostname from DNS which in this case is dnsmasq. There is a race 139condition because the host's name in the DNS may change as a 140result of it getting a DHCP lease, but this does not propagate before 141the name is looked up. The net effect may be that the host believes it 142is called something different to its name in the DNS. To be safe, set 143the hostname on a machine locally, and pass the same name to DHCP when 144requesting a lease. 145<P> 146<H2>Setting up a mailhub.</H2> 147If you generate mail on the machines attached to your private network, you may 148 be interested in the MX record feature of dnsmasq. This allows you to have all 149 the machines on your network use your firewall or another machine as a "smarthost" and 150deliver mail to it. The details of how to set this up are highly dependent on 151your mailer, system and distribution. The only thing that's relevant to dnsmasq is that the mailer 152needs to be able to interrogate the DNS and find an MX record for your mailhub. 153<P> 154By giving dnsmasq the <TT>mx-host</TT> option 155you instruct dnsmasq to serve an MX record for the specified address. 156By default the MX record 157points to the machine on which dnsmasq is running, so mail delivered to that 158name will get sent to the mailer on your firewall machine. You can 159have the MX record point to another machine by using the <TT>mx-target</TT> 160option. 161<P> 162In some cases it's useful for all local machines to see an MX record 163pointing at themselves: this allows mailers which insist on an MX record and 164don't fall back to A records to deliver mail within the 165machine. These MX records are enabled using the <TT>selfmx</TT> option. 166 167<H2>Using special servers.</H2> 168Dnsmasq has the ability to direct DNS queries for certain domains to 169specific upstream nameservers. This feature was added for use with 170VPNs but it is fully general. The scenario is this: you have a 171standard internet connection via an ISP, and dnsmasq is configured to 172forward queries to the ISP's nameservers, then you make a VPN 173connection into your companies network, giving access to hosts inside 174the company firewall. You have access, but since many of the internal hosts 175aren't visible on the public internet, your company doesn't publish 176them to the public DNS and you can't get their IP address from the ISP 177nameservers. The solution is to use the companies nameserver for 178private domains within the company, and dnsmasq allows this. Assuming 179that internal company machines are all in the domain internal.myco.com 180and the companies nameserver is at 192.168.10.1 then the option 181<TT>server=/internal.myco.com/192.168.10.1</TT> will direct all 182queries in the internal domain to the correct nameserver. You can 183specify more than one domain in each server option. If there is 184more than one nameserver just include as many 185<TT>server</TT> options as is needed to specify them all. 186 187<H2>Local domains.</H2> 188Sometimes people have local domains which they do not want forwarded 189to upstream servers. This is accomodated by using server options 190without the server IP address. To make things clearer <TT>local</TT> 191is a synonym for <TT>server</TT>. For example the option 192<TT>local=/localnet/</TT> ensures that any domain name query which ends in 193<TT>.localnet</TT> will be answered if possible from 194<TT>/etc/hosts</TT> or DHCP, but never sent to an upstream server. 195 196<H2>Defeating wildcards in top level domains.</H2> 197In September 2003 Verisign installed a wildcard record in the .com and 198.net top level domains. The effect of this is that queries for 199unregistered .com and .net names now return the address of Verisign's 200sitefinder service, rather than a "no such domain" response. To 201restore the correct behaviour, you can tell dnsmasq the address of the 202sitefinder host and have it substitute an NXDOMAIN reply when it sees 203that address. The sitefinder address is currently 64.94.110.11, so 204giving the option <TT>bogus-nxdomain=64.94.110.11</TT> will enable 205this facility for Verisign. If other TLDs do that same thing you can 206add the correct addresses for them too. See the dnsmasq FAQ for more 207details on the <TT>bogus-nxdomain</TT> option. 208 209<H2>Other configuration details.</H2> 210By default dnsmasq offers DNS service on all the configured interfaces 211of a host. It's likely that you don't (for instance) want to offer a 212DNS service to the world via an interface connected to ADSL or 213cable-modem so dnsmasq allows you to specify which interfaces it will 214listen on. Use either the <TT>interface</TT> or <TT>address</TT> options to do this. 215<P> 216The <TT>filterwin2k</TT> option makes dnsmasq ignore certain DNS requests which 217are made by Windows boxen every few minutes. The requests generally 218don't get sensible answers in the global DNS and cause trouble by 219triggering dial-on-demand internet links. 220<P> 221Sending SIGHUP to the dnsmasq process will cause it to empty its cache and 222then re-load <TT>/etc/hosts</TT> and <TT>/etc/resolv.conf</TT>. 223<P> Sending SIGUSR1 (killall -10 dnsmasq) to the dnsmasq process will 224cause to to write cache usage statisticss to the log, typically 225<TT>/var/log/syslog</TT> or <TT>/var/log/messages</TT>. 226<P> The <TT>log-queries</TT> option tells dnsmasq to verbosely log the queries 227it is handling and causes SIGUSR1 to trigger a complete dump of the 228contents of the cache to the syslog. 229 230<P>For a complete listing of options please take a look at the manpage 231dnsmasq(8). 232