Annotation of embedaddon/dnsmasq/setup.html, revision 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