2.2. Directory Server Instance-specific Files and Directories

To separate multiple instances running on the same host, certain files and directories contain the name of the instance. You set the instance name during the Directory Server setup. By default, this is the host name without domain name. For example, if your fully-qualified domain name is server.example.com, the default instance name is server.

The following are the Directory Server's instance-specific default file and directory locations:

Type	Location
Backup files	`/var/lib/dirsrv/slapd-instance_name/bak/`
Configuration files	`/etc/dirsrv/slapd-instance_name/`
Certificate and key databases	`/etc/dirsrv/slapd-instance_name/`
Database files	`/var/lib/dirsrv/slapd-instance_name/db/`
LDIF files	`/var/lib/dirsrv/slapd-instance/ldif/`
Lock files	`/var/lock/dirsrv/slapd-instance_name/`
Log files	`/var/log/dirsrv/slapd-instance_name/`
PID file	`/var/run/dirsrv/instance_name.pid`
Instance-specific scripts ^[a]	`/usr/lib64/dirsrv/slapd-instance_name/`
Systemd unit files	`/etc/systemd/system/dirsrv.target.wants/dirsrv@instance_name.service`
^[a] Deprecated. For details, see Section 2.2.8, “Scripts”.

2.2.1. Configuration Files

Each Directory Server instance stores its configuration files in the /etc/dirsrv/slapd-instance 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.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.1. LDIF and Schema Configuration Files

The Directory Server configuration data are stored in LDIF files in the /etc/dirsrv/slapd-instance directory. Thus, if a server identifier is phonebook, then for a Directory Server on Red Hat Enterprise Linux 7, 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.1. Directory Server LDIF Configuration Files

Configuration Filename	Purpose
dse.ldif	Contains front-end Directory Specific Entries created by the directory at server startup. These include the Root DSE (`""`) and the contents of `cn=config` and `cn=monitor` (acis only).
00core.ldif	Contains only those schema definitions necessary for starting the server with the bare minimum feature set (no user schema, no schema for any non-core features). The rest of the schema used by users, features, and applications is found in `01common.ldif` and the other schema files. Do not modify this file.
01common.ldif	Contains LDAPv3 standard operational schema, such as `subschemaSubentry`, LDAPv3 standard user and organization schema defined in RFC 2256 (based on X.520/X.521), `inetOrgPerson` and other widely-used attributes, and the operational attributes used by Directory Server configuration. Modifying this file causes interoperability problems. User-defined attributes should be added through the Directory Server Console.
05rfc2247.ldif	Schema from RFC 2247 and related pilot schema, from "Using Domains in LDAP/X500 Distinguished Names."
05rfc2927.ldif	Schema from RFC 2927, "MIME Directory Profile for LDAP Schema." Contains the `ldapSchemas` operational attribute required for the attribute to show up in the `subschema` subentry.
10presence.ldif	Legacy. Schema for instant messaging presence (online) information; the file lists the default object classes with the allowed attributes that must be added to a user's entry in order for instant-messaging presence information to be available for that user.
10rfc2307.ldif	Schema from RFC 2307, "An Approach for Using LDAP as a Network Information Service." This may be superseded by `10rfc2307bis`, the new version of `rfc2307`, when that schema becomes available.
20subscriber.ldif	Contains new schema elements and the Nortel subscriber interoperability specification. Also contains the `adminRole` and `memberOf` attributes and `inetAdmin` object class, previously stored in the `50ns-delegated-admin.ldif` file.
25java-object.ldif	Schema from RFC 2713, "Schema for Representing Java® Objects in an LDAP Directory."
28pilot.ldif	Contains pilot directory schema from RFC 1274, which is no longer recommended for new deployments. Future RFCs which succeed RFC 1274 may deprecate some or all of `28pilot.ldif` attribute types and classes.
30ns-common.ldif	Schema that contains objects classes and attributes common to the Directory Server Console framework.
50ns-admin.ldif	Schema used by Red Hat Administration Server.
50ns-certificate.ldif	Schema for Red Hat Certificate Management System.
50ns-directory.ldif	Contains additional configuration schema used by Directory Server 4.12 and earlier versions of the directory, which is no longer applicable to current releases of Directory Server. This schema is required for replicating between Directory Server 4.12 and current releases.
50ns-mail.ldif	Schema used by Netscape Messaging Server to define mail users and mail groups.
50ns-value.ldif	Schema for servers' value item attributes.
50ns-web.ldif	Schema for Netscape Web Server.
60pam-plugin.ldif	Reserved for future use.
99user.ldif	User-defined schema maintained by Directory Server replication consumers which contains the attributes and object classes from the suppliers.

