Chapter 2. File Locations Overview
Chapter 2. File Locations Overview Red Hat Directory Server is compatible with the Filesystem Hierarchy Standards (FHS). For further information on the FHS, see http://refspecs.linuxfoundation.org/fhs.shtml . 2.1. Directory Server Instance-independent Files and Directories The following are the Directory Server's instance-independent default file and directory locations: Type Location Command-line utilities /usr/bin/ /usr/sbin/ Systemd unit files /usr/lib/systemd/system/dirsrv.target /etc/systemd/system/dirsrv.target.wants/ 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 Systemd unit files /etc/systemd/system/dirsrv.target.wants/dirsrv@ instance_name .service 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: 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, 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(R) 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 . 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 . 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. 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 . Configuration of Databases The cn=UserRoot subtree under the database plug-in entry contain configuration data for the databases containing the default suffix created during setup. 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. Configuration of Indexes Configuration information for indexing is stored as entries in the Directory Server under the following information-tree nodes: 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. 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 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. 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 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: 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: 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. 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: 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 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. 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.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. 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 userRoot directory contents. Example 2.2. userroot Database Directory Contents The userroot subdirectory contains 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 - 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 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 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. 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 -2020_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.
cn=Telephone Syntax,cn=plugins,cn=config 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 dn: cn=Telephone Syntax,cn=plugins,cn=config objectclass: top objectclass: nsSlapdPlugin objectclass: extensibleObject cn: Telephone Syntax nsslapd-pluginType: syntax nsslapd-pluginEnabled: on aci: (targetattr = "*")(version 3.0; acl "Local Directory Administrators Group"; allow (all) groupdn = "ldap:///ou=Directory Administrators,dc=example,dc=com";) ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -b "cn=config" -s sub -x "(objectclass=*)" 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 ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -b "cn=config" -s sub -x "(objectclass=*)" | grep nsslapd-requiresrestart db.001 db.002 __db.003 DBVERSION log.0000000001 userroot/ ancestorid.db DBVERSION entryrdn.db id2entry.db nsuniqueid.db numsubordinates.db objectclass.db parentid.db European.ldif Example.ldif Example-roles.ldif Example-views.ldif exports/ imports/ server/ access access.20200228-171925 errors access.20200221-162824 access.rotationinfo errors.20200221-162824 access.20200223-171949 audit errors.rotationinfo access.20200227-171818 audit.rotationinfo slapd.stats