probind/manual.html at master · bevhost/probind · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
<HTML>
<HEAD>
<TITLE>ProBIND Users Manual</TITLE>
<LINK rel="stylesheet" href="style.css" type="text/css">
</HEAD>
<BODY bgcolor="#cccc99" background="images/BG-shadowleft.gif">

<TABLE width="100%">
<TR>
  <TD align=left valign=bottom><H1>ProBIND Users Manual</H1></TD>
  <TD align=right valign=top>
    <A HREF="http://probind.sourceforge.net" target="_top">
    <IMG SRC="images/probind.gif" alt="ProBIND home page" BORDER=0>
    </A>
  </TD>
</TR>
</TABLE>
<P>
This is the manual for ProBIND, release 1.0. ProBIND is an application
for managing DNS servers. The present release is probably not suitable
for users who are not knowledgeable about DNS in general. If you want
to learn about DNS in general, or BIND in particular, then I highly
recommend <A HREF="http://www.oreilly.com/catalog/dns3">DNS and BIND</A>.

<H2>Index</H2>
<P>
The following sections describe each page of the ProBIND application,
sorted by their place in the menu bar across the top of the page. This
bar is always visible. The start page is identical to the "Browse zones"
page.
<P>
<UL>
<LI><A HREF="#about">About ProBIND</A>
<LI><A HREF="#add">Adding a zone</A>
<LI><A HREF="#del">Deleting a zone</A>
<LI><A HREF="#zones">Browsing zones (start page)</A>
<LI><A HREF="#records">Browsing Records</A>
<LI><A HREF="#misc">Miscellaneous tools</A>
<UL>
<LI><A HREF="#stats">Statistics</A>
<LI><A HREF="#ext">External consistency</A>
<LI><A HREF="#int">Internal consistency</A>
<LI><A HREF="#list">Domain report</A>
<LI><A HREF="#ip">IP ranges</A>
<LI><A HREF="#bulk">Bulk update</A>
<LI><A HREF="#settings">Settings</A>
<LI><A HREF="#servers">Servers</A>
</UL>
<LI><A HREF="#push">Pushing updates</A>
<LI><A HREF="#import">Import</A>
<LI><A HREF="#license">License</A>
</UL>

<H2><A NAME="about">About ProBIND</A></H2>
<P>
ProBIND is a web application for administrating one or more BIND servers.
It is intended for small to medium sized ISPs, but there is no reason
why it couldn't be used wherever many zones must be managed across
a set of master and slave servers.
<P>
ProBIND is written in PHP4, and uses a MySQL database for storing all
information about the DNS servers managed. The database contents are
pushed onto the DNS servers only when a ProBIND user explicitly requests
it (it is also possible to execute the update from a cron job). The
update is done by generating configuration- and zone files based on the
information in the database. The files are then uploaded to the DNS servers.
<P>
The strengths of ProBIND are:
<UL>
<LI>You can easily search zones, either by domain name or a free-text
search on zone annotations.

<LI> You can search for records across all zones, e.g. to find all WWW
records that are CNAMES, and which point to a host with the string
"foo" in its name.

<LI> For those who often create zones which have a lot of standard fluff,
e.g. standard TXT and MX records, the TEMPLATE pseudo-zone will help.
When creating a new zone, the contents of the TEMPLATE pseudo-zone
are copied into the new zone.

<LI> NS records are automatically generated for all your zones. You
may never have to add a single NS record to your database.

<LI> If you let ProBIND handle your reverse zones (the in-addr.arpa zones),
it will automatically generate PTR records for all A records in the database.
You may never have to add a single PTR record to your database.
</UL>

<H2><A NAME="add">Adding a zone</A></H2>
<P>
This page has two sections, separated by a horizontal bar. You
create either a new master zone or a slave zone, by filling out
the fields and clicking the "Add" button in the appropriate section.
The domain name you enter is checked for
basic syntax, i.e. it must contain at least one dot, and it may not
already exist in the database.
<P>
A master domain is one that has been delegated to the DNS servers
you manage with ProBIND, by an outside domain registry, e.g. NSI.
When you create a master zone, the zone is initialized with a
copy of the records in the TEMPLATE pseudo-zone.
<P>
A slave zone is one that is managed elsewhere, but which your server
is a backup for. The zone data will be fetched from the master
server you specify. You can specify either an IP number or a hostname
as the master server, but if you specify a hostname, that hostname
must be resolvable.

