| Simon Kelley | 9e4abcb | 2004-01-22 19:47:41 +0000 | [diff] [blame] | 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> |
| Josh Soref | 730c674 | 2017-02-06 16:14:04 +0000 | [diff] [blame] | 81 | You need to get your DHCP client to write the address(es) of the DNS |
| Simon Kelley | 9e4abcb | 2004-01-22 19:47:41 +0000 | [diff] [blame] | 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 |
| Josh Soref | 730c674 | 2017-02-06 16:14:04 +0000 | [diff] [blame] | 89 | dnsservers=${DNS//,/ } |
| 90 | for serv in $dnsservers; do |
| Simon Kelley | 9e4abcb | 2004-01-22 19:47:41 +0000 | [diff] [blame] | 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 |
| Ville Skyttä | faaf306 | 2018-01-14 17:32:52 +0000 | [diff] [blame] | 128 | they must just be alphanumeric names, without any dots. This is a |
| Simon Kelley | 9e4abcb | 2004-01-22 19:47:41 +0000 | [diff] [blame] | 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 |
| Josh Soref | 730c674 | 2017-02-06 16:14:04 +0000 | [diff] [blame] | 189 | to upstream servers. This is accommodated by using server options |
| Simon Kelley | 9e4abcb | 2004-01-22 19:47:41 +0000 | [diff] [blame] | 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 |
| Simon Kelley | 7de060b | 2011-08-26 17:24:52 +0100 | [diff] [blame] | 224 | cause to write cache usage statisticss to the log, typically |
| Simon Kelley | 9e4abcb | 2004-01-22 19:47:41 +0000 | [diff] [blame] | 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). |