← Back to branch summary

~ubuntu-branches/ubuntu/quantal/maradns/quantal

« back to all changes in this revision

Viewing changes to doc/en/text/recursive.txt

  • Committer: Package Import Robot
  • Author(s): Iain Lane
  • Date: 2012-01-12 23:35:38 UTC
  • mto: This revision was merged to the branch mainline in revision 26.
  • Revision ID: package-import@ubuntu.com-20120112233538-5jkaqrh9nbqtf1ey
Tags: upstream-2.0.04+really1.4.09
Import upstream version 2.0.04+really1.4.09

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/text/recursive.txt
1
 
               Using Deadwood as a recursive DNS server
 
1
               Using MaraDNS as a recursive DNS server
2
2
 
3
 
   This document is a step-by-step guide to setting up Deadwood as
4
 
   a recursive DNS server. It assumes that MaraDNS and Deadwood are
5
 
   already compiled and installed.
 
3
   This document is a step-by-step guide to setting up MaraDNS as a
 
4
   recursive DNS server. It assumes that MaraDNS is already
 
5
   compiled and installed.
6
6
 
7
7
Table of contents
8
8
 
9
9
     * Basic configuration
10
 
     * Using Deadwood on a slow network
 
10
     * Using MaraDNS on a slow network
11
11
     * Using other recursive DNS servers
12
12
     * Using different root servers
13
13
     * Having private host names
17
17
 
18
18
Basic configuration
19
19
 
20
 
   Once Deadwood is installed, the dwood3rc file needs to be set up
21
 
   before Deadwood will function as a recursive DNS server. This
 
20
   Once MaraDNS is installed, the mararc file needs to be set up
 
21
   before MaraDNS will function as a recursive DNS server. This
22
22
   file only needs to be three lines long:
23
23
 
24
24
 ipv4_bind_addresses = "127.0.0.1"
25
25
 chroot_dir = "/etc/maradns"
26
26
 recursive_acl = "127.0.0.1"
27
27
 
28
 
   This three-line file needs to be called /etc/dwood3rc.
 
28
   This three-line file needs to be called /etc/mararc.
29
29
 
30
 
   The first line is the IP address or addresses Deadwood will use.
 
30
   The first line is the IP address or addresses MaraDNS will use.
31
31
   Here, it has the address 127.0.0.1, which means that only the
32
 
   machine running Deadwood will be able to access the MaraDNS
 
32
   machine running MaraDNS will be able to access the MaraDNS
33
33
   server--other machines will not be able to see it.
34
34
 
35
 
   If the machine running Deadwood will be accessed by other
 
35
   If the machine running MaraDNS will be accessed by other
36
36
   machines, this IP needs to be changed to an IP that the machine
37
 
   running Deadwood has.
 
37
   running MaraDNS has.
38
38
 
39
 
   It is possible to have Deadwood run on multiple IP addresses:
 
39
   It is possible to have MaraDNS run on multiple IP addresses:
40
40
 
41
41
 ipv4_bind_addresses = "10.1.3.2, 192.168.0.1, 127.0.0.1"
42
42
 
43
 
   The second line, chroot_dir is the directory Deadwood will be
44
 
   run from. This just has to be an empty directory, ideally owned
45
 
   by the root user.
 
43
   The second line, chroot_dir is the directory MaraDNS will be run
 
44
   from. When MaraDNS is being used as a recursive DNS server, this
 
45
   just has to be an empty directory, ideally owned by the root
 
46
   user.
46
47
 
47
48
   The third line, recursive_acl, determines the range of IPs that
48
49
   can access the recursive DNS server. This is in IP/netmask
53
54
 recursive_acl = "192.168.1.0/24"
54
55
 
55
56
   Here the "/24" indicates that we ignore the fourth number in an
56
 
   IP when determining who can contact Deadwood.
57
 
 
58
 
   Once this is done, other machines can contact the Deadwood
59
 
   server to perform DNS queries. For example, Deadwood is now a
60
 
   DNS server which Windows 98 can use in "Control Panel -> Network
61
 
   -> TCP/IP -> DNS configuration", or a UNIX system can point to
62
 
   from /etc/resolv.conf.
