1. Introduction
===============

The dynamic LDAP back-end is a plug-in for BIND that provides an LDAP
database back-end capabilities. For now, it requires that BIND is patched
to support dynamic loading of database back-ends. You can get a patch
for your version here:

  http://github.com/mnagy/bind-dynamic_db/downloads

Hopefully, the patch will once be included in the official BIND release.


2. Features
===========
* support for dynamic updates
* SASL authentication


2.1 Planned features
--------------------
* persistent search


3. Installation
===============

To install the LDAP back-end, extract the tarball and go to the unpacked
directory. Then follow these steps:

$ ./configure --libdir=<libdir>
$ make

Where <libdir> is a directory where your libdns is installed. This is
typically going to be /usr/lib or /usr/lib64 on 64 bit systems.

Then, to install, run this as root:
# make install

This will install the file ldap.so into the <libdir>/bind/ directory.


4. LDAP schema
==============

You can find the complete LDAP schema in the documentation directory. An
example zone ldif is available in the doc directory.


5. Configuration
================

To configure dynamic loading of back-end, you must put a "dynamic-db"
clause into your named.conf. The clause must then be followed by a
string denoting the name. The name is not that much important, it is
passed to the plug-in and might be used for example, for logging
purposes. Following after that is a set of options enclosed between
curly brackets.

The most important option here is "library". It names a shared object
file that will be opened and loaded. The "arg" option specifies a string
that is passed directly to the plugin. You can specify multiple "arg"
options. The LDAP back-end follows the convention that the first word of
this string is the name of the setting and the rest is the value.


5.1 Configuration options
-------------------------
List of configuration options follows:

uri
	The Uniform Resource Identifier pointing to the LDAP server we
	wish to connect to. This string is directly passed to the
	ldap_initialize(3) function. This option is mandatory.
	Example: ldap://ldap.example.com

connections (default 2)
	Number of connections the LDAP driver should try to establish to
	the LDAP server. It's best if this matches the number of threads
	BIND creates, for performance reasons. However, your LDAP server
	configuration might only allow certain number of connections per
	client.

base
	This is the search base that will be used by the LDAP back-end
	to search for DNS zones. It is mandatory.

auth_method (default "none")
	The method used to authenticate to the LDAP server. Currently
	supported methods are "none", "simple" and "sasl". The none
	method is effectively a simple authentication without password.

bind_dn (default "")
	Distinguished Name used to bind to the LDAP server. If this is
	empty and the auth_method is set to "simple", the LDAP back-end
	will fall-back and use the "none" authentication method.

password (default "")
	Password for simple and SASL authentication. If the authentication
	method is set to "simple" and the password is empty, the LDAP
	driver will fall-back to the "none" authentication method.

sasl_mech (default "GSSAPI")
	Name of the SASL mechanism to be used for negotiation.

sasl_auth_name
	The user name to be used for SASL authentication.

sasl_user
	The user name to be used for SASL proxy authorization.

sasl_password
	The password to use for the SASL authentication.

sasl_realm
	The SASL realm name.

krb5_keytab
	Path to the kerberos keytab containing credentials to be used for
	SASL authentication.

cache_ttl (default 120)
	This is the number of seconds to keep DNS records that we get
	from the LDAP server in an internal cache. To disable the
	caching completely, set this to 0. If your LDAP server is under
	a heavy load and/or you don't update your records very often, you
	probably want to set this option on a higher value.

zone_refresh (default 0)
	Interval (in seconds) of how often the LDAP driver should query the
	LDAP server for changes in zone settings. Currently, this is only
	the idnsUpdatePolicy attribute which specifies the update policy for
	a zone. If this option is set to 0, the LDAP driver will never refresh
	the settings.


5.2 Sample configuration
------------------------
Let's take a look at a sample configuration:

dynamic-db "my_db_name" {
	library "ldap.so";
	arg "uri ldap://ldap.example.com";
	arg "base cn=dns, dc=example, dc=com";
	arg "auth_method none";
	arg "cache_ttl 300";
};

With this configuration, the LDAP back-end will try to connect to server
ldap.example.com with simple authentication, without any password. It
will then do an LDAP subtree search in the "cn=dns,dc=example,dc=com"
base for entries with object class idnsZone, for which the
idnsZoneActive attribute is set to True. For each entry it will find, it
will register a new zone with BIND. The LDAP back-end will keep each
record it gets from LDAP in its cache for 5 minutes.


6. License
==========

This package is licensed under the GNU General Public License, version 2
only. See file COPYING for more information.