← Back to branch summary

~ubuntu-branches/ubuntu/precise/maradns/precise

« back to all changes in this revision

Viewing changes to doc/en/source/recursive.ej

  • Committer: Package Import Robot
  • Author(s): Iain Lane
  • Date: 2012-01-12 23:35:38 UTC
  • mfrom: (1.1.18)
  • Revision ID: package-import@ubuntu.com-20120112233538-wwr0rm4fhnk4w39j
Tags: 2.0.04+really1.4.09-1
Revert to 1.4 series with "really" version number. The 2.0 series packages
are not yet ready to be used.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/source/recursive.ej
4
4
 
5
5
</HEAD><BODY>
6
6
 
7
 
<!-- Copyright 2005-2010 Sam Trenholme
 
7
<!-- Copyright 2005-2007 Sam Trenholme
8
8
 
9
9
    TERMS
10
10
 
19
19
 
20
20
 -->
21
21
 
22
 
<H1>Using Deadwood as a recursive DNS server</H1>
 
22
<H1>Using MaraDNS as a recursive DNS server</H1>
23
23
 
24
 
This document is a step-by-step guide to setting up Deadwood as a recursive 
25
 
DNS server.  It assumes that MaraDNS and Deadwood are already <A 
 
24
This document is a step-by-step guide to setting up MaraDNS as a recursive 
 
25
DNS server.  It assumes that MaraDNS is already <A 
26
26
href=compile.html>compiled and installed</A>.
27
27
 
28
28
<A name=toc>
31
31
 
32
32
<ul>
33
33
<li><A href=#basic>Basic configuration</A>
34
 
<li><A href=#slow>Using Deadwood on a slow network</A>
 
34
<li><A href=#slow>Using MaraDNS on a slow network</A>
35
35
<li><A href=#upstream>Using other recursive DNS servers</A>
36
36
<li><A href=#otherroot>Using different root servers</A>
37
37
<li><A href=#private>Having private host names</A>
44
44
<H2>Basic configuration</H2>
45
45
</A>
46
46
 
47
 
Once Deadwood is installed, the <tt>dwood3rc</tt> file needs to be set up
48
 
before Deadwood will function as a recursive DNS server.  This file only 
 
47
Once MaraDNS is installed, the <tt>mararc</tt> file needs to be set up
 
48
before MaraDNS will function as a recursive DNS server.  This file only 
49
49
needs to be three lines long:
50
50
 
51
51
<pre>
55
55
</pre>
56
56
 
57
57
<p>
58
 
This three-line file needs to be called <tt>/etc/dwood3rc</tt>.
 
58
This three-line file needs to be called <tt>/etc/mararc</tt>.
59
59
 
60
60
<p>
61
 
The first line is the IP address or addresses Deadwood will use.  Here, it
62
 
has the address 127.0.0.1, which means that only the machine running Deadwood
 
61
The first line is the IP address or addresses MaraDNS will use.  Here, it
 
62
has the address 127.0.0.1, which means that only the machine running MaraDNS
63
63
will be able to access the MaraDNS server--other machines will not be able
64
64
to see it.  
65
65
 
66
66
<p>
67
 
If the machine running Deadwood will be accessed by other machines, this
68
 
IP needs to be changed to an IP that the machine running Deadwood has.
 
67
If the machine running MaraDNS will be accessed by other machines, this
 
68
IP needs to be changed to an IP that the machine running MaraDNS has.
69
69
 
70
70
<p>
71
 
It is possible to have Deadwood run on multiple IP addresses:
 
71
It is possible to have MaraDNS run on multiple IP addresses:
72
72
 
73
73
<pre>
74
74
ipv4_bind_addresses = "10.1.3.2, 192.168.0.1, 127.0.0.1"
75
75
</pre>
76
76
 
77
 
The second line, <tt>chroot_dir</tt> is the directory Deadwood will be 
78
 
run from.  This just 
 
77
The second line, <tt>chroot_dir</tt> is the directory MaraDNS will be 
 
78
run from.  When MaraDNS is being used as a recursive DNS server, this just 
79
79
has to be an empty directory, ideally owned by the root user.
80
80
 
81
81
<p>
93
93
</pre>
94
94
 
95
95
Here the "/24" indicates that we ignore the fourth number in an IP
96
 
when determining who can contact Deadwood.
 
96
when determining who can contact MaraDNS.
97
97
 
98
98
<p>
99
 
Once this is done, other machines can contact the Deadwood server to
100
 
