← Back to branch summary

~ubuntu-branches/ubuntu/trusty/maradns/trusty-proposed

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Dariusz Dwornikowski
  • Date: 2014-02-16 19:36:04 UTC
  • mfrom: (1.2.11) (21.1.11 experimental)
  • Revision ID: package-import@ubuntu.com-20140216193604-xtmcopn9pilzszae
Tags: 2.0.09-1
http://bugs.debian.org/739084
http://bugs.debian.org/739755
http://bugs.debian.org/710903
http://bugs.debian.org/709826
http://bugs.debian.org/701657
* New maintainer (Closes: #739084)
* New upstream release to unstable
* Several security bugs (Closes: #739755)
   - security bugfix for CVE-2011-5055, CVE-2011-5056, CVE-2012-0024,
   CVE-2012-1570
   - security bugfix agains blind spoofing attack (no CVE number)
   - security bugfix for packet of death attack (no CVE number)
* Bump standards to 3.9.5
* Updated d/postinst to no longer modify conffiles (Closes: #710903)
* Init script fixed (Closes: #709826)
* --reinstall no longer kills the process (Closes: #701657)
* Updated old d/changelog entries, added information when the CVEs were
  fixed: 2.0.06-1, 2.0.04-1, 1.4.11-1, 1.2.12.06-1, 1.2.12.05-1, 1.0.28-1

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-2007 Sam Trenholme
 
7
<!-- Copyright 2005-2010 Sam Trenholme
8
8
 
9
9
    TERMS
10
10
 
19
19
 
20
20
 -->
21
21
 
22
 
<H1>Using MaraDNS as a recursive DNS server</H1>
 
22
<H1>Using Deadwood as a recursive DNS server</H1>
23
23
 
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 
 
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 
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 MaraDNS on a slow network</A>
 
34
<li><A href=#slow>Using Deadwood 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 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 
 
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 
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/mararc</tt>.
 
58
This three-line file needs to be called <tt>/etc/dwood3rc</tt>.
59
59
 
60
60
<p>
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
 
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
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 MaraDNS will be accessed by other machines, this
68
 
IP needs to be changed to an IP that the machine running MaraDNS has.
 
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.
69
69
 
70
70
<p>
71
 
It is possible to have MaraDNS run on multiple IP addresses:
 
71
It is possible to have Deadwood 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 MaraDNS will be 
78
 
run from.  When MaraDNS is being used as a recursive DNS server, this just 
 
77
The second line, <tt>chroot_dir</tt> is the directory Deadwood will be 
 
78
run from.  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 MaraDNS.
 
96
when determining who can contact Deadwood.
97
97
 
98
98
<p>
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 
 
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 
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 MaraDNS on a slow network</h2></A>
 
106
<h2>Using Deadwood on a slow network</h2></A>
107
107
 
108
 
MaraDNS, on a slow network, may time out.  MaraDNS normally only waits
 
108
Deadwood, on a slow network, may time out.  Deadwood 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 compiles on,
 
125
<!-- Guess what?  All of the supported OSes that MaraDNS compiled 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. -->
 
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
-->
129
135
 
130
136
<A name=upstream>
131
137
<h2>Using other recursive DNS servers</h2> 
132
138
</A>
133
139
 
134
 
It is possible to have MaraDNS contact other recursive name servers,
 
140
It is possible to have Deadwood contact other recursive name servers,
135
141
instead of contacting the actual root servers to process recursive
136
 
queries by using the variable <tt>upstream_servers</tt> in the mararc file.
 
142
queries by using the variable <tt>upstream_servers</tt> in the dwood3rc file.
137
143
 
138
144
<p>
139
145
 
140
146
In other words, one can use one's, say, ISP's DNS servers to resolve the
141
147
names, and have MaraDNS act as a cache for the ISP's DNS servers.  Supposing
142
148
that the ISP name servers have the IPs 10.66.77.88 and 10.99.11.22, the
143
 
mararc file will look like this:
 
149
dwood3rc file will look like this:
144
150
 
145
151
<pre>
146
152
ipv4_bind_addresses = "127.0.0.1"
153
159
<A name=otherroot>
154
160
<h2>Using different root servers</h2></A>
155
161
 
156
 
MaraDNS, by default, uses the ICANN name servers as the root name servers.
 
162
Deadwood, by default, uses the ICANN name servers as the root name servers.
157
163
The reason for this default is practical: In my experience, the ICANN root
158
164
name servers are the ones which least frequently change their IP addresses.
159
165
They are the best name servers for simple "set and forget" recursive
171
177
ipv4_bind_addresses = "127.0.0.1"
172
178
chroot_dir = "/etc/maradns"
173
179
recursive_acl = "127.0.0.1"
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"
 
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"
189
194
</pre>
190
195
 
191
196
This file will do the exact same thing as the following <tt>mararc</tt> file:
196
201
recursive_acl = "127.0.0.1"
197
202
</pre>
198
203
 
199
 
The ICANN servers listed above are the ones that MaraDNS uses when no
 
204
The ICANN servers listed above are the ones that Deadwood use when no
200
205
root servers are specified.
201
206
 
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
 
 
363
207
<A name="privateroot"> 
364
208
<h2>Private names with custom root servers</h2>
365
209
</A>
366
210
 
367
 
MaraDNS, starting with version 1.3.02, can have custom root name servers
 
211
Deadwood can have custom root name servers
368
212
that only resolve names in a subtree of the DNS space.  In other words,
369
 
we can tell MaraDNS to have 192.168.0.7 resolve all names ending in 
 
213
we can tell Deadwood to have 192.168.0.7 resolve all names ending in 
370
214
<tt>office</tt> by having a line like this in one's mararc file:
371
215
 
372
216
<pre>
382
226
recursive_acl = "192.168.0.0/24"
383
227
root_servers = {}
384
228
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"
385
242
</pre>
386
243
 
387
 
And the configuration on 192.168.0.7, the authoritative server:
 
244
And the configuration on 192.168.0.7, the MaraDNS authoritative server:
388
245
 
389
246
<pre>
390
247
ipv4_bind_addresses = "192.168.0.7"
393
250
csv2["office."] = "db.office"
394
251
</pre>
395
252
 
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
 
 
446
253
</BODY>