1. Introduction to OpenLDAP Directory Services

This document describes how to build, configure, and operate OpenLDAP software to provide directory services. This includes details on how to configure and run the stand-alone LDAP daemon, slapd(8) and the stand-alone LDAP update replication daemon, slurpd(8). It is intended for newcomers and experienced administrators alike. This section provides a basic introduction to directory services and, in particular, the directory services provided by slapd(8).

1.1. What is a directory service?

A directory is specialized database optimized for reading, browsing and searching. Directories tend to contain descriptive, attribute-based information and support sophisticated filtering capabilities. Directories generally do not support complicated transaction or roll-back schemes found in database management systems designed for handling high-volume complex updates. Directory updates are typically simple all-or-nothing changes, if they are allowed at all. Directories are tuned to give quick-response to high-volume lookup or search operations. They may have the ability to replicate information widely in order to increase availability and reliability, while reducing response time. When directory information is replicated, temporary inconsistencies between the replicas may be okay, as long as they get in sync eventually.

There are many different ways to provide a directory service. Different methods allow different kinds of information to be stored in the directory, place different requirements on how that information can be referenced, queried and updated, how it is protected from unauthorized access, etc. Some directory services are local, providing service to a restricted context (e.g., the finger service on a single machine). Other services are global, providing service to a much broader context (e.g., the entire Internet). Global services are usually distributed, meaning that the data they contain is spread across many machines, all of which cooperate to provide the directory service. Typically a global service defines a uniform namespace which gives the same view of the data no matter where you are in relation to the data itself. The Internet Domain Name System is an example of a globally distributed directory service.

1.2. What is LDAP?

slapd's model for directory service is based on a global directory model called LDAP. LDAP stands for Lightweight Directory Access Protocol. LDAP is a directory access protocol that runs over TCP/IP. The nitty-gritty details of LDAP are defined in RFC2251 "The Lightweight Directory Access Protocol (v3)." This section gives an overview of LDAP from a user's perspective.

What kind of information can be stored in the directory? The LDAP information model is based on entries. An entry is a collection of attributes that has a globally-unique Distinguished Name (DN). The DN is used to refer to the entry unambiguously. Each of the entry's attributes has a type and one or more values. The types are typically mnemonic strings, like "cn" for common name, or "mail" for email address. The syntax of values depend on the attribute type is. For example, cn attribute might be the value Babs Jensen. A mail attribute might contain the value "babs@example.com". A jpegPhoto attribute would contain a photograph in the JPEG (binary) format.

How is the information arranged? In LDAP, directory entries are arranged in a hierarchical tree-like structure. Traditionally, this structure reflected the geographic and/or organizational boundaries. Entries representing countries appeared at the top of the tree. Below them are entries representing states and national organizations. Below them might be entries representing organizational units, people, printers, documents, or just about anything else you can think of. Figure 1.1 shows an example LDAP directory tree using traditional naming.

Figure 1.1: LDAP directory tree (traditional naming)

The tree may also be arranged based upon Internet domain names. This naming approach is becoming increasing popular as it allows for directory services to be locating using the Domain Name System. Figure 1.2 shows an example LDAP directory tree using domain-based naming.

Figure 1.2: LDAP directory tree (Internet naming)

In addition, LDAP allows you to control which attributes are required and allowed in an entry through the use of a special attribute called objectClass. The values of the objectClass attribute determine the schema rules the entry must obey.

How is the information referenced? An entry is referenced by its distinguished name, which is constructed by taking the name of the entry itself (called the Relative Distinguished Name or RDN) and concatenating the names of its ancestor entries. For example, the entry for Barbara Jensen in the Internet naming example above has an RDN of uid=babs and a DN of uid=babs,ou=People,dc=example,dc=com". The full DN format is described in RFC2253, "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names."

How is the information accessed? LDAP defines operations for interrogating and updating the directory. Operations are provided for adding and deleting an entry from the directory, changing an existing entry, and changing the name of an entry. Most of the time, though, LDAP is used to search for information in the directory. The LDAP search operation allows some portion of the directory to be searched for entries that match some criteria specified by a search filter. Information can be requested from each entry that matches the criteria.

For example, you might want to search the entire directory subtree at and below dc=example,dc=com for people with the name Barbara Jensen, retrieving the email address of each entry found. LDAP lets you do this easily. Or you might want to search the entries directly below the st=California,c=US entry for organizations with the string Acme in their name, and that have a fax number. LDAP lets you do this too. The next section describes in more detail what you can do with LDAP and how it might be useful to you.

How is the information protected from unauthorized access? Some directory services provide no protection, allowing anyone to see the information. LDAP provides a mechanisms for a client to authenticate, or prove its identity to a directory server, paving the way for rich access control to protect the information the server contains. LDAP also supports privacy and integrity security services.

1.3. How does LDAP work?