63
 
 
64
 
Using Deadwood on a slow network
65
 
 
66
 
   Deadwood, on a slow network, may time out. Deadwood normally
67
 
   only waits two seconds for a reply from a remote DNS server.
68
 
   This is not enough time to process queries on some slow
69
 
   networks. This can be changed by increasing the timeout_seconds
70
 
   value.
 
57
   IP when determining who can contact MaraDNS.
 
58
 
 
59
   Once this is done, other machines can contact the MaraDNS server
 
60
   to perform DNS queries. For example, MaraDNS is now a DNS server
 
61
   which Windows 98 can use in "Control Panel -> Network -> TCP/IP
 
62
   -> DNS configuration", or a UNIX system can point to from
 
63
   /etc/resolv.conf.
 
64
 
 
65
Using MaraDNS on a slow network
 
66
 
 
67
   MaraDNS, on a slow network, may time out. MaraDNS normally only
 
68
   waits two seconds for a reply from a remote DNS server. This is
 
69
   not enough time to process queries on some slow networks. This
 
70
   can be changed by increasing the timeout_seconds value.
71
71
 
72
72
   Here is a mararc file which waits six seconds (instead of the
73
73
   default two) for a reply from a remote DNS server:
79
79
 
80
80
Using other recursive DNS servers
81
81
 
82
 
   It is possible to have Deadwood contact other recursive name
 
82
   It is possible to have MaraDNS contact other recursive name
83
83
   servers, instead of contacting the actual root servers to
84
84
   process recursive queries by using the variable upstream_servers
85
 
   in the dwood3rc file.
 
85
   in the mararc file.
86
86
 
87
87
   In other words, one can use one's, say, ISP's DNS servers to
88
88
   resolve the names, and have MaraDNS act as a cache for the ISP's
89
89
   DNS servers. Supposing that the ISP name servers have the IPs
90
 
   10.66.77.88 and 10.99.11.22, the dwood3rc file will look like
 
90
   10.66.77.88 and 10.99.11.22, the mararc file will look like
91
91
   this:
92
92
 
93
93
 ipv4_bind_addresses = "127.0.0.1"
98
98
 
99
99
Using different root servers
100
100
 
101
 
   Deadwood, by default, uses the ICANN name servers as the root
 
101
   MaraDNS, by default, uses the ICANN name servers as the root
102
102
   name servers. The reason for this default is practical: In my
103
103
   experience, the ICANN root name servers are the ones which least
104
104
   frequently change their IP addresses. They are the best name
113
113
 ipv4_bind_addresses = "127.0.0.1"
114
114
 chroot_dir = "/etc/maradns"
115
115
 recursive_acl = "127.0.0.1"
116
 
 root_servers = {}
117
 
 root_servers["."] = "198.41.0.4,"
118
 
 root_servers["."] += "192.228.79.201,"
119
 
 root_servers["."] += "192.33.4.12,"
120
 
 root_servers["."] += "128.8.10.90,"
121
 
 root_servers["."] += "192.203.230.10,"
122
 
 root_servers["."] += "192.5.5.241,"
123
 
 root_servers["."] += "192.112.36.4,"
124
 
 root_servers["."] += "128.63.2.53,"
125
 
 root_servers["."] += "192.36.148.17,"
126
 
 root_servers["."] += "192.58.128.30,"
127
 
 root_servers["."] += "193.0.14.129,"
128
 
 root_servers["."] += "199.7.83.42,"
129
 
 root_servers["."] += "202.12.27.33"
 
116
 ipv4_alias = {}
 
117
 ipv4_alias["icann"]  = "198.41.0.4,"
 
118
 ipv4_alias["icann"] += "192.228.79.201,"
 
119
 ipv4_alias["icann"] += "192.33.4.12,"
 
120
 ipv4_alias["icann"] += "128.8.10.90,"
 
121
 ipv4_alias["icann"] += "192.203.230.10,"
 
122
 ipv4_alias["icann"] += "192.5.5.241,"
 
123
 ipv4_alias["icann"] += "192.112.36.4,"
 
124
 ipv4_alias["icann"] += "128.63.2.53,"
 
