« back to all changes in this revision
Viewing changes to setup.html
- browse files at revision 2
- compare with another revision
- download diff
- download tarball
- view history from revision 2
- Committer: Bazaar Package Importer
- Author(s): Simon Kelley
- Date: 2005-05-04 13:25:23 UTC
- mfrom: (0.2.1 upstream) (1.1.2 hoary)
- Revision ID: james.westby@ubuntu.com-20050504132523-29x9nzdnkypp62nc
Tags: 2.22-2
Make the resolv.conf polling code resistant to
backwards-moving system clocks. (closes: #306117) (closes: #300694)
backwards-moving system clocks. (closes: #306117) (closes: #300694)
added
removed
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 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).
Loggerhead is a web-based interface for Breezy
Version: 2.0.1