Sun Java System Directory Server Enterprise Edition 6.0 Reference

Directory Server Architecture

This section succinctly addresses key concepts of Directory Server from the point of view of someone who must install and manage Directory Server. This section touches on the following topics.

Comparison of Software Installation and Server Instances

For each installation of Directory Server software, you can create multiple server instances. Although you may create server instances in the place on the file system where you install the software, nothing requires you to put both the software and the instances side by side.

The Directory Server software you install includes the executable files, template data, and sample files needed to create, run, and manage actual servers. As the software is separate from the actual servers, you can apply patches or service packs to the software without changing the server data. You therefore do not need to patch each server instance, but instead only the software installation.

A Directory Server instance holds the configuration data and the directory data required to serve directory client applications. Although in production systems you carefully control the user identity of the server, you can typically create and run a Directory Server instance as any user on the system. The directory data belongs then to the user who created the instance.

In Chapter 15, Directory Server File Reference, you see that Software Layout for Directory Server is clearly separate from Directory Server Instance Default Layout. In particular, notice that the documentation mentions install-path when referring to the software installation, but instance-path when referring to a server instance.

Communication With Client Applications

Directory Server listens for LDAP and DSML client application traffic on the port numbers you configure. Directory Server listens for LDAP connections as soon as the server starts. Directory Server only listens for DSML connections over HTTP if you enable the DSML service.

By default, Directory Server listens for LDAP connections on port 389 if the instance was created by root, 1389 if the instance was created by non-root. By default, Directory Server listens for LDAP connections over SSL on port 636 if the instance was created by root, 1636 if the instance was created by non-root. The DSML/HTTP port number is not defined by default. Instead, you supply a port number when enabling the DSML service.

    In order to enable client applications to reach Directory Server, you create instances on hosts with static IP addresses. The hostname is also usually referenced in DNS. Client applications typically need at least two pieces of information to access the directory.

  1. The hostname, or at least the IP address, of the system on which Directory Server runs.

  2. The port number on which Directory Server listens for client connections.

LDAP clients and servers do not usually open a new connection for every request. In the LDAP model, a client connects to the server to authenticate before performing other operations. The connection and authentication process is referred to as binding. Client applications can bind with credentials, but they can also bind anonymously. Directory Server lets you configure access accordingly both for known and anonymous clients. Client applications can also keep a connection open, but bind again, thus changing the authentication identity. This technique can reduce the costs of creating a new connection.

Once the bind has been performed and the client is authenticated, the client can request the following operations.


Add a new directory entry.


Checks whether an attribute value is the same as a given value.


Delete a directory entry.


Change one or more attributes of a directory entry.


Change the distinguished name of a directory entry.

This operation is for moving directory entries from one part of the directory information tree to another. For example, you could move uid=bjensen,ou=employees,dc=example,dc=com to uid=bjensen,ou=people,dc=example,dc=com.

When you move an parent entry, such as ou=people,dc=example,dc=com, the operation can take a very long time as Directory Server must move all child entries of the parent as well.


Change the relative distinguished name of a directory entry.

The relative distinguished name is the attribute value used to distinguish a directory entry from the others at the same level of the directory information tree.

This operation is for renaming directory entries. For example, you could rename uid=bjensen,ou=employees,dc=example,dc=com to uid=bcubbins,ou=people,dc=example,dc=com.

This operation is a special case of modDN. The modRDN operation is always relatively fast, however, as it involves moving only leaf entries.


Find all the directory entries under a specified point in the directory tree that have attribute values matching a filter.

A search filter can specify one or more attribute characteristics. For example, to find entries with the surname Jensen, you use the LDAP filter (sn=Jensen). To find entries with surname Jensen and user ID beginning with the letter B, you use the LDAP filter (&(sn=Jensen)(uid=b*)).

When finished performing operations, a client can unbind. After unbinding, the connection is dropped by the client and the server. Client applications can also abandon operations, such as a search that is taking too long.

Directory Server can handle many client connections simultaneously. To handle connections, Directory Server consumes free file descriptors, and manages a number of threads. You can limit the system resources available to Directory Server through the server configuration. See Chapter 6, Tuning System Characteristics and Hardware Sizing, in Sun Java System Directory Server Enterprise Edition 6.0 Deployment Planning Guide for details.

Directory Server Configuration

