3.5 The slapd.conf Configuration File

The slapd.conf file is the central source of configuration information for the OpenLDAP standalone server (slapd), the replication helper daemon (slurpd), and related tools, such as slapcat and slapadd. As a general rule, the OpenLDAP client tools such as ldapmodify and ldapsearch use ldap.conf (not slapd.conf) for default settings.

In the tradition of Unix configuration files, slapd.conf is an ASCII file with the following rules:

Blank lines and lines beginning with a pound sign (#) are ignored.
Parameters and associated values are separated by whitespace characters (space or tab).
A line with a blank space in the first column is considered to be a continuation of the previous one. There is no need for a line continuation character such as a backslash (\).

For general needs, the slapd.conf file used by OpenLDAP 2 can be broken into two sections. The first section contains parameters that affect the overall behavior of the OpenLDAP servers (for example, the level of information sent to log files). The second section is composed of parameters that relate to a particular database backend used by the slapd daemon. It is possible to define some default settings for these in the global section of slapd.conf. However, any value specified in the database section will override default settings.

Here's a partial listing that shows how these two sections look:

# /usr/local/etc/openldap/slapd.conf
      
# Global section
      
## Global parameters removed for brevity's sake, for now . . . 
      
#######################################################
# Database #1 - Berkeley DB
database      bdb
      
## Database parameters and directives would go here.
      
#######################################################
# Database #2 - Berkeley DB
database      bdb
      
## Database parameters and directives would go here.
      
## And so on . . .

The global section starts at the beginning of the file and continues until the first database directive. We will revisit the few parameters listed here in a few moments.

The start of a database backend section is marked by the database parameter; the section continues until the beginning of the next database section or the end of the file. It is possible to define multiple databases that are served by a single installation of slapd. Each one is logically independent, and the associated database files will be stored separately.

For security reasons, the slapd.conf file should be readable and writable only by the user who runs the slapd daemon, which is normally the superuser. A working server's slapd.conf often contains sensitive information that should be restricted from unauthorized viewing.

3.5.1 Schema Files

The first step in configuring your LDAP server is to decide which schema the directory should support. It's not easy to answer this question in a few lines. We'll start our example with the bare minimum.

OpenLDAP 2 includes several popular schema files to be used at the administrator's discretion. The needs of the applications that will use the directory determine which schema you use. All the attributeType and objectClass definitions required for a bare-bones server are included in the file core.schema. Some of these attributeTypes and objectClasses are:

Attributes for storing the timestamp of the last update on an entry
Attributes for representing name, locations, etc.
Objects to represent an organization or person
Objects to represent DNS domain names
And so on . . .

By default, this file is located in the directory /usr/local/etc/openldap/schema/ after installation. In the configuration file, the include parameter specifies schemas to be included by the server. Here's how the file looks for a minimal configuration:

# /usr/local/etc/openldap/slapd.conf
      
# Global section
      
## Include the minimum schema required.
include     /usr/local/etc/openldap/schema/core.schema
      
#######################################################
## Database sections omitted

I won't discuss the details of what is contained in core.schema yet. I'll delay this discussion until adequate time can be spent on the syntax of the file. If you would like a head start, reading RFC 2552 will provide the necessary knowledge for understanding the majority of OpenLDAP's schema files.

There are several schema files included with a default OpenLDAP 2.1 installation:

corba.schema: A schema for storing Corba objects in an LDAP directory, as described in RFC 2714.
core.schema: OpenLDAP's required core schema. This schema defines basic LDAPv3 attributes and objects described in RFCs 2251-2256.
cosine.schema: A schema for supporting the COSINE and X.500 directory pilots. Based on RFC 1274.
inetorgperson.schema: The schema that defines the inetOrgPerson object class and its associated attributes defined in RFC 2798. This object is frequently used to store contact information for people.
java.schema: A schema defined in RFC 2713 for storing a Java serialized object, a Java marshalled object, a remote Java object, or a JDNI reference in an LDAP directory.
misc.schema: A schema that defines a small group of miscellaneous objects and attributes. Currently, this file contains the schema necessary to implement LDAP-based mail routing in Sendmail 8.10+.
nis.schema: A schema that defines attributes and objects necessary for using LDAP with the Network Information Service (NIS) as described in RFC 2307 (see Chapter 6).
openldap.schema: Miscellaneous objects used by the OpenLDAP project. Provided for information purposes only.

The client applications that you want to support may require you to include schema files in addition to core.schema. Make sure you are aware of dependencies between schema files. Dependencies are normally described at the beginning of the file. For example, many applications require you to include the inetOrgPerson object class, which is frequently used to store contact information. The beginning of the inetorgperson.schema file tells you that you must also include cosine.schema.

3.5.2 Logging

The next group of parameters that you frequently find in the global section of slapd.conf control where slapd logs information during execution, as well as how much information is actually written to the log. Here's our configuration file with logging added:

# /usr/local/etc/openldap/slapd.conf
      
# Global section
      
## Include the minimum schema required.
include     /usr/local/etc/openldap/schema/core.schema
      
## Added logging parameters
loglevel     296
pidfile      /usr/local/var/slapd.pid
argsfile     /usr/local/var/slapd.args
      
#######################################################
## Database sections omitted

The first new parameter is loglevel. This directive accepts an integer representing the types of information that should be recorded in the system logs. It is helpful to think of loglevel as a set of bit flags that can be logically ORed together. The flags are listed in Table 3-2. In this example, the logging level is set to 296, which equals 8 + 32 + 256. Table 3-2 tells us that this value causes slapd to log the following information:

8: Connection management
32: Search filter processing
256: Statistics for connection, operations, and results

Table 3-2. OpenLDAP logging levels

Level

Information recorded

-1

All logging information

0

No Logging information

1

Trace function calls

2

Packet-handling debugging information

4

Heavy trace debugging

8

Connection management

16

Packets sent and received

32

Search filter processing

64

Configuration file processing

128

Access control list processing

256

Statistics for connection, operations, and results

512

Statistics for results returned to clients

1024

Communication with shell backends

2048

Print entry parsing debug information

All debugging information is logged using the LOG_LEVEL4 syslog facility. Therefore, to instruct slapd to write log entries to a separate log file, add the following line to /etc/syslog.conf and instruct the syslogd daemon to reread its configuration file by sending it a hangup (kill -HUP) signal:

local4.debug          /var/log/slapd.log

The syntax of syslog.conf on your system may be slightly different, so you should consult the syslog.conf manpage for details.

Some syslogd daemons require that the specified logging file exists before they write information to the log. If you think you have set up syslog correctly, but no data is being collected and your file doesn't exist, try creating the logging file with the touch command.

The remaining two parameters introduced in this section can be summed up in a sentence or two:

pidfile filename: This parameter specifies the absolute location of a file that will contain the process ID of the currently running master slapd process.
argsfile filename: This parameter specifies the absolute path to a file containing the command-line parameters used by the currently running master slapd. This parameter is processed only if slapd is started without the debug command-line argument.

3.5.3 SASL Options

When I first introduced the topic of installing the Cyrus SASL libraries, I said that SASL is not needed if only simple binds will be used to access the directory. However, it's often useful to allow a combination of simple binds and SASL mechanisms for user connections. For example, we might want to allow most users (who are only allowed to look up data) to authenticate via a simple bind, while requiring administrators (who are allowed to change data) to authenticate via SASL. So let's see how to configure the directory server to require the use of SASL for certain administrative accounts, while still allowing simple binds (possibly over TLS) for most clients.

slapd.conf has three SASL-related global options. These are:

sasl-host hostname

sasl-realm string

sasl-secprops properties

sasl-host is the fully qualified domain name of the host used for SASL authentication. For local authentication mechanisms such as DIGEST-MD5, this will be the host and domain name of the slapd server. sasl-realm is the SASL domain used for authentication. If you are unsure of this value, use sasldblistusers to dump the /etc/sasldb database and obtain the realm name to use.

The third parameter, sasl-secprops, allows you to define various conditions that affect SASL security properties. The possible values for this parameter are given in Table 3-3. Note that it is legal to use multiple values in combination. The default security properties are noanonymous and noplain.

Table 3-3. sasl-secprops parameter values and descriptions

Flag

Description

None

Clears the default security properties (noplain, noanonymous).

noplain

Disables mechanisms vulnerable to passive attacks, such as viewing network packets to examine passwords.

noactive

Disables mechanisms vulnerable to active attacks.

nodict

Disables mechanisms that are vulnerable to dictionary-based password attacks.

noanonymous

Disables mechanisms that support anonymous login.

forwardsec

Requires forward secrecy between sessions.

passcred

Requires mechanisms that pass client credentials.

minssf=factor

Defines the minimum security strength enforced. Possible values include: 0 (no protection), 1 (integrity protection only), 56 (allow DES encryption), 112 (allow 3DES or other string encryption methods), and 128 (allow RC4, Blowfish, or other encryption algorithms of this class).

maxssf=factor

Defines the maximum security strength setting. The possible values are identical to those of minssf.

maxbufsize=size

Defines the maximum size of the security layer receive buffer. A value of 0 disables the security layer. The default value is the maximum of INT_MAX (i.e., 65536).

To fully understand the sasl-secprops parameter, you must also understand the effects of the various cyrus-sasl plug-ins. Table 3-4 summarizes the available mechanisms and property flags.

Table 3-4. SASL authentication mechanism security properties

SASL mechanism

Security property flags

maxssf

ANONYMOUS

NOPLAIN

0

CRAM-MD5

NOPLAIN

NOANONYMOUS

0

DIGEST-MD5

NOPLAIN

NOANONYMOUS

128 if compiled with RC4; 112 if compiled with DES; 0 if compiled with neither RC4 nor DES

GSSAPI

NOPLAIN

NOACTIVE

NOANONYMOUS

56

KERBEROS_V4

NOPLAIN

NOACTIVE

NOANONYMOUS

56

LOGIN

NOANONYMOUS

0

PLAIN

NOANONYMOUS

0

SCRAM-MD5

NONE

0

SRP

NOPLAIN

0

Consider if you had added the following line to the global section of your current slapd.conf:

## No PLAIN or ANONYMOUS mechanisms; use DES encrpytion
sasl-secprops     noplain,noanonymous,minssf=56

Comparing the value of sasl-secprops with the mechanisms listed in Table 3-4 shows that your server will allow only the following mechanisms for authentication:

DIGEST-MD5

GSSAPI

KERBEROS_4

This configuration assumes that all of these SASL plug-ins have been installed as well. Also remember that configuring these SASL parameters does not require that an SASL mechanism must always be used for authentication.

3.5.4 SSL/TLS Options

Like the SASL parameters, slapd.conf offers several options for configuring settings related to SSL and TLS. These parameters include:

TLSCipherSuite cipher-suite-specification

TLSCertificateFile filename

TLSCertificateKeyFile filename

The TLSCipherSuite parameter allows you to specify which ciphers the server will accept. It also specifies a preference order for the ciphers. The value for TLSCipherSuite should be a colon-separated list of cipher suites. The explanation of available cipher suites is lengthy, so I won't reproduce it; refer to the ciphers(1) manpage distributed with OpenSSL. Here are a few common options; the order of preference is from left to right:

RC4:DES:EXPORT40

HIGH:MEDIUM

3DES:SHA1:+SSL2

The next two parameters, TLSCertificateFile and TLSCertificateKeyFile, inform slapd of the location of the server's certificate and the associated private key. This will be used to implement both LDAP over SSL (LDAPS) and the StartTLS extended operation. However, you have yet to create a certificate for your server.

3.5.4.1 Generating the server's certificate

The CA.pl Perl script, installed in /usr/local/misc/ as part of the OpenSSL installation, provides a nice wrapper around the openssl tool and its command-line arguments. To use this script, openssl must be located in the current search path.

Crypto 101

In my own work configuring OpenSSL and the services that use these libraries, I have found the documentation a little sparse. If you are interested in learning more about SSL, cryptography, or digital certificates, the following sources are a good place to start:

"An Introduction to SSL," http://developer.netscape.com/docs/manuals/security/sslin/content.htm.

T. Dierks, et al., "The TLS Protocol Version 1.0", RFC2246, January 1999.

C. Kaufman, et al., Network Security: PRIVATE Communication in a PUBLIC World (Prentice Hall).

Peter Gutannn's "Godzilla Crypto Tutorials Slides," http://www.cs.auckland.ac.nz/~pgut001/.

Bruce Schneier, Applied Cryptography: Protocols, Algorithms, and Source Code in C (John Wiley & Sons).

John Viéga, et al., Network Security with OpenSSL (O'Reilly).

The CA.pl script greatly simplifies the creation of server certificates. In order to create a new certificate, use the -newcert command-line option and answer the questions as prompted. Here's how to use CA.pl to create a new certificate:

$ /usr/local/misc/CA.pl -newcert
Enter PEM pass phrase:test
Verifying password - Enter PEM pass phrase:test
-----
You are about to be asked to enter information that will be incorporated into your 
certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [GB]:US
State or Province Name (full name) [Berkshire]:Alabama
Locality Name (eg, city) [Newbury]:Somewhere
Organization Name (eg, company) [My Company Ltd]:PlaineJoe Dot Org
Organizational Unit Name (eg, section) [  ]:IT
Common Name (eg, your name or your server's hostname) [  ]:pogo.plainjoe.org
Email Address [  ]:[email protected]
Certificate (and private key) is in newreq.pem

This command creates a file named newreq.pem that contains a password-protected private key and a self-signed certificate. Here are the contents of newreq.pem:

Notice that the CA.pl script places a private key in the same file as the public certificate. You must remove the password for the private key unless you always want to start the OpenLDAP server manually. It is extremely important to protect this key carefully. Public key cryptography is no good if the private key is readily available to anyone.

Because this private key is password protected, it will require some modification before integrating it into the server's setup. The following command removes the password from the private key and places the modified version of the key in a separate file:

$ openssl rsa -in newreq.pem -out newkey.pem
read RSA key
Enter PEM pass phrase:test
writing RSA key

The newkey.pem file can be renamed to a filename of your choosing. Something like slapd-key.pem would be appropriate. Make sure that the new file is safely secured using the appropriate filesystem permissions (i.e., rw-------).

Finally, using your favorite text editor, remove the original private key from newreq.pem. I'll rename the certificate file to slapd-cert.pem for the remaining examples in this chapter. At this point, we have the following files:

slapd-key.pem: LDAP server's private key
slapd-cert.pem: LDAP server's public certificate

Here are the TLS configuration parameters in the context of slapd.conf:

# /usr/local/etc/openldap/slapd.conf
      
# Global section
      
## Include the minimum schema required.
include     /usr/local/etc/openldap/schema/core.schema
      
## Added logging parameters
loglevel     296
pidfile      /usr/local/var/slapd.pid
argsfile     /usr/local/var/slapd.args
      
## TLS options for slapd 
TLSCipherSuite          HIGH
TLSCertificateFile      /etc/local/slapd-cert.pem
TLSCertificateKeyFile   /etc/local/slapd-key.pem
      
#######################################################
## Database sections omitted

3.5.5 More Security-Related Parameters

There are also five other security-related global options to be covered prior to continuing on to the database section. These are:

security

require

allow

disallow

password-hash

The security parameter allows us to specify general security strength factors. Table 3-5 lists the options and values for the security parameter. All of these options take an integer value specifying the strength factor; the integer must be one of the values used for the minssf and maxssf parameters described in Table 3-3.

Table 3-5. Possible values for the slapd.conf security parameter

Value

Description

sasl

Defines the SASL security strength factor.

ssf

Defines the overall security strength factor.

tls

Defines the security strength factor to the SSL/TLS security layer.

transport

Defines the security strength provided by the underlying transport layer. Eventually, this option will be used to choose between multiple secure transport layer protocols, such as TLS and IPSEC.

update_sasl

update_ssf

update_tls

update_transport

Define the security strength of the various layers when performing update operations on the directory.

For example, we can require very strong authentication and transport layer security when performing updates by adding the following line to the global section of slapd.conf:

## Require strong authentication and transport layer security for update operations.
## NOTE: This is just an example and will not be added to our final slapd.conf. 
security     update_sasl=128,update_tls=128

To take full advantage of the security parameter, you must disable simple binds and use only SASL mechanisms for authentication. See the disallow parameter in this section for details of how this can be done.

The require parameter differs from the security parameter by allowing an administrator to define general conditions that must be met to provide access to the directory. This setting may be done globally or on a per-database basis. The require parameter accepts a comma-separated list of the strings described in Table 3-6.

Table 3-6. Values for the require parameter

Value

Description

none

Clears all requirements.

authc

Requires client authentication prior to directory access (i.e., no anonymous access).

bind

Requires the client to issue a bind request, possibly an anonymous bind, prior to directory operations.

LDAPv3

Requires the client to use Version 3 of the LDAP protocol for directory access. By default, OpenLDAP supports both LDAPv2 and v3 clients.

SASL strong

Require the client to use strong (SASL) authentication in order to be granted access to the directory. Currently, these two options are identical.

The effect of some of the require settings can be obtained by other means as well. For example, if anonymous users should have no access to directory information, OpenLDAP provides access control lists within a database that can restrict access in a much more flexible way.

The allow (and complementary disallow) parameters provide another means of enabling and disabling certain features. Currently, the allow parameter supports only two options:

none: This is the default setting.
tls_2_anon: Allows TLS to force the current session to anonymous status.

The disallow parameter, however, offers many more options. These include:

bind_v2: Disables LDAPv2 bind requests
bind_anon: Disables anonymous binds
bind_anon_cred: Disables anonymous credentials when the DN is empty
bind_anon_dn: Disables anonymous binds when the DN is nonempty
bind_simple: Disables simple binds
bind_krbv4: Disables Kerberos 4 bind requests
tls_authc: Disables StartTLS if the client is authenticated

Finally, the password-hash parameter defines the default password encryption scheme used to store values in the userPassword attribute. This setting can be overridden on an individual attribute basis by prefixing the password with the appropriate directive. The default encryption scheme is {SSHA}. Other possibilities include:

{SHA}

{SMD5}

{MD5}

{CRYPT}

{CLEARTEXT}

The security parameters and examples presented here are enough for our needs. Refer to the openssl(1) manpage for more information on OpenSSL tools and configuration.

After covering these final parameters, you can complete the global section of your slapd.conf:

# /usr/local/etc/openldap/slapd.conf
      
# Global section
      
## Include the minimum schema required.
include     /usr/local/etc/openldap/schema/core.schema
      
## Added logging parameters
loglevel     296
pidfile      /usr/local/var/slapd.pid
argsfile     /usr/local/var/slapd.args
      
## TLS options for slapd 
TLSCipherSuite          HIGH
TLSCertificateFile      /etc/local/slapd-cert.pem
TLSCertificateKeyFile   /etc/local/slapd-key.pem
      
## Misc security settings
password-hash     {SSHA}
      
#######################################################
## Database sections omitted

3.5.6 Serving Up Data

Following the global section of slapd.conf will be one or more database sections, each defining a directory partition. A database section begins with the database directive and continues until the next occurrence of the database directive or the end of the file. This parameter has several possible values:

bdb: This backend has been specifically written to take advantage of the Berkley DB 4 database manager. This backend makes extensive use of indexing and caching to speed up performance; it is the recommended backend used on an OpenLDAP server.
ldbm: An ldbm database is implemented via either the GNU Database Manager or the Sleepycat Berkeley DB software package. This backend is the older implementation of the bdb backend. The details of this backend are described in the slapd-ldbm(5) manpage.
passwd: The passwd backend is a quick and dirty means of providing a directory interface to the system passwd(5) file. It has only one configuration parameter: the file directive, which defines the location of the password file (if different from /etc/passwd) used to respond to directory queries. The details of this backend are described in the slapd-passwd(5) manpage.
shell: The shell backend directive allows the use of alternative (and external) databases. This directive lets you specify external programs that are called for each of the LDAPv3 core operations. The details of this backend are described in the slapd-shell(5) manpage.

The first step in writing a database section is defining the type of backend. The examples in the remainder of this book almost exclusively use the bdb database value.

## Begin a new database section.
database     bdb

The next item is to define the directory partition's naming context. The naming context allows slapd to serve multiple, potentially disconnected partitions from a single server. Each partition has a unique naming context that identifies the root entry in the tree. The following example defines the naming context of the database to correspond with the local domain name, a practice recommended by RFC 2247 ("Using Domains in LDAP/X.500 Distinguished Names"):

## Define the beginning of example database.
database     bdb
      
## Define the root suffix you serve.
suffix          "dc=plainjoe,dc=org"

Each LDAP directory can have a root DN (rootdn), which is similar to the superuser account on Unix systems. When authenticated, this DN is authorized to do whatever the user desires; access control restrictions do not apply. For this reason, some administrators prefer not to configure a root DN at all, or at least remove it once the directory has been sufficiently populated to hand over control to existing user accounts.

The naming of the root DN is arbitrary, although the cn values of "admin" and "Manager" have become common choices. The root DN also requires a corresponding root password (rootpw), which can be stored in clear text or encrypted form using one of the prefixes accepted by the password-hash parameter. OpenLDAP 2 provides the slappasswd(8c) utility for generating {CRYPT}, {MD5}, {SMD5}, {SSHA}, and {SHA} passwords. Do not place the root password in plain text regardless of what the permissions on slapd.conf are. Even if the password is encrypted, it is extremely important not to allow unauthorized users to view slapd.conf.

## Define a root DN for superuser privileges.
rootdn      "cn=Manager,dc=plainjoe,dc=org"
      
## Define the password used with rootdn. This is a salted secure hash of the phrase 
## "secret."
rootpw          {SSHA}2aksIaicAvwc+DhCrXUFlhgWsbBJPLxy

You aren't required to define a root password. If no rootpw directive is present, the rootdn is authenticated using the server's default authentication method (e.g., SASL). OpenLDAP 2.1 uses a DN representation of an SASL identify. The general syntax is:

uid=name,[cn=realm],cn=SASL Mechanism,cn=auth

The cn=realm portion on the DN is omitted if the mechanism does not support the concept of realms or if the one specified is the default realm for the server. If your OpenLDAP server existed within the PLAINJOE.ORG realm and you chose to use a Kerberos 5 principal named [email protected] as the rootdn, it would appear as:

rootdn "uid=ldapadmin,cn=gssapi,cn=auth"

The next two parameters should be left to their default values:

lastmod: This parameter determines whether slapd will maintain the operational attributes modifiersName, modifyTimestamp, creatorsName, and createTimestamp for all entries defined in core.schema. The default behavior is to maintain the information for all entries. The option accepts a value of off or on. Disabling this parameter means that client-side caching of information is not possible because no marker exists to test whether an entry has been updated.
readonly: The readonly parameter allows a server to disable all update access, including update access by the rootdn. Directory data is writable by default, assuming that there are no access control lists in place. Under some circumstances, such as backing up the data, you may want to prevent the directory from accepting modifications. Like the lastmod parameter, the readonly options also accept the values off or on.

3.5.6.1 bdb backend-specific parameters

The database parameters discussed up to this point are applicable to OpenLDAP's various database backends in general. This section examines several parameters that are used only by the bdb database.

The directory and mode parameters define the physical location and filesystem permissions of the created database files. These parameters are necessary because, when using an ldbm backend, slapd manages the data store itself. In the following configuration file, the directory and mode parameters tell slapd and the other LDAP tools how to locate and store the database files for this partition. The files are stored in the directory /var/ldap/plainjoe.org/ and created with read/write permission (0600) for the owner only (the account under which the slapd daemon runs).

## Define the beginning of example database.
database        bdb
      
## Define the root suffix you serve.
suffix          "dc=plainjoe,dc=org"
      
## Define a root DN for superuser privileges.
rootdn          "cn=Manager,dc=plainjoe,dc=org"
      
## Define the password used with rootdn. This is the Base64-encoded MD5 hash of
## "secret."
rootpw          {SSHA}2aksIaicAvwc+DhCrXUFlhgWsbBJPLxy
      
## Directory containing the database files
directory       /var/ldap/plainjoe.org
      
## Files should be created rw for the owner **only**.
mode            0600

It's a good idea to maintain tight security on the physical database files even if the directory server is a closed box (i.e., no users can log into the server and run a shell). It is easier to manage the server when the only way to access the backend storage is via slapd itself.

The index parameter specifies the attributes on which slapd should maintain indexes. These indexes are used to optimize searches, similar to the indexes used by a relational database management system. slapd supports four types of indexes. However, not all attributes support all four index types. Each index type corresponds to one of the matching rules defined in the directory schema.

approx (approximate): Indexes the information for an approximate, or phonetic, match of an attribute's value.
eq (equality): Indexes the information necessary to perform an exact match of an attribute value. The match may be case-sensitive or whitespace-sensitive, depending on the matching rules defined in the attribute's syntax.
pres (presence): Indexes the information necessary to determine if an attribute has any value at all. If an attribute does not possess a value, then the attribute is not present in the directory entry.
sub (substring): Indexes the information necessary to perform a simple substring match on attribute values.

There can be multiple index definitions for the same database�and even multiple attributes or index types�on the same line. Each attribute or index type should be separated by a comma; use whitespace to separate the attribute list from the list of index types. Here's how to define an equality and presence index on the cn attribute:

## Maintain presence and equality searches on the cn and uid attributes.
index          cn          pres,eq

Which indexes should be maintained depends on the client applications that the server will support and the types of searches that those applications will perform. The best way to determine which indexes to maintain is to include the search processing debug output (loglevel 32) in the server's log file.

OpenLDAP 2 requires an equality index on the objectClass attribute for performance reasons.

## Must be maintained for performance reasons index objectClass eq

I cannot stress the use of proper indexes enough. Misconfigured indexes are probably the number one reason administrators experience performance problems with OpenLDAP servers. Many of the applications and scenarios presented later in the book focus on functionality and not necessarily performance. This should not be construed as lessening the importance of properly indexing the attributes used freqently in searches. It simply means that I assume you have learned your lesson about indexes here and can fill in the blanks later.

While an indexed database offers many performance benefits over flat text files, these benefits can be increased by caching entries and indexes in memory to prevent disk I/O in response to common searches. The cachesize parameter allows you to tune caching according to the needs of the directory.

The cachesize parameter defines the number of entries that should be cached in memory. The default is to cache 1,000 entries. If your total directory size is less than 1,000 entries, there is no need to modify this setting. If, however, your directory contains 1,000,000 entries, a cache size of 100,000 would not be unusual.

When setting parameters to integer values in slapd.conf, make sure to remove commas from the number. For example, 100,000 should be entered as 100000.

Here is what the database section looks like so far:

## Define the beginning of example database.
database        bdb
      
## Define the root suffix you serve.
suffix          "dc=plainjoe,dc=org"
      
## Define a root DN for superuser privileges. This is the Base64-encoded MD5 hash of
## "secret."
rootdn          "cn=Manager,dc=plainjoe,dc=org"
      
## Define the password used with rootdn.
rootpw          {SSHA}2aksIaicAvwc+DhCrXUFlhgWsbBJPLxy
      
## Directory containing the database files
directory       /var/ldap/plainjoe.org
      
## Files should be created rw for the owner **only**.
mode            0600
      
## Indexes to maintain
index           objectClass     eq
index           cn              pres,eq
      
## db tuning parameters; cache 2,000 entries in memory
cachesize       2000

[ Team LiB ]