perform DNS queries.  For example, Deadwood is now a DNS server which 
 
99
Once this is done, other machines can contact the MaraDNS server to
 
100
perform DNS queries.  For example, MaraDNS is now a DNS server which 
101
101
Windows 98 can use in "Control Panel -> Network -> TCP/IP -> DNS 
102
102
configuration", or a UNIX system can point to from 
103
103
<tt>/etc/resolv.conf</tt>.
104
104
 
105
105
<A name=slow>
106
 
<h2>Using Deadwood on a slow network</h2></A>
 
106
<h2>Using MaraDNS on a slow network</h2></A>
107
107
 
108
 
Deadwood, on a slow network, may time out.  Deadwood normally only waits
 
108
MaraDNS, on a slow network, may time out.  MaraDNS normally only waits
109
109
two seconds for a reply from a remote DNS server.  This is not enough
110
110
time to process queries on some slow networks.  This can be changed by
111
111
increasing the <tt>timeout_seconds</tt> value.
122
122
timeout_seconds = 6
123
123
</pre>
124
124
 
125
 
<!-- Guess what?  All of the supported OSes that MaraDNS compiled on,
 
125
<!-- Guess what?  All of the supported OSes that MaraDNS compiles on,
126
126
     with the exception of the mingw32 semi-port (which has its own
127
127
     workaround), have /dev/urandom support.  So we don't need to tell
128
 
     people how to set up a random_seed_file in the tutorial. 
129
 
  
130
 
     Good thing I wrote mkSecretTxt for Deadwood in Windows to have
131
 
     a good source of random numbers
132
 
 
133
 
     DOC HERE: Use mkSecretTxt.exe to make secret.txt in Windows 
134
 
-->
 
128
     people how to set up a random_seed_file in the tutorial. -->
135
129
 
136
130
<A name=upstream>
137
131
<h2>Using other recursive DNS servers</h2> 
138
132
</A>
139
133
 
140
 
It is possible to have Deadwood contact other recursive name servers,
 
134
It is possible to have MaraDNS contact other recursive name servers,
141
135
instead of contacting the actual root servers to process recursive
142
 
queries by using the variable <tt>upstream_servers</tt> in the dwood3rc file.
 
136
queries by using the variable <tt>upstream_servers</tt> in the mararc file.
143
137
 
144
138
<p>
145
139
 
146
140
In other words, one can use one's, say, ISP's DNS servers to resolve the
147
141
names, and have MaraDNS act as a cache for the ISP's DNS servers.  Supposing
148
142
that the ISP name servers have the IPs 10.66.77.88 and 10.99.11.22, the
149
 
dwood3rc file will look like this:
 
143
mararc file will look like this:
150
144
 
151
145
<pre>
152
146
ipv4_bind_addresses = "127.0.0.1"
159
153
<A name=otherroot>
160
154
<h2>Using different root servers</h2></A>
161
155
 
162
 
Deadwood, by default, uses the ICANN name servers as the root name servers.
 
156
MaraDNS, by default, uses the ICANN name servers as the root name servers.
163
157
The reason for this default is practical: In my experience, the ICANN root
164
158
name servers are the ones which least frequently change their IP addresses.
165
159
They are the best name servers for simple "set and forget" recursive
177
171
ipv4_bind_addresses = "127.0.0.1"
178
172
chroot_dir = "/etc/maradns"
179
173
recursive_acl = "127.0.0.1"
180
 
root_servers = {}
181
 
root_servers["."] = "198.41.0.4,"     
182
 
root_servers["."] += "192.228.79.201,"
183
 
root_servers["."] += "192.33.4.12,"
184
 
root_servers["."] += "128.8.10.90,"
185
 
root_servers["."] += "192.203.230.10,"
186
 
root_servers["."] += "192.5.5.241,"
187
 
root_servers["."] += "192.112.36.4,"
188
 
root_servers["."] += "128.63.2.53,"
189
 
root_servers["."] += "192.36.148.17,"
190
 
root_servers["."] += "192.58.128.30,"
191
 
root_servers["."] += "193.0.14.129,"
192
 
root_servers["."] += "199.7.83.42,"
193
 
root_servers["."] += "202.12.27.33"
 
174
ipv4_alias = {}
 
175
ipv4_alias["icann"]  = "198.41.0.4,"     
 
176
ipv4_alias["icann"] += "192.228.79.201,"
 
177
ipv4_alias["icann"] += "192.33.4.12,"
 
178
ipv4_alias["icann"] += "128.8.10.90,"
 
