setup.html

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