Annotation of embedaddon/dnsmasq/setup.html, revision 1.1.1.1
1.1 misho 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).
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to setup.html CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dnsmasq