| 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 |
|