179
ipv4_alias["icann"] += "192.203.230.10,"
 
180
ipv4_alias["icann"] += "192.5.5.241,"
 
181
ipv4_alias["icann"] += "192.112.36.4,"
 
182
ipv4_alias["icann"] += "128.63.2.53,"
 
183
ipv4_alias["icann"] += "192.36.148.17,"
 
184
ipv4_alias["icann"] += "192.58.128.30,"
 
185
ipv4_alias["icann"] += "193.0.14.129,"
 
186
ipv4_alias["icann"] += "199.7.83.42,"
 
187
ipv4_alias["icann"] += "202.12.27.33"
 
188
root_servers["."] = "icann"
194
189
</pre>
195
190
 
196
191
This file will do the exact same thing as the following <tt>mararc</tt> file:
201
196
recursive_acl = "127.0.0.1"
202
197
</pre>
203
198
 
204
 
The ICANN servers listed above are the ones that Deadwood use when no
 
199
The ICANN servers listed above are the ones that MaraDNS uses when no
205
200
root servers are specified.
206
201
 
 
202
<p>
 
203
 
 
204
As an aside, the <tt>ipv4_alias</tt> variable is a general purpose way of
 
205
giving names to any set of IPs in a <tt>mararc</tt> file.  We can use 
 
206
shortcuts like this, in fact:
 
207
 
 
208
<pre>
 
209
ipv4_alias = {}
 
210
ipv4_alias["localhost"] = "127.0.0.1"
 
211
ipv4_bind_addresses = "localhost"
 
212
chroot_dir = "/etc/maradns"
 
213
recursive_acl = "localhost"
 
214
ipv4_alias["icann-a"] = "198.41.0.4"
 
215
ipv4_alias["icann-b"] = "192.228.79.201"
 
216
ipv4_alias["icann-c"] = "192.33.4.12"
 
217
ipv4_alias["icann-d"] = "128.8.10.90"
 
218
ipv4_alias["icann-e"] = "192.203.230.10"
 
219
ipv4_alias["icann-f"] = "192.5.5.241"
 
220
ipv4_alias["icann-g"] = "192.112.36.4"
 
221
ipv4_alias["icann-h"] = "128.63.2.53"
 
222
ipv4_alias["icann-i"] = "192.36.148.17"
 
223
ipv4_alias["icann-j"] = "192.58.128.30"
 
224
ipv4_alias["icann-k"] = "193.0.14.129"
 
225
ipv4_alias["icann-l"] = "199.7.83.42"
 
226
ipv4_alias["icann-m"] = "202.12.27.33"
 
227
ipv4_alias["icann"] = "icann-a,icann-b,icann-c,icann-d,icann-e,icann-f,"
 
228
ipv4_alias["icann"] += "icann-g,icann-h,icann-i,icann-j,icann-k,icann-l,"
 
229
ipv4_alias["icann"] += "icann-m"
 
230
root_servers["."] = "icann"
 
231
</pre>
 
232
 
 
233
This works the same as the above two examples.  The reason why we don't have
 
234
commas in any of the aliases besides icann is because the comma before 
 
235
the quote is only needed on a line before a line that uses 
 
236
the <tt>+=</tt> operator.
 
237
 
 
238
<p>
 
239
 
 
240
Here is what a configuration file which uses OpenNIC's glue root servers
 
241
as the root servers.  This list is current as of February 22, 2006; note
 
242
that OpenNIC frequently changes these IPs and you need to verify that
 
243
these IPs are current at <A 
 
244
href=http://www.opennic.unrated.net/>http://www.opennic.unrated.net/</A>.
 
245
A number of alternate root server organizations no longer exist; please
 
246
make sure these people still exist before using this list.
 
247
 
 
248
<pre>
 
249
ipv4_bind_addresses = "127.0.0.1"
 
250
chroot_dir = "/etc/maradns"
 
251
recursive_acl = "127.0.0.1"
 
252
ipv4_alias = {}
 
253
# This ends with a comma because the next line is a += line
 
254
ipv4_alias["opennic"]  = "131.161.247.232,"
 
255
ipv4_alias["opennic"] += "208.185.249.250,"
 
256
ipv4_alias["opennic"] += "66.227.42.140,"
 
257
ipv4_alias["opennic"] += "66.227.42.149,"
 
258
ipv4_alias["opennic"] += "64.81.44.251,"
 
259
ipv4_alais["opennic"] += "216.87.84.214,"
 