2.2.1.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.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: dirsrv
...

2.2.1.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.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.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 Red Hat Directory Server Administration 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.1.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.1.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 admin account 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 Red Hat Directory Server Administration Guide.

2.2.1.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.1.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.1.2.2.1. Modifying Configuration Entries Using LDAP

The configuration entries in the directory can be searched and modified using LDAP either using 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 Red Hat Directory Server Administration Guide. However, certain changes do require the server to be restarted before they are taken into account. See Section 2.2.1.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 Manager by 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.1.2.2.2. Restrictions to Modifying Configuration Entries and Attributes

Certain restrictions apply when modifying server entries and attributes:

The cn=monitor entry 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 ldapdelete is used for deleting an entire entry, use ldapmodify to remove an attribute from an entry.

2.2.1.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.1.2.2.4. Deleting Configuration Attributes

All core configuration attributes are present, even if they are not written in the /etc/dirsrv/slapd-instance-name/dse.ldif file, because they all have default values used by the server.

For details about deleting core configuration attributes and a list of attributes that cannot be deleted, see the corresponding section in the Red Hat Directory Server Administration Guide.

2.2.2. Database Files

Each Directory Server instance contains the /var/lib/dirsrv/slapd-instance/db directory for storing all of the database files. The following is a sample listing of the /var/lib/dirsrv/slapd-instance/db directory contents.

Example 2.1. Database Directory Contents

__db.001  __db.003  __db.005   NetscapeRoot/
__db.002  __db.004  DBVERSION  log.0000000007  userRoot/

db.00x files — Used internally by the database and should not be moved, deleted, or modified in any way.
log.xxxxxxxxxx files — Used to store the transaction logs per database.
DBVERSION — Used for storing the version of the database.
NetscapeRoot — Stores the o=NetscapeRoot database created by default when the setup-ds-admin.pl script is run.
userRoot — Stores the user-defined suffix (user-defined databases) created at setup; for example, dc=example,dc=com.

Note

If a new database is created (for example, testRoot) to store the directory tree under a new suffix, the directory named testRoot also appears in the /var/lib/dirsrv/slapd-instance/db directory.

The following is a sample listing of the NetscapeRoot directory contents.

Example 2.2. NetscapeRoot Database Directory Contents

./		entrydn.db*		parentid.db*
../		givenName.db*		sn.db*
DBVERSION*	id2entry.db*		uid.db*
aci.db*	nsUniqueId.db*		uniquemember.db*
ancestorid.db*	numsubordinates.db*
cn.db*		objectclass.db*

The NetscapeRoot subdirectories contain an index_name.db file for every index currently defined in the database. In addition to these files, the NetscapeRoot and userRoot subdirectories contain the following files:

ancestorid.db — Contains a list of IDs to find the ID of the entry's ancestor.
entrydn.db — Contains a list of full DNs to find any ID.
id2entry.db — Contains the actual directory database entries. All other database files can be recreated from this one, if necessary.
nsuniqueid.db — Contains a list of unique IDs to find any ID.
numsubordinates.db — Contains IDs that have child entries.
objectclass.db — Contains a list of IDs which have a particular object class.
parentid.db — Contains a list of IDs to find the ID of the parent.

2.2.3. LDIF Files

Sample LDIF files are stored in the /var/lib/dirsrv/slapd-instance/ldif directory for storing LDIF-related files. Example 2.3, “LDIF Directory Contents” lists the /ldif directory contents.

