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