<H2><A NAME="del">Deleting a zone</A></H2>
<P>
Enter the full name of the zone you wish to delete, and click on the
"Delete" button. You will be prompted for a confirmation before the deletion
takes place.
<P>
If you would rather point and click to identify the zone to be deleted,
then locate the zone on the <A HREF="#zones">Browse zones</A> page, and
click on the "Delete" button on the zone page.
<P>
NB: There is no "undelete" feature in ProBIND. So watch your clicks.

<H2><A NAME="zones">Browsing zones</A></H2>
<P>
This is the main page in ProBIND. The area below the main menu bar is
split into two frames. The left frame is used to search and list zones
from the database. The right frame is used to display the contents of
individual zones selected in the left frame.
<P>
In the left frame, you select what to search in: All zones, all master
zones, all slave zones, or the annotations on the zones. This is
combined with the text in the "For" field, to extract a list of matching
zones from the database. The search is of the case-insensitive substring
variety. Some examples:
<UL>
<LI>To list all zones in the database, select "All zones", clear the
text field and click on "Search".
<LI>To list all .com zones you have authoritative information for, select
"Master zones", enter ".com" (without the quotes) in the text field and
click on Search.
<LI>To find all zones where the annotations have been modified in October,
select "Annotations" and enter "oct" in the text field. Then click "Search".
This assumes that the people who maintain the annotations date their entries.
<LI>To find all slave zones in the database, select "Slave zones" and
clear the text field. Then click on "Search".
</UL>
<P>
The display in the right frame consists of three distinct types of information:
Zone parameters, explicit resource records and automatically generated
(implicit) resource records.
<P>The zone parameter block on top begins with the name of the zone
being displayed, and ends with a row of buttons: "Delete", "Details", "Update"
and "Add RR". In between there are 6 fields, 5 of which can be modified:
<UL>
<LI>The Zonefile is the filename of the zonefile on the DNS servers. This
name is automatically generated when you create a zone, or it is
inherited from the original zone file that was <A HREF="#import">imported</A>
into the database. Normally, you would have no need to change this.
<LI>The Serial no. field contains the last serial number used to update
the zonefile on the DNS servers. This field is automatically updated
each time you perform the <A HREF="#push">Push updates</A> operation.
Normally, you would have no need to change this.
<LI>Refresh interval. This is how often a secondary (slave) DNS server
shall check with the master for updates. When the zone is created,
this value is inherited from the TEMPLATE zone. NB: Refresh and retry
values are less important with modern (BIND8) DNS serves, as they implement
the NOTIFY scheme described in RFC1996.
<LI>Retry period. If a secondary DNS server cannot reach a master server,
this is the period it will wait before retrying.
<LI>Expire period. This is how long a secondary DNS server will remember
zone data from a master server it cannot reach. At the end of this interval,
all data for a zone are discarded.
<LI>Updated. This flag displays the status of the zone in the database. "No"
means that the zone data have not been updated since the last time the
database was synchronized with the DNS servers. "Yes" means that is has.
</UL>
For a discussion of these parameters, and recommendations for their
values, see the <A HREF="http://www.ripe.net/ripe/docs/ripe-203.html">
RIPE recommendations</A>.
<P>
The buttons have the following uses:
<UL>
<LI>"Delete" does just that - it takes you to a form where you must confirm
your intention to delete the displayed zone.
<LI>"Details" takes you to a sub-page that contains information about when
the zone was created in the database, when it was last changed and a text
annotation. The annotation is useful both as a place to document e.g.
contact information about a zone, and as a log book where the DNS
maintainers can describe what they did, and when.
<LI>"Update". Click on this button after updating any of the text fields
above, or if you just want this zone to be in the next upload of the
database to the DNS servers.
<LI>"Add RR" takes you to a sub-page where you can add Resource Records
to the zone.
</UL>
<P>
After the button row follows the explicit resource records. These are just
the records which have been entered in the database, either manually, or
<A HREF="#import">imported</A>. There will always be an SOA record, which
cannot be deleted, and where you can only change the TTL (Time To Live)
value. NB: If you change the TTL for the SOA record, you will also change
the TTL for all implicit resource records, and for all those explicit
resource records that had the same TTL as the SOA record. The TTL in the
SOA record also becomes the default TTL for new resource records.
<P>
There is an "Upd" (for update) and "Del" (for delete) button for each
resource record. These buttons updates the RR in the database, or deletes
it, respectively. NB: The "Upd" button only affects the resource record
it is associated with. So if you want to update a lot of records, you
have to it one at a time.
<P>
The last part of the zone display is the implicit resource records. These
records do not exist in the database, and you cannot manipulate them
directly. They will exist in the zone files uploaded to the DNS servers.
For most zones, this will just be the NS records implied by the DNS
server descriptions you enter on the <A HREF="#servers">DNS servers</A>
page. For in-addr.arpa zones, PTR records implied by A records in the
database will also appear.