Example 2.3. LDIF Directory Contents

European.ldif 
Example.ldif 
Example-roles.ldif
Example-views.ldif

European.ldif — Contains European character samples.
Example.ldif — Is a sample LDIF file.
Example-roles.ldif — Is a sample LDIF file similar to Example.ldif, except that it uses roles and class of service instead of groups for setting access control and resource limits for directory administrators.

Note

The LDIF files exported by db2ldif or db2ldif.pl scripts in the instance directory are stored in /var/lib/dirsrv/slapd-instance/ldif.

2.2.4. Lock Files

Each Directory Server instance contains a /var/lock/dirsrv/slapd-instance directory for storing lock-related files. The following is a sample listing of the locks directory contents.

Example 2.4. Lock Directory Contents

exports/ imports/ server/

The lock mechanisms control how many copies of the Directory Server process can be running at one. For example, if there is an import job, then a lock is placed in the imports/ directory to prevent any other ns-slapd (normal), ldif2db (another import), or db2ldif (export) operations from running. If the server is running as normal, there is a lock in the server/ directory, which prevents import operations (but not export operations), while if there is an export operation, the lock in the exports/ directory allows normal server operations but prevents import operations.

The number of available locks can affect overall Directory Server performance. The number of locks is set in the nsslapd-db-locks attribute. Tuning that attribute value is described in the Performance Tuning Guide.

2.2.5. Log Files

Each Directory Server instance contains a /var/log/dirsrv/slapd-instance directory for storing log files. The following is a sample listing of the /logs directory contents.

Example 2.5. Log Directory Contents

access                  access.20190228-171925  errors
access.20190221-162824  access.rotationinfo     errors.20190221-162824
access.20190223-171949  audit                   errors.rotationinfo
access.20190227-171818  audit.rotationinfo	slapd.stats

The content of the access, audit, and error log files is dependent on the log configuration.
The slapd.stats file is a memory-mapped file which cannot be read by an editor. It contains data collected by the Directory Server SNMP data collection component. This data is read by the SNMP subagent in response to SNMP attribute queries and is communicated to the SNMP master agent responsible for handling Directory Server SNMP requests.

Chapter 7, Log File Reference contains a solid overview of the access, error, and audit log file formats and the information in them.

2.2.6. PID Files

slapd-serverID.pid and slapd-serverID.startpid files are created in the /var/run/dirsrv directory when the server is up and running. Both files store the server's process ID.

2.2.7. Tools

Directory Server tools are stored in these directories on Red Hat Enterprise Linux 7:

/usr/bin
/usr/sbin

The contents of those directories are listed below. Chapter 9, Command-Line Utilities has more information on command-line scripts.

Example 2.6. /bin Contents

dbscan       ldif
dbscan-bin   ldif-bin

Example 2.7. /sbin Contents

ds_removal      migrate-ds-admin.pl   remove-ds.pl         setup-ds-admin.pl
ds_unregister   register-ds-admin.pl  remove-ds-admin.pl   setup-ds.pl

2.2.8. Scripts

On Red Hat Enterprise Linux 7.3 and later, the command-line scripts Directory Server uses are stored in the /usr/sbin/ directory. Use the -Z instance_name option with the commands in order to set the instance the script should be executed on.

Note

The /usr/lib64/dirsrv/slapd-instance/ directory previously used for command-line scripts is deprecated. However, until the instance-specific scripts are removed in a future Directory Server release, existing scripts in this directory are updated when running the setup-ds.pl --update command.

For further details and a list of scripts, see Chapter 10, Command-Line Scripts.

2.2.9. Backup Files

Each Directory Server instance contains the following directory and file for storing backup-related files:

/var/lib/dirsrv/slapd-instance/bak — This contains a directory dated with the instance, time and date of the database backup, such as instance-2019_05_02_16_56_05/, which in turn holds the database backup copy.
/etc/dirsrv/slapd-instance/dse_original.ldif — This is a backup copy of the dse.ldif configuration file from the time of installation.

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.