LDAP to DNS gateway

ldap2dns is a program to read DNS (Domain Name
Service) records from an LDAP directory and format them
into flat files suitable for TinyDNS (or Bind).

ldap2dns reduces all kind of administration
overhead: No more flat file editing, no more zone file
editing. After having installed ldap2dns, the
administrator only has to modify the data stored in the
LDAP directory.

Optionally access control can be configured for each zone,
GUIs can be more easily implemented, and add all other kind
of zone and resource record information can be managed
without interfering with the DNS server.

ldap2dns is designed to write ASCII data files used
by tinydns from the djbdns package, but also may be used to write zone db files used
by named as found in the BIND package.

ldap2dns is known to compile and run under Linux and
Solaris using GCC or Sun Studio C Compiler.

Often it is desirable to store DNS
information in a database rather than in flat text files.
This can greatly help to reduce administration overhead since
associate information such as billing contact, account
management, etc. can be stored and processed inside the same
database. Also due to the nature of DNS, information must be
stored redundantly on two or more hosts. The classical data
replication through zone transfer is unreliable, insecure and
difficult to administer.

To solve this problem some proprietary attempts have been
proposed to store DNS information in relational databases.
The nature of DNS, however, is hierarchical and such should
the database be. Using a relational database to store DNS
information is undesirable, because it becomes difficult to
store free form information. Within a hierachical data
scheme, the administrator might define more than one
IP-address for each canonical name. To implement such a
feature in a relational database without breaking the
normalization rules, one would have to add another
table.

One of the most widely spread hierarchical database protocols
is LDAP. ldap2dns retrieves DNS information stored in
an LDAP directory service and generates a file suitable for
name-servers.

The two most-widely-used domain name service daemons, named and tinydns are
supported.

ldap2dns specifically has been designed to work with
tinydns and is the favored name server daemon for the author
of this program. ldap2dns can also generate files
suitable for named version 8 (and possibly version 9),
but this feature is not well supported.

There is a RFC for a format description how to store DNS information
in LDAP. This paper a draft RFC which expired in February
1999, looks as if it has been specially designed to be used
by named. This scheme does not have strict
attribute-value-pair mapping, making it difficult to be used
by user interfaces. It also lacks of an implementation (or I
have never heard of any).
Since tinydns is going another descriptive way the
original author implemented a similar object-scheme more
suitable for tinydns.

• Install an LDAP server such as openldap. Other LDAP implementations
  may work but have not been tested. If you are building from
  source you will need to also install the development
  libraries and include files. On most package based systems
  these would be the -devel packages (example:
  openldap-devel).
  
• Install djbdns or BIND.
  Configuring the nameserver to automatically start and work
  in your environment is beyond the scope of this
  document.
  
• Install ldap2dns
  From RPM:
  

  $ sudo rpm -Uhv ldap2dns.rpm
  

  Replace "ldap2dns.rpm" with the file you have
  downloaded.
  Now that you have it installed, skip to Usage to continue.
  
  To build ldap2dns from source:
  Unpack the package and build it:
  

  $ gzcat ldap2dns.tar.gz | tar x
  $ cd ldap2dns-version
  $ make
  $ sudo make install
  

• Copy the file ldap2dns.schema into the directory
  /etc/openldap/schema. Add the following line to Your
  slapd.conf file:
  

  include         /etc/openldap/schema/ldap2dns.schema
  

  Now restart your LDAP server.
  

Note: If you are running OpenLDAP 2.0 or earlier look
for appropriate schema files for your version in the
deprecated/ subdirectory. These files are known to
work as of ldap2dns 0.3.5 but are no longer supported for
future feature updates.

• Start to populate your LDAP server with DNS
  information. As a first test do
  

  $ ldapadd -D "binddn" -w password < example.ldif
  

  Replace 'myorg' and 'binddn' with whatever is appropriate on
  Your system. Start a search and see if something was added
  

  $ ldapsearch -D "binddn" "objectclass=dnsrrset"
  

