summaryrefslogtreecommitdiffstats
path: root/setup.html
diff options
context:
space:
mode:
Diffstat (limited to 'setup.html')
-rwxr-xr-xsetup.html231
1 files changed, 231 insertions, 0 deletions
diff --git a/setup.html b/setup.html
new file mode 100755
index 0000000..1183f3b
--- /dev/null
+++ b/setup.html
@@ -0,0 +1,231 @@
+<HTML>
+<HEAD>
+<TITLE> Configuring Dnsmasq.</TITLE>
+</HEAD>
+<BODY BGCOLOR="WHITE">
+<H1 ALIGN=center>Dnsmasq setup</H1>
+<H2>Installation.</H2>
+To compile and install dnsmasq, the following command (as root) is enough.
+
+<PRE>
+make install
+</PRE>
+
+You might want to edit config.h. Dnsmasq has
+been run on (at least) Linux, uCLinux, AIX 4.1.5, FreeBSD 4.4 OpenBSD and Tru64 4.x
+
+Dnsmasq is normally run on a firewall machine (the machine with the
+modem or other connection to your ISP.) but it can run on any machine
+with access to the ISPs nameservers.
+
+Put the binary in <TT>/usr/local/sbin/dnsmasq</TT> (running <TT>make install</TT> will do this) and arrange for it
+to be started at boot time.
+
+Note that dnsmasq needs to run as root, since it binds privileged ports. It will drop root privileges after start-up. Dnsmasq
+logs problems using the syslog facility as a daemon. It logs debugging
+information to local0
+<P>
+<H2>Configuration.</H2>
+Configuration for dnsmasq is pretty simple in almost all cases. The
+program has collected a fair few options as it has developed but most of them
+are not needed most of the time. A machine which already has a DNS
+configuration (ie one or more external nameservers in <TT>/etc/resolv.conf</TT>
+and any local hosts in <TT>/etc/hosts</TT>) can be turned into a nameserver
+simply by running dnsmasq, with no options or configuration at
+all. Set the IP address of the machine running dnsmasq as the DNS
+server in all the other machines on your network, and you're done.
+<P>
+With a few option flags, it is possible to make dnsmasq do more clever
+tricks. Options for dnsmasq can be set either on the command line
+when starting dnsmasq, or in its configuration file, <TT>/etc/dnsmasq.conf</TT>.
+
+<h2>Making the nameserver machine use dnsmasq.</h2>
+In the simple configuration described above, processes local to the
+machine will not use dnsmasq, since they get their information about
+which nameservers to use from /etc/resolv.conf, which is set to the
+upstream nameservers. To fix this, simply replace the nameserver in
+<TT>/etc/resolv.conf</TT> with the local address 127.0.0.1 and give the
+address(es) of the upstream nameserver(s) to dnsmasq directly. You can
+do this using either the <TT>server</TT> option, or by putting them into
+another file, and telling dnsmasq about its location with
+the <TT>resolv-file</TT> option.
+
+<h2>Automatic nameserver configuration.</h2>
+The two protocols most used for automatic IP network configuration
+(PPP and DHCP) can determine the IP addresses for nameservers automatically.
+The daemons can be made to write out a file in the resolv.conf format with the
+nameservers in which is perfect for dnsmasq to use. When the
+nameservers change, for instance on dialling into a new ISP using PPP,
+dnsmasq will automatically re-read this file and begin using the new
+nameserver(s) completely transparently.
+
+<h3>Automatic DNS server configuration with PPP.</h3>
+Later versions of pppd have an option "usepeerdns" which instructs it to write a file containing
+the address(es) of the DNS severs in <TT>/etc/ppp/resolv.conf</TT>. Configure dnsmasq
+as above with "nameserver 127.0.0.1" in <TT>/etc/resolv.conf</TT> and run dnsmasq
+with to option <TT>resolv-file=/etc/ppp/resolv.conf</TT>.
+<P>
+On Redhat (at least versions 7.1, 7.2 and 7.3) you can set pppd
+options by adding "PPPOPTIONS=usepeerdns" to
+<TT>/etc/sysconfig/network-scripts/ifcfg-ippp0</TT>. In the same file, make sure
+that "PEERDNS=no" to stop RedHat's network initscripts from copying
+<TT>/etc/ppp/resolv.conf</TT> into <TT>/etc/resolv.conf</TT>.<BR>
+
+On SuSE (at least version 8.1, and 8.2) you should use YaST to activate
+<TT>[x] Modify DNS when connected</TT> then stop SuSEs network initscripts
+from copying <TT>/etc/ppp/resolv.conf</TT> into <TT>/etc/resolv.conf</TT>
+by modifying MODIFY_RESOLV_CONF_DYNAMICALLY="no" in <TT>/etc/sysconfig/network/config</TT>.
+
+
+<h3>Automatic DNS server configuration with DHCP.</h3>
+You need to get your DHCP client to write the addresse(s) of the DNS
+servers to a file other than <TT>/etc/resolv.conf</TT>. For dhcpcd, the
+<TT>dhcpcd.exe</TT> script gets run with the addresses of the nameserver(s) in
+the shell variable <TT>$DNS</TT>. The following bit of shell script
+uses that to write a file suitable for dnsmasq.
+<PRE>
+
+echo -n >|/etc/dhcpc/resolv.conf
+dnsservs=${DNS//,/ }
+for serv in $dnsservs; do
+ echo "nameserver $serv" >>/etc/dhcpc/resolv.conf
+done
+
+</PRE>
+
+Remember to give dhcpcd the <TT>-R</TT> flag to stop it overwriting
+<TT>/etc/resolv.conf</TT>.
+
+<P>
+For other DHCP clients it should be possible to achieve the same effect.
+
+<h3> DHCP and PPP.</h3>
+On a laptop which may potentially connect via a modem and PPP or
+ethernet and DHCP it is possible to combine both of the above
+configurations. Running dnsmasq with the flags
+<TT>resolv-file=/etc/ppp/resolv.conf resolv-file=/etc/dhcpc/resolv.conf</TT>
+makes it poll <B>both</B> files and use whichever was updated
+last. The result is automatic switching between DNS servers.
+</H3>
+
+<H2> Integration with DHCP.</H2>
+Dnsmasq reads <TT>/etc/hosts</TT> so that the names of local machines are
+available in DNS. This is fine when you give all your local machines
+static IP addresses which can go in <TT>/etc/hosts</TT>, but it doesn't work
+when local machines are configured via DHCP, since the IP address
+allocated to machine is not fixed. Dnsmasq comes with an integrated
+DHCP daemon to solve this problem.
+<P>
+The dnsmasq DHCP daemon allocates addresses to hosts on the network and tries
+to determine their names. If it succeeds it add the name and address
+pair to the DNS. There are basically two ways to associate a name with
+a DHCP-configured machine; either the machine knows its name which it
+gets a DHCP lease, or dnsmasq gives it a name, based on the MAC
+address of its ethernet card. For the former to work, a machine needs to know its name when it
+requests a DHCP lease. For dhcpcd, the -h option specifies this. The
+names may be anything as far as DHCP is concerned, but dnsmasq adds
+some limitations. By default the names must no have a domain part, ie
+they must just be a alphanumeric name, without any dots. This is a
+security feature to stop a machine on your network telling DHCP that
+its name is "www.microsoft.com" and thereby grabbing traffic which
+shouldn't go to it. A domain part is only allowed by dnsmasq in DHCP machine names
+if the <TT>domain-suffix</TT> option is set, the domain part must match the
+suffix.
+<P>
+As an aside, make sure not to tell DHCP to set the hostname when it
+obtains a lease (in dhcpcd that's the -H flag.)
+This is not reliable since the DHCP server gets the
+hostname from DNS which in this case is dnsmasq. There is a race
+condition because the host's name in the DNS may change as a
+result of it getting a DHCP lease, but this does not propagate before
+the name is looked up. The net effect may be that the host believes it
+is called something different to its name in the DNS. To be safe, set
+the hostname on a machine locally, and pass the same name to DHCP when
+requesting a lease.
+<P>
+<H2>Setting up a mailhub.</H2>
+If you generate mail on the machines attached to your private network, you may
+ be interested in the MX record feature of dnsmasq. This allows you to have all
+ the machines on your network use your firewall or another machine as a "smarthost" and
+deliver mail to it. The details of how to set this up are highly dependent on
+your mailer, system and distribution. The only thing that's relevant to dnsmasq is that the mailer
+needs to be able to interrogate the DNS and find an MX record for your mailhub.
+<P>
+By giving dnsmasq the <TT>mx-host</TT> option
+you instruct dnsmasq to serve an MX record for the specified address.
+By default the MX record
+points to the machine on which dnsmasq is running, so mail delivered to that
+name will get sent to the mailer on your firewall machine. You can
+have the MX record point to another machine by using the <TT>mx-target</TT>
+option.
+<P>
+In some cases it's useful for all local machines to see an MX record
+pointing at themselves: this allows mailers which insist on an MX record and
+don't fall back to A records to deliver mail within the
+machine. These MX records are enabled using the <TT>selfmx</TT> option.
+
+<H2>Using special servers.</H2>
+Dnsmasq has the ability to direct DNS queries for certain domains to
+specific upstream nameservers. This feature was added for use with
+VPNs but it is fully general. The scenario is this: you have a
+standard internet connection via an ISP, and dnsmasq is configured to
+forward queries to the ISP's nameservers, then you make a VPN
+connection into your companies network, giving access to hosts inside
+the company firewall. You have access, but since many of the internal hosts
+aren't visible on the public internet, your company doesn't publish
+them to the public DNS and you can't get their IP address from the ISP
+nameservers. The solution is to use the companies nameserver for
+private domains within the company, and dnsmasq allows this. Assuming
+that internal company machines are all in the domain internal.myco.com
+and the companies nameserver is at 192.168.10.1 then the option
+<TT>server=/internal.myco.com/192.168.10.1</TT> will direct all
+queries in the internal domain to the correct nameserver. You can
+specify more than one domain in each server option. If there is
+more than one nameserver just include as many
+<TT>server</TT> options as is needed to specify them all.
+
+<H2>Local domains.</H2>
+Sometimes people have local domains which they do not want forwarded
+to upstream servers. This is accomodated by using server options
+without the server IP address. To make things clearer <TT>local</TT>
+is a synonym for <TT>server</TT>. For example the option
+<TT>local=/localnet/</TT> ensures that any domain name query which ends in
+<TT>.localnet</TT> will be answered if possible from
+<TT>/etc/hosts</TT> or DHCP, but never sent to an upstream server.
+
+<H2>Defeating wildcards in top level domains.</H2>
+In September 2003 Verisign installed a wildcard record in the .com and
+.net top level domains. The effect of this is that queries for
+unregistered .com and .net names now return the address of Verisign's
+sitefinder service, rather than a "no such domain" response. To
+restore the correct behaviour, you can tell dnsmasq the address of the
+sitefinder host and have it substitute an NXDOMAIN reply when it sees
+that address. The sitefinder address is currently 64.94.110.11, so
+giving the option <TT>bogus-nxdomain=64.94.110.11</TT> will enable
+this facility for Verisign. If other TLDs do that same thing you can
+add the correct addresses for them too. See the dnsmasq FAQ for more
+details on the <TT>bogus-nxdomain</TT> option.
+
+<H2>Other configuration details.</H2>
+By default dnsmasq offers DNS service on all the configured interfaces
+of a host. It's likely that you don't (for instance) want to offer a
+DNS service to the world via an interface connected to ADSL or
+cable-modem so dnsmasq allows you to specify which interfaces it will
+listen on. Use either the <TT>interface</TT> or <TT>address</TT> options to do this.
+<P>
+The <TT>filterwin2k</TT> option makes dnsmasq ignore certain DNS requests which
+are made by Windows boxen every few minutes. The requests generally
+don't get sensible answers in the global DNS and cause trouble by
+triggering dial-on-demand internet links.
+<P>
+Sending SIGHUP to the dnsmasq process will cause it to empty its cache and
+then re-load <TT>/etc/hosts</TT> and <TT>/etc/resolv.conf</TT>.
+<P> Sending SIGUSR1 (killall -10 dnsmasq) to the dnsmasq process will
+cause to to write cache usage statisticss to the log, typically
+<TT>/var/log/syslog</TT> or <TT>/var/log/messages</TT>.
+<P> The <TT>log-queries</TT> option tells dnsmasq to verbosely log the queries
+it is handling and causes SIGUSR1 to trigger a complete dump of the
+contents of the cache to the syslog.
+
+<P>For a complete listing of options please take a look at the manpage
+dnsmasq(8).