LDAP directory service is based on a client-server model. One or more LDAP servers contain the data making up the LDAP directory tree. An LDAP client connects to an LDAP server and asks it a question. The server responds with the answer and/or with a pointer to where the client can get additional information (typically, another LDAP server). No matter which LDAP server a client connects to, it sees the same view of the directory; a name presented to one LDAP server references the same entry it would at another LDAP server. This is an important feature of a global directory service, like LDAP.

1.4. What is slapd and what can it do?

slapd is an LDAP directory server that runs on many different platforms. You can use it to provide a directory service of your very own. Your directory can contain pretty much anything you want to put in it. You can connect it to the global LDAP directory service, or run a service all by yourself. Some of slapd's more interesting features and capabilities include:

LDAPv2 and LDAPv3: slapd supports both version 2 and 3 of the Lightweight Directory Access Protocol. slapd provides support for the latest features while maintaining interoperability with existing clients. slapd supports both IPv4 and IPv6.

Simple Authentication and Security Layer: slapd supports strong authentication services through the use of SASL. slapd's SASL implementation utilizes Cyrus SASL software which supports a number of mechanisms including DIGEST-MD5, EXTERNAL, and GSSAPI.

Transport Layer Security: slapd provides privacy and integrity protections through the use of TLS (or SSL). slapd's TLS implementation utilizes OpenSSL software.

Access control: slapd provides a rich and powerful access control facility, allowing you to control access to the information in your database(s). You can control access to entries based on LDAP authorization information, IP address, domain name and other criteria. slapd supports both static and dynamic access control information.

Internationalization: slapd supports Unicode and language tags.

Choice of databases: slapd comes with a variety of different backend databases you can choose from. They include LDBM, a high-performance disk-based embedded database; SHELL, a database interface to arbitrary shell scripts; and PASSWD, a simple password file database. LDBM utilizes either BerkeleyDB or GDBM.

Multiple database instances: slapd can be configured to serve multiple databases at the same time. This means that a single slapd server can respond to requests for many logically different portions of the LDAP tree, using the same or different backend databases.

Generic modules API: If you require even more customization, slapd lets you write your own modules easily. slapd consists of two distinct parts: a front end that handles protocol communication with LDAP clients; and modules which handle specific tasks such as database operations. Because these two pieces communicate via a well-defined C API, you can write your own customized modules which extend slapd in numerous ways. Also, a number of programmable database modules are provided. These allow you to expose external data sources to slapd using popular programming languages (Perl, Shell, SQL, and TCL).

Threads: slapd is threaded for high performance. A single multi-threaded slapd process handles all incoming requests, reducing the amount of system overhead required.

Replication: slapd can be configured to maintain replica copies of its database. This single-master/multiple-slave replication scheme is vital in high-volume environments where a single slapd just doesn't provide the necessary availability or reliability. slapd also includes experimental support for multi-master replication.

Configuration: slapd is highly configurable through a single configuration file which allows you to change just about everything you'd ever want to change. Configuration options have reasonable defaults, making your job much easier.

slapd also has its limitations, of course. The main LDBM database backend does not handle range queries or negation queries very well. These features and more will be coming in a future release.

1.5. What about X.500?

Technically, LDAP is a directory access protocol to an X.500 directory service, the OSI directory service. Initial LDAP servers were gateways between LDAP and the X.500 Directory Access Protocol (DAP). DAP is a heavyweight protocol that operates over a full OSI protocol stack and requires a significant amount of computing resources. LDAP is designed to operate over TCP/IP and provides most of the functionality of DAP at a much lower cost.

This use of LDAP makes it easy to access the X.500 directory, but still requires a full X.500 service to make data available to the many LDAP clients being developed. As with full X.500 DAP clients, a full X.500 DAP server is no small piece of software to operate.

The stand-alone LDAP daemon, or slapd(8), is meant to remove much of the burden from the server side just as LDAP itself removed much of the burden from clients. If you are already running a X.500 DAP service and you want to continue to do so, you can probably stop reading this guide, which is all about running LDAP via slapd, without running X.500 DAP. If you are not running X.500 DAP, want to stop running X.500 DAP, or have no immediate plans to run X.500 DAP, read on.

It is possible to replicate data from an LDAP directory server to a X.500 DAP DSA. This requires an LDAP/DAP gateway. OpenLDAP does not provide such a gateway, but our replication daemon can be used to replicate to such a gateway. See the Replication with slurpd chapter of this document for information regarding replication.

1.6. What is slurpd and what can it do?

slurpd(8) is a daemon that helps slapd provide replicated service. It is responsible for distributing changes made to the master slapd database out to the various slapd replicas. It frees slapd from having to worry that some replicas might be down or unreachable when a change comes through; slurpd handles retrying failed requests automatically. slapd and slurpd communicate through a simple text file that is used to log changes.

See the Replication with slurpd chapter for information about how to configure and run slurpd(8).