Sun ONE logo     Previous      Contents      Index      Next     
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:

cn=Telephone Syntax,cn=plugins,cn=config

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

DIT showing all the configuration entries below cn=config

This overview is divided into the following sections:

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:

ServerRoot/slapd-serverID/config

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:

ServerRoot/slapd-serverID/config/schema

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.

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 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

dn: cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsslapdConfig
nsslapd-accesslog-logging-enabled: on
nsslapd-enquote-sup-oc: on
nsslapd-localhost: myServer.example.com
nsslapd-errorlog: ServerRoot/slapd-myServer/logs/errors
nsslapd-schemacheck: on
nsslapd-port: 389
nsslapd-localuser: nobody
...

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
objectclass: top
objectclass: nsSlapdPlugin
objectclass: ds-signedPlugin
objectclass: extensibleObject
cn: Telephone Syntax
nsslapd-pluginPath: ServerRoot/lib/syntax-plug-in.so
nsslapd-pluginInitfunc: tel_init
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. 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";
 allow (all)
 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";
 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-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.



Note

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".



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 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
changetype: modify
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: off

Restrictions to Modifying Configuration Entries

Certain restrictions apply when modifying server entries:

  • The dse.ldif cn=monitor entry and its child entries are read-only and cannot be modified.

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.


Previous      Contents      Index      Next     
Copyright 2003 Sun Microsystems, Inc. All rights reserved.