260
ipv4_alias["opennic"] += "208.185.249.251,"
 
261
ipv4_alias["opennic"] += "131.161.247.231,"
 
262
# This is the last line, so no comma at the end
 
263
ipv4_alias["opennic"] += "65.243.92.254"
 
264
# Considering how often alternate root DNS server lists change or disappear,
 
265
# we will have the ICANN list on hand as a backup.
 
266
ipv4_alias["icann"]  = "198.41.0.4,"     
 
267
ipv4_alias["icann"] += "192.228.79.201,"
 
268
ipv4_alias["icann"] += "192.33.4.12,"
 
269
ipv4_alias["icann"] += "128.8.10.90,"
 
270
ipv4_alias["icann"] += "192.203.230.10,"
 
271
ipv4_alias["icann"] += "192.5.5.241,"
 
272
ipv4_alias["icann"] += "192.112.36.4,"
 
273
ipv4_alias["icann"] += "128.63.2.53,"
 
274
ipv4_alias["icann"] += "192.36.148.17,"
 
275
ipv4_alias["icann"] += "192.58.128.30,"
 
276
ipv4_alias["icann"] += "193.0.14.129,"
 
277
ipv4_alias["icann"] += "198.32.64.12,"
 
278
ipv4_alias["icann"] += "202.12.27.33"
 
279
# Now, set the root servers; chance this to icann if you want to use the
 
280
# icann servers instead.
 
281
root_servers["."] = "opennic"
 
282
</pre>
 
283
 
 
284
<A name=private>
 
285
<h2>Having private host names</h2>
 
286
</A>
 
287
 
 
288
One may wish to have private host names when running MaraDNS as a recursive
 
289
name server.  These are names that are not attached to the root servers,
 
290
but will resolve on the recursive name server.  For example, it might make
 
291
sense to have "router.office." resolve to the IP of a router in an
 
292
office.
 
293
 
 
294
<p>
 
295
 
 
296
There are two ways to do this with MaraDNS: By using a custom
 
297
root server for only names that end in "office", or by having the
 
298
authoritative half of MaraDNS handle custom name resolutions.
 
299
 
 
300
<p>
 
301
 
 
302
<A name="privateauth">
 
303
<h2>Using authoritative records for private names</h2>
 
304
</A>
 
305
 
 
306
We can have local names by taking advantage of the fact that
 
307
MaraDNS 
 
308
can act as both a recursive and authoritative name server on the same IP.
 
309
MaraDNS first looks up authoritative names before performing recursion.
 
310
For example, if <tt>www.google.com</tt> is defined in a MaraDNS zone
 
311
file, MaraDNS will use the value in the zone file instead of contacting
 
312
nameservers on the internet to get the IP for <tt>www.google.com</tt>.
 
313
 
 
314
<p>
 
315
 
 
316
The procedure to do this is as follows:
 
317
 
 
318
<ul>
 
319
<li>Have an authoritative and recursive DNS server share the same IP.  Make
 
320
  sure this DNS server is not accessible from the public internet.
 
321
<li>For this authoritative server, have zone files for the zones which one
 
322
  wants to have non-public information.  Recursive queries will be resolved
 
323
  as usual (since the authoritative server is also a recursive server);
 
324
  authoritative queries for the special zones will get the special data.
 
325
<li>The <A href=man.maradns.html>maradns man page</A> has a section on 
 
326
  firewall configuration which 
 
327
  describes how to set up an IP filter to allow MaraDNS to send packets.
 
328
  Basically, don't allow outside IPs to hit this combined server on port
 
329
  53 (UDP); instead allow UDP connections to ports 15000-19095.
 
330
</ul>
 
331
 
 
332
Here is how the configuration may look:
 
333
 
 
334
<pre>
 
335
ipv4_bind_addresses = "192.168.0.1"
 
336
chroot_dir = "/etc/maradns"
 
337
recursive_acl = "192.168.0.0/24"
 
338
csv2 = {}
 
339
csv2["office."] = "db.office"
 
340
</pre>
 
341
 
 
342
Replace 192.168.0.1 with the IP of the machine running the recursive MaraDNS;
 
343
replace 192.168.0.0/24 (This means "anything that begins with 192.168.0")
 
344
with the IP range allowed to access the recursive DNS server.
 
345
 
 
346
<p>
 
347
 
 
348
The file "db.example.com." will be a csv2 zone file with records for the 
 
349
bogus example.com domain, such as router.example.com.
 
350
 
 
351
<p>
 