125
 ipv4_alias["icann"] += "192.36.148.17,"
 
126
 ipv4_alias["icann"] += "192.58.128.30,"
 
127
 ipv4_alias["icann"] += "193.0.14.129,"
 
128
 ipv4_alias["icann"] += "199.7.83.42,"
 
129
 ipv4_alias["icann"] += "202.12.27.33"
 
130
 root_servers["."] = "icann"
130
131
 
131
132
   This file will do the exact same thing as the following mararc
132
133
   file:
135
136
 chroot_dir = "/etc/maradns"
136
137
 recursive_acl = "127.0.0.1"
137
138
 
138
 
   The ICANN servers listed above are the ones that Deadwood use
 
139
   The ICANN servers listed above are the ones that MaraDNS uses
139
140
   when no root servers are specified.
140
141
 
 
142
   As an aside, the ipv4_alias variable is a general purpose way of
 
143
   giving names to any set of IPs in a mararc file. We can use
 
144
   shortcuts like this, in fact:
 
145
 
 
146
 ipv4_alias = {}
 
147
 ipv4_alias["localhost"] = "127.0.0.1"
 
148
 ipv4_bind_addresses = "localhost"
 
149
 chroot_dir = "/etc/maradns"
 
150
 recursive_acl = "localhost"
 
151
 ipv4_alias["icann-a"] = "198.41.0.4"
 
152
 ipv4_alias["icann-b"] = "192.228.79.201"
 
153
 ipv4_alias["icann-c"] = "192.33.4.12"
 
154
 ipv4_alias["icann-d"] = "128.8.10.90"
 
155
 ipv4_alias["icann-e"] = "192.203.230.10"
 
156
 ipv4_alias["icann-f"] = "192.5.5.241"
 
157
 ipv4_alias["icann-g"] = "192.112.36.4"
 
158
 ipv4_alias["icann-h"] = "128.63.2.53"
 
159
 ipv4_alias["icann-i"] = "192.36.148.17"
 
160
 ipv4_alias["icann-j"] = "192.58.128.30"
 
161
 ipv4_alias["icann-k"] = "193.0.14.129"
 
162
 ipv4_alias["icann-l"] = "199.7.83.42"
 
163
 ipv4_alias["icann-m"] = "202.12.27.33"
 
164
 ipv4_alias["icann"] = "icann-a,icann-b,icann-c,icann-d,icann-e,icann-f,"
 
165
 ipv4_alias["icann"] += "icann-g,icann-h,icann-i,icann-j,icann-k,icann-l,"
 
166
 ipv4_alias["icann"] += "icann-m"
 
167
 root_servers["."] = "icann"
 
168
 
 
169
   This works the same as the above two examples. The reason why we
 
170
   don't have commas in any of the aliases besides icann is because
 
171
   the comma before the quote is only needed on a line before a
 
172
   line that uses the += operator.
 
173
 
 
174
   Here is what a configuration file which uses OpenNIC's glue root
 
175
   servers as the root servers. This list is current as of February
 
176
   22, 2006; note that OpenNIC frequently changes these IPs and you
 
177
   need to verify that these IPs are current at
 
178
   http://www.opennic.unrated.net/. A number of alternate root
 
179
   server organizations no longer exist; please make sure these
 
180
   people still exist before using this list.
 
181
 
 
182
 ipv4_bind_addresses = "127.0.0.1"
 
183
 chroot_dir = "/etc/maradns"
 
184
 recursive_acl = "127.0.0.1"
 
185
 ipv4_alias = {}
 
186
 # This ends with a comma because the next line is a += line
 
187
 ipv4_alias["opennic"]  = "131.161.247.232,"
 
188
 ipv4_alias["opennic"] += "208.185.249.250,"
 
189
 ipv4_alias["opennic"] += "66.227.42.140,"
 
190
 ipv4_alias["opennic"] += "66.227.42.149,"
 
191
 ipv4_alias["opennic"] += "64.81.44.251,"
 
192
 ipv4_alais["opennic"] += "216.87.84.214,"
 
193
 ipv4_alias["opennic"] += "208.185.249.251,"
 
