Debian Codegraph @

README.html

raw
1 <H1 align=center>LDAP to DNS gateway</H1>
2 <P>
3 <B>ldap2dns</B> is a program to create DNS (Domain Name Service) records directly
4 from a LDAP directory. It can and should be be used to replace the secondary
5 name-server by a second primary one.<BR>
6 <B>ldap2dns</B> reduces all kind of administration overhead:
7 No more flat file editing, no more zone file editing. After having installed
8 <B>ldap2dns</B>, the administrator only has to access the LDAP directory.<BR>
9 Optionally she can add access control for each zone, create a GUI
10 and add all other kind of zone and resource record information without
11 interfering with the DNS server.<BR>
12 <B>ldap2dns</B> is designed to write ASCII data files used by <I>tinydns</I>
13 from the <I>djbdns</I> package, but also may be used to write .db-files used
14 by <I>named</I> as found in the <I>BIND</I> package.<BR>
15 <P>
16
17 <H3>1. Introduction</H3>
18 Often it is desirable to store DNS information in a database rather than
19 in flat text files. This can greatly help to reduce administration overhead
20 since associate information such as billing contact, account management, etc.
21 can be stored and processed inside the same database. Also due to the nature of
22 DNS, information must be stored redundantly on two or more hosts.
23 The classical data replication through zone transfer is unreliable, insecure
24 and difficult to administer.<BR>
25 To solve this problem some proprietary attempts have been proposed to
26 store DNS information in relational databases. The nature of DNS, however,
27 is hierarchical and such should the database be. Using a relational database
28 to store DNS information is undesirable, because it becomes difficult
29 to store free form information. Within a hierachical data scheme, the
30 administrator might define more than one IP-address for each canonical name.
31 To implement such a feature in a relational database without breaking the
32 normalization rules, one would have to add another table.<BR>
33 One of the most widely spread hierarchical database protocols is LDAP.
34 <B>ldap2dns</B> retrieves DNS information stored in an LDAP directory service
35 and generates a file suitable for name-servers.<BR>
36 Actually the most widely spread name-servers
37 <A HREF="http://www.isc.org/products/BIND/">named</A> and
38 <A HREF="http://cr.yp.to/djbdns/tinydns.html">tinydns</A> are
39 supported. <B>ldap2dns</B> specially has been designed to work with
40 tinydns and is the favored name server daemon for the author of this program.
41 <B>ldap2dns</B> can also generate files suitable for <I>named</I> version 8,
42 but this feature is not well supported.
43 There is a
44 <A HREF="http://www.alternic.org/drafts/drafts-m-n/draft-miller-dns-ldap-schema-00.txt">
45 RFC</A> for a format description how to store DNS information in LDAP.
46 This paper a draft RFC which expired in February 1999, looks as if it has been
47 specially designed to be used by <I>named</I>. This scheme
48 does not have strict attribute-value-pair mapping, making it difficult to be used by
49 user interfaces. It also lacks of an implementation (or I have never heard of any).<BR>
50 Since <I>tinydns</I> is going another descriptive way. Therefore I implemented a similar
51 object-scheme more suitable for <I>tinydns</I>. Two object-classes have been defined.
52 <B>DNSzone</B> stores all the information to define a DNS zone, such as the SOA
53 (Start Of Authority), serial numbers etc. <B>DNSrrset</B> is used to store the information
54 for a single resource record, such as the domain name, IP-addresses, class and type.<BR>
55 Here are the tables:
56 <P>
57 <H4>DNSzone</H4>
58 This object-class represents a DNS zone. It is the container for all the resource records
59 within a zone. Zones can be primary or secondary. If used in conjunction with
60 <I>tinydns</I> zones are always primary. Secondary zones don't make sense anyway!
61 In addition to being a container, the zone object has attributes related to
62 the management of the zone. These include the zone's SOA information. Each zone-object
63 can have none to many children of class <B>DNSrrset</B>.<BR>
64
65 <TABLE bgcolor=#EEEEEE>
66 <TR><TH>ATTRIBUTE</TH><TH>VALUE</TH><TH>Comment</TH></TR>
67 <TR><TD>objectclass</TD><TD>DNSzone</TD><TD>required</TD></TR>
68 <TR><TD>cn</TD><TD><I>common name</I></TD><TD>required</TD></TR>
69 <TR><TD>DNSzonename</TD><TD><I>Name of the zone</I></TD><TD>required, multivalued</TD></TR>
70 <TR><TD>DNSserial</TD><TD><I>Serial number of SOA</I></TD><TD>optional</TD></TR>
71 <TR><TD>DNSrefresh</TD><TD><I>Refresh time of SOA</I></TD><TD>optional, only used for zone transfers</TD></TR>
72 <TR><TD>DNSretry</TD><TD><I>Retry time of SOA</I></TD><TD>optional, only used for zone transfers</TD></TR>
73 <TR><TD>DNSexpire</TD><TD><I>Expire time of SOA</I></TD><TD>optional, only used for zone transfers</TD></TR>
74 <TR><TD>DNSminimum</TD><TD><I>Minimum time to live</I></TD><TD>optional, only used for zone transfers</TD></TR>
75 <TR><TD>DNSadminmailbox</TD><TD><I>Hostmaster's contact address</I></TD><TD>optional</TD></TR>
76 <TR><TD>DNSzonemaster</TD><TD><I>Primary nameserver for this zone</I></TD><TD>optional</TD></TR>
77 <TR><TD>DNStype</TD><TD>SOA</TD><TD>must be SOA</TD></TR>
78 <TR><TD>DNSclass</TD><TD>IN</TD><TD>must be IN</TD></TR>
79 <TR><TD>DNSttl</TD><TD><I>time to live</I></TD><TD>optional, only used with tinydns</TD></TR>
80 <TR><TD>DNStimestamp</TD><TD><I>timestamp</I></TD><TD>optional, only used with tinydns</TD></TR>
81 </TABLE>
82 <UL>
83 <LI><B>DNSzonename:</B> This field is required to describe the zone's domain name, for instance
84 myorg.com. More than one <B>DNSzonename</B> my be specified for a <B>DNSzone</B> so that the
85 same host is accessable with different zonenames.</LI>
86
87 <LI><B>DNSserial:</B> This is the serial number as used for BIND's zone transfers. Here it is
88 used to inform <B>ldap2dns</B> that it has to rebuild its data-file. Without increasing the serial
89 number <B>ldap2dns</B> will ignore all modifications until it is restarted.</LI>
90
91 <LI><B>DNSrefresh, DNSretry, DNSexpire, DNSminimum:</B> You may safly ignore these numbers
92 if You don't do zone-transfers. Since Your secondary nameserver will connect to the LDAP
93 server the same way Your primary does, You don't need zone-transfers anyway.</LI>
94
95 <LI><B>DNSzonemaster:</B> Here you specify the canonical name of your primary nameserver.</LI>
96
97 <LI><B>DNSadminmailbox:</B> This is the contact address of Your DNS-administrator. The first dot
98 is converted to a <I>@</I>.</LI>
99
100 <LI><B>DNStype:</B> Must be <B>SOA</B> (Start Of Authority)</LI>
101
102 <LI><B>DNSclass:</B> Must be <B>IN</B> (Internet, or do still use Chaosnet?)</LI>
103
104 <LI><B>DNSttl:</B> This is the time-to-live value as used by <B>tinydns</B>.
105 If TTL is nonzero (or omitted), the timestamp is a starting time from whereon this zone's
106 information is valid. If TTL is zero, the timestamp is an ending time (``time to die'').</LI>
107
108 <LI><B>DNStimestamp:</B> This is the timestamp as used by <B>tinydns</B>. It represents a
109 string as external TAI64 timestamp, printed as 16 lowercase hexadecimal characters</LI>
110 </UL>
111 <P>
112
113 <H4>DNSrrset</H4>
114 The Resource Record Set represents all of the resource records for
115 a given host name within a zone. It must be a child of a DNSzone object.<BR>
116
117 <TABLE bgcolor=#EEEEEE>
118 <TR><TH>ATTRIBUTE</TH><TH>VALUE</TH><TH>Comment</TH></TR>
119 <TR><TD>objectclass</TD><TD>DNSrrset</TD><TD>required</TD></TR>
120 <TR><TD>cn</TD><TD><I>common name</I></TD><TD>required</TD></TR>
121 <TR><TD>DNSdomainname</TD><TD><I>Name of this record</I></TD><TD>optional, relative to zonename</TD></TR>
122 <TR><TD>DNSipaddr</TD><TD><I>IP address</I></TD><TD>optional, mutivalued</TD></TR>
123 <TR><TD>DNScname</TD><TD><I>Canonical name</I></TD><TD>optional, without ending dot relative to zonename</TD></TR>
124 <TR><TD>DNSpreference</TD><TD><I>integer</I></TD><TD>optional, only used for MX records</TD></TR>
125 <TR><TD>DNStype</TD><TD>A, CNAME, NS, MX, PTR or TXT</TD><TD>must be any valid record type</TD></TR>
126 <TR><TD>DNSclass</TD><TD>IN</TD><TD>must be IN</TD></TR>
127 <TR><TD>DNSttl</TD><TD><I>time to live</I></TD><TD>optional, only used with tinydns</TD></TR>
128 <TR><TD>DNStimestamp</TD><TD><I>timestamp</I></TD><TD>optional, only used with tinydns</TD></TR>
129 </TABLE>
130 <P>
131
132 <UL>
133 <LI><B>DNSrrset:</B> This object-class must be a direct child of DNSzone. Its <B>dn</B> should be
134 specified as <PRE>cn=<I>domainname</I>,cn=<I>zonename</I>,...</PRE></LI>
135
136 <LI><B>DNSdomainname</B> This is the partial domain-name, ie. the part in front of the
137 zone-name.</LI>
138
139 <LI><B>DNSipaddr:</B> This specifies the IP-address in dotted format. It can be used for <B>DNSrrset</B>'s
140 of type <B>A, NS, MX</B> or <B>PTR</B>. <B>DNSipaddr</B> is multivalued to specifiy more than one
141 IP-address for a service. If used in <B>DNSrrset</B>'s with <B>DNStype</B> = <B>PTR</B> it
142 overrides the old-fashioned form used in <B>DNSdomainname</B> such as 13.178.23.in-addr.arpa
143 for reverse lookups.</LI>
144
145 <LI><B>DNScname:</B> Whenever there is a mapping of a domain-name to a canonical name, use
146 this attribute. <B>DNScname</B> may be used for <B>DNSrrset</B>'s with <B>DNStype CNAME,
147 NS, MX, PTR or TXT</B>. If the last character of a CNAME is a dot its name is considered
148 absolute. If it does not contain a dot, its name is prepended to the zone-name.</LI>
149
150 <LI><B>DNSpreference:</B> This number is the mail-exchange preference as used by BIND.</LI>
151
152 <LI><B>DNStype:</B> This must be <B>A, CNAME, NS, MX, PTR</B> or <B>TXT</B>. It specifies
153 the DNSrrset type.</LI>
154
155 <LI><B>DNSclass:</B> Must be <B>IN</B></LI>
156
157 <LI><B>DNSttl:</B> This is the time-to-live value as used by <B>tinydns</B>.
158 If TTL is non-zero (or omitted), the time-stamp is a starting time from where-on this zone's
159 information is valid. If TTL is zero, the timestamp is an ending time (``time to die'').</LI>
160
161 <LI><B>DNStimestamp:</B> This is the timestamp as used by <B>tinydns</B>. It represents a
162 string as external TAI64 time-stamp, printed as 16 lowercase hexadecimal characters</LI>
163 </UL>
164 <P>
165
166 <H3>2. Installation</H3>
167 <UL>
168 <LI>Install an LDAP server such as <A HREF="www.openldap.org">openldap</A>. Other
169 LDAP implementations may work but have not been tested. Also install the
170 development libraries and include files.</LI>
171
172 <LI>Install <A HREF="http://cr.yp.to/djbdns.html">djbdns</A> or if you really
173 have to, go with BIND.<BR>
174 I suggest to install <I>tinydns</I> included in the <B>djbdns</B> package, because it is
175 safer, but You may have reasons why You want to use BIND.</LI>
176
177 <LI>Install <B>ldap2dns</B><BR>
178 Unpack the package and build it:
179 <PRE>
180 gzcat ldap2dns.tar.gz | tar x
181 cd ldap2dns-version
182 make
183 make install
184 </PRE>
185 If you run <B>ldap2dns</B> togther with tinydns, go into
186 /var/tinydns and run ldap2tinydns-conf.
187 </LI>
188
189 <LI>Add the extra object-classes to the slapd.conf file.
190 If You are using openldap-1.2.x:<BR>
191 copy the files dns.oc.conf and dns.ac.conf into the directory /etc/openldap or
192 appropriate and add the following two lines to Your slapd.conf file:<BR>
193 <PRE>
194 include /etc/openldap/dns.at.conf
195 include /etc/openldap/dns.oc.conf
196 </PRE>
197 or, if You are using openldap-2.0.x:<BR>
198 copy the file dns.schema into the directory /etc/openldap/schema or
199 appropriate and add the following line to Your slapd.conf file:<BR>
200 <PRE>
201 include /etc/openldap/schema/dns.schema
202 </PRE>
203 Now restart your LDAP server.</LI>
204 <P>
205
206 <LI>Start to populate your LDAP server with DNS information. As a first test do
207 <PRE>
208 $ ldapadd -D "<I>binddn</I>" -w <I>password</I> < example.ldif
209 </PRE>
210 Replace 'myorg' and 'binddn' with whatever is appropriate on Your system.
211 Start a search and see if something was added
212 <PRE>
213 $ ldapsearch -D "<I>binddn</I>" "objectclass=dnsrrset" </LI>
214 </PRE>
215
216 <LI>Test <B>ldap2dns</B>
217 <PRE>
218 $ ./ldap2dns -D "<I>binddn</I>" [ -b "<I>searchbase</I>" ] [ -w <I>passwd</I> ] -o data -o db -L
219 </PRE>
220 This should create a 'data' file, a 'corp.local.db' file and should print the
221 DNS content.<BR>
222 Note: The <I>data</I> file is text data which can be processed with <B>tinydns-data</B>.
223 <I>corp.local.db</I> is the file as used by <B>named</B>. If You are using bind, You also
224 have to adopt the file <I>/etc/named.conf</I> and You have to restart named.</LI>
225 </UL>
226 <P>
227
228 <H3>3. Running ldap2dns</H3>
229 If You are a tinydns user, run <B>ldap2dns</B> in /services/tinydns/root.<BR>
230 If You are an openldap user, the command line switches are the same as for ldapsearch
231 or ldapadd.
232 <PRE>
233 $ ldap2dns -D "<I>binddn</I>" [ -w <I>passwd</I> ] -b "<I>searchbase</I>" -o data -e "cd /var/tinydns/root && /usr/bin/tinydns-data"
234 </PRE>
235 This generates a data file which is converted into a data.cdb by tinydns-data as
236 soon as ldap2dns detects a modification in the LDAP directory.
237 The password is required if You restrict read queries to authenticated users only.
238 Test with
239 <PRE>
240 $ dnsq any corp.local <I>ipaddr</I>
241 </PRE>
242 Replace <I>ipaddr</I> with whatever You configured tinydns to listen to.
243 <P>
244
245 If You are a BIND user, run <B>ldap2dns</B> in /var/named with
246 <PRE>
247 $ ldap2dns -D "<I>binddn</I>" -w <I>passwd</I> -b "<I>searchbase</I>" -o db -e "kill -HUP `cat /var/run/named-pid`"
248 </PRE>
249 Do not forget to add You primary definition to Your named.boot file.
250 Your named should be restarted automatically as soon as ldap2dns detects a modification
251 in the LDAP directory. If bind is not restarted, do so with
252 <PRE>
253 # kill -HUP <I>PID</I>
254 </PRE>
255 Now run
256 <PRE>
257 $ nslookup - localhost
258 > ns1.corp.local
259 </PRE>
260 Note that <B>nslookup</B> only works with <B>tinydns</B> if Your nameserver resolves its IP-address
261 backwards.
262 <P>
263
264 <H3>4. Running ldap2dnsd</H3>
265 <B>ldap2dnsd</B> is a hard link onto <B>ldap2dns</B>. If invoked, the program
266 starts as backgound-daemon and contineously checks for modifications in the LDAP directory.
267 If the the daemon sees a modification in the <B>DNSserial</B> numbers it updates the data
268 or .db files, depending what kind of output was configured. This check is done about once
269 a minute.<BR>
270 The command-line options for <B>ldap2dnsd</B> are the same as for <B>ldap2dns</B>.
271 Use the -u option to modify the update intervall. You may also use -u on <B>ldap2dns</B>
272 to start as a foreground daemon. This is useful if You want to run <B>ldap2dns</B> from
273 <A HREF="http://cr.yp.to/daemontools.html">daemontools</A>. To do this run <B>ldap2tinydns-conf</B>
274 in /service/tinydns and link /service/ldap2dns onto /service/tinydns/ldap2dns.
275 <PRE>
276 # ln -s /service/tinydns/ldap2dns /service/ldap2dns
277 </PRE>
278 After a few seconds <B>daemontools</B> starts <B>ldap2dns</B> which itself generates data
279 files whenever a modification is commited into the LDAP directory.
280 <P>
281 <B>ldap2dns</B> and <B>ldap2dnsd</B> recognize the following options:
282 <PRE>
283 -D <I>binddn</I> specify the distinguished name to bind to the LDAP directory
284 -w <I>bindpasswd</I> use bindpasswd as the password for simple authentication
285 -b <I>searchbase</I> use searchbase as the starting point for the search instead of the default
286 -o Generate a "data" file to be processed by tinydns-data.
287 -o db For each zone generate a "<zonename>.db" file to be used by named.
288 -L[<I>filename</I>] print output in LDIF format for reimport. If no filename is specified output goes to stdout.
289 -h <I>host</I> specify the hostname of LDAP directory. Default is localhost.
290 -p <I>port</I> portnumber to connect to LDAP directory. Defaults is 389
291 -v run in verbose mode
292 -vv even more verbose
293 -V print version and exit
294 -u <I>numsecs</I> update DNS data every numsecs.
295 </PRE>
296 <B>ldap2dns</B> and <B>ldap2dnsd</B> recognizes the following environement variables:<BR>
297 <B>TINYDNSDIR</B>: Specifies the directory where ldap2dns writes its data file.<BR>
298 <B>LDAP2DNS_UPDATE</B>: Specifies the update intervall as the -u command line option would.<BR>
299 <B>LDAP2DNS_OUTPUT</B>: Specifies the default output, as the -o command line option would.
300 <P>
301 <B>ldap2dns</B> and <B>ldap2dnsd</B> use the following parameters from /etc/ldap.conf if not
302 specified on the command line:
303 <B>BASE</B>: The LDAP search base.<BR>
304 <B>HOST</B>: The LDAP server.<BR>
305 <B>PORT</B>: The LDAP port.
306 <P>
307
308 <H3>5. Importing DNS data from Your named</H3>
309 A perl-script <I>import.pl</I> is contained in this package. Edit the first
310 lines of the script to conform to Your configuration.
311 If You have installed the Perl packages Net::LDAP and Net::DNS
312 skip the following lines, otherwise do
313 <PRE>
314 # perl -MCPAN -e 'shell'
315 (...snip...)
316 > install Net::DNS
317 > install Net::LDAP
318 </PRE>
319 Now check that Your nameserver allows zone transfers to your host and run the import script:
320 <PRE>
321 $ echo 'primary mydomain.org ' | ./import.pl
322 </PRE>
323 for a single domain or
324 <PRE>
325 # cat named.boot | ./import.pl
326 </PRE>
327 to populate Your LDAP directory.
328 <P>
329
330 <H3>6. Coming soon</H3>
331 A browser-based administration toolkit, which connects directly
332 to the LDAP-directory service. <A HREF="ldap2dns/example.html">
333 Here is a screenshot</A>
334 <P>
335
336 <H3>7. To Do</H3>
337 <UL>
338 <LI>Write a man page.</LI>
339 <LI>named.conf should be created automatically.</LI>
340 </UL>
341 <P>
342
343 <H3>8. Copyright and disclaimer</H3>
344 This program is licensed under the GPL version 2 or at Your choice any later
345 version.<BR>
346 It is maintained by <A HREF="mailto:[email protected]?subject=ldap2dns">Jacob Rief</A>.
347 If you run <B>ldap2dns</B> on a productive nameserver, please mail me
348 and tell me on what OS and with which nameserver you do so.
349