• Test ldap2dns

  $ ./ldap2dns -D "binddn" [ -b "searchbase" ] [ -w passwd ] -o data -o db -L
  

  This should create a 'data' file, a 'corp.local.db' file and
  should print the DNS content.
  Note: The data file is text data which can be
  processed with tinydns-data. corp.local.db is the file as used by named. If You are using
  bind, You also have to adopt the file
  /etc/named.conf and You have to restart named.
  

Two object-classes have been defined.
DNSzone stores all the information to define a DNS
zone, such as the SOA (Start Of Authority), serial numbers
etc. DNSrrset is used to store the information for a
single resource record, such as the domain name,
IP-addresses, class and type.
Here are the tables:

DNSzone

This object-class represents a DNS zone. It is the
container for all the resource records within a zone. Zones
can be primary or secondary. If used in conjunction with
tinydns zones are always primary. Secondary zones
don't make sense anyway! In addition to being a container,
the zone object has attributes related to the management of
the zone. These include the zone's SOA information. Each
zone-object can have none to many children of class
DNSrrset.

ATTRIBUTE	VALUE	Comment
objectclass	DNSzone	required
cn	common name	required
DNSzonename	Name of the zone	required, multivalued
DNSserial	Serial number of SOA	optional
DNSrefresh	Refresh time of SOA	optional, only used for zone transfers
DNSretry	Retry time of SOA	optional, only used for zone transfers
DNSexpire	Expire time of SOA	optional, only used for zone transfers
DNSminimum	Minimum time to live	optional, only used for zone transfers
DNSadminmailbox	Hostmaster's contact address	optional
DNSzonemaster	Primary nameserver for this zone	optional
DNStype	SOA	must be SOA
DNSclass	IN	must be IN
DNSttl	time to live	optional, only used with tinydns
DNStimestamp	timestamp	optional, only used with tinydns

• DNSzonename: This field is required to describe
  the zone's domain name, for instance myorg.com. More than
  one DNSzonename my be specified for a
  DNSzone so that the same host is accessable with
  different zonenames.
  
• DNSserial: This is the serial number as used for
  BIND's zone transfers. Here it is used to inform
  ldap2dns that it has to rebuild its data-file.
  Without increasing the serial number ldap2dns will
  ignore all modifications until it is restarted.
  
• DNSrefresh, DNSretry, DNSexpire, DNSminimum: You
  may safly ignore these numbers if You don't do
  zone-transfers. Since Your secondary nameserver will
  connect to the LDAP server the same way Your primary
  does, You don't need zone-transfers anyway.
  
• DNSzonemaster: Here you specify the canonical name
  of your primary nameserver.
  
• DNSadminmailbox: This is the contact address of
  Your DNS-administrator. The first dot is converted to a
  @.
  
• DNStype: Must be SOA (Start Of Authority)
  
• DNSclass: Must be IN (Internet, or do still
  use Chaosnet?)
  
• DNSttl: This is the time-to-live value as used by
  tinydns. If TTL is nonzero (or omitted), the
  timestamp is a starting time from whereon this zone's
  information is valid. If TTL is zero, the timestamp is an
  ending time (``time to die'').
  
• DNStimestamp: This is the timestamp as used by
  tinydns. It represents a string as external TAI64
  timestamp, printed as 16 lowercase hexadecimal characters
  

DNSrrset

The Resource Record Set represents all of the resource
records for a given host name within a zone. It must be a
child of a DNSzone object.

ATTRIBUTE	VALUE	Comment
objectclass	DNSrrset	required
cn	common name	required
DNSdomainname	Name of this record	optional, relative to zonename
DNSipaddr	IP address	optional, mutivalued
DNScname	Canonical name	optional, without ending dot relative to zonename
DNSpreference	integer	optional, only used for MX records
DNStype	A, CNAME, NS, MX, PTR or TXT	must be any valid record type
DNSclass	IN	must be IN
DNSttl	time to live	optional, only used with tinydns
DNStimestamp	timestamp	optional, only used with tinydns
DNSsrvpriority	SRV Priority	optional, defaults to 0 for SRV records
DNSsrvweight	SRV Weight	optional, defaults to 0 for SRV records
DNSsrvport	SRV Port	Required for SRV records