194
 ipv4_alias["opennic"] += "131.161.247.231,"
 
195
 # This is the last line, so no comma at the end
 
196
 ipv4_alias["opennic"] += "65.243.92.254"
 
197
 # Considering how often alternate root DNS server lists change or disappear,
 
198
 # we will have the ICANN list on hand as a backup.
 
199
 ipv4_alias["icann"]  = "198.41.0.4,"
 
200
 ipv4_alias["icann"] += "192.228.79.201,"
 
201
 ipv4_alias["icann"] += "192.33.4.12,"
 
202
 ipv4_alias["icann"] += "128.8.10.90,"
 
203
 ipv4_alias["icann"] += "192.203.230.10,"
 
204
 ipv4_alias["icann"] += "192.5.5.241,"
 
205
 ipv4_alias["icann"] += "192.112.36.4,"
 
206
 ipv4_alias["icann"] += "128.63.2.53,"
 
207
 ipv4_alias["icann"] += "192.36.148.17,"
 
208
 ipv4_alias["icann"] += "192.58.128.30,"
 
209
 ipv4_alias["icann"] += "193.0.14.129,"
 
210
 ipv4_alias["icann"] += "198.32.64.12,"
 
211
 ipv4_alias["icann"] += "202.12.27.33"
 
212
 # Now, set the root servers; chance this to icann if you want to use the
 
213
 # icann servers instead.
 
214
 root_servers["."] = "opennic"
 
215
 
 
216
Having private host names
 
217
 
 
218
   One may wish to have private host names when running MaraDNS as
 
219
   a recursive name server. These are names that are not attached
 
220
   to the root servers, but will resolve on the recursive name
 
221
   server. For example, it might make sense to have
 
222
   "router.office." resolve to the IP of a router in an office.
 
223
 
 
224
   There are two ways to do this with MaraDNS: By using a custom
 
225
   root server for only names that end in "office", or by having
 
226
   the authoritative half of MaraDNS handle custom name
 
227
   resolutions.
 
228
 
 
229
Using authoritative records for private names
 
230
 
 
231
   We can have local names by taking advantage of the fact that
 
232
   MaraDNS can act as both a recursive and authoritative name
 
233
   server on the same IP. MaraDNS first looks up authoritative
 
234
   names before performing recursion. For example, if
 
235
   www.google.com is defined in a MaraDNS zone file, MaraDNS will
 
236
   use the value in the zone file instead of contacting nameservers
 
237
   on the internet to get the IP for www.google.com.
 
238
 
 
239
   The procedure to do this is as follows:
 
240
 
 
241
     * Have an authoritative and recursive DNS server share the
 
242
       same IP. Make sure this DNS server is not accessible from
 
243
       the public internet.
 
244
     * For this authoritative server, have zone files for the zones
 
245
       which one wants to have non-public information. Recursive
 
246
       queries will be resolved as usual (since the authoritative
 
247
       server is also a recursive server); authoritative queries
 
248
       for the special zones will get the special data.
 
249
     * The maradns man page has a section on firewall
 
250
       configuration which describes how to set up an IP filter to
 
251
       allow MaraDNS to send packets. Basically, don't allow
 
252
       outside IPs to hit this combined server on port 53 (UDP);
 
253
       instead allow UDP connections to ports 15000-19095.
 
254
 
 
255
   Here is how the configuration may look:
 
256
 
 
257
 ipv4_bind_addresses = "192.168.0.1"
 
258
 chroot_dir = "/etc/maradns"
 
259
 recursive_acl = "192.168.0.0/24"
 
260
 csv2 = {}
 
261
 csv2["office."] = "db.office"
 
262
 
 
263
   Replace 192.168.0.1 with the IP of the machine running the
 