Directory Server stores server instance configuration data in files, but the configuration data is also accessible over LDAP.

The files are stored under instance-path as follows. Directory Server stores the LDAP schema, which define what directory entries can contain, under instance-path/config/schema/. See Sun Java System Directory Server Enterprise Edition 6.0 Man Page Reference for reference information about the schema, and Chapter 11, Directory Server Schema, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide for instructions on managing schema. Directory Server stores other configuration information in the dse.ldif(4) file, instance-path/config/dse.ldif. Avoid updating this file by hand.

Over LDAP, the schema information is accessible under cn=schema. The other configuration information is accessible under cn=config. In practice, you do not generally update data under cn=config directly. Instead, you use either the web based Directory Service Control Center, or the dsconf command. Both Directory Service Control Center and the dsconf command change Directory Server over LDAP. Yet, both also spare you much of the complexity of making configuration adjustments with LDAP modify operations.

Almost all Directory Server product documentation is devoted to Directory Server configuration. In Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide, you find extensive instructions for accomplishing a variety of tasks using command line configuration tools. The Directory Service Control Center online help can help get you back on track when the Directory Service Control Center interface does not seem intuitive enough.

Data Storage in Directory Server

Directory Server manages at least one binary tree database to hold directory data. By default, database files are stored under instance-path/db/. In general, do not change or move these files.

If you examine the content of the instance-path/db/ directory, you find database log files. You also find subdirectories for each database managed by the server. For instance, instance-path/db/example/ holds data for the directory entries under dc=example,dc=com. When you examine the files, you find a number of database indexes, such as example_sn.db3 for surname attribute values. You also find a example_id2entry.db3 file containing directory entry information. You can configure Directory Server to encrypt the information in these files if necessary.

From the point of view of client applications, Directory Server presents the directory data stored as directory entries arranged in the directory information tree. Directory Server uses the attribute value indexes to retrieve entries quickly. You can configure which indexes Directory Server maintains.

For instructions on backing up directory data, see Chapter 8, Directory Server Backup and Restore, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide. For instructions on configuring indexes, see Chapter 12, Directory Server Indexing, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide. You can also back up directory data and configure indexes using Directory Service Control Center.

Data Replication Between Server Instances

Directory Server allows you to replicate directory data among as many server instances as necessary. Directory Server replication works as an LDAP extended operation that replays update operations from one server to another. The protocol for Directory Server replication is optimized to work quickly over the network. The protocol is also optimized to resolve conflicts when the same data is modified simultaneously on two different server instances.

The unit of Directory Server replication is the suffix. A replication agreement between two servers handles all the directory entries under a base entry in the directory information tree, such as dc=example,dc=com. Each agreement to replicate is set up point to point. On one hand, point to point agreements prevent replication from single points of failure when the network becomes partitioned. On the other hand, point to point agreements can be complex to manage as the number of replicas increases. Luckily, Directory Service Control Center handles much of the complexity for you. Directory Service Control Center allows you to manage groups of replicas that provide a common directory service.

You can configure timing, priority, and which data is replicated. You can also configure some servers, called masters, to accepts both updates and lookups. You can configure other servers, called consumers, to accept only lookups. In addition, you can publish update information over LDAP for client applications that must follow updates as they happen. For further explanation of replication, see Chapter 4, Directory Server Replication. For instructions on configuring replication, see Chapter 10, Directory Server Replication, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Access Control in Directory Server

Directory Server offers an access control mechanism that works through aci attributes placed on directories entries. ACI stands for Access Control Instruction.

ACIs are evaluated based on a user's bind identity. ACIs can be evaluated therefore for all users who can bind to the directory. ACIs can also be applied for anonymous users who did not provide bind credentials. Rules about the bind identity can specify not only which users, but also which systems the users connect from, what time of day they connect, or what authentication method they use.

You configure an ACI to apply to the entries in its scope. Entries that can be in scope include entries on the branch of the directory information tree starting with the entry holding the ACI. Directory Server allows you to configure ACIs to be applied according to a number of different criteria. Directory Server also lets you configure ACIs not only to allow access, but also to deny access.

ACIs can specify which operations are allowed and denied. For example, you typically allow many users to read information, but only a few to update and add directory data.

For further explanation of access control in Directory Server, see How Directory Server Provides Access Control. For instructions on configuring access control, see Chapter 6, Directory Server Access Control, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.