<H2><A NAME="records">Browsing records</A></H2>
<P>
On this page you can browse the resource records in the database. NB:
you can only browse explicit records, not the implicit ones you can see
in the bottom of the zone display when you <A HREF="#zones">browse
zones</A>.
<P>
This page consists of 5 entry fields and a "Search" button. You can
leave any field blank, in which case it wont influence the search.
If you fill out more than one field, only resource records which match
all your criteria will be returned.  The fields are:
<UL>
<LI>Zone. This is the domain name of the zone containing records, e.g.
example.com
<LI>Domain. This is the domain name of the record you are looking for, e.g.
www.
<LI>Type. This is the resource record type, e.g. A.
<LI>Pref. This is the preference value for MX records.
<LI>Data. This is the RDATA field of the resource record, e.g. an IP number.
</UL>
In all fields, except the type field, you can specify a substring match
by applying the '%' as a wildcard. E.g., if you want to find all 'www'
records in .net domains, you would enter '%.net' in the Zone field, and
'www' in the Domain field.
<P>
When you click on the "Search" button, you get a page back with the
search form at the top, in case you want to refine your search
criteria. Below this, you get a list of the records which match your
search criteria. If more than 50 records were found, use the Next and
Previous buttons to navigate through the list.

<H2><A NAME="misc">Miscellaneous tools</A></H2>
<P>
When you click on "Misc. tools" in the main menu bar, you get a second
menu bar with 7 choices:

<H3><A NAME="stats">Statistics</A></H3>
<P>
The statistics display is the default display of the "tools" pages. It
contains a count of all zones and (explicit) resource records in the
database, and a summary of the DNS server descriptions.
<P>
If the database contains updates which have not yet been uploaded to the
DNS servers, this page will also have a list of zones which have been added,
updated or deleted since the last time the DNS servers were brought up
to date.
<P>
NB: Sometimes you may see that one or more in-addr.arpa zones in the
list of changed zones, even if no one have touched them. The explanation
is that changes to other zones have touched one or more A records, with
IP numbers which correspond to those in-addr.arpa zones. This insures that
changes to A records will also result in changes to the automatically
generated PTR records on the DNS servers.

<H3><A NAME="ext">External consistency checks</A></H3>
<P>
There are two different kinds of external consistency checks: One that
finds all lame delegations, and one that finds all delegations which are
not quite lame, but which do not quite match the NS servers known to the
database either.
<P>
Both types of consistency checks require the hostname or IP number of a
DNS server <B>NOT</B> managed by this ProBIND installation. The whole
idea of having an external consistency check is to check that you are
in agreement with the outside world, and you can only do that by asking
a name server controlled by someone else.
<P>
The name server field will contain a default external DNS server. This
default value is controlled by the DEFAULT EXTERNAL DNS value in the
<A HREF="#settings">settings</A>.