264
   recursive MaraDNS; replace 192.168.0.0/24 (This means "anything
 
265
   that begins with 192.168.0") with the IP range allowed to access
 
266
   the recursive DNS server.
 
267
 
 
268
   The file "db.example.com." will be a csv2 zone file with records
 
269
   for the bogus example.com domain, such as router.example.com.
 
270
 
 
271
   If you want to have some of these private names be CNAMES for
 
272
   hostnames on the internet (e.g. "google.example.com. CNAME
 
273
   www.google.com."), please read the dangling CNAME document.
 
274
 
 
275
   More information on having host names for an internal network is
 
276
   available in the network section of the authoritative
 
277
   document.
 
278
 
141
279
Private names with custom root servers
142
280
 
143
 
   Deadwood can have custom root name servers that only resolve
144
 
   names in a subtree of the DNS space. In other words, we can tell
145
 
   Deadwood to have 192.168.0.7 resolve all names ending in office
146
 
   by having a line like this in one's mararc file:
 
281
   MaraDNS, starting with version 1.3.02, can have custom root name
 
282
   servers that only resolve names in a subtree of the DNS space.
 
283
   In other words, we can tell MaraDNS to have 192.168.0.7 resolve
 
284
   all names ending in office by having a line like this in one's
 
285
   mararc file:
147
286
 
148
287
 root_servers["office."] = "192.168.0.7"
149
288
 
155
294
 recursive_acl = "192.168.0.0/24"
156
295
 root_servers = {}
157
296
 root_servers["office."] = "192.168.0.7"
158
 
 root_servers["."] = "198.41.0.4,"
159
 
 root_servers["."] += "192.228.79.201,"
160
 
 root_servers["."] += "192.33.4.12,"
161
 
 root_servers["."] += "128.8.10.90,"
162
 
 root_servers["."] += "192.203.230.10,"
163
 
 root_servers["."] += "192.5.5.241,"
164
 
 root_servers["."] += "192.112.36.4,"
165
 
 root_servers["."] += "128.63.2.53,"
166
 
 root_servers["."] += "192.36.148.17,"
167
 
 root_servers["."] += "192.58.128.30,"
168
 
 root_servers["."] += "193.0.14.129,"
169
 
 root_servers["."] += "199.7.83.42,"
170
 
 root_servers["."] += "202.12.27.33"
171
297
 
172
 
   And the configuration on 192.168.0.7, the MaraDNS authoritative
173
 
   server:
 
298
   And the configuration on 192.168.0.7, the authoritative server:
174
299
 
175
300
 ipv4_bind_addresses = "192.168.0.7"
176
301
 chroot_dir = "/etc/maradns"
177
302
 csv2 = {}
178
303
 csv2["office."] = "db.office"
 
304
 
 
305
Customizing the resolution of some names
 
306
 
 
307
   One may wish to customize the resolution of certain names when
 
308
   using MaraDNS as both an authoritative and recursive name
 
309
   server. For example, if a high-profile domain is hijacked (such
 
310
   as what happened with panix.com in January of 2005), it may be
 
311
   desirable to have the correct name for the domain be temporarily
 
312
   locally set. This is also useful for a list of blocked sites (so
 
313
   the user gets a friendly "this site is blocked" instead of just
 
314
   being unable to connect to the site in question), and for setups
 
315
   where some machines need special DNS resolution for names that
 
316
   other machines do not need DNS resolution for.
 
317
 
 
318
   The procedure for doing this is almost identical to the
 
319
   procedure for having private host names as described above. Here
 
320
   is an example relevant mararc file:
 
321
 
 
322
 ipv4_bind_addresses = "192.168.0.1"
 
323
 chroot_dir = "/etc/maradns"
 
324
 recursive_acl = "192.168.0.0/24"
 
325
 csv2 = {}
 
326
 csv2["example.com."] = "db.example.com"
 
327
 
 
328
   The only things that need to be changed in this mararc file are
 
329
   the ipv4_bind_addresses and the recursive_acl parameters. The
 
330
   csv2["example.com."] is not changed.
 
331
 
 
332
   Now, let us suppose we want to have the A records for
 
333
   "www.phishsite.foo" and "phishsite.foo" resolve to an IP address
 
334
   that we control the web site for. We would add the following
 
335
   records (lines) to the file /etc/maradns/db.example.com
 
336
 
 
337
 www.phishsite.foo. 192.168.0.2
 
338
 phishsite.foo. 192.168.0.2
 
339
 
 
340
   We can also add a star record:
 
341
 
 
342
 *.phishsite.foo. 192.168.0.2