|Sun ONE Directory Server 5.2 Reference Manual|
Chapter 3 Core Server Configuration
The configuration information for Sun ONE Directory Server 5.2 is stored as LDAP entries within the directory itself. Therefore, changes to the server configuration must be implemented through the use of the server 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 via LDAP while it is still running, and avoids having to shut it down.
This chapter provides details of how the configuration is organized, and how to alter it. An alphabetical reference for all attributes is provided in Chapter 4 "Core Server Configuration Attributes.
This chapter is divided into the following sections:
Server Configuration Overview
When you install the Sun ONE Directory Server 5.2, 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 in LDIF format: dse.ldif. This dse.ldif file contains all of the server configuration information. It is worth noting that 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 Sun ONE Directory Server 5.2 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 the entry:
Similarly, database-specific configuration is stored under:
cn=ldbm database,cn=plugins,cn=config and cn=chaining database,cn=plugins,cn=config
Figure 3-1 shows how the configuration data fits within the cn=config Directory Information Tree.
Figure 3-1    Configuration Data Under cn=config
This overview is divided into the following sections:
- LDIF Configuration Files - Location
- Schema Configuration Files - Location
- How the Server Configuration is Organized
- Migration of Pre-Directory Server 5.x Configuration Files to LDIF Format
LDIF Configuration Files - Location
The Directory Server configuration data is automatically output to files in LDIF format that are located in the following directory by default:
In this chapter, all examples use myServer for the server identifier where appropriate.
Schema Configuration Files - Location
Schema configuration is also stored in LDIF format and these files are located in the following directory:
For a full list of the LDIF configuration files that are supplied with Directory Server, see Table 4-7.
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, and directory specific entries related to the database, also created by the directory at server startup. The file includes the Root DSE (named by "") and the entire contents of cn=config.When the server generates the dse.ldif file, it lists the entries in hierarchical order. It does so in the order that the entries appear in the directory under cn=config.
This section provides an overview of configuration attributes, plug-in functionality configuration, database configuration, and index configuration.
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 example shows part of the dse.ldif file for a Directory Server and indicates, amongst other things, that schema checking has been turned on. This is represented by the attribute nsslapd-schemacheck, which takes the value on.
Code Example 3-1    Extract of dse.ldif File
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 example shows the configuration entry for a plug-in, in this case the Telephone Syntax plug-in.
Code Example 3-2    Configuration Entry for Telephone Syntax Plug-in
dn: cn=Telephone Syntax,cn=plugins,cn=config
cn: Telephone Syntax
Some of these attributes are common to all plug-ins and some may be particular to a specific plug-in. You can check which attributes are currently being used by a plug-in by performing an ldapsearch on the cn=config subtree.
For a list of plug-ins supported by Sun ONE Directory Server 5.2, general plug-in configuration information, the plug-in configuration attribute reference, and a list of plug-ins requiring the server to be restarted see Chapter 5 "Plug-In Implemented Server Functionality."
Configuration of Databases
The cn=NetscapeRoot and cn=UserRoot subtrees contain configuration data for the databases containing the o=NetscapeRoot and o=UserRoot suffixes respectively. The cn=NetscapeRoot subtree contains the configuration data used by the Sun ONE Administration Server for authentication and all actions that cannot be performed through LDAP (such as start/stop). The cn=UserRoot subtree contains all the configuration data for the first user-defined database created during server installation. The cn=UserRoot subtree is called UserRoot by default. However, this is not hard-coded, and, given the fact that there will be multiple database instances, this name will be changed and defined by the user when new databases are added.
Configuration of Indexes
Configuration information for indexing is stored as entries in the Directory Server under the three following information tree nodes:
- cn=index,cn=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 regarding indexes in general, see the Sun ONE Directory Server Administration Guide and for information regarding the index configuration attributes, see "Default Index Attributes" on page 238. The attributes are presented here because this node is the first to appear in the representation of the configuration attributes based on the cn=config information tree.
Migration of Pre-Directory Server 5.x Configuration Files to LDIF Format
Sun ONE Directory Server 5.2 recognizes configuration files that are in LDIF format only, which means that the slapd.conf and slapd.ldbm.conf configuration files from 4.x versions of Directory Server must be converted to LDIF format. Directory Server 4.x configurations can be migrated to the new LDIF format using the migrateInstance5 tool. For information on the attributes that are migrated with this tool, see Chapter 6 "Migration From Earlier Versions."
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 on the types of modification that can be made and discusses attributes that require the server to be restarted for changes to take effect. This section has been divided into the following parts:
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. Code Example 3-3 shows an example of these default ACIs.
Code Example 3-3    Default ACIs in dse.ldif
aci: (targetattr = "*")(version 3.0; acl "Configuration Adminstrators Group";
groupdn = "ldap:///cn=Configuration Administrators,ou=Groups, ou=TopologyManagement, o=NetscapeRoot";)
aci: (targetattr = "*")(version 3.0; acl "Configuration Adminstrators";
allow (all) userdn = "ldap:///uid=admin,ou=Administrators,ou=TopologyManagement,o=NetscapeRoot";)
aci: (targetattr = "*")(version 3.0; acl "Local Directory Adminstrators Group";
groupdn = "ldap:///ou=Directory Administrators, dc=example,dc=com";)
aci: (targetattr = "*")(version 3.0; acl "SIE Group"; allow(all) groupdn = "ldap:///cn=slapd-myServer, cn=Netscape Directory Server, cn=Server Group, cn=myServer.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, who has the uid admin that can be configured at installation time
- Members of the local Directory Administrators Group
- The local Directory Administrator (root DN)
- The SIE (Server Instance Entry) Group that is usually assigned using the Set Access Permissions from the main topology view in the main console.
For more information see Chapter 6, "Managing Access Control" in the Sun ONE Directory Server Administration Guide.
Changing Configuration Attributes
You can view and change server attribute values in one of three ways: by using LDAP through Sun ONE Server Console, by performing ldapsearch and ldapmodify commands, or by manually editing the dse.ldif file.
If you edit the dse.ldif file, you must stop the server beforehand, otherwise your changes will be lost. Editing the dse.ldif file is recommended only for changes to attributes which cannot be altered dynamically. For further information, see "Configuration Changes Requiring Server Restart".
The following sections describe how to modify entries using LDAP (both via the Sun ONE Server Console and over the command line), the restrictions to modifying entries, the restrictions 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 via the Sun ONE 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 that you can make the changes while the server is running. You must remember to specify the port number when modifying configuration entries as the server is not necessarily running on port 389. For further information see Chapter 2, "Creating Directory Entries" in the Sun ONE Directory Server Administration Guide. However, certain changes do require the server to be restarted before they are taken into account. For further information, see "Configuration Changes Requiring Server Restart".
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 Sun ONE 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 bindDN -w password -p port -b cn=config objectclass=*
where bindDN is the DN chosen for the Directory Manager when the server was installed and password is the password chosen for Directory Manager. For more information on using ldapsearch see Chapter 1 "Command-Line Utilities."
Previously we saw an example of the configuration entry for the Telephone Syntax plug-in where the plug-in was enabled. If you want to disable this feature you can use the following series of commands to implement this change.
Code Example 3-4    Disabling the Telephone Syntax Plug-in
ldapmodify -D bindDN -w password -p port
dn: cn=Telephone Syntax,cn=plugins,cn=config
Restrictions to Modifying Configuration Entries
Certain restrictions apply when modifying server entries:
Restrictions to Modifying Configuration Attributes
Certain restrictions apply when modifying server attributes:
- If an attribute is added to cn=config, the server will ignore it.
- If an invalid value is entered for an attribute, the server will ignore it.
- Since ldapdelete is used for deleting entire entries, you should use ldapmodify if you want to remove an attribute from an entry.
Configuration Changes Requiring Server Restart
Some configuration attributes cannot be altered dynamically while the server is running. In these cases the server needs to be shut down and restarted for the changes to take effect. The modifications should be made either through the Directory Server console or by manually editing the dse.ldif file. Table 4-8 under Configuration Quick Reference Tables in the following chapter contains a list of these attributes.