Show Table of Contents
2.2. Configuration Files
Each Directory Server instance stores its configuration files in the
/etc/dirsrv/slapd-instance_name directory.
The configuration information for Red Hat Directory Server is stored as LDAP entries within the directory itself. Therefore, changes to the server configuration must be implemented through the use of the server itself rather than by simply editing configuration files. The principal advantage of this method of configuration storage is that it allows a directory administrator to reconfigure the server using LDAP while it is still running, thus avoiding the need to shut the server down for most configuration changes.
2.2.1. Overview of the Directory Server Configuration
When the Directory Server is set up, its default configuration is stored as a series of LDAP entries within the directory, under the subtree
cn=config. When the server is started, the contents of the cn=config subtree are read from a file (dse.ldif) in LDIF format. This dse.ldif file contains all of the server configuration information. The latest version of this file is called dse.ldif, the version prior to the last modification is called dse.ldif.bak, and the latest file with which the server successfully started is called dse.ldif.startOK.
Many of the features of the Directory Server are designed as discrete modules that plug into the core server. The details of the internal configuration for each plug-in are contained in separate entries under
cn=plugins,cn=config. For example, the configuration of the Telephone Syntax Plug-in is contained in this entry:
cn=Telephone Syntax,cn=plugins,cn=config
Similarly, database-specific configuration is stored under
cn=ldbm database,cn=plugins,cn=config for local databases and cn=chaining database,cn=plugins,cn=config for database links.
The following diagram illustrates how the configuration data fits within the
cn=config directory information tree.
Figure 2.1. Directory Information Tree Showing Configuration Data
2.2.1.1. LDIF and Schema Configuration Files
The Directory Server configuration data are stored in LDIF files in the
/etc/dirsrv/slapd-instance_name directory. Thus, if a server identifier is phonebook, then for a Directory Server on Red Hat Enterprise Linux 5 (64-bit), the configuration LDIF files are all stored under /etc/dirsrv/slapd-phonebook.
This directory also contains other server instance-specific configuration files.
Schema configuration is also stored in LDIF format, and these files are located in the
/etc/dirsrv/schema directory.
The following table lists all of the configuration files that are supplied with the Directory Server, including those for the schema of other compatible servers. Each file is preceded by a number which indicates the order in which they should be loaded (in ascending numerical and then alphabetical order).
Table 2.3. Directory Server LDIF Configuration Files
2.2.1.2. How the Server Configuration Is Organized
The
dse.ldif file contains all configuration information including directory-specific entries created by the directory at server startup, such as entries related to the database. The file includes the root Directory Server entry (or DSE, named by "") and the contents of cn=config and cn=monitor.
When the server generates the
dse.ldif file, it lists the entries in hierarchical order in the order that the entries appear in the directory under cn=config, which is usually the same order in which an LDAP search of subtree scope for base cn=config returns the entries.
dse.ldif also contains the cn=monitor entry, which is mostly read-only, but can have ACIs set on it.
Note
The
dse.ldif file does not contain every attribute in cn=config. If the attribute has not been set by the administrator and has a default value, the server will not write it to dse.ldif. To see every attribute in cn=config, use ldapsearch.
2.2.1.2.1. Configuration Attributes
Within a configuration entry, each attribute is represented as an attribute name. The value of the attribute corresponds to the attribute's configuration.
The following code sample is an example of part of the
dse.ldif file for a Directory Server. The example shows, among other things, that schema checking has been enabled; this is represented by the attribute nsslapd-schemacheck, which takes the value on.
dn: cn=config objectclass: top objectclass: extensibleObject objectclass: nsslapdConfig nsslapd-accesslog-logging-enabled: on nsslapd-enquote-sup-oc: off nsslapd-localhost: phonebook.example.com nsslapd-schemacheck: on nsslapd-port: 389 nsslapd-localuser: nobody ...
2.2.1.2.2. Configuration of Plug-in Functionality
The configuration for each part of Directory Server plug-in functionality has its own separate entry and set of attributes under the subtree
cn=plugins,cn=config. The following code sample is an example of the configuration entry for an example plug-in, the Telephone Syntax plug-in.
dn: cn=Telephone Syntax,cn=plugins,cn=config objectclass: top objectclass: nsSlapdPlugin objectclass: extensibleObject cn: Telephone Syntax nsslapd-pluginType: syntax nsslapd-pluginEnabled: on
Some of these attributes are common to all plug-ins, and some may be particular to a specific plug-in. Check which attributes are currently being used by a given plug-in by performing an
ldapsearch on the cn=config subtree.
For a list of plug-ins supported by Directory Server, general plug-in configuration information, the plug-in configuration attribute reference, and a list of plug-ins requiring restart for configuration changes, see Chapter 4, Plug-in Implemented Server Functionality Reference.
2.2.1.2.3. Configuration of Databases
The
o=NetscapeRoot and cn=UserRoot subtrees under the database plug-in entry contain configuration data for the databases containing the o=NetscapeRoot suffix and the default suffix created during setup, such as dc=example,dc=com.
These entries and their children have many attributes used to configure different database settings, like the cache sizes, the paths to the index files and transaction logs, entries and attributes for monitoring and statistics; and database indexes.
2.2.1.2.4. Configuration of Indexes
Configuration information for indexing is stored as entries in the Directory Server under the following information-tree nodes:
- cn=index,o=NetscapeRoot,cn=ldbm database,cn=plugins,cn=config
- cn=index,cn=UserRoot,cn=ldbm database,cn=plugins,cn=config
- cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config
For more information about indexes in general, see the Directory Server Administrator's Guide. For information about the index configuration attributes, see Section 4.4.1, “Database Attributes under cn=config,cn=ldbm database,cn=plugins,cn=config”.
2.2.2. Accessing and Modifying Server Configuration
This section discusses access control for configuration entries and describes the various ways in which the server configuration can be viewed and modified. It also covers restrictions to the kinds of modification that can be made and discusses attributes that require the server to be restarted for changes to take effect.
2.2.2.1. Access Control for Configuration Entries
When the Directory Server is installed, a default set of access control instructions (ACIs) is implemented for all entries under
cn=config. The following code sample is an example of these default ACIs.
aci: (targetattr = "*")(version 3.0; acl "Configuration Administrators Group"; allow (all)
groupdn = "ldap:///cn=Configuration Administrators,u=Groups,ou=TopologyManagement,o=NetscapeRoot";)
aci: (targetattr = "*")(version 3.0; acl "Configuration Administrator"; allow (all)
userdn = "ldap:///uid=admin,ou=Administrators,ou=TopologyManagement,o=NetscapeRoot";)
aci: (targetattr = "*")(version 3.0; acl "Local Directory Administrators Group"; allow (all)
groupdn = "ldap:///ou=Directory Administrators,dc=example,dc=com";)
aci: (targetattr = "*")(version 3.0; acl "SIE Group"; allow(all)
groupdn = "ldap:///cn=slapd-phonebook,cn=Red Hat Directory Server,
cn=Server Group,cn=phonebook.example.com,dc=example,dc=com,o=NetscapeRoot";)
These default ACIs allow all LDAP operations to be carried out on all configuration attributes by the following users:
- Members of the Configuration Administrators group.
- The user acting as the administrator, the
adminaccount that was configured at setup. By default, this is the same user account which is logged into the Console. - Members of local Directory Administrators group.
- The SIE (Server Instance Entry) group, usually assigned using the Set Access Permissions process the main console.
For more information on access control, see the Directory Server Administrator's Guide.
2.2.2.2. Changing Configuration Attributes
Server attributes can be viewed and changed in one of three ways: through the Directory Server Console, by performing
ldapsearch and ldapmodify commands, or by manually editing the dse.ldif file.
Note
Before editing the
dse.ldif file, the server must be stopped; otherwise, the changes are lost. Editing the dse.ldif file is recommended only for changes to attributes which cannot be altered dynamically. See Section 2.2.2.2.3, “Configuration Changes Requiring Server Restart” for further information.
The following sections describe how to modify entries using LDAP (both by using Directory Server Console and by using the command line), the restrictions that apply to modifying entries, the restrictions that apply to modifying attributes, and the configuration changes requiring restart.
2.2.2.2.1. Modifying Configuration Entries Using LDAP
The configuration entries in the directory can be searched and modified using LDAP either via the Directory Server Console or by performing
ldapsearch and ldapmodify operations in the same way as other directory entries. The advantage of using LDAP to modify entries is changes can be made while the server is running.
For further information, see the "Creating Directory Entries" chapter in the Directory Server Administrator's Guide. However, certain changes do require the server to be restarted before they are taken into account. See Section 2.2.2.2.3, “Configuration Changes Requiring Server Restart” for further information.
Note
As with any set of configuration files, care should be taken when changing or deleting nodes in the
cn=config subtree as this risks affecting Directory Server functionality.
The entire configuration, including attributes that always take default values, can be viewed by performing an
ldapsearch operation on the cn=config subtree:
ldapsearch -D "cn=directory manager" -W -p 389 -h server.example.com -b "cn=config" -s sub -x "(objectclass=*)"
- bindDN is the DN chosen for the Directory Manager when the server was installed (
cn=Directory Managerby default). - password is the password chosen for the Directory Manager.
To disable a plug-in, use
ldapmodify to edit the nsslapd-pluginEnabled attribute:
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x dn: cn=Telephone Syntax,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginEnabled nsslapd-pluginEnabled: off
2.2.2.2.2. Restrictions to Modifying Configuration Entries and Attributes
Certain restrictions apply when modifying server entries and attributes:
- The
cn=monitorentry and its child entries are read-only and cannot be modified, except to manage ACIs. - If an attribute is added to
cn=config, the server ignores it. - If an invalid value is entered for an attribute, the server ignores it.
- Because
ldapdeleteis used for deleting an entire entry, useldapmodifyto remove an attribute from an entry.
2.2.2.2.3. Configuration Changes Requiring Server Restart
Some configuration attributes cannot be altered while the server is running. In these cases, for the changes to take effect, the server needs to be shut down and restarted. The modifications should be made either through the Directory Server Console or by manually editing the
dse.ldif file. Some of the attributes that require a server restart for any changes to take effect are listed below. This list is not exhaustive; to see a complete list, run ldapsearch and search for the nsslapd-requiresrestart attribute. For example:
ldapsearch -D "cn=directory manager" -W -p 389 -h server.example.com -b "cn=config" -s sub -x "(objectclass=*)" | grep nsslapd-requiresrestart
| nsslapd-cachesize | nsslapd-certdir |
| nsslapd-dbcachesize | nsslapd-dbncache |
| nsslapd-plugin | nsslapd-changelogdir |
| nsslapd-changelogmaxage | nsslapd-changelogmaxentries |
| nsslapd-port | nsslapd-schemadir |
| nsslapd-saslpath | nsslapd-secureport |
| nsslapd-tmpdir | nsSSL2 |
| nsSSL3 | nsSSLclientauth |
| nsSSLSessionTimeout | nsslapd-conntablesize |
| nsslapd-lockdir | nsslapd-maxdescriptors |
| nsslapd-reservedescriptors | nsslapd-listenhost |
| nsslapd-schema-ignore-trailing-spaces | nsslapd-securelistenhost |
| nsslapd-workingdir | nsslapd-return-exact-case |
| nsslapd-maxbersize[a] | |
[a]
Although this attribute requires a restart, it is not returned in the search.
| |
2.2.2.2.4. Deleting Configuration Attributes
Core server configuration attributes cannot be deleted, by default. All core configuration attributes are present, even if they are not written in the
dse.ldif file, because they all have default values used by the server. Deleting any of those attributes is generally not allowed because the server requires that those attributes be present for it to run.
The
nsslapd-allowed-to-delete-attrs parameter lists core configuration attributes which are allowed to be deleted from the configuration. Delete operations for those attributes will succeed.
The value of
nsslapd-allowed-to-delete-attrs is a space-separated list of attribute names. By default, only two attributes are listed:
nsslapd-allowed-to-delete-attrs: nsslapd-listenhost nsslapd-securelistenhost
Warning
Be extremely cautious about adding core server configuration attributes to the list of deleteable attributes. Some attributes are critical for the server to operate, and deleting those attributes could cause the server not to run.
Where did the comment section go?
Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.