• DNSrrset: This object-class must be a direct child
  of DNSzone. Its dn should be specified as
  

  cn=domainname,cn=zonename,...
  

• DNSdomainname This is the partial domain-name, ie.
  the part in front of the zone-name.
  
• DNSipaddr: This specifies the IP-address in dotted
  format. It can be used for DNSrrset's of type
  A, NS, MX or PTR. DNSipaddr is
  multivalued to specifiy more than one IP-address for a
  service. If used in DNSrrset's with DNStype = PTR it overrides the old-fashioned form used in
  DNSdomainname such as 13.178.23.in-addr.arpa for
  reverse lookups.
  
• DNScname: Whenever there is a mapping of a
  domain-name to a canonical name, use this attribute.
  DNScname may be used for DNSrrset's with
  DNStype CNAME, NS, MX, PTR or TXT. If the last
  character of a CNAME is a dot its name is considered
  absolute. If it does not contain a dot, its name is
  prepended to the zone-name.
  
• DNSpreference: This number is the mail-exchange
  preference as used by BIND.
  
• DNStype: This must be A, CNAME, NS, MX, PTR or TXT. It specifies the DNSrrset type.
  
• DNSclass: Must be IN
• DNSttl: This is the time-to-live value as used by
  tinydns. If TTL is non-zero (or omitted), the
  time-stamp is a starting time from where-on this zone's
  information is valid. If TTL is zero, the timestamp is an
  ending time (``time to die'').
  
• DNStimestamp: This is the timestamp as used by
  tinydns. It represents a string as external TAI64
  time-stamp, printed as 16 lowercase hexadecimal
  characters
  
• DNSsrvpriority: Integer representing the relative
  priority of this DNS SRV record. See menandmice.com for more information about DNS SRV
  records.
  
• DNSsrvweight: DNS SRV record weight field. Integer
  
• DNSsrvport: DNS SRV record port number. Integer
  

ldap2dns and ldap2dnsd recognize the following options:

