Annotation of embedaddon/dnsmasq/setup.html, revision 1.1.1.2

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>
1.1.1.2 ! misho      81: You need to get your DHCP client to write the address(es) of the DNS
1.1       misho      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
1.1.1.2 ! misho      89: dnsservers=${DNS//,/ }
        !            90: for serv in $dnsservers; do
1.1       misho      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
1.1.1.2 ! misho     128: they must just be alphanumeric names, without any dots.  This is a
1.1       misho     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
1.1.1.2 ! misho     189: to upstream servers. This is accommodated by using server options
1.1       misho     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>