<H3><A NAME="int">Internal consistency checks</A></H3>
<P>
Currently, there are four kinds of internal consistency checks. Actually,
it would be more accurate to call them checks for well-formedness of the
database. Except for the "Find resource records with invalid data" check,
none of the records found by these checks are necessarily errors.
<P>
<UL>
<LI>Find PTR records with no matching A records. This can be useful if
you have <A HREF="#import">imported></A> a lot of data, and now have
doubts about whether they are all current.
<LI>Find multiple A records for the same IP address. Having many A records
which point to the same IP number is common practice today. But sometimes
it is nice to get a list of all the places it is done.
<LI>Find zones with too few MX records. There is nothing wrong with
not having any MX records for a zone, it can be a deliberate decision. But
if you have <A HREF="#import">imported</A> a lot of zones, it can be nice
to verify that they all have the expected minimum of two MX'es.
<LI>Find resource records with invalid data. Any records returned by this
check <B>are</B> errors. All MX records are checked for a preference value.
All A records are checked to make sure that they point to an IP number.
</UL>

<H3><A NAME="list">Annotated domain list</A></H3>
<P>
This page can be very long. It is a list of all domains contained in the
database, as well as any existing annotations for those domains.

<H3><A NAME="ip">IP range display</A></H3>
<P>
This page is utterly useless if you have no reverse (in-addr.arpa) zones
in your database. It gives you a condensed view of which IP numbers have
been allocated.

<H3><A NAME="bulk">Bulk update</A></H3>
<P>
Sometimes, the mechanism for deciding which zones needs to be updated on
the DNS servers is just not good enough. E.g. if you have added a new
DNS server, if one of your DNS servers appears to have missed some updates,
or if you change the RNAME setting. In those situations, you want to make
sure that all your DNS servers get a complete upload of everything in the
ProBIND database.
<P>
This is what the bulk update feature is for. When you perform a bulk update,
all data in the database are marked updated. This makes sure that the next
<A HREF="#push">push updates</A> operation will upload the entire database
to the DNS servers.
<P>
NB: You must confirm this operation by clicking on an appropriately
scary-looking button, since this can make the next DNS server update a
very slow operation.

<H3><A NAME="settings">Settings</A></H3>
<P>
On this page you control 4 ProBIND parameters which don't really fit anywhere
else. This is also where you break hanging database locks. The parameters
are:
<UL>
<LI>DEFAULT EXTERNAL DNS. This is the default DNS server suggested for the
external consistency checks. This would normally be a DNS server operated
by your upstream provider.
<LI>DEFAULT PTR DOMAIN. When generating the zone file for an in-addr.arpa
zone, ProBIND automatically generates PTR records implied by A records
elsewhere in the database. And, since some DNS administrators don't like
to run with their arpa zones empty, it also generates PTR records for all
IP numbers not explicitly allocated in the database. Those PTR records
point to a host named "host-aaa-bbb-ccc-ddd" in the default PTR domain.
E.g: if you enter "unassigned.mydomain.net" here, PTR records for your
unassigned IP numbers will point to "host-aaa-bbb-ccc-ddd.unassigned.mydomain.net".
<LI>Default MNAME. This is the MNAME parameter in the SOA records generated
for your zones. The MNAME is the origin of your zones. This field should
contain the name of your master DNS server.
<LI>Default RNAME. This is the RNAME parameter in the SOA records generated
for your zones. The RNAME is the email address for your DNS administrator.
Traditionally, this would be root@yourdomain.net or hostmaster.mydomain.net.
NB: It doesn't matter if you enter a '@' or a '.' here - ProBIND automatically
converts it to the proper all-dots form.
</UL>
<P>
Sometimes you will see an additional field, below the "Update settings"
button. This will only happen when someone has started an operation that
locks parts of the database, usually to make sure that the uploads to the
DNS servers get a proper snapshot of the database. If this operation hangs,
or does not complete for one reason or another, the database lock is
not released. Before you use the provided button to break the lock, please
wait a few minutes and reload this page.