-D binddn specify the distinguished name to bind to the LDAP directory
-w bindpasswd use bindpasswd as password for simple authentication
-b searchbase use searchbase as starting point for search instead default
-o data generate a "data" file to be processed by tinydns-data
-o db for each zone generate a ".db" file to be used by named
-L[filename] print output in LDIF format to [filename] or stdout for reimport
-h host specify the hostname of LDAP directory. Default is localhost
-p port portnumber to connect to LDAP directory. Defaults is 389
-H ldapURI URI for LDAP server (examples: ldap://hostname or ldaps://hostname:636)
-v run in verbose mode
-vv even more verbose
-V print version and exit
-u numsecs update DNS data every numsecs.
-t timeout timeout for LDAP searches, in seconds
-M reclimit Limit LDAP results to reclimit number of records.

ldap2dns and ldap2dnsd recognize the following
environment variables:
TINYDNSDIR: Specifies the directory where ldap2dns
writes its data file.
LDAP2DNS_UPDATE: Specifies the update intervall as the
-u command line option would.
LDAP2DNS_OUTPUT: Specifies the default output, as the
-o command line option would. ldap2dns and
ldap2dnsd use the following parameters from
/etc/ldap.conf if not specified on the command line:
BASE: The LDAP search base.
HOST: The LDAP server.
PORT: The LDAP port.

If You are a tinydns user, run ldap2dns in
/services/tinydns/root.
If You are an openldap user, the command line switches are
the same as for ldapsearch or ldapadd.

$ ldap2dns -D "binddn" [ -w passwd ] -b "searchbase" \
-o data -e "cd /var/tinydns/root && /usr/bin/tinydns-data"

This generates a data file which is converted into a data.cdb
by tinydns-data as soon as ldap2dns detects a modification in the
LDAP directory. The password is required if You restrict read
queries to authenticated users only. Test with

$ dnsq any corp.local ipaddr

Replace ipaddr with whatever You configured tinydns to
listen to. If You are a BIND user, run ldap2dns in
/var/named with

$ ldap2dns -D "binddn" -w passwd -b "searchbase" \
-o db -e "kill -HUP `cat /var/run/named-pid`"

Do not forget to add You primary definition to your
named.conf file. Your named should be restarted automatically as
soon as ldap2dns detects a modification in the LDAP directory. If
bind is not restarted, do so with

# kill -HUP PID

Now run

$ nslookup - localhost
> ns1.corp.local

Note that nslookup only works with tinydns if
your nameserver resolves its IP-address backwards.
When ldap2dns is invoked as
ldap2dnsd, the program starts as backgound-daemon and
continuously checks for modifications in the LDAP directory.
If the the daemon sees a modification in the DNSserial numbers it updates the data or .db files, depending what kind
of output was configured. This check is done about once a
minute and is configurable.
The command-line options for ldap2dnsd are the same as
for ldap2dns. Use the -u option to modify the update
interval. You may also use -u on ldap2dns to start as
a foreground daemon. This is useful if You want to run
ldap2dns from daemontools.

These instructions assume you will be running ldap2dns under daemontoolsb> and that tinydns is also
running under daemontools. These instructions also assume you
are using Dan Bernstein's standard directory locations. Make
sure you change the below examples to match your
environment.

Start by creating the a non-root user to run your ldap2dns
and associated logging mechanism:

# groupadd -r ldap2dns
# useradd -r -d /dev/null -s /bin/false -c "ldap2dns Daemon" \
 -g ldap2dns ldap2dns
# groupadd -r l2dnslog
# useradd -r -d /dev/null -s /bin/false -c "ldap2dns Logger" \
 -g l2dnslog l2dnslog

Next configure the ldap2dns area to be managed by
daemontools. Typically this is /etc/ldap2dns

# cd /etc
# ldap2tinydns-conf ldap2dns l2dnslog /etc/ldap2dns /etc/tinydns/root

The syntax is close to tinydns-conf except that you will also
need to specify the path to the root directory for tinydns.
This is the directory that holds the data file.

Next edit the file /etc/ldap2dns/run and optionally
the environment variables in /etc/ldap2dns/env as
necessary for your environment. This may include configuring
a base DN, a bind DN, a password, and an interval.

When everything is ready configured properly create a symlink
from /etc/ldap2dns into /service. This action
will cause daemontools to launch ldap2dns.

# ln -s /etc/ldap2dns /service/ldap2dns

After a few seconds daemontools starts
ldap2dnsd which itself generates data files whenever a
modification is commited into the LDAP directory. A perl-script import.pl is contained
in this package. Edit the first lines of the script to
conform to Your configuration. If You have installed the Perl
packages Net::LDAP and Net::DNS skip the following lines,
otherwise do

# perl -MCPAN -e 'shell'
(...snip...)
> install Net::DNS
> install Net::LDAP

Now check that Your nameserver allows zone transfers to your
host and run the import script:

$ echo 'primary mydomain.org ' | ./import.pl

for a single domain or

# cat named.boot | ./import.pl

to populate Your LDAP directory. Use the supplied data2ldap.pl in the
scripts/ directory

$ data2ldap.pl data data.ldif ou=DNS,dc=example,dc=com

More to come...

A browser-based administration toolkit,
which connects directly to the LDAP-directory service.

• Write a man page.
  
• named.conf should be created automatically.
  

This program is Copyright 1999-2004 Jacob
Rief and 2005-2006 Ben Klang
This program is licensed under the GPL version 2

ldap2dns was originally written by Jacob Rief
(jacob.rief@tiscover.com). It is now maintained by Ben Klang
(bklang@alkaloid.net). If you run ldap2dns on a
production nameserver, please send the maintainer an email
and mention on what OS and with which nameserver you do
so.

Disclaimer: The author and all contributors
disclaim any kind of warranty or liability or suitability for
any purpose. By running this software you agree that you are
a competent systems administrator and will bear the
responsibility for your actions.

Latest Release: ldap2dns
version 0.4.1

Released October 19, 2006
ChangeLog

Developer Access:

The bleeding edge of ldap2dns is in the Alkaloid
Networks subversion repository found at https://svn.alkaloid.net/gpl/ldap2dns/trunk.

Following the Subversion standard, releases are kept in
/gpl/ldap2dns/tags and branches are in
/gpl/ldap2dns/branches.