352
 
 
353
If you want to have some of these private names be CNAMES for hostnames
 
354
on the internet (e.g. "google.example.com. CNAME www.google.com."), please 
 
355
read the <A href=dangling.html>dangling CNAME document</A>.
 
356
 
 
357
<p>
 
358
 
 
359
More information on having host names for an internal network is available
 
360
in the <A href="authoritative.html#network">network section of the
 
361
authoritative document</A>.
 
362
 
207
363
<A name="privateroot"> 
208
364
<h2>Private names with custom root servers</h2>
209
365
</A>
210
366
 
211
 
Deadwood can have custom root name servers
 
367
MaraDNS, starting with version 1.3.02, can have custom root name servers
212
368
that only resolve names in a subtree of the DNS space.  In other words,
213
 
we can tell Deadwood to have 192.168.0.7 resolve all names ending in 
 
369
we can tell MaraDNS to have 192.168.0.7 resolve all names ending in 
214
370
<tt>office</tt> by having a line like this in one's mararc file:
215
371
 
216
372
<pre>
226
382
recursive_acl = "192.168.0.0/24"
227
383
root_servers = {}
228
384
root_servers["office."] = "192.168.0.7"
229
 
root_servers["."] = "198.41.0.4,"     
230
 
root_servers["."] += "192.228.79.201,"
231
 
root_servers["."] += "192.33.4.12,"
232
 
root_servers["."] += "128.8.10.90,"
233
 
root_servers["."] += "192.203.230.10,"
234
 
root_servers["."] += "192.5.5.241,"
235
 
root_servers["."] += "192.112.36.4,"
236
 
root_servers["."] += "128.63.2.53,"
237
 
root_servers["."] += "192.36.148.17,"
238
 
root_servers["."] += "192.58.128.30,"
239
 
root_servers["."] += "193.0.14.129,"
240
 
root_servers["."] += "199.7.83.42,"
241
 
root_servers["."] += "202.12.27.33"
242
385
</pre>
243
386
 
244
 
And the configuration on 192.168.0.7, the MaraDNS authoritative server:
 
387
And the configuration on 192.168.0.7, the authoritative server:
245
388
 
246
389
<pre>
247
390
ipv4_bind_addresses = "192.168.0.7"
250
393
csv2["office."] = "db.office"
251
394
</pre>
252
395
 
 
396
<A name=custom>
 
397
<h2>Customizing the resolution of some names</h2>
 
398
</A>
 
399
 
 
400
One may wish to customize the resolution of certain names when using
 
401
MaraDNS as both an authoritative and recursive name server.  For example,
 
402
if a high-profile domain is hijacked (such as what happened with
 
403
panix.com in January of 2005), it may be desirable to have the correct
 
404
name for the domain be temporarily locally set.  This is also useful for 
 
405
a list of blocked sites (so the user gets a friendly "this site is blocked"
 
406
instead of just being unable to connect to the site in question), and for
 
407
setups where some machines need special DNS resolution for names that
 
408
other machines do not need DNS resolution for.
 
409
 
 
410
<p>
 
411
 
 
412
The procedure for doing this is almost identical to the procedure for
 
413
having private host names as described above.  Here is an example
 
414
relevant <tt>mararc</tt> file:
 
415
 
 
416
<pre>
 
417
ipv4_bind_addresses = "192.168.0.1"
 
418
chroot_dir = "/etc/maradns"
 
419
recursive_acl = "192.168.0.0/24"
 
420
csv2 = {}
 
421
csv2["example.com."] = "db.example.com"
 
422
</pre>
 
423
 
 
424
The only things that need to be changed in this mararc file are
 
425
the <tt>ipv4_bind_addresses</tt> and the <tt>recursive_acl</tt>
 
426
parameters.  The <tt>csv2["example.com."]</tt> is <i>not</i> changed.
 
427
 
 
428
<p>
 
429
 
 
430
Now, let us suppose we want to have the A records for "www.phishsite.foo" 
 
431
and "phishsite.foo" resolve to an IP address that we control the web
 
432
site for.  We would add the following records (lines) to the file
 
433
<tt>/etc/maradns/db.example.com</tt>
 
434
 
 
435
<pre>
 
436
www.phishsite.foo. 192.168.0.2
 
437
phishsite.foo. 192.168.0.2
 
438
</pre>
 
439
 
 
440
We can also add a star record:
 
441
 
 
442
<pre>
 
443
*.phishsite.foo. 192.168.0.2
 
444
</pre>
 
445
 
253
446
</BODY>