<H3><A NAME="servers">DNS servers</A></H3>
<P>
In order to function properly, ProBIND must have some information about the
DNS servers it is supposed to manage. This is where you supply that
information. The page consists of a list of DNS servers already defined,
and an "Add another server" button. Clicking on the button (or on one
of the existing servers) takes you to a detailed DNS server description,
which must be correctly filled out:
<UL>
<LI>The name of the DNS server. This must be the fully qualified hostname.
If your DNS server has multiple hostnames, take some care in selecting the
proper one here.
<LI>The IP number corresponding to the hostname must also be supplied.
<LI>You must specify whether the server is a master or a slave. Only master
servers receive full named.conf and zone files. Slave servers receive just
enough information to request data from the masters. There are no restrictions
on the number of masters and slaves you define, but it would be usual to
define at least one master.
<LI>You must specify whether ProBIND should push updates to the DNS server
or not. Why on earth would anyone define a DNS server here, but not want
to update it? One reason could be a multi-homed DNS server that receives
updates through one network interface (lets call it "inside"), but is
reachable by the general public only on another network interface (lets
call it "outside"). In that situation you would define two DNS servers
here, one for each interface. The outside interface would be published
in an NS record, but not updated, and the inside interface would be updated,
but not published.
<LI>You must also specify whether ProBIND should publish the existence
of the DNS server in the NS records it generates. See the note above.
<LI>ProBIND also needs to know which directory on the DNS server contains
the named.conf and zone files.
<LI>A great many DNS administrators wants or needs to add some global
options to the named.conf file. This is indirectly supported in ProBIND
through the use of named.conf templates. A template file must be located
in the etc directory of the ProBIND installation. The template is essentially
the entire named.conf file, except for the actual zone definitions. When
the named.conf file is prepared for upload to the DNS server, the template
is read, and two macros are expanded: $ZONE_DIR and $ZONE_DEFINITIONS. They
expand to the directory containing zone files and the actual zone definitions,
respectively. A minimal named.conf template would look like this:
<PRE>
options {
	directory "$ZONE_DIR";
};

$ZONE_DEFINITIONS

zone "." {
	type hint;
	file "db.cache";
};
</PRE>
<LI>ProBIND also needs to know how to upload the file to the DNS server. The
script must exist in the sbin directory of the ProBIND installation. The
script is called from a working directory containing the generated named.conf
and all the zone files that must be uploaded. The script gets two parameters:
the hostname of the DNS server to update, and the directory on the server
to upload to. Additionally, the working directory may contain a file named
"deadlist". It will contain a list of zones which have been deleted from
the database, and which should also be deleted from the DNS server. It is
the responsibility of this script to restart the DNS server process after
a successful upload. See the "push" and "nop" scripts for examples.
<LI>Finally, you can add a bit of text to describe the server.
</UL>

<H2><A NAME="push">Push updates</A></H2>
<P>
The final operation in ProBIND is the step where the contents of the database
are pushed (uploaded) to the managed DNS servers. If the database contains
no changes, this page just tells you that there is nothing to be done.
<P>
On the other hand, if there are updates in the database, you must confirm
your decision to upload them to the DNS servers by clicking on an
appropriately scary-looking button.
<P>
The mechanics of the upload process is controlled by the DNS
<A HREF="#servers">server descriptions</A>.
<P>
NB: This operation can take a very long time.

<H2><A NAME="import">Import</A></H2>
<P>
You probably already manage a lot of zones if you are looking at this
program. This means that you are also not interested in manually entering
all your existing zones through the web interface. This is where the
import script enters the picture.
<P>
To import your existing configuration, copy named.conf and all of your zone
files into a directory on your ProBIND host.
<P>
Then execute this command (assuming that you installed ProBIND in
/www/htdocs/probind):
<P>
/www/htdocs/probind/etc/import -v named.conf | tee import.log
<P>
Review the import log and the database carefully. You do not want to
update your BIND servers until your are confident that the database
accurately represents your DNS data.
<P>
If you have a lot of comments in your zone files, run import with the -a
flag too (i.e. import -av named.conf). That way the unaltered text of a
zone file is put into the ProBIND database as a comment text for the zone.

<H2><A NAME="license">License</A></H2>
<P>
ProBIND was developed by Flemming S. Johansen &lt;fjohansen@proventum.net&gt;
as part of his duties as resident DNS manager at Proventum. The software
is copyrighted &copy 2000 by
<A HREF="http://www.proventum.net">Proventum</A>.
<P>
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
<P>
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.
<P>
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
<P>

</BODY>
</HTML>