test

Sun Java System Directory Server Enterprise Edition 6.0 Reference

Part I Directory Server Reference

This part explains how Directory Server works. The information here is primarily descriptive. For instructions, try Part I, Directory Server Administration, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide instead.

This part covers the following chapters.

For additional reference information, see Sun Java System Directory Server Enterprise Edition 6.0 Man Page Reference.

Chapter 1 Directory Server Overview

This chapter outlines the architecture of Directory Server. This chapter includes the following topics.

Introduction to Directory Server

Directory Server serves directory data to standards compliant LDAP and DSML applications. Directory Server stores the data in customized, binary tree databases, allowing quick searches even for large data sets.

Directories are object oriented databases. Directories organize their data objects, called entries, into a directory information tree, often called a DIT. Each entry is identified by a distinguished name, such as uid=bjensen,ou=people,dc=example,dc=com. The distinguished name identifies where the entry is located in the directory information tree. For example, uid=bjensen,ou=people,dc=example,dc=com is a user entry for Barbara Jensen on the ou=people branch of the dc=example,dc=com part of the tree.

Each directory entry has attributes. For entries that concern people, these attributes may reflect names, phone numbers, and email addresses, for example. An attribute has at least one type name, which is the name of the attribute. For example, people entries can have an attribute surname, which can also be called by the shorter name sn. Attributes can also have one or more values. For example, if Barbara Jensen marries Quentin Cubbins, and takes Quentin's surname, her entry could have sn: Jensen and sn: Cubbins.

Directories are designed to be fast when looking up entries based on the values of their attributes. An example query might be, “Find all the entries under dc=example,dc=com with surname Jensen.” This fast lookup capability makes directories well suited for applications where you store information that must be read often. Directories are therefore good data stores for telephone and email information. Directories are also good for handling authentication credentials, identity information, and application configuration data.

Directory Server is also designed to handle high update rates as the information in the directory changes. Today, the size of many directory deployments mean that handling updates well can be as important as handling lookups.

Directory Server supports many directory related standards and RFCs. Directory Server allows fast data replication across the network for high availability. Directory Server lets you configure servers comprehensively without restarting them. Furthermore, Directory Server gives you extensive control over access to directory data.

The list of Directory Server features is too long to cover in a short introduction. Sun Java System Directory Server Enterprise Edition 6.0 Evaluation Guide includes a more extensive list. The other chapters in this part of this Reference help you to understand many of the features in detail.

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

Add a new directory entry.

compare

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

delete

Delete a directory entry.

modify

Change one or more attributes of a directory entry.

modDN

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.

modRDN

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.

search

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.

Chapter 2 Directory Server Security

For information about the security in Directory Server, see the following sections:

How Directory Server Provides Security

Directory Server provides security through a combination of the following methods:

How Directory Server Provides Access Control

Directory Server uses access control instructions (ACIs) to define what rights to grant or deny to requests from LDAP clients. When a directory server receives a request, it uses the ACIs defined in the server, and any authentication information provided by the user to allow or deny access to directory information. The server can allow or deny permissions such as read, write, search, or compare.

For information about ACIs in Directory Server, see the following sections:

Introduction to ACIs

ACIs are stored in the aci operational attribute. The aci attribute is available for use on every entry in the directory, regardless of whether the aci attribute is defined for the object class of the entry. The aci attribute is multi-valued, therefore multiple ACIs can be defined for the same portion of a directory.

ACIs can be used to control access to the following portions of a directory:

ACIs can be used to define access for the following users:

Scope and Hierarchy in ACIs

ACIs can be created at any node in a directory tree, including the root DSE.

The scope of an ACI can be the target entry, the target entry and its immediate children, or the target entry and all of its children. When no scope is specified, the ACI applies to the target entry and all of its children.

When a server evaluates access permissions to an entry, it verifies the ACIs for the entry and the ACIs for the parent entries back up to the base of the entry’s root suffix. ACIs are not evaluated across chained suffixes on other servers.

Access to an entry in a server must be explicitly granted by an ACI. By default, ACIs define anonymous read access and allow users to modify their own entries, except for attributes needed for security. If no ACI applies to an entry, access is denied to all users except the Directory Manager.

Access granted by an ACI is allowed unless any other ACI in the hierarchy denies it. ACIs that deny access, no matter where they appear in the hierarchy, take precedence over ACIs that allow access to the same resource.

The Directory Manager is the only privileged user to whom access control does not apply. When a client is bound to the directory as the Directory Manager, the server does not evaluate any ACIs before performing operations.

In previous versions of Directory Server, ACIs could not be added or deleted directly under the root DSE. This limitation has been removed in Directory Server 6.0.

ACI Limitations

The following restrictions apply to ACIs

Default ACIs

The following default ACIs are defined on the root DSE:

ACIs and Replication

ACIs are stored as attributes of entries. Therefore, if an entry that contains ACIs is part of a replicated suffix, the ACIs are replicated like any other attribute.

ACIs are always evaluated locally, on the directory server that services the incoming LDAP requests.

When a consumer server receives an update request, the consumer server returns a referral to the master server for evaluation of whether the request can be serviced on the master.

Effective Rights

The effective rights feature can be used to obtain the following information:

To use the effective rights feature, you must have the access control rights to use the effective rights control and read access to the aclRights attribute.

If a proxy control is attached to an effective rights control-based search operation, the effective rights operation is authorized as the proxy user. Therefore the proxy user needs to have the right to use the effective rights control. The entries that the proxy user has the right to search and view are returned.

ACI Syntax

The aci attribute has the following syntax:

aci: (target)(version 3.0; acl "name";permission bindRules;)

The following values are used in the ACI syntax:

target

Specifies the entry, attributes, or set of entries and attributes for which you want to control access. The target can be a distinguished name, one or more attributes, or a single LDAP filter. The target is optional. When a target is not specified, the ACI applies to the entry on which it is defined and its subtree. For information about targets, see ACI Targets.

version 3.0

A required string that identifies the ACI version.

name

A required string that identifies the ACI. Although there are no restrictions on the name, it is good practice to use unique, descriptive names for ACIs. Using unique names, will allow you to use Get Effective Rights to determine which ACI is in force.

permission

States what rights you are allowing or denying. For information about permissions, see ACI Permissions.

bindRules

Specifies the credentials and bind parameters that a user has to provide to be granted access. Bind rules can also be based on user membership, group membership, or connection properties of the client. For information about bind rules, see ACI Bind Rules.

The permission and bind rule portions of the ACI are set as a pair, also called an Access Control Rule (ACR). The specified permission to access the target is granted or denied depending on whether the accompanying bind rule is evaluated to be true or false.

Multiple targets and multiple permission-bind rule pairs can be used. This allows you to refine both the entry and attributes being targeted and efficiently set multiple access controls for a given target. The following example shows an ACI with multiple targets and multiple permission-bind rule pairs:

aci: (targetdefinition)...(targetdefinition)(version 3.0;acl "name"; 
permission bindRule; ...; permission bindRule;)

In the following example, the ACI states that bjensen has rights to modify all attributes in her own directory entry:

aci: (target="ldap:///uid=bjensen,dc=example,dc=com"
  (targetattr="*")(targetScope="subtree")(version 3.0; acl "example";
   allow (write) userdn="ldap:///self";)

The following sections describe the syntax of targets, permissions and bind rules.

ACI Targets

An ACI target statement specifies the entry, attributes, or set of entries and attributes for which you want to control access.

Target Syntax

An ACI target statement has this syntax:

(keyword = "expression")

The following values are used in the target.

keyword

Indicates the type of target.

expression

Identifies the target. The quotation marks ("") around expression are syntactically required, although the current implementation accepts expressions like targetattr=*.

=
!=

Indicates that the target is or is not the object specified in the expression.

The != operator cannot be used with the targettrfilters keyword or the targetscope keyword.

Target Keywords

For a description of target keywords, see the following sections:

The following table lists the target keywords and their associated expressions.

Table 2–1 Target Keywords and Their Expressions

Keyword 

Type of target 

Expression 

target

A directory entry or its subtree 

ldap:///distinguished_name

targetattr

The attributes of an entry 

attribute

targetfilter

A set of entries or attributes that match an LDAP filter 

LDAP_filter

targetattrfilters

An attribute value or combination of values that match an LDAP filter 

LDAP_operation:LDAP_filter

targetScope

The scope of the target 

base, onelevel, subtree

target Keyword

The target keyword specifies that an ACI is defined for a directory entry. The target keyword uses the following syntax: 

(target = "distinguished_name")

or

(target != "distinguished_name")

The distinguished name must be in the subtree rooted at the entry where the ACI is defined. For example, the following target may be used in an ACI on ou=People,dc=example,dc=com: 


(target = "ldap:///uid=bjensen,ou=People,dc=example,dc=com")

The DN of the entry must be a distinguished name in string representation (RFC 4514). Therefore, characters that are syntactically significant for a DN, such as commas, must be escaped with a single backslash (\).

Wild cards, show as asterisk characters can be used in the expression for the target keyword. The asterisk matches an attribute value, a substring of a value, or a DN component. For example, all of the following expressions match uid=bjensen,ou=people,dc=example,dc=com.

The following further examples show permitted uses of wild cards.

Other usage of wild cards to such as target="ldap:///uid=bjensen,o*,dc=com" might be accepted, but are deprecated.

targetattr Keyword

The targetattr keyword specifies that an ACI is defined for one or more attributes in the targeted entries. The targetattr keyword uses the following syntax: 


(targetattr = "attribute")

or


(targetattr != "attribute")

If no targetattr keyword is present, no attributes are targeted. To target all attributes, the targetattr keyword must be targetattr="*".

Targeted attributes do not need to exist on the target entry or its subtree, but the ACI applies whenever they do.

Targeted attributes do not need to be defined in the schema. The absence of schema checking makes it possible to implement an access control policy before importing data and its schema.

The targetattr keyword can be used for multiple attributes, by using this syntax:


(targetattr = "attribute1 || attribute2|| ... attributeN")

Targeted attributes include all subtypes of the named attribute. For example, (targetattr = "locality") also targets locality;lang-fr.

Wild cards can be used in the expression for the targetattr keyword, but the use of wild cards would serve no purpose and may reduce performance.

targetfilter Keyword

The targetfilter keyword is used in ACIs to target entries that match an LDAP filter. The ACI applies to all entries that match the LDAP filter and that are in the scope of the ACI. The targetfilter keyword uses the following syntax: 


(targetfilter = "(standard LDAP search filter)")
Example 2–1 Using the targetfilter Keyword to Target Specific Entries

The following example is for employees with a status of salaried or contractor, and an attribute for the number of hours worked as a percentage of a full-time position. The filter targets entries for contractors or part-time employees:


(targetfilter = "(|(status=contractor)(fulltime<=79))")

The Netscape extended filter syntax is not supported in ACIs. For example, the following target filter is not valid:


(targetfilter = "(locality:fr:=<= Québec)")

The filter syntax that describes matching rules for internationalized values is supported. For example, the following target filter is valid:


(targetfilter = "(locality:2.16.840.1.113730.3.3.2.18.1.4:=Québec)")

The targetfilter keyword selects whole entries as targets of the ACI. The targetfilter keyword and the targetattr keyword can be used together to create ACIs that apply to a subset of attributes in the targeted entries.

targetattrfilters Keyword

The targetattrfilters keyword is used in ACIs to target specific attribute values by using LDAP filters. By using the targetattrfilters keyword, you can grant or deny permissions on an attribute if that attribute's value meets the criteria defined in the ACI. An ACI that grants or denies access based on an attribute's value, is called a value-based ACI. The targetattrfilters keyword uses this syntax:


(targettrfilters="Op=attr1:F1 [(&& attr2:F2)*][;Op=attr:F [(&& attr:F)*]")

The targetattrfilters keyword can have the following values:

Op

An add or delete operation

add

To create an attribute

delete

To delete an attribute

attr

The target attributes

F

Filters that apply to the associated attribute

The following conditions must be met when filters apply to entries, and those entries are created, deleted or modified:

Example 2–2 Using the targetattrfilters Keyword to Allow Users to Add Roles to Their Own Entries

The following ACI allows users to add any role to their own entry, except the superAdmin role. It also allows users to add a telephone number with a 123 prefix.

(targettrfilters="add=nsroleDN:(!(nsRoleDN=cn=superAdmin))
 && telephoneNumber:(telephoneNumber=123*)")
Example 2–3 Using the targetattrfilters Keyword to Allow Group Members to Modify Specific Attributes

The following example allows members of the Engineering Admins group to modify the departmentNumber and manager attributes of all entries in the Engineering business category. This example filters entries with the businessCategory attributes set to Engineering: 


dn: dc=example,dc=com
objectClass: top
objectClass: organization
aci: (targetattr="departmentNumber || manager")
  (targetfilter="(businessCategory=Engineering)")
  (version 3.0; acl "eng-admins-write"; allow (write)
  groupdn ="ldap:///cn=Engineering Admins, dc=example,dc=com";)

targetScope Keyword

The targetScope keyword is used in ACIs to specify the scope of the ACI. The targetScope keyword uses this syntax:

(targetScope="base")

The targetScope keyword can have one of these values:

base

The ACI applies to the target resource only

onelevel

The ACI applies to the target resource and its first-generation children

subtree

The ACI applies to the target resource and its subtree

If the targetScope keyword is not specified, the default value is subtree.

ACI Permissions

Permissions specify the type of access that is allowed or denied by the ACI. For information about bind rules, see the following sections:

Permission Syntax

An ACI permission statement has this syntax:

allow|deny (right1, right2 ...)

Rights define the operations you can perform on directory data. In an ACI statement, rights is a list of comma-separated keywords enclosed within parentheses.

Rights are granted independently of one another. This means, for example, that a user who is granted add rights but not delete rights can create an entry but cannot delete an entry. When you are planning the access control policy for your directory, ensure that you grant rights in a way that makes sense for users. For example, it might not make sense to grant write permission without granting read and search permissions.

Permission Rights

The following rights can be allowed or denied in an ACI permission statement:

Read

Permission to read directory data. This permission applies only to the search operation.

Write

Permission to modify an entry by adding, modifying, or deleting attributes. This permission applies to the modify and modify DN operations.

Add

Permission to create entries. This permission applies only to the add operation

Delete

Permission to delete entries. This permission applies only to the delete operation.

Search

Permission to search for directory data. Users must have Search and Read rights in order to view the data returned as part of a search result. This permission applies only to the search operation.

Compare

Permission for users to compare data they supply with data stored in the directory. With compare rights, the directory returns a success or failure message in response to an inquiry, but the user cannot see the value of the entry or attribute. This permission applies only to the compare operation.

Selfwrite

Permission for users to add or delete their own DN in an attribute of the target entry. The syntax of this attribute must be distinguished name. This right is used only for group management. The Selfwrite permission works with proxy authorization; it grants the right to add or delete the proxy DN from the group entry (not the DN of the bound user).

Proxy

Permission for the specified DN to access the target with the rights of another entry. You can grant proxy access using the DN of any user in the directory except the Directory Manager DN. You cannot grant proxy rights to the Directory Manager.

Import

Permission for an entry to be imported to the specified DN. This permission applies the modify DN operation.

Export

Permission for an entry to be exported from the specified DN. This permission applies the modify DN operation.

All

Permission for the specified DN to have the following rights for the targeted entry: read, write, search, delete, compare, and selfwrite. The All access right does control permission for the following rights to the target entry: proxy, import, and export.

Permissions for Typical LDAP Operations

This section describes the rights required to perform a set of LDAP operations.

Adding an entry:

  • Grant add permission on the entry being added.

  • Grant write permission on the value of each attribute in the entry. This right is granted by default but could be restricted using the targettrfilters keyword.

Deleting an entry:

  • Grant delete permission on the entry to be deleted.

  • Grant write permission on the value of each attribute in the entry. This right is granted by default but could be restricted using the targettrfilters keyword.

Modifying an attribute in an entry:

  • Grant write permission on the attribute type.

  • Grant write permission on the value of each attribute type. This right is granted by default but could be restricted using the targettrfilters keyword.

Modifying the RDN of an entry:

  • Grant write permission on the entry.

  • Grant write permission on the attribute type used in the new RDN.

  • Grant write permission on the attribute type used in the old RDN, if you want to grant the right to delete the old RDN.

  • Grant write permission on the value of attribute type used in the new RDN. This right is granted by default but could be restricted using the targettrfilters keyword.

Moving an entry to another subtree:

  • Grant export permissions on the entry that you want to move.

  • Grant import permission on the new superior entry of the entry that you want to move.

Comparing the value of an attribute:

Grant compare permission on the attribute type.

Searching for entries:

  • Grant search permission on each attribute type used in the search filter.

  • Grant read permission on at least one attribute type used in the entry to ensure that the entry is returned.

  • Grant read permission an each attribute type to be returned with the entry.

Example 2–4 Granting ACI Permissions to Perform a Search

This example configures permissions to allow bjensen to search her own entry.

(target="ldap:///dc=example,dc=com")
ldapsearch -h host -p port -D "uid=bjensen,dc=example,dc=com" \
           -w password -b "dc=example,dc=com" \
             "(objectclass=*)" mail

The following ACI determines whether bjensen can be granted access for searching her own entry:

aci: (targetattr = "mail")(version 3.0; acl "self access to 
 mail"; allow (read, search) userdn = "ldap:///self";)

The search result list is empty because this ACI does not allow bjensen the right to search on the objectclass attribute. To perform the search operation described, you must modify the ACI as follows:

aci: (targetattr = "mail || objectclass")(version 3.0; acl 
 "self access to mail"; allow (read, search) userdn = 
 "ldap:///self";)

ACI Bind Rules

Bind rules identify the set of users to which an ACI applies. The permission and bind rule portions of the ACI are set as a pair. The specified permission to access the target is granted or denied depending on whether the accompanying bind rule is evaluated to be true or false.

For information about bind rules, see the following sections:

Introduction to Bind Rules

Bind rules identify a set of users by using the following methods:

A simple bind rule might require a person accessing the directory to belong to a specific group. A complex bind rule can require a person to belong to a specific group and to log in from a machine with a specific IP address, between 8 am and 5 pm. Additionally, bind rules can be complex constructions that combine these criteria by using Boolean operators.

The server evaluates the logical expressions used in ACIs according to a three-valued logic, similar to the one used to evaluate LDAP filters, as described in section 4.5.1.7 of RFC 4511 Lightweight Directory Access Protocol (v3). Therefore, if any component in the expression evaluates to Undefined (for example if the evaluation of the expression aborted due to a resource limitation), then the server handles this case correctly. The server does not erroneously grant access because an Undefined value occurred in a complex Boolean expression.

Bind Rule Syntax

An ACI bind rule has this syntax:

keyword = "expression";

or

keyword != "expression";

The following values are used in the bind rule:

keyword

Indicates the type of bind rule.

expression

Identifies the bind rule.

Bind Rule Keywords

For information about bind rule keywords, see the following sections:

The following table summarizes the keywords for bind rules.

Table 2–2 Bind Rule Keywords and Their Expressions

Keyword 

Used to define access based on 

Expression 

userdn

Specified user 

 
ldap:///distinguished_name
ldap:///all
ldap:///anyone
ldap:///self
ldap:///parent
ldap:///suffix??sub?(filter)

groupdn

Specified group or groups 

[ldap:///DN]

roledn

Specified role or roles 

[ldap:///DN]

userattr

Matched attribute value 

 
attribute#bindType

or 

attribute#value

ip

Specified IP address or IP addresses 

IP_address

dns

Specified domain or domains 

DNS_host_name

timeofday

Specified time of day 

 
0 - 2359

dayofweek

Specified day or days of the week 

sun, mon, tue, wed, thu, fri, and sat

authmethod

Specified authentication method 

none, simple, ssl, sasl authentication_method

userdn Keyword

The userdn keyword is used to allow or deny access to a specified user. The following sections contain more information about the userdn keyword.

Syntax of the userdn Keyword

The userdn keyword uses this syntax:

userdn = "ldap:///dn [|| ldap:///dn]..."
userdn != "ldap:///dn [|| ldap:///dn]..."

The userdn keyword can alternatively be expressed as an LDAP URL filter. For information about expressing the userdn keyword as an LDAP URL, see LDAP URLs in the userdn Keyword.

dn can have of the following values:

distinguished-name

A fully qualified DN. Characters that are syntactically significant for a DN, such as commas, must be escaped with a single backslash (\). The wild card * can be used to specify a set of users. For example, if the following user DN is specified, users with a bind DN beginning with the letter b are allowed or denied access:

uid=b*,dc=example,dc=com
anyone

Allows or denies access for anonymous and authenticated users, regardless of the circumstances of the bind.

This access can be limited to specific types of access (for example, access for read or access for search) or to specific subtrees or individual entries within the directory. The following ACI on the dc=example,dc=com node allows anonymous access to read and search the entire dc=example,dc=com tree.

aci: (version 3.0; acl "anonymous-read-search"; 
 allow (read, search) userdn = "ldap:///anyone";)
all

Allows or denies access for authenticated users. This all value prevents anonymous access. The following ACI on the dc=example,dc=com node allows authenticated users to read the entire dc=example,dc=com tree:

aci: (version 3.0; acl "all-read"; 
 allow (read) userdn="ldap:///all";)
self

Allows or denies users access to their own entries if the bind DN matches the DN of the targeted entry. The following ACI on the dc=example,dc=com node allows authenticated users in the dc=example,dc=com tree to write to their userPassword attribute.

aci: (targetattr = "userPassword") 
 (version 3.0; acl "modify own password"; allow (write) 
 userdn = "ldap:///self";)
parent

Allows or denies users access to the entry if the bind DN is the parent of the targeted entry.

The following ACI on the dc=example,dc=com node allows authenticated users in the dc=example,dc=com tree to modify any child entries of their bind DN:

aci: (version 3.0; acl "parent access"; 
 allow (write) userdn="ldap:///parent";)

LDAP URLs in the userdn Keyword

The userdn keyword can also be expressed as an LDAP URL with a filter, by using this syntax:

userdn = ldap:///suffix??sub?(filter)

LDAP URLs always apply to the local server. Do not specify a hostname or port number within an LDAP URL.

The following ACI on the dc=example,dc=com node allows all users in the accounting and engineering branches of the example.com tree to access to the targeted resource dynamically based on the following URL

userdn = "ldap:///dc=example,dc=com??sub?(|(ou=eng)(ou=acct))"

LDAP URLs can be used with the logical OR operator and the not-equal operator as shown in the following examples.

Example 2–5 Using the userdn Keyword With a Logical OR Operator in LDAP URLs

This bind rule is evaluated to be true for users that bind with either of the specified DN patterns.

userdn = "ldap:///uid=b*,c=example.com || ldap:///cn=b*,dc=example,dc=com";
Example 2–6 Using the userdn Keyword With a Not-Equal Operator in LDAP URLs

This bind rule is evaluated to be true if the client is not binding as a UID-based DN in the accounting subtree. This bind rule only makes sense if the targeted entry is not under the accounting branch of the directory tree.

userdn != "ldap:///uid=*,ou=Accounting,dc=example,dc=com";

groupdn Keyword

The groupdn keyword specifies that access to a targeted entry is granted or denied if the user binds by using a DN that belongs to a specific group. The groupdn keyword uses this syntax:

groupdn="ldap:///groupDN [|| ldap:///groupDN]..."

The bind rule is evaluated to be true if the bind DN belongs to a group that is specified by any of the values for groupDN.

In the following example, the bind rule is true if the bind DN belongs to the Administrators group :

aci: (version 3.0; acl "Administrators-write"; allow (write)
 groupdn="ldap:///cn=Administrators,dc=example,dc=com";)

Characters that are syntactically significant for a DN, such as commas, must be escaped with a single backslash (\).

roledn Keyword

The roledn keyword specifies that access to a targeted entry is granted or denied if the user binds using a DN that belongs to a specific role. The roledn keyword requires one or more valid distinguished names, in this format:

roledn = "ldap:///dn [|| ldap:///dn]... [|| ldap:///dn]"

The bind rule is evaluated to be true if the bind DN belongs to the specified role.

Characters that are syntactically significant for a DN, such as commas, must be escaped with a single backslash (\).

The roledn keyword has the same syntax and is used in the same way as the groupdn keyword.

userattr Keyword

The userattr keyword specifies which attribute values in the entry that was used to bind must match those in the targeted entry. The userattr keyword can be used for the following attributes:

An attribute generated by a Class of Service (CoS) definition cannot be used with the userattr keyword. ACIs that contain bind rules that depend on attribute values generated by CoS will not work.

The userattr keyword uses this syntax:

userattr = "attrName#bindType"

Alternatively, if you are using an attribute type that requires a value other than a user DN, group DN, role DN, or an LDAP filter, the userattr keyword uses this syntax:

userattr = "attrName#attrValue"

The userattr keyword can have one of the following values:

attrName

The name of the attribute used for value matching

bindType

One of the following types of bind: USERDN,GROUPDN,ROLEDN,LDAPURL

attrValue

Any string that represents an attribute value

Examples of userattr Keyword With Various Bind Types

Example 2–7 Using the userattr Keyword With the USERDN Bind Type

The following is an example of the userattr keyword associated with a bind based on the user DN:

userattr = "manager#USERDN"

The bind rule is evaluated to be true if the bind DN matches the value of the manager attribute in the targeted entry. You can use this to allow a user’s manager to modify employees’ attributes. This mechanism only works if the manager attribute in the targeted entry is expressed as a full DN.

The following example grants a manager full access to his or her employees’ entries:

aci: (target="ldap:///dc=example,dc=com")(targetattr="*")
 (version 3.0;acl "manager-write";
 allow (all) userattr = "manager#USERDN";)
Example 2–8 Using the userattr Keyword With the GROUPDN Bind Type

The following is an example of the userattr keyword associated with a bind based on a group DN:

userattr = "owner#GROUPDN"

The bind rule is evaluated to be true if the bind DN is a member of the group specified in the owner attribute of the targeted entry. For example, you can use this mechanism to allow a group to manage employees’ status information. You can use an attribute other than owner, as long as the attribute you use contains the DN of a group entry.

The group you point to can be a dynamic group, and the DN of the group can be under any suffix in the directory. However, the evaluation of this type of ACI by the server is very resource intensive.

If you are using static groups that are under the same suffix as the targeted entry, you can use the following expression:

userattr = "ldap:///dc=example,dc=com?owner#GROUPDN"

In this example, the group entry is under the dc=example,dc=com suffix. The server can process this type of syntax more quickly than the previous example.

Example 2–9 Using the userattr Keyword With the ROLEDN Bind Type

The following is an example of the userattr keyword associated with a bind based on a role DN:

userattr = "exampleEmployeeReportsTo#ROLEDN"

The bind rule is evaluated to be true if the bind DN belongs to the role specified in the exampleEmployeeReportsTo attribute of the targeted entry. For example, if you create a nested role for all managers in your company, you can use this mechanism to grant managers at all levels access to information about employees that are at a lower grade than themselves.

The DN of the role can be under any suffix in the directory. If, in addition, you are using filtered roles, the evaluation of this type of ACI uses a lot of resources on the server.

Example 2–10 Using the userattr Keyword With the LDAPURL Bind Type

The following is an example of the userattr keyword associated with a bind based on an LDAP filter:

userattr = "myfilter#LDAPURL"

The bind rule is evaluated to be true if the bind DN matches the filter specified in the myfilter attribute of the targeted entry. The myfilter attribute can be replaced by any attribute that contains an LDAP filter.

Example 2–11 Using the userattr Keyword With Any Attribute Value

The following is an example of the userattr keyword associated with a bind based on any attribute value:

userattr = "favoriteDrink#Milk"

The bind rule is evaluated to be true if the bind DN and the target DN include the favoriteDrink attribute with a value of Milk.

Use of the userattr Keyword With the parent Keyword for Inheritance

The userattr keyword can be used with the parent keyword to specify the number of levels below the target that should inherit the ACI. The userattr keyword and parent keyword use this syntax:

userattr = "parent[inheritance_level].attribute#bindType"

The userattr keyword and parent keyword can have the following values:

inheritance_level

A comma separated list that indicates how many levels below the target should inherit the ACI. These levels below the targeted entry can be specified: [0,1,2,3,4]. Zero (0) indicates the targeted entry.

attribute

The attribute targeted by the userattr or groupattr keyword.

bindType

The type of bind can be USERDN or GROUPDN. Inheritance cannot be used with LDAPURL and ROLEDN binds.

The following example shows how the userattr keyword is used with the parent keyword for inheritance:

userattr = "parent[0,1].manager#USERDN"

This bind rule is evaluated to be true if the bindDN matches the manager attribute of the targeted entry. The permissions granted when the bind rule is evaluated to be true apply to the target entry and to all entries immediately below it.

Use of the userattr Keyword to Grant Add Permissions

If you use the userattr keyword in conjunction with all or add permissions, you might find that the behavior of the server is not what you expect. Typically, when a new entry is created in the directory, Directory Server evaluates access rights on the entry being created, and not on the parent entry. However, for ACIs that use the userattr keyword, this behavior could create a security hole, and the server’s normal behavior is modified to avoid it.

Consider the following example:

aci: (target="ldap:///dc=example,dc=com")(targetattr="*")
 (version 3.0; acl "manager-write"; allow (all)
 userattr = "manager#USERDN";)

This ACI grants managers all rights on the entries of employees that report to them. However, because access rights are evaluated on the entry being created, this type of ACI would also allow any employee to create an entry in which the manager attribute is set to their own DN. For example, disgruntled employee Joe (cn=Joe,ou=eng,dc=example,dc=com), might want to create an entry in the Human Resources branch of the tree, to use (or misuse) the privileges granted to Human Resources employees.

He could do this by creating the following entry:

dn: cn= Trojan Horse,ou=Human Resources,dc=example,dc=com
objectclass: top
...
cn: Trojan Horse
manager: cn=Joe,ou=eng,dc=example,dc=com

To avoid this type of security threat, the ACI evaluation process does not grant add permission at level 0, that is, to the entry itself. You can, however, use the parent keyword to grant add rights below existing entries. You must specify the number of levels below the parent for add rights. For example, the following ACI allows child entries to be added to any entry in the dc=example,dc=com that has a manager attribute that matches the bind DN:

aci: (target="ldap:///dc=example,dc=com")(targetattr="*")
 (version 3.0; acl "parent-access"; allow (add)
 userattr = "parent[0,1].manager#USERDN";)

This ACI ensures that add permission is granted only to users whose bind DN matches the manager attribute of the parent entry.

ip Keyword

The ip keyword is used to specify that a bind operation must originate from a specific IP address. The ip keyword uses this syntax:

ip = "IPaddressList" or ip != "IPaddressList"

The IPaddressList value is a list of one or more comma-separated elements from the following elements:

The bind rule is evaluated to be true if the client accessing the directory is located at the named IP address.

The ip keyword can be used to force all directory updates to occur from a given machine or network domain. However, the IP address from which a user authenticates can be spoofed, and can therefore not be trusted. Do not base ACIs on this information alone.

The wild card * can be used to specify a set of IP addresses.

dns Keyword

Note –

The dns keyword requires that the naming service used on your machine is DNS. If the name service is not DNS, you should use the ip keyword instead.

The dns keyword is used to specify that a bind operation must originate from a specific domain or host machine. The dns keyword uses this syntax:

dns = "DNS_Hostname" or dns != "DNS_Hostname"

The dns keyword requires a fully qualified DNS domain name. Granting access to a host without specifying the domain creates a potential security threat. For example, the following expression is allowed but not recommended:

dns = "legend.eng";

You should use a fully qualified name such as:

dns = "legend.eng.example.com";

The dns keyword allows wild cards.

dns = "*.example.com";

The bind rule is evaluated to be true if the client accessing the directory is located in the named domain. This can be useful for allowing access only from a specific domain. Note that wild cards do not work if your system uses a naming service other than DNS.

timeofday Keyword

The timeofday keyword is used to specify that access can occur at a certain time of day. The time and date on the server are used for the evaluation of the timeofday and dayofweek bind rules, and not the time on the client. The timeofday keyword uses this syntax:

timeofday operator "time"

The timeofday keyword can have the following values:

operator

  • Equal to (=)

  • Not equal to (!=)

  • Greater than or equal to (>=)

  • Less than (<)

  • Less than or equal to (<=)

time

Four digits representing hours and minutes in the 24-hour clock (0 to 2359)

  • timeofday = "1200"; is true if the client is accessing the directory during the minute that the system clock shows noon.

  • timeofday != "0100"; is true for access at any other time than 1 a.m.

  • timeofday > "0800"; is true for access from 8:01 a.m. through 11:59 p.m.

  • timeofday >= "0800"; is true for access from 8:00 a.m. through 11:59 p.m.

  • timeofday < "1800"; is true for access from 12:00 midnight through 5:59 p.m.

dayofweek Keyword

The dayofweek keyword is used to specify that access can occur on a certain day or on certain days of the week. The time and date on the server are used for the evaluation of the timeofday and dayofweek bind rules, and not the time on the client. The dayofweek keyword uses this syntax:

dayofweek = "day1, day2 ..."

The bind rule is true if the directory is being accessed on one of the days listed.

The dayofweek keyword can have one or more of the following values: sun, mon, tue, wed, thu, fri, sat.

authmethod Keyword

The authmethod keyword is used to specify that a client must bind to the directory by using a specific authentication method. The authmethod keyword uses this syntax:

authmethod = "authentication_method"

The authmethod keyword can have the following values:

None

Authentication is not checked during bind rule evaluation. This is the default.

Simple

The bind rule is evaluated to be true if the client is accessing the directory using a username and password.

SSL

The client must bind to the directory over a Secure Sockets Layer (SSL) or Transport Layer Security (TLS) connection.

The bind rule is evaluated to be true if the client authenticates to the directory by using a certificate over LDAPS. It will not be true if the client authenticates by using simple authentication (bind DN and password) over LDAPS.

SASL sasl_mechanism

The bind rule is evaluated to be true if the client authenticates to the directory by using one of the following SASL mechanisms: DIGEST-MD5, GSSAPI, or EXTERNAL.

Boolean Bind Rules

Bind rules can be complex expressions that use the Boolean expressions AND, OR, and NOT to set precise access rules. Boolean bind rules use this syntax: 

(bindRuleA and (bindRuleB or (bindRuleC and bindRuleD));)

Parentheses defines the order in which rules are evaluated, and a trailing semicolon must appear after the final rule.

Example 2–12 Boolean Bind Rule

The bind rule is true if both of the following conditions are met:

(dns = "*.example.com"
  and (groupdn = "ldap:///cn=administrators, dc=example,dc=com"
  or (groupdn = "ldap:///cn=mail administrators, dc=example,dc=com"
  and groupdn = "ldap:///cn=calendar administrators, dc=example,dc=com"));)

Tuning and Access Control

Directory Server offers performance and scalability improvements for Access Control Instructions. The improvements include better memory management. The improvements also include support for macro ACIs. Improvements notwithstanding, Directory Server uses significant system resources to evaluate complex ACIs. Extensive use of complex ACIs can therefore negatively impact performance.

Macro ACIs help you limit the number of ACIs used. By limiting the number of ACIs, you render access control easier to manage and reduce the load on the system. Macros are placeholders that represent a DN, or a portion of a DN, in an ACI. A macro can be used in an ACI target, in an ACI bind rule, or in both. When Directory Server receives a request, it checks which ACI macros match against the resource targeted for the resulting operation. If a macro matches, Directory Server replaces it with the value of the actual DN. Directory Server then evaluates the ACI normally.

Testing has demonstrated that a Directory Server instance can support more than 50,000 ACIs. Nevertheless, keep the number of ACIs as small as possible. Keeping the number of ACIs small limits negative impact on performance. Keeping the number small also reduces the complexity of managing access controls. For deployments involving complex ACI environments, consider using Directory Proxy Server to provide some access control features.

How Directory Server Provides Authentication

Authentication is the process of confirming an identity. In network interactions, authentication involves the confident identification of one party by another party. Network interactions typically take place between a client, such as browser software running on a personal computer, and a server, such as the software and hardware used to host a Web site. Client authentication refers to the confident identification of a client by a server; server authentication refers to the confident identification of a server by a client.

For information about authentication, see the following sections:

Anonymous Access

Anonymous access lets a user bind to the directory without providing authentication credentials. With access control, you can give anonymous users whatever privileges you choose. Often, anonymous users are allowed to read non-sensitive data from the directory, such as names, telephone numbers, and email addresses.

You can also restrict the privileges of anonymous access, or limit anonymous access to a subset of attributes that contain address book information. Anonymous access should not be allowed for sensitive data.

In cases where anonymous users have access to something, you may want to prevent users who fail to bind properly nevertheless being granted access as anonymous. See the require-bind-pwd-enabled in server(5dsconf) for more information.

Password-Based Authentication

Simple password authentication offers an easy way of authenticating users. In password authentication, the user must supply a password for each server, and the administrator must keep track of the name and password for each user, typically on separate servers.

Steps in Password-Based Authentication

Figure 2–1 shows the steps involved in authenticating a client by using a name and password. The figure assumes the following points.

Figure 2–1 Password-Based Authentication

Figure shows password-based authentication.

    In Figure 2–1, password authentication is performed in the following steps.

  1. The user enters a name and password.

    For the LDAP bind to Directory Server, the client application must bind with a Distinguished Name. Therefore the client application may use the name entered by the user to retrieve the DN.

  2. The client sends the DN and password across the network.

  3. The server determines whether the password sent from the client matches the password stored for the entry with the DN sent from the client.

    If so, the server accepts the credentials as evidence authenticating the user identity.

  4. The server determines whether the identified user is permitted to access the requested resource.

    If so, the server allows the client to access the resource.

Password Policy

A password policy is a set of rules that govern how passwords are administered in a system. Directory Server supports multiple password policies. The password policy can be configured to suit the security requirements of your deployment.

Instances of Directory Server are created with a default password policy.

Types of Password Policy

Directory Server provides the following password policies.

Default password policy

The default password policy is defined in the configuration entry cn=PasswordPolicy,cn=config. The default password policy applies to all accounts in the directory except for the directory manager.

The parameters of the default policy can be modified to override the default settings. However, because the default password policy is part of the configuration for the instance, modifications to the default password policy cannot be replicated.

Specialized password policy

A password policy can be configured for an individual user or for set of users by using the CoS and roles features. However, specialized password policies can not be applied to static groups.

A specialized password policy is defined in a subentry in the directory tree. Like the default password policy, the specialized password policy uses the pwdPolicy object class. For example, the following entry defines a specialized password policy:


dn: cn=TempPolicy,dc=example,dc=com
objectClass: top
objectClass: pwdPolicy
objectClass: LDAPsubentry
cn: TempPolicy
pwdCheckQuality: 2
pwdLockout: on
pwdLockoutDuration: 300
pwdMaxFailure: 3
pwdMustChange: on

A specialized password policy can be assigned to a single user account or can be assigned to a set of users by using roles. For example, in the following entry the password policy defined in cn=TempPolicy,dc=example,dc=com is assigned to the pwdPolicySubentry attribute of the user entry:


dn: uid=dmiller,ou=people,dc=example,dc=com
objectClasaccess controls: person
objectClass: top
sn: miller
cn: david
userPassword: secret12
pwdPolicySubentry: cn=TempPolicy,dc=example,dc=com

When referenced by a user entry, a specialized password policy overrides the default password policy.

Because specialized password policies are defined the directory data, they can be replicated.

Configuration of Password Policy

For information about how to configure password policy, see Chapter 7, Directory Server Password Policy, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

For information about the attributes used to configure password policies, see the pwpolicy(5dssd) man page.

Certificate-based Authentication

For information about client authentication with certificates, see the following sections:

Introduction to Certificate-based Authentication

Figure 2–2 shows how certificates and the SSL protocol are used together for authentication. To authenticate a user to a server, a client digitally signs a randomly generated piece of data and sends both the certificate and the signed data across the network. For the purposes of this discussion, the digital signature associated with some data can be thought of as evidence provided by the client to the server. The server authenticates the user’s identity on the strength of this evidence.

Like for password-based authentication illustrated in Figure 2–1, Figure 2–2 assumes that the user has already decided to trust the server and has requested a resource. The server has requested client authentication in the process of evaluating whether to grant access to the requested resource.

Figure 2–2 Certificate-Based Authentication

Figure shows certificate-based authentication

Unlike for password-based authentication illustrated in Figure 2–1, Figure 2–2 requires the use of SSL. In Figure 2–2 it is assumed that the client has a valid certificate that can be used to identify the client to the server.

Certificate-based authentication is generally considered preferable to password-based authentication because it is based on what the user has, the private key, as well as what the user knows, the password that protects the private key. However, it’s important to note that these two assumptions are true only if unauthorized personnel have not gained access to the user’s machine or password, the password for the client software’s private key database has been set, and the software is set up to request the password at reasonably frequent intervals.

Note –

Neither password-based authentication nor certificate-based authentication address security issues related to physical access to individual machines or passwords. Public-key cryptography can only verify that a private key used to sign some data corresponds to the public key in a certificate. It is the user’s responsibility to protect a machine’s physical security and to keep the private-key password secret.

Certificates replace the authentication portion of the interaction between the client and the server. Instead of requiring a user to send passwords across the network throughout the day, single sign-on requires the user to enter the private-key database password just once, without sending it across the network. For the rest of the session, the client presents the user’s certificate to authenticate the user to each new server it encounters. Existing authorization mechanisms based on the authenticated user identity are not affected.

Steps for Configuring Certificate-based Authentication

    In Figure 2–2, certificate-based authentication is set in the following steps.

  1. The client software maintains a database of the private keys that correspond to the public keys published in any certificates issued for that client. The client asks for the password to this database the first time the client needs to access it during a given session—for example, the first time the user attempts to access an SSL-enabled server that requires certificate-based client authentication. After entering this password once, the user doesn’t need to enter it again for the rest of the session, even when accessing other SSL-enabled servers.

  2. The client unlocks the private-key database, retrieves the private key for the user’s certificate, and uses that private key to digitally sign some data that has been randomly generated for this purpose on the basis of input from both the client and the server. This data and the digital signature constitute “evidence” of the private key’s validity. The digital signature can be created only with that private key and can be validated with the corresponding public key against the signed data, which is unique to the SSL session.

  3. The client sends both the user’s certificate and the evidence, the randomly generated piece of data that has been digitally signed, across the network.

  4. The server uses the certificate and the evidence to authenticate the user’s identity.

  5. At this point the server may optionally perform other authentication tasks, such as checking that the certificate presented by the client is stored in the user’s entry in an LDAP directory. The server then continues to evaluate whether the identified user is permitted to access the requested resource. This evaluation process can employ a variety of standard authorization mechanisms, potentially using additional information in an LDAP directory, company databases, and so on. If the result of the evaluation is positive, the server allows the client to access the requested resource.

Certificates and Certificate Authorities (CA)

A certificate is an electronic document that identifies an individual, a server, a company, or some other entity. A certificate also associates that identity with a public key. Like a driver’s license, a passport, or other commonly used personal IDs, a certificate provides generally recognized proof of someone's or something's identity.

Certificate authorities, CAs, validate identities and issue certificates. CAs can be independent third parties or organizations that run their own certificate-issuing server software. The methods used to validate an identity vary depending on the policies of a given CA. In general, before issuing a certificate, the CA must use its published verification procedures for that type of certificate to ensure that an entity requesting a certificate is in fact who it claims to be.

A certificate issued by a CA binds a particular public key to the name of the entity the certificate identifies, such as the name of an employee or a server. Certificates help prevent the use of fake public keys for impersonation. Only the public key certified by the certificate works with the corresponding private key possessed by the entity identified by the certificate.

In addition to a public key, a certificate always includes the name of the entity it identifies, an expiration date, the name of the CA that issued the certificate, a serial number, and other information. Most importantly, a certificate always includes the digital signature of the issuing CA. The CA’s digital signature allows the certificate to function as a “letter of introduction” for users who know and trust the CA but don’t know the entity identified by the certificate.

Any client or server software that supports certificates maintains a collection of trusted CA certificates. These CA certificates determine which other certificates the software can validate, in other words, which issuers of certificates the software can trust. In the simplest case, the software can validate only certificates issued by one of the CAs for which it has a certificate. It’s also possible for a trusted CA certificate to be part of a chain of CA certificates, each issued by the CA above it in a certificate hierarchy.

For information about CAs, see the following sections:

CA Hierarchies

In large organizations, it may be appropriate to delegate the responsibility for issuing certificates to several different certificate authorities. For example, the number of certificates required may be too large for a single CA to maintain; different organizational units may have different policy requirements; or it may be important for a CA to be physically located in the same geographic area as the people to whom it is issuing certificates.

It’s possible to delegate certificate-issuing responsibilities to subordinate CAs. The X.509 standard includes a model for setting up a hierarchy of CAs.

Figure 2–3 Hierarchy of Certificate Authorities

Figure shows a hierarchy of certificate authorities

In this model, the root CA is at the top of the hierarchy. The root CA’s certificate is a self-signed certificate. That is, the certificate is digitally signed by the same entity, the root CA, that the certificate identifies. The CAs that are directly subordinate to the root CA have CA certificates signed by the root CA. CAs under the subordinate CAs in the hierarchy have their CA certificates signed by the higher-level subordinate CAs.

Organizations have a great deal of flexibility in terms of the way they set up their CA hierarchies. Figure 2–3 shows just one example; many other arrangements are possible.

Certificate Chains

CA hierarchies are reflected in certificate chains. A certificate chain is a series of certificates issued by successive CAs. Figure 2–4 shows a certificate chain leading from a certificate that identifies some entity through two subordinate CA certificates to the CA certificate for the root CA (based on the CA hierarchy shown in the following figure).

Figure 2–4 Certificate Chain

Figure shows a certificate chain.

A certificate chain traces a path of certificates from a branch in the hierarchy to the root of the hierarchy. In a certificate chain, the following occur:

In Figure 2–4, the public key in the certificate for the USA CA can be used to verify the USA CA’s digital signature on the certificate for the Engineering CA.

Verifying a Certificate Chain

Certificate chain verification is the process of making sure a given certificate chain is well-formed, valid, properly signed, and trustworthy. Directory Server software uses the following steps to form and verify a certificate chain, starting with the certificate being presented for authentication:

  1. The certificate validity period is checked against the current time provided by the verifier’s system clock.

  2. The issuer’s certificate is located. The source can be either the verifier’s local certificate database (on that client or server) or the certificate chain provided by the subject (for example, over an SSL connection).

  3. The certificate signature is verified using the public key in the issuer certificate.

  4. If the issuer’s certificate is trusted by the verifier in the verifier’s certificate database, verification stops successfully here. Otherwise, the issuer’s certificate is checked to make sure it contains the appropriate subordinate CA indication in the Directory Server certificate type extension, and chain verification returns to step 1 to start again, but with this new certificate.

Figure 2–5 Verifying A Certificate Chain

Figure shows verification of a certificate chain.

Figure 2–5 shows what happens when only Root CA is included in the verifier’s local database. If a certificate for one of the intermediate CAs shown in Figure 2–6, such as Engineering CA, is found in the verifier’s local database, verification stops with that certificate, as shown in the following figure.

Figure 2–6 Verifying A Certificate Chain to an Intermediate CA

Figure shows verification of a certificate chain to an intermediate CA.

Expired validity dates, an invalid signature, or the absence of a certificate for the issuing CA at any point in the certificate chain causes authentication to fail. For example, the following figure shows how verification fails if neither the Root CA certificate nor any of the intermediate CA certificates are included in the verifier’s local database.

Figure 2–7 Certificate Chain That Cannot Be Verified

Figure shows verification of a certificate chain that cannot be verified.

For general information about the way digital signatures work, see Digital Signatures.

Types of Certificates

Directory Server uses the following types of certificate:

Client SSL certificates

Client SSL certificates are used to identify clients to servers via SSL (client authentication). Typically, the identity of the client is assumed to be the same as the identity of a human being, such as an employee in an enterprise. Client SSL certificates can also be used for form signing and as part of a single sign-on solution.

For example, a bank gives a customer a client SSL certificate that allows the bank’s servers to identify that customer and authorize access to the customer’s accounts. A company might give a new employee a client SSL certificate that allows the company’s servers to identify that employee and authorize access to the company’s servers.

Server SSL certificates

Server SSL certificates are used to identify servers to clients via SSL (server authentication). Server authentication may be used with or without client authentication. Server authentication is a requirement for an encrypted SSL session.

For example, internet sites that engage in electronic commerce usually support certificate-based server authentication, at a minimum, to establish an encrypted SSL session and to assure customers that they are dealing with a web site identified with a particular company. The encrypted SSL session ensures that personal information sent over the network, such as credit card numbers, cannot easily be intercepted.

S/MIME certificates

S/MIME certificates are used for signed and encrypted email. As with client SSL certificates, the identity of the client is typically assumed to be the same as the identity of a human being, such as an employee in an enterprise. A single certificate may be used as both an S/MIME certificate and an SSL certificate. S/MIME certificates can also be used for form signing and as part of a single sign-on solution.

For example, a company deploys combined S/MIME and SSL certificates solely for the purpose of authenticating employee identities, thus permitting signed email and client SSL authentication but not encrypted email. Another company issues S/MIME certificates solely for the purpose of both signing and encrypting email that deals with sensitive financial or legal matters.

Object-signing certificates

Object-signing certificates are used to identify signers of Java code, JavaScript scripts, or other signed files.

For example, a software company signs software distributed over the Internet to provide users with some assurance that the software is a legitimate product of that company. Using certificates and digital signatures in this manner can also make it possible for users to identify and control the kind of access downloaded software has to their computers.

CA certificates

CA certificates are used to identify CAs. Client and server software use CA certificates to determine what other certificates can be trusted.

For example, the CA certificates stored in client software determine what other certificates that client can authenticate. An administrator can implement some aspects of corporate security policies by controlling the CA certificates stored in each user’s client.

Contents of a Certificate

The contents of certificates supported by Directory Server and many other software companies are organized according to the X.509 v3 certificate specification, which has been recommended by the International Telecommunications Union (ITU), an international standards body, since 1988. Examples in this section show samples of the data and signature sections of a certificate.

Every X.509 certificate consists of the following sections.

Example 2–13 Data and Signature Sections of a Certificate in Human-Readable Format

Certificate:
Data:
   Version: v3 (0x2)
   Serial Number: 3 (0x3)
   Signature Algorithm: PKCS #1 MD5 With RSA Encryption
   Issuer: OU=Certificate Authority, O=Example Industry, C=US
   Validity:
    Not Before: Fri Oct 17 18:36:25 2003
    Not  After: Sun Oct 17 18:36:25 2004
   Subject: CN=Jane Doe, OU=Finance, O=Example Industry, C=US
   Subject Public Key Info:
    Algorithm: PKCS #1 RSA Encryption
    Public Key:
       Modulus:
          00:ca:fa:79:98:8f:19:f8:d7:de:e4:49:80:48:e6:2a:2a:86:
          ed:27:40:4d:86:b3:05:c0:01:bb:50:15:c9:de:dc:85:19:22:
          43:7d:45:6d:71:4e:17:3d:f0:36:4b:5b:7f:a8:51:a3:a1:00:
          98:ce:7f:47:50:2c:93:36:7c:01:6e:cb:89:06:41:72:b5:e9:
          73:49:38:76:ef:b6:8f:ac:49:bb:63:0f:9b:ff:16:2a:e3:0e:
          9d:3b:af:ce:9a:3e:48:65:de:96:61:d5:0a:11:2a:a2:80:b0:
          7d:d8:99:cb:0c:99:34:c9:ab:25:06:a8:31:ad:8c:4b:aa:54:
          91:f4:15
       Public Exponent: 65537 (0x10001)
   Extensions:
    Identifier: Certificate Type
      Critical: no
      Certified Usage:
      SSL Client
    Identifier: Authority Key Identifier
      Critical: no
      Key Identifier:
        f2:f2:06:59:90:18:47:51:f5:89:33:5a:31:7a:e6:5c:fb:36:
        26:c9
   Signature:
    Algorithm: PKCS #1 MD5 With RSA Encryption
   Signature:
 6d:23:af:f3:d3:b6:7a:df:90:df:cd:7e:18:6c:01:69:8e:54:65:fc:06:
 30:43:34:d1:63:1f:06:7d:c3:40:a8:2a:82:c1:a4:83:2a:fb:2e:8f:fb:
 f0:6d:ff:75:a3:78:f7:52:47:46:62:97:1d:d9:c6:11:0a:02:a2:e0:cc:
 2a:75:6c:8b:b6:9b:87:00:7d:7c:84:76:79:ba:f8:b4:d2:62:58:c3:c5:
 b6:c1:43:ac:63:44:42:fd:af:c8:0f:2f:38:85:6d:d6:59:e8:41:42:a5:
 4a:e5:26:38:ff:32:78:a1:38:f1:ed:dc:0d:31:d1:b0:6d:67:e9:46:a8:
 d:c4
Example 2–14 Certificate In the 64-Byte Encoded Form Interpreted by Software

-----BEGIN CERTIFICATE-----
MIICKzCCAZSgAwIBAgIBAzANBgkqhkiG9w0BAQQFADA3MQswCQYDVQQGEwJVUzER
MA8GA1UEChMITmV0c2NhcGUxFTATBgNVBAsTDFN1cHJpeWEncyBDQTAeFw05NzEw
MTgwMTM2MjVaFw05OTEwMTgwMTM2MjVaMEgxCzAJBgNVBAYTAlVTMREwDwYDVQQK
EwhOZXRzY2FwZTENMAsGA1UECxMEUHViczEXMBUGA1UEAxMOU3Vwcml5YSBTaGV0
dHkwgZ8wDQYJKoZIhvcNAQEFBQADgY0AMIGJAoGBAMr6eZiPGfjX3uRJgEjmKiqG
7SdATYazBcABu1AVyd7chRkiQ31FbXFOGD3wNktbf6hRo6EAmM5/R1AskzZ8AW7L
iQZBcrXpc0k4du+2Q6xJu2MPm/8WKuMOnTuvzpo+SGXelmHVChEqooCwfdiZywyZ
NMmrJgaoMa2MS6pUkfQVAgMBAAGjNjA0MBEGCWCGSAGG+EIBAQQEAwIAgDAfBgNV
HSMEGDAWgBTy8gZZkBhHUfWJM1oxeuZc+zYmyTANBgkqhkiG9w0BAQQFAAOBgQBt
I6/z07Z635DfzX4XbAFpjlRl/AYwQzTSYx8GfcNAqCqCwaSDKvsuj/vwbf91o3j3
UkdGYpcd2cYRCgKi4MwqdWyLtpuHAH18hHZ5uvi00mJYw8W2wUOsY0RC/a/IDy84
hW3WWehBUqVK5SY4/zJ4oTjx7dwNMdGwbWfpRqjd1A==
-----END CERTIFICATE-----

Certificate Management

The set of standards and services that facilitate the use of public-key cryptography and X.509 v3 certificates in a network environment is called thepublic key infrastructure (PKI). For information about the certificate management issues addressed by Directory Server, see the following sections:

Issuing Certificates

The process for issuing a certificate depends on the certificate authority that issues it and the purpose for which it is used. The process for issuing non-digital forms of identification varies in similar ways. For example, if you want to get a generic ID card (not a driver’s license) from the Department of Motor Vehicles in California, the requirements are straightforward: you need to present some evidence of your identity, such as a utility bill with your address on it and a student identity card. If you want to get a regular driving license, you also need to take a test — a driving test when you first get the license, and a written test when you renew it. If you want to get a commercial license for an eighteen-wheeler, the requirements are much more stringent. If you live in some other state or country, the requirements for various kinds of licenses differ.

Similarly, different CAs have different procedures for issuing different kinds of certificates. In some cases the only requirement may be your mail address. In other cases, your UNIX login and password may be sufficient. At the other end of the scale, for certificates that identify people who can authorize large expenditures or make other sensitive decisions, the issuing process may require notarized documents, a background check, and a personal interview.

Depending on an organization’s policies, the process of issuing certificates can range from being completely transparent for the user to requiring significant user participation and complex procedures. In general, processes for issuing certificates should be highly flexible, so organizations can tailor them to their changing needs.

Issuing certificates is one of several management tasks that can be handled by separate Registration Authorities.

Certificates and the LDAP Directory

The Lightweight Directory Access Protocol (LDAP) for accessing directory services supports great flexibility in the management of certificates within an organization. System administrators can store much of the information required to manage certificates in an LDAP-compliant directory. For example, a CA can use information in a directory to pre-populate a certificate with a new employee’s legal name and other information. The CA can leverage directory information in other ways to issue certificates one at a time or in bulk, using a range of different identification techniques depending on the security policies of a given organization. Other routine management tasks, such as key management and renewing and revoking certificates, can be partially or fully automated with the aid of the directory.

Information stored in the directory can also be used with certificates to control access to various network resources by different users or groups. Issuing certificates and other certificate management tasks can thus be an integral part of user and group management.

Key Management

Before a certificate can be issued, the public key it contains and the corresponding private key must be generated. Sometimes it may be useful to issue a single person one certificate and key pair for signing operations, and another certificate and key pair for encryption operations. Separate signing and encryption certificates make it possible to keep the private signing key on the local machine only, thus providing maximum nonrepudiation, and to back up the private encryption key in some central location where it can be retrieved in case the user loses the original key or leaves the company.

Keys can be generated by client software or generated centrally by the CA and distributed to users via an LDAP directory. There are trade-offs involved in choosing between local and centralized key generation. For example, local key generation provides maximum nonrepudiation, but may involve more participation by the user in the issuing process. Flexible key management capabilities are essential for most organizations.

Key recovery, or the ability to retrieve backups of encryption keys under carefully defined conditions, can be a crucial part of certificate management (depending on how an organization uses certificates). Key recovery schemes usually involve an m of n mechanism: for example, m of n managers within an organization might have to agree, and each contribute a special code or key of their own, before a particular person’s encryption key can be recovered. This kind of mechanism ensures that several authorized personnel must agree before an encryption key can be recovered.

Renewal and Revocation of Certificates

Like a driver’s license, a certificate specifies a period of time during which it is valid. Attempts to use a certificate for authentication before or after its validity period fails. Therefore, mechanisms for managing certificate renewal are essential for any certificate management strategy. For example, an administrator may wish to be notified automatically when a certificate is about to expire, so that an appropriate renewal process can be completed in plenty of time without causing the certificate’s subject any inconvenience. The renewal process may involve reusing the same public-private key pair or issuing a new one.

A driver’s license can be suspended even if it has not expired—for example, as punishment for a serious driving offense. Similarly, it’s sometimes necessary to revoke a certificate before it has expired—for example, if an employee leaves a company or moves to a new job within the company.

Certificate revocation can be handled in several different ways. For some organizations, it may be sufficient to set up servers so that the authentication process includes checking the directory for the presence of the certificate being presented. When an administrator revokes a certificate, the certificate can be automatically removed from the directory, and subsequent authentication attempts with that certificate fails even though the certificate remains valid in every other respect. Another approach involves publishing a certificate revocation list (CRL)—that is, a list of revoked certificates—to the directory at regular intervals and checking the list as part of the authentication process. For some organizations, it may be preferable to check directly with the issuing CA each time a certificate is presented for authentication. This procedure is sometimes called real-time status checking.

Registration Authorities

Interactions between entities identified by certificates (sometimes called end entities) and CAs are an essential part of certificate management. These interactions include operations such as registration for certification, certificate retrieval, certificate renewal, certificate revocation, and key backup and recovery. In general, a CA must be able to authenticate the identities of end entities before responding to the requests. In addition, some requests need to be approved by authorized administrators or managers before being serviced.

As previously discussed, the means used by different CAs to verify an identity before issuing a certificate can vary widely, depending on the organization and the purpose for which the certificate is used. To provide maximum operational flexibility, interactions with end entities can be separated from the other functions of a CA and handled by a separate service called a Registration Authority RA.

An RA acts as a front end to a CA by receiving end entity requests, authenticating them, and forwarding them to the CA. After receiving a response from the CA, the RA notifies the end entity of the results. RAs can be helpful in scaling a PKI across different departments, geographical areas, or other operational units with varying policies and authentication requirements.

SASL-based Authentication

Client authentication during an SSL or TLS connection can also use the Simple Authentication and Security Layer (SASL). Directory Server supports the following SASL mechanisms.

DIGEST-MD5

The DIGEST-MD5 mechanism authenticates clients by comparing a hashed value sent by the client with a hash of the user's password. However, because the mechanism must read user passwords, all users wishing to be authenticated through DIGEST-MD5 must have clear text passwords in the directory.

GSSAPI

GSSAPI is available on the Solaris Operating System only. The General Security Services API (GSSAPI) allows Directory Server to interact with the Kerberos V5 security system to identify a user. The client application must present its credentials to the Kerberos system, which in turn validates the user's identity to Directory Server.

For information about how to configure SASL-based authentication, see Configuring Client Authentication in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Proxy Authorization

Proxy authorization allows requests from clients to be processed with a proxy identity instead of the identity of the client. A client, binding with its own identity is granted, through proxy authorization, the rights of a proxy user. The Access Control Instructions (ACIs) of the proxy user, not the ACIs of the client, are evaluated to allow or deny the operation.

Before performing an operation with proxy authorization, the account of the proxy user is validated. If the proxy user account is locked out, inactivated, if the password has been reset or has expired the client operation is aborted.

By using proxy authorization, an LDAP application can use a single bind to service multiple users who are making requests against Directory Server. Instead of having to bind and authenticate for each user, the client application binds to Directory Server and uses proxy rights.

The following conditions must be satisfied in order to use proxy authorization:

The following sample shows the user ClientApplication performing a search operation by using the Administrator proxy identity:


$ ldapsearch \
-D "uid=ClientApplication,ou=Applications,dc=example,dc=com" \
-w password \
-y "uid=Administrator,ou=Administrators,dc=example,dc=com" ...

Note that the client binds as itself, but is granted the privileges of the proxy entry. The client does not need the password of the proxy entry.

Proxy rights can be granted to any user except the Directory Manager.

For information about how to configure proxy authorization, see Proxy Authorization in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Account Inactivation

A user account or a set of accounts can be inactivated temporarily or indefinitely by using the ns-inactivate(1M) command. When the account is inactivated, the user cannot bind to Directory Server. This feature is called account inactivation.

User accounts and roles can be inactivated. When a role is inactivated, the members of the role are inactivated, not the role itself.

For information about how to configure account inactivation, see Manually Locking Accounts in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Global Account Lockout

Depending on the password policy settings, a client account can be locked out of an account when the number of failed bind attempts exceeds the number of allowed bind attempts. In a replicated topology the client is locked out of all instances of Directory Server, not just the instance to which the client was attempting to bind. This feature is called global account lockout.

In versions of Directory Server prior to Directory Server 6, account lockout was based on integer counters. By default, these counters were not replicated.

In this version of the product, bind failures are recorded by using timestamps. By default, the timestamps are replicated, and prioritized replication is used to replicate updates to the lockout data that are caused by failed bind requests.

Global account lockout can be used in the following scenarios:

How Directory Server Provides Encryption

For information about how Directory Server encrypts data, see the following sections:

Secure Sockets Layer (SSL)

SSL provides encrypted communications and optional authentication between a Directory Server and its clients. SSL can be used over LDAP or DSML over HTTP. SSL is enabled by default over LDAP and can be enabled for DSML over HTTP.

Replication can be configured to use SSL for secure communications between servers. When replication is configured to use SSL, data sent to and from the server is encrypted by using SSL.

By default, Directory Server allows simultaneous unsecured and secure communications, suing different port numbers. Unsecured LDAP communications are handled on one port, conventionally port number 389. Secure LDAP communications are handled on another port, conventionally port number 636.

For security reasons, you can also restrict all communications to the secure port. Client authentication is also configurable. You can set client authentication to required or allowed. This setting determines the level of security you enforce.

SSL enables support for the Start TLS extended operation that provides security on a regular LDAP connection. Clients can bind to the non-SSL port and then use the Transport Layer Security protocol to initiate an SSL connection. The Start TLS operation allows more flexibility for clients, and can help simplify port allocation.

For information about SSL, see the following sections:

Overview of SSL

TCP/IP governs the transport and routing of data over the Internet. Other protocols, such as the HTTP, LDAP, or IMAP use TCP/IP to support typical application tasks such as displaying web pages or running mail servers.

Figure 2–8 Where SSL Runs

Figure shows that SSL runs above the TCP/IP layer but below other protocols

The SSL protocol runs above TCP/IP and below higher-level protocols such as HTTP or IMAP. It uses TCP/IP on behalf of the higher-level protocols, and in the process allows an SSL-enabled server to authenticate itself to an SSL-enabled client, allows the client to authenticate itself to the server, and allows both machines to establish an encrypted connection.

SSL addresses the following concerns about communication over the Internet and other TCP/IP networks:

SSL server authentication allows a user to confirm a server’s identity.

SSL-enabled client software can use standard techniques of public-key cryptography to check that a server’s certificate and public ID are valid and have been issued by a certificate authority (CA) listed in the client’s list of trusted CAs. This confirmation might be important if the user, for example, is sending a credit card number over the network and wants to check the receiving server’s identity.

SSL client authentication allows a server to confirm a user’s identity.

Using the same techniques as those used for server authentication, SSL-enabled server software can check that a client’s certificate and public ID are valid and have been issued by a certificate authority (CA) listed in the server’s list of trusted CAs. This confirmation might be important if the server, for example, is a bank sending confidential financial information to a customer and wants to check the recipient’s identity.

An encrypted SSL connection requires all information sent between a client and a server to be encrypted by the sending software and decrypted by the receiving software, thus providing a high degree of confidentiality.

Confidentiality is important for both parties to any private transaction. In addition, all data sent over an encrypted SSL connection is protected with a mechanism for detecting tampering—that is, for automatically determining whether the data has been altered in transit.

The SSL protocol includes two sub-protocols: the SSL record protocol and the SSL handshake protocol.

The SSL record protocol defines the format used to transmit data. The SSL handshake protocol involves using the SSL record protocol to exchange a series of messages between an SSL-enabled server and an SSL-enabled client when they first establish an SSL connection. This exchange of messages is designed to facilitate the following actions:

  • Authenticate the server to the client.

  • Allow the client and server to select the cryptographic algorithms, or ciphers, that they both support.

  • Optionally authenticate the client to the server.

  • Use public-key encryption techniques to generate shared secrets.

  • Establish an encrypted SSL connection.

For more information about the handshake process, see SSL Handshake.

Cryptographic Algorithms Used With SSL

Cipher suites define the following aspects of SSL communication:

The SSL protocol supports many ciphers. Clients and servers can support different cipher suites, depending on factors such as the version of SSL they support, and company policies regarding acceptable encryption strength. The SSL handshake protocol determines how the server and client negotiate which cipher suites they use to authenticate each other, to transmit certificates, and to establish session keys.

SSL 2.0 and SSL 3.0 protocols support overlapping sets of cipher suites. Administrators can enable or disable any of the supported cipher suites for both clients and servers. When a client and server exchange information during the SSL handshake, they identify the strongest enabled cipher suites they have in common and use those for the SSL session. Decisions about which cipher suites to enable depend on the sensitivity of the data involved, the speed of the cipher, and the applicability of export rules.

Key-exchange algorithms like KEA and RSA govern the way in which a server and client determine the symmetric keys they use during an SSL session. The most commonly used SSL cipher suites use the RSA key exchange.

The list of ciphers enabled for Directory Server, and also the list of ciphers supported by Directory Server can be obtained with the dsconf command. For information about using the dsconf command to list available ciphers and manage ciphers, see Choosing Encryption Ciphers in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Support for ciphers is provided by the Network Security Services, NSS, component. For details about NSS, see theNSS project site.

SSL Handshake

The SSL protocol uses a combination of public-key and symmetric key encryption. Symmetric key encryption is much faster than public-key encryption, but public-key encryption provides better authentication techniques. An SSL session always begins with an exchange of messages called the SSL handshake. The handshake allows the server to authenticate itself to the client by using public-key techniques, and then allows the client and the server to cooperate in the creation of symmetric keys used for rapid encryption, decryption, and tamper detection. Optionally, the handshake also allows the client to authenticate itself to the server.

For information about the SSL handshake, see the following sections:

Messages Exchanged During SSL Handshake

The following steps describes the sequence of messages exchanged during an SSL handshake. These step describe the programmatic details of the messages exchanged during the SSL handshake.

  1. The client sends the server the client’s SSL version number, cipher settings, randomly generated data, and other information the server needs to communicate with the client using SSL.

  2. The server sends the client the server’s SSL version number, cipher settings, randomly generated data, and other information the client needs to communicate with the server over SSL. The server also sends its own certificate and, if the client is requesting a server resource that requires client authentication, requests the client’s certificate.

  3. The client uses some of the information sent by the server to authenticate the server. For details, see Server Authentication During SSL Handshake. If the server cannot be authenticated, the user is warned of the problem and informed that an encrypted and authenticated connection cannot be established. If the server can be successfully authenticated, the client goes on to Step 4.

  4. Using all data generated in the handshake so far, the client, with the cooperation of the server, depending on the cipher being used, creates the pre-master secret for the session, encrypts it with the server’s public key, obtained from the server’s certificate, sent in Step 2, and sends the encrypted pre-master secret to the server.

  5. If the server has requested client authentication (an optional step in the handshake), the client also signs another piece of data that is unique to this handshake and known by both the client and server. In this case the client sends both the signed data and the client’s own certificate to the server along with the encrypted pre-master secret.

  6. If the server has requested client authentication, the server attempts to authenticate the client. For details, see Server Authentication During SSL Handshake. If the client cannot be authenticated, the session is terminated. If the client can be successfully authenticated, the server uses its private key to decrypt the pre-master secret, then performs a series of steps (which the client also performs, starting from the same pre-master secret) to generate the master secret.

  7. Both the client and the server use the master secret to generate the session keys, which are symmetric keys used to encrypt and decrypt information exchanged during the SSL session and to verify its integrity—that is, to detect changes in the data between the time it was sent and the time it is received over the SSL connection.

  8. The client sends a message to the server informing it that future messages from the client are encrypted with the session key. It then sends a separate (encrypted) message indicating that the client portion of the handshake is finished.

  9. The server sends a message to the client informing it that future messages from the server are encrypted with the session key. It then sends a separate (encrypted) message indicating that the server portion of the handshake is finished.

  10. The SSL handshake is now complete, and the SSL session has begun. The client and the server use the session keys to encrypt and decrypt the data they send to each other and to validate its integrity.

Before continuing with a session, directory servers can be configured to check that the client’s certificate is present in the user’s entry in an LDAP directory. This configuration option provides one way of ensuring that the client’s certificate has not been revoked.

Both client and server authentication involve encrypting some piece of data with one key of a public-private key pair and decrypting it with the other key:

Server Authentication During SSL Handshake

SSL-enabled client software always requires server authentication, or cryptographic validation by a client of the server’s identity. The server sends the client a certificate to authenticate itself. The client uses the certificate to authenticate the identity the certificate claims to represent.

To authenticate the binding between a public key and the server identified by the certificate that contains the public key, an SSL-enabled client must receive a yes answer to the four questions shown in the following figure.

Figure 2–9 Authenticating a Client Certificate During SSL Handshake

Figure shows authentication of a client certificate.

An SSL-enabled client goes through the following steps to authenticate a server’s identity:

  1. Is today’s date within the validity period?

    The client checks the server certificate’s validity period. If the current date and time are outside of that range, the authentication process won’t go any further. If the current date and time are within the certificate’s validity period, the client goes on to the next step.

  2. Is the issuing CA a trusted CA?

    Each SSL-enabled client maintains a list of trusted CA certificates, represented by the shaded area on the right—hand side of Figure 2–9. This list determines which server certificates the client accepts. If the distinguished name (DN) of the issuing CA matches the DN of a CA on the client’s list of trusted CAs, the answer to this question is yes, and the client goes on to the next step. If the issuing CA is not on the list, the server is not authenticated unless the client can verify a certificate chain ending in a CA that is on the list.

  3. Does the issuing CA’s public key validate the issuer’s digital signature?

    The client uses the public key from the CA’s certificate (which it found in its list of trusted CAs in step 2) to validate the CA’s digital signature on the server certificate being presented. If the information in the server certificate has changed since it was signed by the CA or if the CA certificate’s public key doesn’t correspond to the private key used by the CA to sign the server certificate, the client won’t authenticate the server’s identity. If the CA’s digital signature can be validated, the server treats the user’s certificate as a valid “letter of introduction” from that CA and proceeds. At this point, the client has determined that the server certificate is valid.

  4. Does the domain name in the server’s certificate match the domain name of the server itself?

    This step confirms that the server is actually located at the same network address specified by the domain name in the server certificate. Although step 4 is not technically part of the SSL protocol, it provides the only protection against a form of security attack known as man-in-the-middle. Clients must perform this step and must refuse to authenticate the server or establish a connection if the domain names don’t match. If the server’s actual domain name matches the domain name in the server certificate, the client goes on to the next step.

  5. The server is authenticated.

    The client proceeds with the SSL handshake. If the client doesn’t get to step 5 for any reason, the server identified by the certificate cannot be authenticated, and the user is warned of the problem and informed that an encrypted and authenticated connection cannot be established. If the server requires client authentication, the server performs the steps described in Client Authentication During SSL Handshake.

After the steps described here, the server must successfully use its private key to decrypt the pre-master secret sent by the client.

Man-In-the-Middle Attack

The man-in-the-middle is a rogue program that intercepts all communication between the client and a server with which the client is attempting to communicate via SSL. The rogue program intercepts the legitimate keys that are passed back and forth during the SSL handshake, substitutes its own, and makes it appear to the client that it is the server, and to the server that it is the client.

The encrypted information exchanged at the beginning of the SSL handshake is actually encrypted with the rogue program’s public key or private key, rather than the client’s or server’s real keys. The rogue program ends up establishing one set of session keys for use with the real server, and a different set of session keys for use with the client. This allows the rogue program not only to read all the data that flows between the client and the real server, but also to change the data without being deleted. Therefore, it is extremely important for the client to check that the domain name in the server certificate corresponds to the domain name of the server with which a client is attempting to communicate—in addition to checking the validity of the certificate by performing the other steps described in Server Authentication During SSL Handshake

Client Authentication During SSL Handshake

SSL-enabled servers can be configured to require client authentication, or cryptographic validation by the server of the client’s identity. When a server configured this way requests client authentication separate piece of digitally signed data to authenticate itself. The server uses the digitally signed data to validate the public key in the certificate and to authenticate the identity the certificate claims to represent.

The SSL protocol requires the client to create a digital signature by creating a one-way hash from data generated randomly during the handshake and known only to the client and server. The hash of the data is then encrypted with the private key that corresponds to the public key in the certificate being presented to the server.

To authenticate the binding between the public key and the person or other entity identified by the certificate that contains the public key, an SSL-enabled server must receive a yes answer to the first four questions shown in Figure 2–10. Although the fifth question is not part of the SSL protocol, directory servers can be configured to support this requirement to take advantage of the user entry in an LDAP directory as part of the authentication process.

Figure 2–10 Authentication and Verification During SSL Handshake

Figure shows authentication and verification.

An SSL-enabled server goes through the following steps to authenticate a user’s identity:

  1. Does the user’s public key validate the user’s digital signature?

    The server checks that the user’s digital signature can be validated with the public key in the certificate. If so, the server has established that the public key asserted to belong to John Doe matches the private key used to create the signature and that the data has not been tampered with since it was signed.

    At this point, however, the binding between the public key and the DN specified in the certificate has not yet been established. The certificate might have been created by someone attempting to impersonate the user. To validate the binding between the public key and the DN, the server must also complete steps 3 and 4 in this list.

  2. Is today’s date within the validity period?

    The server checks the certificate’s validity period. If the current date and time are outside of that range, the authentication process won’t go any further. If the current date and time are within the certificate’s validity period, the server goes onto the next step.

  3. Is the issuing CA a trusted CA?

    Each SSL-enabled server maintains a list of trusted CA certificates, represented by the shaded area on the right—hand side of Figure 2–10. This list determines which certificates the server accepts. If the DN of the issuing CA matches the DN of a CA on the server’s list of trusted CAs, the answer to this question is yes, and the server goes on to the next step. If the issuing CA is not on the list, the client is not authenticated unless the server can verify a certificate chain ending in a CA that is trusted or not trusted within their organizations by controlling the lists of CA certificates maintained by clients and servers.

  4. Does the issuing CA’s public key validate the issuer’s digital signature?

    The server uses the public key from the CA’s certificate (which it found in its list of trusted CAs in the previous step) to validate the CA’s digital signature on the certificate being presented. If the information in the certificate has changed since it was signed by the CA or if the public key in the CA certificate doesn’t correspond to the private key used by the CA to sign the certificate, the server won’t authenticate the user’s identity. If the CA’s digital signature can be validated, the server treats the user’s certificate as a valid “letter of introduction” from that CA and proceeds. At this point, the SSL protocol allows the server to consider the client authenticated and proceed with the connection as described in step 6. The directory servers may optionally be configured to perform step 5 before step 6.

  5. Is the user’s certificate listed in the LDAP entry for the user?

    This optional step provides one way for a system administrator to revoke a user’s certificate even if it passes the tests in all the other steps. The Certificate Management System can automatically remove a revoked certificate from the user’s entry in the LDAP directory. All servers that are set up to perform this step then refuses to authenticate that certificate or establish a connection. If the user’s certificate in the directory is identical to the user’s certificate presented in the SSL handshake, the server goes on to the next step.

  6. Is the authenticated client authorized to access the requested resources?

    The server checks what resources the client is permitted to access according to the server’s access control lists (ACLs) and establishes a connection with appropriate access. If the server doesn’t get to step 6 for any reason, the user identified by the certificate cannot be authenticated, and the user is not allowed to access any server resources that require authentication.

Digital Signatures

Digital signatures can be used by Directory Server to maintain integrity of information. If encryption and message digests are applied to the information being sent, the recipient can determine that the information was not tampered with during transit.

Tamper detection and related authentication techniques rely on a mathematical function called a one-way hash. This function is also called a message digest. A one-way hash is a number of fixed length with the following characteristics:

It is possible to use a private key for encryption and a public key for decryption. Although this is not desirable when you are encrypting sensitive information, it is a crucial part of digitally signing any data. Instead of encrypting the data itself, the signing software creates a one-way hash of the data, then uses your private key to encrypt the hash. The encrypted hash, along with other information, such as the hashing algorithm, is known as a digital signature. Figure 2–11 shows two items transferred to the recipient of some signed data.

Figure 2–11 Digital Signatures

Figure shows digital signatures

In Figure 2–11, the original data and the digital signature, which is basically a one-way hash (of the original data) that has been encrypted with the signer's private key. To validate the integrity of the data, the receiving software first uses the signer’s public key to decrypt the hash. It then uses the same hashing algorithm that generated the original hash to generate a new one-way hash of the same data. (Information about the hashing algorithm used is sent with the digital signature, although this isn’t shown in the figure.) Finally, the receiving software compares the new hash against the original hash. If the two hashes match, the data has not changed since it was signed. If they don’t match, the data may have been tampered with since it was signed, or the signature may have been created with a private key that doesn’t correspond to the public key presented by the signer.

If the two hashes match, the recipient can be certain that the public key used to decrypt the digital signature corresponds to the private key used to create the digital signature. Confirming the identity of the signer, however, also requires some way of confirming that the public key really belongs to a particular person or other entity.

The significance of a digital signature is comparable to the significance of a handwritten signature. Once you have signed some data, it is difficult to deny doing so later — assuming that the private key has not been compromised or out of the owner’s control. This quality of digital signatures provides a high degree of nonrepudiation — that is, digital signatures make it difficult for the signer to deny having signed the data. In some situations, a digital signature may be as legally binding as a handwritten signature.

Key Encryption

With most modern cryptography, the ability to keep encrypted information secret is based not on the cryptographic algorithm, which is widely known, but on a key. A key is a number that must be used with the algorithm to produce an encrypted result or to decrypt previously encrypted information. For information about encryption and decryption with keys, see the following sections:

Symmetric-Key Encryption

With symmetric-key encryption, the encryption key can be calculated from the decryption key, and vice versa. With most symmetric algorithms, the same key is used for both encryption and decryption. The following figure shows a symmetric-key encryption.

Figure 2–12 Symmetric-Key Encryption

Figure shows symmetric-key encryption.

Implementations of symmetric-key encryption can be highly efficient, so that users do not experience any significant time delay as a result of the encryption and decryption. Symmetric-key encryption also provides a degree of authentication, since information encrypted with one symmetric key cannot be decrypted with any other symmetric key. Thus, as long as the symmetric key is kept secret by the two parties using it to encrypt communications, each party can be sure that it is communicating with the other as long as the decrypted messages continue to make sense.

Symmetric-key encryption is effective only if the symmetric key is kept secret by the two parties involved. If anyone else discovers the key, it affects both confidentiality and authentication. A person with an unauthorized symmetric key not only can decrypt messages sent with that key, but can encrypt new messages and send them as if they came from one of the two parties who were originally using the key.

Symmetric-key encryption plays an important role in the SSL protocol, which is widely used for authentication, tamper detection, and encryption over TCP/IP networks. SSL also uses techniques of public-key encryption, which is described in the next section.

Public-Key Encryption

The most commonly used implementations of public-key encryption are based on algorithms patented by RSA Data Security. Therefore, this section describes the RSA approach to public-key encryption.

Public-key encryption (also called asymmetric encryption) involves a pair of keys—a public key and a private key—associated with an entity that needs to authenticate its identity electronically or to sign or encrypt data. Each public key is published, and the corresponding private key is kept secret. The following figure shows a simplified view of the way public-key encryption works.

Figure 2–13 Public-Key Encryption

Figure shows public-key encryption

Public—key encryption lets you distribute a public key, and only you can read data encrypted by this key. In general, to send encrypted data to someone, you encrypt the data with that person’s public key, and the person receiving the encrypted data decrypts it with the corresponding private key.

Compared with symmetric-key encryption, public-key encryption requires more computation and is therefore not always appropriate for large amounts of data. However, it’s possible to use public-key encryption to send a symmetric key, which can then be used to encrypt additional data. This is the approach used by the SSL protocol.

As it happens, the reverse of the scheme shown in Figure 2–13 also works: data encrypted with your private key can be decrypted with your public key only. This would not be a desirable way to encrypt sensitive data, however, because it means that anyone with your public key, which is by definition published, could decrypt the data. Nevertheless, private-key encryption is useful, because it means you can use your private key to sign data with your digital signature—an important requirement for electronic commerce and other commercial applications of cryptography. Client software can then use your public key to confirm that the message was signed with your private key and that it hasn’t been tampered with since being signed. Digital Signatures on Digital Signatures and subsequent sections describe how this confirmation process works.

Key Length and Encryption Strength

The strength of encryption is related to the difficulty of discovering the key, which in turn depends on both the cipher used and the length of the key. For example, the difficulty of discovering the key for the RSA cipher most commonly used for public-key encryption depends on the difficulty of factoring large numbers, a well-known mathematical problem.

Encryption strength is often described in terms of the size of the keys used to perform the encryption: in general, longer keys provide stronger encryption. Key length is measured in bits. For example, 128-bit keys for use with the RC4 symmetric-key cipher supported by SSL provide significantly better cryptographic protection than 40-bit keys for use with the same cipher. Roughly speaking, 128-bit RC4 encryption is 3 x 1026 times stronger than 40-bit RC4 encryption.

Different ciphers may require different key lengths to achieve the same level of encryption strength. The RSA cipher used for public-key encryption, for example, can use only a subset of all possible values for a key of a given length, due to the nature of the mathematical problem on which it is based. Other ciphers, such as those used for symmetric key encryption, can use all possible values for a key of a given length, rather than a subset of those values. Thus a 128-bit key for use with a symmetric-key encryption cipher would provide stronger encryption than a 128-bit key for use with the RSA public-key encryption cipher. This difference explains why the RSA public-key encryption cipher must use a 512-bit key (or longer) to be considered cryptographically strong, whereas symmetric key ciphers can achieve approximately the same level of strength with a 64-bit key. Even this level of strength may be vulnerable to attacks in the near future.

Attribute Encryption

Attribute encryption enables sensitive attributes of an entry to be stored in encrypted form. By encrypting sensitive attributes, you can prevent them from being read while the data is stored in database files, backup files, or exported LDIF files, or while the data is exported. Figure 2–14 shows a user entry being added to the database, where attribute encryption has been configured to encrypt the salary attribute.

Figure 2–14 Attribute Encryption

Figure shows attributes encrypted in the database.

The attribute encryption feature supports a wide range of encryption algorithms and different platforms. Attribute encryption uses the private key of the server’s SSL certificate to generate its own key. This key is then used to perform the encryption and decryption operations.

Attribute encryption is configured at the suffix level. This means that an attribute is encrypted for every entry in which it appears in a suffix. To encrypt an attribute in an entire directory, you must enable encryption for that attribute in every suffix.

If you choose to encrypt an attribute that some entries use as a naming attribute, values that appear in the DN will not be encrypted, but values stored in the entry will be encrypted.

Encrypting the userPassword attribute provides no security benefit unless the password needs to be stored in clear text, as is the for DIGEST-MD5 SASL authentication. If the password already has an encryption mechanism defined in the password policy, further encryption provides little additional security.

When encrypted attributes are stored, they are prefaced with a cipher tag that indicates what encryption algorithm has been used. An encrypted attribute using the DES encryption algorithm would appear as follows:


{CKM_DES_CBC}3hakc&jla+=snda%

While attribute encryption offers increased data security, the feature does impact performance. you should think carefully about which attributes require encryption and encrypt only those attributes that are particularly sensitive. Because sensitive data can be accessed directly through index files, it is necessary to encrypt the index keys corresponding to the encrypted attributes, to ensure that the attributes are fully protected.

For information about how to encrypt attributes, see Encrypting Attribute Values in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Chapter 3 Directory Server Monitoring

For information about monitoring Directory Server, see the following sections.

Ways to Monitor Directory Server

Directory Server can be monitored in the following ways:

Directory Service Control Center

Directory Service Control Center, DSCC, can be used to monitor current activities of a Directory Server instance.

DSCC provides general server information, including a resource summary, current resource usage, connection status, and global database cache information. It also provides general database information, such as the database type, status, and entry cache statistics. Cache information and information relative to each index file within the database is also provided. In addition, DSCC provides information relative to the connections and the operations performed on each chained suffix.

Command line

The dsconf command can be used to configure logging and to monitor the replication status of Directory Server. For information about how to configure logging, see Configuring Logs for Directory Server in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide. For information about how to use the dsconf command for monitoring, see Getting Replication Status by Using the Command Line in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

The ldapsearch command can be used to search the cn=monitor entry for information about current activities of a Directory Server instance. For information about cn=monitor, see Directory ServerMonitoring Attributes.

Log analyzer tool

The Directory Server Resource Kit provides a log analyzer tool called logconv(1).

The logconv tool extracts usage statistics and counts the occurrences of significant events in the access logs.

Java Management Extensions, JMX

Directory Server exposes management information through JMX according to the Common Monitoring Information and Data Model. See the Sun Java Enterprise System 5 Monitoring Guide for details.

Java ES Monitoring Framework, Java ES MF, provides an JMX entry point to retrieve data. For information about the JMX entry points exposed for monitoring Directory Server, see Directory Server and SNMP.

Simple Network Management Protocol, SNMP

Directory Server exposes management information through SNMP. See the Sun Java Enterprise System 5 Monitoring Guide for details.

Java ES MF provides an SNMP entry point to retrieve SNMP data. For information about the SNMP entry points exposed for monitoring Directory Server, see Directory Server and SNMP.

Simple Object Access Protocol, SOAP

Java ES MF provides a SOAP entry point to retrieve data. See the Sun Java Enterprise System 5 Monitoring Guide for details.

Directory Server and SNMP

Directory Server implements the dsTable and the dsApplIfOpsTable of the Directory Server Monitoring MIB defined by RFC 2605. It does not implement the dsIntTable.

Directory Server also implements the Network Services Monitoring MIB defined by RFC 2788.

Directory Server support for SNMP has the following limitations.

This rest of this section explains how the information flows from the monitoring application to Directory Server and back, particularly in the case where you use SNMP.

The SNMP interface is exposed by Java ES MF. See the Sun Java Enterprise System 5 Monitoring Guide for details.

The monitoring framework is contained within the Common Agent Container, cacao, which is installed alongside Directory Server. Figure 3–1 shows the monitoring framework.

Figure 3–1 Overall Monitoring Information Flow

Figure shows how information about Directory Server is monitored through a Common Agent Container.

SNMP support for monitoring Directory Server is managed by a Directory Server agent in the Common Agent Container. On Directory Server startup, the Monitoring server plug-in registers theDirectory Server instance with the Directory Server agent within the Common Agent Container.

Figure 3–2 shows how SNMP information about Directory Server flows through the Common Agent Container.

Figure 3–2 SNMP Information Flow

Figure shows how SNMP information about Directory Server flows through the Common Agent Container.

    SNMP information about Directory Server flows as follows.

  1. The network management station sends a GET message through the master SNMP agent, which by default uses standard port 161, to the SNMP mediation layer, which by default uses port 11161.

    For information about how to configure access to the SNMP mediation layer, see the Sun Java Enterprise System 5 Monitoring Guide.

  2. The SNMP mediation layer forwards any requests destined for the Directory Server to the Directory Server agent.

  3. When the server state changes, Directory Server pushes SNMP information to the Directory Server agent.

  4. The Directory Server agent relays the response back to the SNMP client via the SNMP mediation layer and master SNMP agent to the network management station. The network management station then displays the data through its network management application.

Directory Server and CMM/JMX

Directory Server supports monitoring through JMX, which is exposed by Java ES MF. See the Sun Java Enterprise System 5 Monitoring Guide for details on the interface itself.

The monitoring framework is contained within the Common Agent Container, cacao, which is installed alongside Directory Server. Figure 3–1 shows the monitoring framework. The information flow for JMX is similar to the flow shown for SNMP in Figure 3–2.

The monitoring information exposed through JMX is organized according to the Common Monitoring Information and Data Model, CMM. CMM allows applications exposing their monitoring information to associate human-readable descriptions with the individual counters and other information. CMM is therefore meant to be self-documenting. Directory Server implements the following CMM classes.

When examining the content of the monitoring information, notice that CMM_ServiceAccessURI is implemented not only for LDAP and for LDAPS, but also for DSML/HTTP or DSML/HTTPS if the DSML front end has been enabled.

Java ES Monitoring Console offers a browser-based user interface to examine the information exposed. See the Sun Java Enterprise System 5 Monitoring Guide for instructions on preparing the Monitoring Console for use.

Directory ServerMonitoring Attributes

Read-only monitoring information is stored under the cn=monitor entry.

cn=monitor

The cn=monitor entry is an instance of the extensibleObject object class. For cn=monitor configuration attributes to be taken into account by the server, this object class, in addition to the top object class, is present in the entry. The cn=monitor read-only attributes are presented in this section.

backendMonitorDN

DN for each Directory Server backend.

For further database monitoring information, refer to dse.ldif(4).

bytesSent

Number of bytes sent by Directory Server.

cache-avail-bytes

The number of bytes available for caching.

connection

List of open connections given in the following format:

connection=31:20010201164808Z:45:45::cn=admin,cn=Administrators,cn=config:LDAP

connectionPeak

Maximum number of simultaneous connections since server startup.

currentConnections

Number of current Directory Server connections.

currentTime

Current time usually given in Greenwich Mean Time, indicated by GeneralizedTime syntax Z notation, for example 20010202131102Z.

dTableSize

Size of the Directory Server descriptor table.

entriesSent

Number of entries sent by Directory Server.

nbackEnds

Number of Directory Server backends.

opsCompleted

Number of Directory Server operations completed.

opsInitiated

Number of Directory Server operations initiated.

request-que-backlog

The number of requests waiting to be processed by a thread. Each request received by the server is accepted, then placed in a queue until a thread is available to process it. The queue backlog should always be small, 0 or close to 0. If the queue backlog is large, use the nsslapd-threadnumber attribute to increase the number of threads available in the server.

readWaiters

Number of connections where some requests are pending and not currently being serviced by a thread in Directory Server.

currentpsearches

Number of persistent searches currently running on the server. You can set a maximum number of persistent searches on the server by using the command dsconf set-server-prop max-psearch-count:number.

startTime

Directory Server start time.

threads

Number of operation threads Directory Server creates during startup. This attribute can be set using the nsslapd-threadnumber attribute under cn=config. The nsslapd-threadnumber attribute is not present in the configuration by default, but can be added.

totalConnections

Total number of Directory Server connections.

version

Directory Server version and build number.

cn=disk,cn=monitor

The cn=disk entry enables you to monitor disk conditions over LDAP. This entry is an instance of the extensibleObject object class. A cn=disknumber,cn=disk,cn=monitor entry exists for each disk. The following disk monitoring attributes appear under each of these individual disk entries.

disk-dir

Specifies the pathname of a directory used by the server on disk. Where several database instances reside on the same disk or an instance refers to several directories on the same disk, the short pathname is displayed. The disk numbering is arbitrary.

disk-free

Indicates the amount of free disk space available to the server, in MB.

Note –

The disk space available to the server process may be less than the total free disk space. For example, on some platforms a process that is not running as root may not have all the free disk space available to it.

disk-state

Indicates the state of the disk, based on the available free space and on the thresholds set for disk low and disk full with the configuration parameters nsslapd-disk-low-threshold and nsslapd-disk-full-threshold. Possible values are normal, low, and full.

cn=counters,cn=monitor

This entry holds counter information for the various subtree entry counter plug-ins, if they are enabled.

cn=monitor,cn=Class of Service,cn=plugins, cn=config

This entry holds counters related to the Class of Service plug-in. This entry is an instance of the extensibleObject object class.

classicHashAvgClashListLength

When the CoS plug-in uses the hash table for fast lookup, if more than one classic CoS template corresponds to the hash key used, the plug-in next checks for matches in what is called the clash list, a list of templates sharing an identical hash key. The value of this attribute provides the average length across all hash tables of classic CoS template clash lists, giving some indication of how much linear searching the plug-in must perform after using the hash table during fast lookup.

classicHashAvgClashPercentagePerHash

The average number of clashes per hash table. That is, the average percentage per hash of classic CoS templates sharing an identical hash key.

classicHashMemUsage

The memory overhead in bytes to hold hash tables for fast classic CoS template lookups.

classicHashValuesMemUsage

The memory in bytes used to hold hash values for fast classic CoS template lookups.

numClassicDefinitions

The number of classic CoS definition entries in use.

numClassicHashTables

The number of hash tables created for fast lookup where more than 10 classic CoS templates apply for a single CoS definition. Hash tables are not created for smaller lists of templates.

numClassicTemplates

The number of classic CoS template entries in use.

numCoSAttributeTypes

The number of distinct attributes with values calculated through CoS.

numIndirectDefinitions

The number of indirect CoS definition entries in use.

numPointerDefinitions

The number of pointer CoS definition entries in use.

numPointerTemplates

The number of pointer CoS template entries in use.

Chapter 4 Directory Server Replication

This chapter includes the following sections:

Introduction to Replication

This introduction to replication addresses the following topics:

Types of Replica

A database that participates in replication is called a replica. There are three kinds of replica:

A single instance of Directory Server can be configured to manage several replicas.

A replica can act as a supplier of updates, or a consumer of updates, or both.

A replica can be promoted or demoted to change its behavior with respect to other replicas. Dedicated consumers can be promoted to hubs, and hubs can be promoted to masters. Masters can be demoted to hubs, and hubs can be demoted to dedicated consumers.

A server that contains a consumer replica only is called a dedicated consumer.

Unit of Replication

The smallest logical unit of replication is a suffix, also known as a naming context. The term suffix arises from the way the base DN for the naming context is a suffix for all DNs in that context. For example, the suffix dc=example,dc=com contains all directory entries in the Example.com naming context.

The replication mechanism requires one suffix to correspond to one database. The unit of replication applies to both suppliers and consumers. Therefore, two suffixes on a master replica cannot be replicated to one suffix on a consumer replica, and vice versa.

Replica Identity

Master replicas require a unique replica identifier that is a 16-bit integer between 1 and 65534. Consumer and hub replicas all have the replica ID of 65535. The replica ID identifies the replica on which changes are made.

If multiple suffixes are configured on one master, you can use the same replica ID for each suffix on the master. In this way, when a change is made on that replica ID, it is possible to identify the server on which change was made.

Replication Agreements

Replication agreements define the relationships between a supplier and a consumer. The replication agreement is configured on the supplier. A replication agreement contains the following replication parameters:

Replication Authentication

Before a master can update a consumer, the consumer authenticates the master by using a special entry called the Replication Manager entry. The master uses the Replication Manager entry to bind to the consumer.

The Replication Manager entry has a special user profile that bypasses all access control rules defined on the consumer server. The special user profile is only valid in the context of replication.

The Replication Manager entry has the following characteristics.

The Replication Manager entry is created by default when you configure replication through the browser-based interfaceDirectory Service Control Center. You can also create your own Replication Manager entry. For information about how to create a Replication Manager entry, see Using a Non-Default Replication Manager in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Authentication can be performed in the following ways for SSL with replication.

Replication Change Log

All modifications received by a master replica are recorded in a change log. A change log is maintained on all master replicas and hub replicas.

In earlier versions of Directory Server, the change log was accessible over LDAP. In this version of the product, the change log is not accessible over LDAP but is stored in its own database. If your application needs to read the change log, use the retro change log plug-in for backward compatibility. For more information about the retro change log plug-in, see Replication and the Retro Change Log Plug-In.

Change Sequence Number

Each change to a master replica is identified by a change sequence number, CSN. The CSN is generated by the master server and is not visible to the client application. The CSN contains the timestamp, a sequence number, the replica ID, and a subsequence number. The change log is ordered by the CSN.

Replica Update Vector

The replica update vector, RUV, identifies the state of each replica in a topology. Stored on the supplier and on the consumer, the RUV is used to establish which changes need to be replicated. The RUV stores the URL of the supplier, the ID of the supplier, the minimum CSN, and the maximum CSN.

RUVs can be read through nsds50ruv(5dsconf) and nsds50ruv(5dsconf) attributes.

Deleted Entries: Tombstones

Directory entries deleted on one replica are maintained by Directory Server until no longer needed for replication. Such deleted entries are called tombstones, as they have objectclass: nsTombstone. In rare cases, you might need to remove tombstones manually over LDAP.

Tombstones visible only to Directory Manager. Furthermore, tombstones show up only in a search with filter (objectclass=nsTombstone). The following ldapsearch command returns tombstone entries under dc=example,dc=com.


$ ldapsearch -D "cn=Directory Manager" -b dc=example,dc=com "(objectclass=nsTombstone)"

Consumer Initialization and Incremental Updates

During consumer initialization, or total update, all data is physically copied from a master to a consumer. When you have created a replication agreement, the consumer defined by that agreement must be initialized. When a consumer has been initialized, the master can begin to replay, or replicate, update operations to the consumer. Under normal circumstances, the consumer should not require further initialization. However, if the data on a master is restored from a backup, it might be necessary to re-initialize the consumers that depend on that master.

In a multi-master replication topology, the default behavior of a read-write replica that has been re-initialized from a backup or from an LDIF file, is to refuse client update requests. By default, the replica remains in read-only mode until it is configured to accept updates again. You set the suffix property repl-accept-client-update-enabled to on using the dsconf set-suffix-prop command when the oldest updates are on the read-only replica.

When a consumer has been initialized, replication updates are sent to the consumer when the modifications are made on the supplier. These updates are called incremental updates. A consumer can be incrementally updated by several suppliers at once, provided that the updates originate from different replica IDs.

The binary copy feature can be used to clone master replicas or consumer replicas by using the binary backup files of one server to restore another server. For information about how to use binary copy for replication, see Initializing a Replicated Suffix by Using Binary Copy in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Referrals and Replication

When a consumer receives a request to modify data, it does not forward the request to the server that contains the master replica. Instead, it returns to the client a list of the URLs of the masters that can satisfy the request. These URLs are called referrals.

The replication mechanism automatically configures consumers to return referrals for all known masters in the replication topology. However, you can also add your own referrals and overwrite the referrals set automatically by the server. The ability to control referrals helps enables you to perform the following tasks:

Directory Proxy Server is able to follow referrals.

Replication Configurations

This section covers the following topics:

For information about planning your replication, see the Sun Java System Directory Server Enterprise Edition 6.0 Deployment Planning Guide.

Multi-Master Replication

In multi-master replication, replicas of the same data exist on more than one server. For information about multi-master replication, see the following sections:

Concepts of Multi-Master Replication

In a multi-master configuration, data is updated on multiple masters. Each master maintains a change log, and the changes made on each master are replicated to the other servers. Each master plays the role of supplier and consumer.

Multi-master replication can cause synchronization conflicts. Conflicts are usually resolved automatically by using the timestamp associated with each change, where the most recent change takes precedence. Some rare conflicts must be resolved manually. For more information, see Solving Common Replication Conflicts in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Each supplier in a multi-master environment must have a replication agreement. The following figure shows two master servers and their replication agreements.

Figure 4–1 Multi-Master Replication Configuration (Two Masters)

Figures shows multi-master replication with two master servers and their replication agreements.

In the preceding figure, Master A and Master B have a master replica of the same data. Each master has a replication agreement that specifies the replication flow. Master A acts as a master in the scope of Replication Agreement 1, and as a consumer in the scope of Replication Agreement 2.

Multi-master replication can be used for the following tasks:

Multi-Master Replication Over Wide Area Networks

Directory Server supports multi-master replication over WANs, enabling multi-master replication configurations across geographical boundaries in international, multiple data center deployments.

The replication protocol provides full asynchronous support, window and grouping mechanisms, and support for compression. These features render multi-master replication over WAN a viable deployment possibility.

In a multi-master replication over WAN configuration, all instances of Directory Server separated by a WAN must support multi-master replication over WANs.

Group Mechanism and Window Mechanism

The group mechanism and window mechanism can be used to group changes rather than send them individually. The group mechanism and window mechanism can also be used to specify a number of requests that can be sent to the consumer without the supplier waiting for an acknowledgement from the consumer.

For information about how to adjust the group size and window size, see Configuring Network Parameters in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Replication Compression Mechanisms

Replication compression helps to streamline replication flow and avoid bottlenecks caused by limited bandwidth.

Fully Meshed Multi-Master Topology

In a fully meshed multi-master topology, each master is connected to each of the other masters. A fully meshed topology provides high availability and guaranteed data integrity. The following figure shows a fully meshed, four-way, multi-master replication topology with some consumers.

Figure 4–2 Fully Meshed, Four-Way, Multi-Master Replication Configuration

Figure shows a fully meshed, four-way, multi-master replication topology

In Figure 4–2, the suffix is held on four masters to ensure that it is always available for modification requests. Each master maintains its own change log. When one of the masters processes a modification request from a client, it records the operation in its change log. The master then sends the replication update to the other masters, and in turn to the other consumers. Each master also stores a Replication Manager entry used to authenticate the other masters when they bind to send replication updates.

Each consumer stores one or more entries that correspond to the Replication Manager entries. The consumers use the entries to authenticate the masters when they bind to send replication updates. It is possible for each consumer to have just one Replication Manager entry that enables all masters to use the same Replication Manager entry for authentication. By default, the consumers have referrals set up for all masters in the topology. When consumers receive modification requests from the clients, they send the referrals to back to the client. For more information about referrals, see Referrals and Replication.

Figure 4–3 presents a detailed view of the replication agreements, change logs, and Replication Manager entries that must be set up on Master A.Figure 4–4 provides the same detailed view for Consumer E.

Figure 4–3 Replication Configuration for Master A (Fully Meshed Topology)

Figure shows the replication agreements, change logs, and Replication Manager entries in a fully meshed replication topology.

Figure 4–4 Replication Configuration for Consumer Server E (Fully Meshed Topology)

Figure shows a detailed view of the Replication Manager entries that must be set up on Consumer E in a fully meshed topology.

Master A requires the following:

Consumer E requires the following:

Cascading Replication

In a cascading replication configuration, a server acting as a hub receives updates from a server acting as a supplier. The hub replays those updates to consumers. The following figure illustrates a cascading replication configuration.

Figure 4–5 Cascading Replication Configuration

Figure shows cascading replication.

Cascading replication is useful in the following scenarios:

The following figure shows cascading replication to a large number of consumers.

Figure 4–6 Cascading Replication to a Large Number of Consumers

Figure shows cascading replication to a large number of consumers with replication traffic through several hubs..

In Figure 4–6, hubs 1 and 2 relay replication updates to consumers 1 through 10, leaving the master replicas with more resources to process directory updates.

The masters and the hubs maintain a change log. However, only the masters can process directory modification requests from clients. The hubs contains a Replication Manager entry for each master that sends updates to them. Consumers 1 through 10 contain Replication Manager entries for hubs 1 and 2.

The consumers and hubs can process search requests received from clients, but cannot process modification requests. The consumers and hubs refer modification requests to the masters.

Prioritized Replication

In previous versions of Directory Server, updates were replicated in chronological order. In this version of the product, updates can be prioritized for replication. Priority is a boolean feature, it is on or off. There are no levels of priority. In a queue of updates waiting to be replicated, updates with priority are replicated before updates without priority.

Priority rules are configured with the following replication priority rule properties:

For information about these properties, see repl-priority(5dsconf).

When the master replicates an update to one or more hubs or consumer replicas, the priority of the update is the same across all of the hubs and consumer replicas. If one parameter is configured in a priority rule for prioritized replication, all updates that match that parameter are prioritized for replication. If two or more parameters are configured in a priority rule for prioritized replication, all updates that match all parameters are prioritized for replication.

In the following scenario, it is possible that a master replica attempts to replicate an update to an entry before it has replicated the addition of the entry:

In this scenario, the update operation cannot be replicated until the add operation is replicated. The update waits for its chronological turn, after the add operation, to be replicated.

Fractional Replication

Fractional replication can be used to replicate a subset of the attributes of all entries in a suffix or sub-suffix. Fractional replication can be configured, per agreement, to include attributes in the replication or to exclude attributes from the replication. Usually, fractional replication is configured to exclude attributes. The interdependency between features and attributes make managing a list of included attributes difficult.

Fractional replication can be used for the following purposes:

Fractional replication is configured with the replication agreement properties repl-fractional-include-attr and repl-fractional-exclude-attr attributes. For information about these properties, see repl-agmt(5dsconf). For information about how to configure fractional replication, see Fractional Replication in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Fractional replication is not backward compatible with versions of Directory Server prior to Directory Server 5.2. If you are using fractional replication, ensure that no other instances of Directory Server are prior to Directory Server 5.2.

Replication and the Retro Change Log Plug-In

The retro change log is a plug-in used by LDAP clients for maintaining application compatibility with earlier versions of Directory Server. The retro change log is stored in a separate database from the Directory Server change log, under the suffix cn=changelog.

A retro change log can be enabled on a standalone server or on each server in a replication topology. When the retro change log is enabled on a server, updates to all suffixes on that server are logged by default.

For information about how to use the retro change log, see Using the Retro Change Log in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Retro Change Log and Multi-Master Replication

When a retro change log is enabled with replication, the retro change log receives updates from all master replicas in the topology. The updates from each master replica are combined in the retro change log. The following figure illustrates the retro change log on two servers in a multi-master topology.

Figure 4–7 Retro Change Log and Multi-Master Replication

Figure shows the retro change log on two servers in a multi-master topology.

The retro change log uses the following attributes during replication:

changeNumber (cN)

Identifies the order in which an update is logged to the retro change log

replicationCSN (CSN)

Identifies the time when an update is made to a given replica

replicaIdentifier (RI)

Identifies the replica that is updating the retro change log

The diagram shows that the retro change logs, RCL1 and RCL2, contain the same list of updates, but that the updates do not have the same order. However, for a given replicaIdentifier, updates are logged in the same order on each retro change log. The order in which updates are logged to the retro change log is given by the changeNumber attribute.

Failover of the Retro Change Log

The following figure illustrates a simplified replication topology where a client reads a retro change log on a consumer server.

Figure 4–8 Simplified Topology for Replication of the Retro Change Log

Figure shows a simplified replication topology where a client reads a retro change log on a consumer server.

All of the updates made to each master replica in the topology are logged to each retro change log in the topology.

The client application reads the retro change log of Directory Server 3 and stores the last CSN for each replica identifier. The last CSN for each replica identifier is given by the replicationCSN attribute.

The following figure shows the client redirecting its reads to Directory Server 2 after the failure of Directory Server 3.

Figure 4–9 Failover of the Retro Change Log

Figure shows a client redirecting its reads to Directory Server 2 after the failure of Directory Server 3.

After failover, the client application must use the retro change log (RCL2) of Directory Server 2 to manage its updates. Because the order of the updates in RCL2 is not the same as the order in RCL3, the client must synchronize its updates with RCL2.

The client examines RCL2 to identify the cN that corresponds to its record of the last CSN for each replica identifier. In the example in Failover of the Retro Change Log, the client identifies the following correspondence between last CSN and cN:

The client identifies the update corresponding to the lowest cN in this list. In the example in Failover of the Retro Change Log, the lowest cN in the list is cN4. To ensure that the client processes all updates, it must process all updates logged to RCL2 after cN4. The client does not process updates logged to RCL2 before cN4 nor does it process the update corresponding to cN4.

Replication Conflicts and the Retro Change Log

When a replication conflict occurs, Directory Server performs operations to resolve the conflict. When the retro change log is running and the changeIsReplFixupOp attribute is set to true, the following information about the operations is logged in the changeHasReplFixupOp attribute:

For more information about these attributes, see the Sun Java System Directory Server Enterprise Edition 6.0 Man Page Reference.

Restrictions on Using the Retro Change Log

Observe the following restrictions when you use the retro change log:

Chapter 5 Directory Server Data Caching

For fast response time to client requests, Directory Server caches directory information in memory. If you must have top Directory Server performance, but cannot fit all directory data in available memory, you can tune cache settings to optimize performance.

This chapter covers what cache is, and also provides recommendations about tuning cache settings. This chapter includes the following sections:

Caches and How Directory Server Uses Them

This section describes the types of cache whose settings you can tune. It also describes how Directory Server uses those types of cache. This section covers the following topics:

Types of Cache

This section describes the types of cache used by Directory Server.

Figure 5–1 shows the caches for an instance of Directory Server with three suffixes, each with its own entry cache.

Directory Server also uses a file system cache. The file system cache is managed by the underlying operating system, and by I/O buffers in disk subsystems.

Figure 5–1 Entry and Database Caches in Context

Figure shows caches for an instance of Directory Server with three suffixes, each with its own entry cache.

Database Cache

Each instance of Directory Server has one database cache. The database cache holds pages from the database that contain indexes and entries. Each page is not an entry, but a slice of memory that contains a portion of the database.

Directory Server moves pages between the database files and the database cache to maintain the maximum database cache size you specify. The amount of memory used by Directory Server for the database cache can be larger than the specified size. This is because Directory Server requires additional memory to manage the database cache.

For very large database caches, it is important that the memory used by Directory Server does not exceed the size of available physical memory. If the available physical memory is exceeded, the system pages repeatedly and performance is degraded.

The memory can be monitored by empirical testing and by the use of tools such as pmap(1) on Solaris systems. The ps(1) utility can also be used with the -p pid and -o format options to view current memory used by a particular process such as Directory Server ns-slapd. For more information, refer to the operating system documentation.

For 32-bit servers, the database cache size must be limited so that the total Directory Server ns-slapd process size is less than the maximum process size allowed by the operating system. Usually, this limit is in the 2-3 GB range.

Entry Cache

The entry cache holds recently accessed entries that are formatted for delivery to client applications. The entry cache is allocated as required until it reaches the a size larger than, but based on the maximum entry cache size you specify.

As entries stored in the entry cache are already formatted, Directory Server returns entries from an entry cache efficiently. Entries in the database must be formatted and stored in the entry cache before they are delivered to client applications.

The maximum size you specify indicates how much memory Directory Server requests from the underlying memory allocation library. Depending on how the memory allocation library handles requests for memory, the actual memory used may be much larger than the amount of memory available to Directory Server for the entry cache.

The memory used by the Directory Server process depends on the memory allocation library that is used, and depends on the entries cached. Entries with many small attribute values usually require more overhead than entries with few large attribute values.

For 32-bit servers, the entry cache size must be limited so that the total Directory Server ns-slapd process size is less than the maximum process size allowed by the operating system. In practice, this limit is generally in the 2-3 GB range.

Import Cache

The import cache is created and used when a suffix is initialized. If the deployment involves offline suffix initialization only, import cache and database cache are not used together. In this case, the import cache and database cache do not need to be added together when the cache size is aggregated. See Total Aggregate Cache Size. When the import cache size is changed, the change takes effect the next time the suffix is reset and initialized. The import cache is allocated for the initialization, then released after the initialization.

Directory Server handles import cache in the same way as it handles database cache. Sufficient physical memory must be available to prevent swapping. The benefits of having a larger import cache diminish for cache sizes larger than 1 GB.

File System Cache

The operating system allocates available memory not used by Directory Server caches and other applications to the file system cache. The file system cache holds data recently that was read from the disk, making it possible for subsequent requests to obtain data from cache rather than to read it again from the disk. Because memory access is many times faster than disk access, leaving some physical memory available for the file system cache can boost performance.

For 32-bit servers, a file system cache can be used as a replacement for some of the database cache. Database cache is more efficient for Directory Server use than file system cache, but file system cache is not directly associated with the Directory Server ns-slapd process. Potentially, a larger total cache can be made available to Directory Server than would be available by using database cache alone.

64-bit servers do not have the same process size limit issue as 32-bit servers. Use database cache instead of file system cache with 64-bit servers.

Refer to the operating system documentation for information about file system cache.

Total Aggregate Cache Size

The sum of all caches used simultaneously must remain smaller than the total size of available physical memory, minus the memory intended for file system cache, minus the memory intended for other processes such as Directory Server itself.

For 32-bit servers, the total aggregate cache size must be limited so that the total Directory Server ns-slapd process size is less than the maximum process size allowed by the operating system. In practice, this limit is generally in the 2-3 GB range.

If suffixes are initialized while Directory Server is online, the sum of the database cache, the entry cache, and the import cache sizes should remain smaller than the total size of available physical memory.

Table 5–1 Import Operations and Cache Use

Cache Type  

Offline Import  

Online Import  

Database 

no 

yes 

Entry 

yes 

yes 

Import 

yes 

yes 

If all suffixes are initialized while Directory Server is offline, the import cache does not coexist with the database cache, so the same memory can be allocated to the import cache for offline suffix initialization and to the database cache for online use. If you opt to implement this special case, however, ensure that no online bulk loads are performed on a production server. The sum of the caches used simultaneously must remain smaller than the total size of available physical memory.

How Directory Server Performs Searches by Using Cache

In Figure 5–2, individual lines represent threads that access different levels of memory. Broken lines represent probable bottlenecks to minimize through effective tuning of Directory Server.

Figure 5–2 How Directory Server Performs Searches

Figure illustrates how Directory Server performs searches that specify a base DN and searches that use filters.

The following sections describe how Directory Server performs searches by using the cache. By processing subtree searches as described in the following sections, Directory Server returns results without loading the whole set of results into memory.

How Directory Server Performs Base Searches

    Base searches specify a base DN and are the simplest type of searches for Directory Server to manage. Directory Server processes base searches in the following stages.

  1. Directory Server attempts to retrieve the entry from the entry cache.

    If the entry is found in the entry cache, Directory Server checks whether the candidate entry matches the filter provided for the search.

    If the entry matches the filter provided for the search, Directory Server returns the formatted, cached entry to the client application.

  2. Directory Server attempts to retrieve the entry from the database cache.

    If the entry is found in the database cache, Directory Server copies the entry to the entry cache for the suffix. Directory Server proceeds as if the entry had been found in the entry cache.

  3. Directory Server attempts to retrieve the entry from the database itself.

    If the entry is found in the database, Directory Server copies the entry to the database cache . Directory Server proceeds as if the entry had been found in the database cache.

How Directory Server Performs Subtree and One-Level Searches

    Searches on a subtree or a level of a tree involve additional processing to handle multiple entries. Directory Server processes subtree searches and one-level search in the following stages.

  1. Directory Server attempts to define a set of candidate entries that match the filter from indexes in the database cache.

    If no appropriate index is present, the set of candidate entries must be found directly in the database itself.

  2. For each candidate entry, Directory Server performs the following tasks.

    1. Performs a base search to retrieve the entry.

    2. Checks whether the entry matches the filter provided for the search.

    3. Returns the entry to the client application if the entry matches the filter.

How Directory Server Performs Updates by Using the Cache

In Figure 5–3, individual lines represent threads that access different levels of memory. Broken lines represent probable bottlenecks to minimize through effective tuning of Directory Server.

Figure 5–3 How Directory Server Performs Updates

Figure illustrates how Directory Server manages updates.

The figure does not show the impact of the internal base search performed to get the entry for update.

    Directory Server processes updates in the following stages.

  1. Directory Server performs a base DN search to retrieve the entry, or to update or verify the entry in the case of an add operation that it does not already exist.

  2. Directory Server updates the database cache and any indexes affected.

    If data affected by the change have not been loaded into the database cache, this step can result in disk activity while the relevant data are loaded into the cache.

  3. Directory Server writes information about the changes to the transaction log and waits for the information to be flushed to disk, which happens periodically, at each checkpoint. Directory Server database files are thus updated during the checkpoint operation, not for each write.

  4. Directory Server formats and copies the updated entry to the entry cache for the suffix.

  5. Directory Server returns an acknowledgement of successful update to the client application.

How Directory Server Initializes a Suffix by Using the Cache

The following figure illustrates how Directory Server initializes a suffix by using the cache. Individual lines represent threads that access different levels of memory. Broken lines represent probable bottlenecks to minimize through effective tuning of Directory Server.

Figure 5–4 How Directory Server Initializes a Suffix

Figure illustrates how Directory Server initializes a suffix by using the cache.

Directory Server initializes a suffix in the following stages:

  1. Starts a thread to feed an entry cache, used as a buffer, from LDIF.

  2. Starts a thread for each index affected and a thread to create entries in the import cache. These threads consume entries fed into the entry cache.

  3. Reads from and writes to the database files when import cache runs out.

Directory Server can also write log messages during suffix initialization, but does not write to the transaction log.

Tools for suffix initialization delivered with Directory Server provide feedback on the cache hit rate and import throughput. If cache hit rate and import throughput drop together, it is possible that the import cache is too small.

Tuning Cache Settings

This section provides recommendations for setting database and entry cache sizes. It does not cover import cache sizes.

The recommendations here pertain to maximizing either search rate or modify rate, not both at once.

This section covers the following topics:

Basic Tuning Recommendations

Here you find the basic recommendations for maximizing search rates or maximizing modification rates achieved by Directory Server. Set cache sizes according to the following recommendations:

For Maximum Search Rate (Searches Only)

If the directory data do not fit into available physical memory, or only just fit with no extra room to spare, set cache sizes to their minimum values, 500k for db-cache-size, 200k for entry-cache-size, and allow the server to use as much of the operating system's file system cache as possible.

If the directory data fit into available physical memory with physical memory to spare, allocate memory to the entry cache until either the entry cache is full or, on a 32–bit system, the entry cache reaches maximum size. Then allocate memory to the database cache until it is full or reaches maximum size.

See Configuring Memory in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide for instructions on setting cache sizes.

For Maximum Modification Rate (Modifications Only)

If the directory data do not fit into available physical memory, or only just fit with no extra room to spare, set the entry cache sizes to the minimum value, 200k for entry-cache-size, set the database cache to a value in the 100M to 1G range, and allow the server to use as much of the operating system's file system cache as possible. Keeping some database cache available ensures the modifications to remain cached between each database checkpoint.

If the directory data fit into available physical memory with physical memory to spare, allocate memory to the entry cache until either the entry cache is full or, on a 32–bit system, the entry cache reaches maximum size. Then allocate memory to the database cache until it is full or reaches maximum size.

See Configuring Memory in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide for instructions on setting cache sizes.

Small, Medium, and Large Data Sets

A working set refers to the data actually pulled into memory so the server can respond to client applications. The data set here is then the entries in the directory that you see are in fact getting used due to client traffic. The data set may include every entry in the directory, or may be composed most of the time of the some smaller number of entries, such as entries corresponding to people in a time zone where users are active.

We define three data set sizes, based on how much of the directory data set fits into available physical memory:

Small

The data set fits entirely into physical memory with fully-loaded database and entry caches.

Medium

The data set fits in physical memory, and extra physical memory can be dedicated to entry cache.

Large

The data set is too small to fit completely in available physical memory.

The ideal case is of course the small data set. If your data set is small, set database cache size and entry cache size such that all entries fit in both the database cache and the entry cache.

The following sections provide recommendations for medium and large data sets where the server performs either all searches or all modify operations.

Optimum Search Performance (Searches Only)

Figure 5–5 shows search performance on a hypothetical system. As expected, Directory Server offers top search performance for a given system configuration when the whole data set fits into memory.

Figure 5–5 Search Performance

Performance improves as more of the data set fits into memory.

For large data sets better performance has been observed when database cache and entry cache are set to their minimum sizes and available memory is left to the operating system for use in allocating file system cache. As shown, performance improves when more of the data set fits into the file system cache.

For medium data sets better performance has been observed when the file system cache holds the whole data set, and extra physical memory available is devoted to entry cache. As shown, performance improves when more of the medium data set fits in entry cache.

Optimum Modify Performance (Modifications Only)

Figure 5–6 shows modify performance on a hypothetical system. As expected, Directory Server offers top modify performance for a given system configuration when the whole data set fits into memory.

Figure 5–6 Modify Performance

Performance improves as more of the data set fits into memory.

For large data sets better performance has been observed when database cache and entry cache are set to their minimum sizes and available memory is left to the operating system for use in allocating file system cache. As shown, performance improves when more of the data set fits into the file system cache.

For medium data sets, modify performance reaches its maximum as all entries fit into file system cache. As suggested in Basic Tuning Recommendations, keeping some database cache available ensures the modifications to remain cached between each database checkpoint.

Chapter 6 Directory Server Indexing

Like a book index, Directory Server indexes speed up searches by associating search strings with the contents of a directory. For information about indexes used by Directory Server, see following sections:

Overview of Indexes

Directory Server uses indexes to speed up search operations by associating lookup information with Directory Server entries. During a search operation, Directory Server uses the index to find entries that match the search key . Without an index, Directory Server must check every entry in a suffix to find matches for the search key.

Indexes are stored in database files, and are created and managed independently for each suffix in a directory. Each index file contains all of the indexes defined in the suffix for a given attribute. For example, all indexes maintained for the cn attribute are stored in the databaseName_cn.db3 file. When an indexed entry is modified, Directory Server updates the index files.

Directory Server supports the following types of indexes:

Tuning Indexes for Performance

The use of indexes can enhance performance by reducing the time taken to perform a search. However, indexes also have an associated cost. When an entry is updated, the indexes referring to that entry must also be updated. The more an entry is indexed, the more resources are required to update the index; indexes take up disk space and memory space.

When you design indexes, ensure that you offset the benefit of faster searches against the associated costs of the index. Maintaining useful indexes is good practice; maintaining unused indexes for attributes on which clients rarely search is wasteful.

You can optimize performance of searches in the following ways:

To prevent Directory Server from performing searches on non-indexed entries, set the require-index-enabled suffix property for the suffix.

To limit the number of values per index key for a given search you can set an index list threshold. If the number of entries in the list for a search key exceeds the index list threshold, an unindexed search is performed. The threshold can be set for an entire server instance, for an entire suffix, and for an individual attribute type. You can also set individual thresholds for equality, presence, and substring indexes.

For a detailed procedure on how to change the index list threshold, seeChanging the Index List Threshold in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide. This procedure modifies the all-ids-threshold configuration property.

The global value of all-ids-threshold for the server instance should be about 5% of the total number of entries in the directory. For example, the default value of 4000 is generally right for instances of Directory Server that handle 80 000 entries or less. You should avoid setting the threshold above 50 000, even for very large deployments. However, you might set all-ids-threshold to a value other than the 5% guideline in the following situations:

You should limit the number of unindexed searches that are performed. Use the logconv utility provided with the Directory Server Resource Kit to examine the access logs for evidence of frequent unindexed searches. For more information, see the logconv(1) man page.

System Indexes and Default Indexes

This section addresses the following topics:

System Indexes

System indexes are required for Directory Server to function properly and efficiently. System indexes cannot be deleted or modified. Table 6–1 lists the system indexes created automatically in every suffix.

Table 6–1 System Indexes in Every Suffix

Attribute 

Equality Index 

Presence Index 

Description 

aci

 

X 

Allows the directory server to quickly obtain the access control information maintained in the directory 

ancestorid

X 

 

Enhances directory performance during subtree searches 

entrydn

X 

 

Speeds up entry retrieval based on DN searches 

id2entry

X 

 

Contains the actual database of directory entries. All other database files can be recreated from this one 

nsUniqueId

X 

 

Used to search for specific entries 

nscpEntryDN

X 

 

Used internally in Directory Server for replication 

nsds5ReplConflict

X 

X 

Helps to find replication conflicts 

numsubordinates

 

X 

Used by Directory Service Control Center to enhance display performance on the Directory tab 

objectClass

X 

 

Accelerate subtree searches 

parentID

X 

 

Enhances directory performance during one-level searches 

Default Indexes

When you create a new suffix in your directory, the server configures a set of default indexes in the corresponding database directory. The default indexes can be modified depending on your indexing needs, although you should ensure that no server plug-ins or other servers in your enterprise depend on an indexed attribute before you eliminate index.

Table 6–2 lists the default indexes that are configured in Directory Server.

Table 6–2 Default Indexes in Every New Suffix

Attribute 

Equality Index 

Presence Index 

Substring Index 

Description 

cn

X 

X 

X 

Improves the performance of the most common types of directory searches. 

givenName

X 

X 

X 

Improves the performance of the most common types of directory searches. 

mail

X 

X 

X 

Improves the performance of the most common types of directory searches. 

mailAlternateAddress

X 

   

Used by Messaging Server. 

mailHost

X 

   

Used by Messaging Server. 

member

X 

   

Improves server performance. This index is also used by the referential integrity plug-in.  

nsCalXItemId

X 

X 

X 

Used by Calendar Server. 

nsLIProfileName

X 

   

Used by roaming feature of Messaging Server. 

nsRoleDN

X 

   

Improves the performance of role-based operations. 

nswcalCALID

X 

   

Used by Calendar Server. 

owner

X 

   

Improves server performance. This index is also used by the referential integrity plug-in.  

pipstatus

X 

   

Used by other servers. 

pipuid

 

X 

 

Used by other servers. 

seeAlso

X 

   

Improves server performance. This index is used by the referential integrity plug-in.  

sn

X 

X 

X 

Improves the performance of the most common types of user directory searches. 

telephoneNumber

X 

X 

X 

Improves the performance of the most common types of user directory searches. 

uid

X 

   

Improves server performance. 

uniquemember

X 

   

Improves server performance. This index is also used by the referential integrity plug-in.  

Types of Index

With the exception of the approximate index, the indexes in this section are used by Directory Server to speed up basic matching rules. This section covers the following index types:

Presence Index

The presence index includes all entries in the database that have a value for a specified attribute, irrespective of that value. The following figure shows a presence index for the nsRoleDN attribute. For information about this attribute, see nsRoleDN(5dsat).

Figure 6–1 Presence Index

Illustration of a presence index for the nsRoleDN attribute.

Directory Server uses the value of the entryid attribute to store a reference to the entry. Directory Server retrieves the entry by using the instance-path/db/dbinstance/dbinstance_id2entry.db3 index file, where dbinstance depends on the database identifier.

When Directory Server receives a request to remove an attribute value indexed for presence, it must remove the entry from the presence index for that attribute before acknowledging the update to the client application.

The cost of presence indexes is generally low, although the list of entries maintained for a presence index may be long. When the index list length is small, presence indexes are useful for attributes in a relatively small percentage of directory entries.

Equality Index

The equality index includes all entries in the database that have a specified value for a given attribute. This index requires a value to be specified in the search filter. The following figure shows an equality index for the sn, surname, attribute. The index maintains a list of values for the sn attribute. For information about this attribute, see sn(5dsat).

Figure 6–2 Equality Index

Illustration of a equality index for the sn attribute.

When Directory Server receives a request to update an entry indexed for equality, it must do the following tasks before performing the update and acknowledging the update to the client:

The cost of equality indexes is generally lower than for substring indexes, but equality indexes require more space than presence indexes. Some client applications such as messaging servers might rely on equality indexes for search performance. Avoid using equality indexes for large binary attributes such as photos and hashed passwords.

Substring Index

Substring indexes are used for searches on three-character groups, for example, sn=*abc*. The three-character groups are stored in the index. Substring indexes cannot be applied to binary attributes such as photos. The following figure shows a substring index for the SN attribute.

Figure 6–3 Substring Index for the SN Attribute

Illustration of a substring index for the SN attribute.

The Directory Server search algorithm includes optimizations for the following searches, however, these searches are more likely to reach the index list threshold:

Directory Server builds an index of substrings according to its own built-in rules. Substring indexes cannot be configured by the system administrator.

When Directory Server receives a request to update an entry that has an attribute indexed for substrings, it must do the following tasks before performing the update and acknowledging the update to the client:

Maintaining substring indexes is relatively costly; the cost is a function of the length of the string indexed. To minimize cost, avoid unnecessary substring indexes, especially for attributes that have potentially long string values such as a description.

Browsing Index

Browsing indexes are also called virtual list view indexes. Browsing indexes are used for search operations that request server-side sorting or virtual list view, VLV, results. By using browsing indexes, you can improve the performance of searches that request server-side sorting of a large number of results. Depending on your directory configuration, the server may refuse to perform searches that request sorting when no browsing index is defined. This prevents large sorting operations from overloading server resources.

Browsing indexes are configured with the following parameters in the vlvSearch(5dsoc) object class, vlvBase(5dsat), vlvScope(5dsat), and vlvFilter(5dsat). Browsing index are sorted by the following parameter in the vlvIndex(5dsoc) object class, vlvSort(5dsat).

    Browsing indexes are configured in two steps.

  1. The base of the search, the scope of the search, and a filter for the search are configured by the vlvBase, vlvScope, and vlvFilter attributes in the vlvSearch object class.

  2. The name of the attributes that sort the index are configured by the vlvSort attribute in the vlvIndex object class.

The following figure shows a browsing index.

Figure 6–4 Representation of a Browsing Index

Illustration of a browsing index.

When Directory Server receives a request to update an entry with a vlvFilter value, it must do the following tasks before performing the update and acknowledging the update to the client:

Approximate Index

Approximate indexes work with the English language only to provide efficient “sounds-like” searches. For example, the approximate index is useful for searching partial names or misspelled names. Directory Server uses a variation of the metaphone phonetic algorithm to perform searches on an approximate index. Because the algorithm is based loosely on syllables, it is not effective for attributes that contain numbers, such as telephone numbers.

International Index

International indexes are also called matching rule indexes. International indexes associate language-specific matching rules with attributes. This index type enables attributes to be sorted and searched for in accordance with the language rules. International indexes use matching rules for particular locales to maintain indexes.

Standard support for international and other types of indexing can be extended by using a custom matching rule server plug-in.

Chapter 7 Directory Server Logging

For information about the types of logs used in Directory Server and for a description of the server logs, see the following sections:

Introduction to Logs

The following table summarizes the different logs used by the Directory Server.

Table 7–1 Logs Used by Directory Server

Log 

Type 

Description 

Retro change log 

Database 

Maintaining application compatibility with earlier versions of Directory Server. 

Transaction log 

Database 

Ensuring data integrity by committing each update operation to the transaction log on disk before the result code for the update operation is returned to the client application. 

When Directory Server accepts an update operation, it writes a log message about the operation to the transaction log. If the system crashes, Directory Server uses the transaction log to recover the database. 

Access log 

Flat file 

Evaluating directory use patterns, verifying configuration settings, diagnosing access problems. For information about access logs, see Access Logs.

Error log 

Flat file 

Debugging directory deployments. For information about error logs, see Error Logs.

Audit log 

Flat file 

Providing audit trails for security and data integrity. For information about audit logs, see Audit Logs.

Retro Changelog

The following server properties configure the retro change log.

retro-cl-deleted-entry-attr

Attributes to record when an entry is deleted

retro-cl-enabled

Whether the retro changelog is enabled

retro-cl-ignored-attr

Attributes not to record when updates occur

retro-cl-max-age

Maximum age of records maintained

retro-cl-max-entry-count

Maximum total records maintained

retro-cl-path

File system directory where the log is housed

retro-cl-suffix-dn

Suffixes for which the log is maintained

See server(5dsconf) for details.

Transaction Log

The following server properties configure the transaction log.

db-checkpoint-interval

How often Directory Server checkpoints the transaction log, ensures the entire database system is synchronized to disk, and cleans up transaction logs

db-durable-transaction-enabled

Whether update operations are committed to the transaction log on disk before result codes are sent to clients

db-log-buf-size

The buffer size for log information stored in memory until the buffer fills or the transaction commit forces the buffer to be written to disk

db-log-path

The path of the transaction log

db-batched-transaction-count

How many updates are accumulated before being committed to the directory database

See server(5dsconf) for details.

Access, Error, and Audit Logs

Access logs, error logs and audit logs are flat files that contain information about operations. For information about how to view and configure logs, see Chapter 14, Directory Server Logging, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

By default, the logs are stored in the directory instance-path/logs/.

Log files can be rotated on demand, or can be scheduled to be rotated on a specific day-of-the week and time of day, or when the log file exceeds a specified minimum size.

Old log files are stored in the same path with the same name and an extension that contains the date that the file was created, in the format filename.YYYYMMDD-hhmmss. The server also maintains a file with the same name and the .rotationinfo extension to record the creation dates of all log files.

For information about access logs, error logs and audit logs, see the following sections:

Access Logs

Access logs contain information about connections between an LDAP client and a directory server. A connection is a sequence of requests from the same client, and can contain the following components:

Error Logs

Error logs contain a unique identifier of the error, warning or information message, and a human readable message. Errors are defined according to the following severity.

Error

The error is severe. Immediate action should be taken to avoid the loss or corruption of directory data.

Warning

The error is important. Action should be taken at some stage to prevent a severe error occurring in the future.

Info

An informative message, usually describing server activity. No action is necessary.

Audit Logs

Audit logs contain records of all modifications to configuration or suffix entries. The modifications are written in LDIF format.

Audit logging is not enabled by default. To enable audit logging, use the procedure To Enable the Audit Log in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Content of Access, Error, and Audit Logs

The remainder of this chapter describes each of the parts of the log files.

Time Stamp

Each line of an access log file begins with a timestamp of this format:[20/Dec/2006:11:39:51 -0700]. The time stamp, -0700 indicates the time difference in relation to GMT.

The format of the time stamp can vary according to your platform. The connection, closed, and abandon records appear individually. All other records appear in pairs, consisting of a request for service record followed by a result record. The record pairs usually, but not exclusively, appear on adjacent lines.

Connection Number

The connection number is represented by conn=value. Every external request is listed with an incremental connection number.

When conn=Internal the operation is an internal operation. To log internal access operations, specify an access logging level of acc-internal in the dsconf configuration attribute.

File Descriptor

The file descriptor is represented by fd=value.

Every connection from an external LDAP client to a directory server requires a file descriptor from the operating system. The file descriptor is taken from a pool of available file descriptors.

Slot Number

The slot number has the same meaning as file descriptor. Slot number is a legacy section of the access log and can be ignored.

Operation Number

The operation number is represented by op=value.

For a connection, all operation request and result pairs are given incremental operation numbers beginning with op=0. The operation number identifies the operation being performed.

When op=-1, the LDAP request for the connection was not issued by an external LDAP client, but was initiated internally.

Method Type

The method type is represented by method=value.

The method type indicates which bind method was used by the client. The method type can have one of the following values.

0

No authentication

128

Simple bind with user password

sasl

SASL bind using external authentication mechanism

LDAP Version

The LDAP version can be LDAPv2 or LDAPv3. The LDAP version gives the LDAP version number that the LDAP client used to communicate with the LDAP server.

Error Number

The error number is represented by err=number.

The error number provides the LDAP result code returned from the LDAP operation. The LDAP error number 0 means that the operation was successful. For a list of LDAP result codes refer to Result Codes in Log Files.

Tag Number

The tag number is represented by tag=value.

The tags are used internally for message decoding and are not intended for use outside. The following tags are used most often.

tag=97

A client bind operation

tag=100

The entry for which you were searching

tag=101

The result from a search operation

tag=103

The result from a modify operation

tag=105

The result from an add operation

tag=107

The result from a delete operation

tag=109

The result from a modify DN operation

tag=111

The result from a compare operation

tag=115

A search reference when the entry you perform your search on holds a referral to the entry you require. Search references are expressed in terms of a referral.

tag=120

A result from an extended operation

Number of Entries

The number of entries is represented by nentries=value.

The number of entries indicates the number of entries that matched an LDAP search request.

Elapsed Time

The elapsed time is represented by etime=value.

Elapsed time indicates the time that it took to perform the LDAP operation. An etime value of 0 means that the operation took milliseconds to perform.

To log the time in microseconds, specify an access logging level of acc-timing in the dsconf configuration attribute.

LDAP Request Type

The LDAP request type indicates the type of LDAP request made by the client. The following types of LDAP requests can be made:

SRCH

Search

MOD

Modify

DEL

Delete

ADD

Add

MODDN

Modify DN

EXT

Extended operation

ABANDON

Abandon operation

LDAP Response Type

The LDAP response type indicates the LDAP response being returned by the server. The following LDAP responses can be returned:

RESULT

Result

ENTRY

Entry

REFERRAL

Referral or search reference

Unindexed Search Indicator

The unindexed search indicator is represented by notes=U.

In an unindexed search, the database is searched instead of the index file. Unindexed searches occur for the following reasons:

An unindexed search indicator is often accompanied by a large etime value because unindexed searches are usually more time consuming than indexed searches.

Extended Operation OID

An extended operation OID is represented by EXT oid="OID number". See extended-operations(5dsconf) for a list of supported extended operations.

Change Sequence Number in Log Files

The replication change sequence number is represented in log files by csn=value.

The presence of a change sequence number indicates that replication is enabled for this naming context.

Abandon Message

The abandon message is represented by ABANDON.

The presence of the abandon message indicates that an operation has been aborted. If the message ID succeeds in locating the operation that has been aborted, the log message reads as follows:

conn=12 op=2 ABANDON targetop=1 msgid=2 nentries=0 etime=0

However, if the message ID does not succeed in locating the operation, or if the operation had already finished prior to the ABANDON request being sent, then the log message reads as follows:

conn=12 op=2 ABANDON targetop=NOTFOUND msgid=2

The abandon message uses the following parameters:

nentries

Gives the number of entries sent before the operation was aborted

etime

Gives the number of seconds that elapsed before the operation was aborted

targetop

Identifies the operation to be aborted. If the value is NOTFOUND, the operation to be aborted was either an unknown operation or already complete

Message ID

The message ID is represented by msgId=value.

The message ID is the LDAP operation identifier generated by the client. The message ID can have a different value to the operation number, but identifies the same operation. The message ID in an ABANDON operation specifies which client operation is being abandoned.

The operation number starts counting at 0. However, in many client implementations the message ID number starts counting at 1. This explains why the message ID is frequently equal to the operation number plus 1.

SASL Multi-Stage Bind Logging

Directory Server logs each stage in the multi stage bind process and, where appropriate, the progress statement SASL bind in progress is included.

The DN used for access control decisions is logged in the BIND result line and not in the bind request line.

conn=14 op=1 RESULT err=0 tag=97 nentries=0 etime=0 dn="uid=myname,dc=example,dc=com"

For SASL binds, the DN value displayed in the BIND request line is not used by the server and is, therefore, not relevant. However, for SASL binds, the authenticated DN must be used for audit purposes. Therefore, the authenticated DN must be clearly logged. Having the authenticated DN logged in the BIND result line avoids any confusion as to which DN is which.

Options Description

The options description, options=persistent, indicates that a persistent search is being performed. Persistent searches can be used as a form of monitoring and can be configured to return changes to given configurations. The access log distinguishes between persistent and regular searches.

Connection Codes in Log Files

A connection code is included in the closing message of a log file. The connection code provides additional information about why the connection was closed. The following table describes the common connection codes.

Table 7–2 Summary of Connection Codes

Connection Code 

Description 

A1 

The client has closed the connection without performing an UNBIND. 

B1 

This connection code can have one of the following causes: 

  • The client has closed the connection without performing an UNBIND.

  • The BER element was corrupt. If BER elements, which encapsulate data being sent over the wire, are corrupt when they are received, a B1 connection code is logged to the access log. BER elements can be corrupted by physical layer network problems or bad LDAP client operations, such as an LDAP client aborting before receiving all request results.

B2 

The BER element is longer than the nsslapd-maxbersize attribute value.

B3 

A corrupt BER tag was encountered. 

B4 

The server failed to flush data response back to client. This code can occur when the client closes the connection to the server, before the server finished sending data to the client. 

P1 

The client connection was closed by a custom plug-in. None of the plug-ins provided by Directory Server close a connection. 

P2 

A closed connection or corrupt connection has been detected. 

T1 

The server closed the client connection because it was idle for longer than the idle-timeout server property.

T2 

The server closed the client connection because it was stalled for longer than the nsslapd-ioblocktimeout attribute value. This code can occur for the following reasons:

  • There is a network problem.

  • The server sends a lot of data to the client but the client does not read the data. As a result, the server’s transmit buffer becomes full.

U1 

The server closed the client connection because client sent an UNBIND request. 

Result Codes in Log Files

The following tables summarizes the LDAP result codes generated by an LDAP server and an LDAP client.

Table 7–3 Summary of Result Codes for LDAP Servers

Result Code 

Description 

0 

Success 

1 

Operations error 

2 

Protocol error 

3 

Time limit exceeded 

4 

Size limit exceeded 

5 

Compare false 

6 

Compare true 

7 

Authentication method not supported 

8 

Strong authentication required 

9 

Partial results and referral received 

10 

Referral received 

11 

Administrative limit exceeded 

12 

Unavailable critical extension 

13 

Confidentiality required 

14 

SASL bind in progress 

16 

No such attribute 

17 

Undefined attribute type 

18 

Inappropriate matching 

19 

Constraint violation 

20 

Type or value exists 

21 

Invalid syntax 

32 

No such object 

33 

Alias problem 

34 

Invalid DN syntax 

35 

Object is a leaf 

36 

Alias de-referencing problem 

48 

Inappropriate authentication 

49 

Invalid credentials 

50 

Insufficient access 

51 

Server is busy 

52 

Server is unavailable 

53 

Server is unwilling to perform 

54 

Loop detected 

64 

Naming violation 

65 

Object class violation 

66 

Operation not permitted on a non-leaf entry 

67 

Operation not permitted on a RDN 

68 

Entry already exists 

69 

Cannot modify object class 

70 

Results too large 

71 

Affects multiple servers 

76 

Virtual list view error 

Table 7–4 Summary of Result Codes for LDAP Clients

Result Code 

Description 

80 

Unknown error 

81 

Cannot contact LDAP server 

82 

Local error 

83 

Encoding error 

84 

Decoding error 

85 

Timed out 

86 

Unknown authentication method 

87 

Bad search filter 

88 

User cancelled operation 

89 

Bad parameter to an LDAP routine 

90 

Out of memory 

91 

Cannot connect to the LDAP server 

92 

Not supported by this version of LDAP 

93 

Requested LDAP control not found 

94 

No results returned 

95 

Additional results to return 

96 

Client detected loop 

97 

Referral hop limit exceeded 

Chapter 8 Directory Server Groups and Roles

This chapter describes how groups and roles are used by Directory Server to associate entries with each other. For information about groups and roles, see the following sections.

Directory Server Groups

A group is an entry that identifies the other entries that are in a group. Static and dynamic groups are supported. The group mechanism makes it easy to retrieve a list of entries that are members of a given group.

Static Groups

Static groups specify the DN of each member of the group. Static groups use one of the following object class and attribute pairs:

The member attribute and uniqueMember attribute contain the DN for every entry that is a member of the group. The uniqueMember attribute value for the DN is optionally followed by a hash, #, and a unique identifier label to guarantee uniqueness.

Dynamic Groups

Dynamic groups specify one or more URL search filters. All entries that match the URL search filters are members of the group. Membership of a dynamic group is defined each time the filters are evaluated. Dynamic groups use one of the following object class and attribute pairs:

The memberURL attribute and the uniqueMember attribute specify one or more one or more URL search filters.

Nested Groups

Static groups can be nested by specifying the DN of another group as a value for the member attribute or uniqueMember attribute.

Mixed Groups

Directory Server also supports mixed groups, that is groups that reference individual entries, static groups, and dynamic groups.

Directory Server Roles

Roles are similar to groups but work in the opposite way — where a group entry lists the DN of the member entries, the DN of a role entry is listed on each member entry. The role mechanism makes it is easy to retrieve a list of roles that are assigned to an entry.

Each role has members, or entries that possess the role. The role mechanism is managed by the nsRoleDN attribute and the nsRole attribute. The nsRoleDN attribute is used to add an entry to a role. The nsRole attribute is a read-only attribute, maintained by the directory server, that lists the roles to which an entry belongs. The nsRole attribute can be read or searched by clients to enumerate all roles to which an entry belongs. If you do not want to expose role membership, define access controls to read-protect the nsRole attribute.

By default, the scope of a role is limited to the subtree where it is defined. The scope of a role can be extended to other subtrees on the same server instance.

Managed Roles

Managed roles are functionally very similar to static groups. Managed roles explicitly assign a role to each member entry by adding the nsRoleDN attribute to the entry. The value of this attribute is the DN of the role definition entry.

The role definition entry only defines the scope of the role in the directory. Members of the role are entries that lie within the scope of the role definition, and that identify the role definition entry with their nsRoleDN attributes.

Filtered Roles

Filtered roles are equivalent to dynamic groups. Entries are assigned a role if they match a specified search filter. The value of the search filter is defined by the nsRoleFilter attribute. When the server returns an entry in the scope of a filtered role, that entry contains the generated nsRole attribute that identifies the role.

Nested Roles

Nested roles are equivalent to nested groups. Nested roles enable you to create roles that contain other roles and to extend the scope of existing roles. A nested role can itself contain another nested role. Up to 30 levels of nesting are supported

A nested role lists the definition entries of other roles and combines all the members of their roles. If an entry is a member of a role that is listed in a nested role, then the entry is also a member of the nested role.

Limitations on Using Roles

When you use roles to support your directory service, be aware of the following limitations.

Roles and chaining

If your directory tree is distributed over several servers by using the chaining feature, entries that define roles must be located on the same server as the entries that possess those roles. If one server, A, receives entries from another server, B, through chaining, those entries will contain the roles defined on B, but will not be assigned any of the roles defined on A.

Filtered Roles cannot use CoS generated attributes

The filter string of a filtered role cannot be based on the values of a CoS virtual attribute. However, the specifier attribute in a CoS definition may reference the nsRole attribute generated by a role definition. For information about CoS, see Chapter 9, Directory Server Class of Service.

Extending the scope of roles

You can extend the scope of roles to different subtrees but they must be on the same server instance. You cannot extend the scope of roles to other servers.

Searches on the nsRole attribute

The nsRole attribute can be used in any search filter with any of the comparison operators. When you search on nsRole attribute, consider the following points:

  • Searches on the nsRole attribute can take a long time because all roles must be evaluated before the entries can be filtered.

  • Directory Server is optimized for equality searches on membership in managed roles. For example, this search will be nearly as fast as a search on real attributes.

    (&(nsRole=cn=managersRole,ou=People,dc=example,dc=com)
 (objectclass=person)

  • The nsRoleDN attribute is indexed by default in all suffixes. Optimizations for searching the membership of managed roles are lost if indexing is disabled for the nsRoleDN attribute.

  • Searches for entries that contain a filtered role involve an internal search with the role filter. This internal operation will be fastest if all attributes that appear in the role filter are indexed in all suffixes in the scope of the role.

Chapter 9 Directory Server Class of Service

The Class of Service (CoS) mechanism allows attributes to be shared between entries. CoS values are calculated dynamically when they are requested. For information about CoS, see the following sections:

About CoS

Imagine a directory containing thousands of entries that all have the same value for the facsimileTelephoneNumber attribute. Traditionally, to change the fax number, you would update each entry individually, a time consuming job for administrators. Using CoS, the fax number is stored in a single place, and the facsimileTelephoneNumber attribute is automatically generated on every entry as it is returned.

To client applications, a CoS attribute is generated in the same ways as any other attribute. However, directory administrators now have only a single fax value to manage. Also, because there are fewer values stored in the directory, the database uses less disk space. The CoS mechanism also allows entries to override a generated value or to generate multiple values for the same attribute.

Note –

Because CoS virtual attributes are not indexed, referencing them in an LDAP search filter may have an impact on performance.

Generated CoS attributes can be multivalued. Specifiers can designate several template entries, or there can be several CoS definitions for the same attribute. Alternatively, you can specify template priorities so that only one value is generated from all templates.

Roles and classic CoS can be used together to provide role-based attributes. These attributes appear on an entry because it possesses a particular role with an associated CoS template. You could use a role-based attribute to set the server look through limit on a role-by-role basis, for example.

CoS functionality can be used recursively; you can generate attributes through CoS that depend on other attributes generated through CoS. Complex CoS schemes can simplify client access to information and ease administration of repeated attributes, but they also increase management complexity and degrade server performance. Avoid overly complex CoS schemes; many indirect CoS schemes can be redefined as classic or pointer CoS, for example.

You should also avoid changing CoS definitions more often than necessary. Modifications to CoS definitions do not take effect immediately, because the server caches CoS information. Although caching accelerates read access to generated attributes, when changes to CoS information occur, the server must reconstruct the cache. This task can take some time, usually in the order of seconds. During cache reconstruction, read operations may still access the old cached information, rather than the newly modified information, which means that if you change CoS definitions too frequently, you are likely to be accessing outdated data.

CoS Definition Entries and CoS Template Entries

The CoS mechanism relies on two types of entries, the CoS definition entry and the CoS template entry. This section describes the CoS definition entry and the CoS template entry.

CoS Definition Entry

The CoS definition entry identifies the type of CoS and the names of the CoS attributes that will be generated. Like the role definition entry, the CoS definition entry inherits from the LDAPsubentry object class. Multiple definitions may exist for the same CoS attribute, which, as a result, may be multivalued.

The CoS definition entry is an instance of the cosSuperDefinition object class. The CoS definition entry also inherits from one of the following object classes to specify the type of CoS:

The CoS definition entry contains the attributes specific to each type of CoS for naming the virtual CoS attribute, the template DN, and the specifier attribute in target entries. By default, the CoS mechanism will not override the value of an existing attribute with the same name as the CoS attribute. However, the syntax of the CoS definition entry allows you to control this behavior.

When schema checking is turned on, the CoS attribute will be generated on all target entries that allow that attribute. When schema checking is turned off, the CoS attribute will be generated on all target entries.

The location of the definition entry determines the scope of the CoS, which is the entire subtree below the parent of the CoS definition entry. All entries in the branch of the definition entry’s parent are called target entries for the CoS definition.

The following figure shows a CoS definition entry at the root of the ou=people subtree. The scope of the CoS is only the two subtrees beneath the root. The CoS does not extend above this root, or to other subtrees in the DIT.

Figure 9–1 CoS Scope

Figure shows CoS scope beneath the CoS definition entry.

CoS Template Entry

The CoS template entry contains the value that is generated for the CoS attribute. All entries within the scope of the CoS use the values defined here. There may be several templates, each with a different value, in which case the generated attribute may be multivalued. The CoS mechanism selects one of these values based on the contents of both the definition entry and the target entry.

The CoS template entry is an instance of the cosTemplate object class. The CoS template entry contains the value or values of the attributes generated by the CoS mechanism. The template entries for a given CoS are stored in the directory tree at the same level as the CoS definition.

When possible, definition and template entries should be located in the same place, for easier management. You should also name them in a way that suggests the functionality they provide. For example, a definition entry DN such as "cn=classicCosGenEmployeeType,ou=People,dc=example,dc=com" is more descriptive than "cn=ClassicCos1,ou=People,dc=example,dc=com". For more information about the object classes and attributes associated with each type of CoS, see Class of Service in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Pointer CoS, Indirect CoS, and Classic CoS

The following types of CoS differ in how the template, and therefore the generated value, is selected:

Pointer CoS

Pointer CoS is the simplest type of CoS. The pointer CoS definition entry provides the DN of a specific template entry of the cosTemplate object class. All target entries have the same CoS attribute value, as defined by this template.

The following figure shows a pointer CoS that defines a common postal code for all of the entries stored under dc=example,dc=com. The CoS definition entry, CoS template entry and target entry are indicated.

Figure 9–2 Example of a Pointer CoS Definition and Template

Example of a Pointer CoS Definition and Template

The template entry is identified by its DN, cn=exampleUS,cn=data, in the CoS definition entry. Each time the postalCode attribute is queried on entries under dc=example,dc=com, Directory Server returns the value available in the template entry cn=exampleUS,cn=data. Therefore, the postal code will appear with the entry uid=wholiday,ou=people,dc=example,dc=com, but it is not stored there.

In a scenario where several shared attributes are generated by CoS for thousands or millions of entries, instead of existing as real attributes in each entry, the storage space savings and performance gains provided by CoS are considerable.

Indirect CoS

Indirect CoS allows any entry in the directory to be a template and provide the CoS value. The indirect CoS definition entry identifies an attribute, called the indirect specifier, whose value in a target entry determines the template used for that entry. The indirect specifier attribute in the target entry must contain a DN. With indirect CoS, each target entry may use a different template and thus have a different value for the CoS attribute.

For example, an indirect CoS that generates the departmentNumber attribute may use an employee’s manager as the specifier. When retrieving a target entry, the CoS mechanism will use the DN value of the manager attribute as the template. It will then generate the departmentNumber attribute for the employee using the same value as the manager’s department number.

Note –

Because templates may be arbitrary entries anywhere in the directory tree, implementing access control for indirect CoS can become extremely complex. In deployments where performance is critical, you should also avoid overusing indirect CoS due to its resource intensive nature.

In many cases, results that are similar to those made possible by indirect CoS can be achieved by limiting the location of the target entries with classic CoS or using the less flexible pointer CoS mechanism.

The following figure shows an indirect CoS that uses the manager attribute of the target entry to identify the template entry. In this way, the CoS mechanism can generate the departmentNumber attribute of all employees to be the same as their manager’s, ensuring that it is always up to date.

Figure 9–3 Example of an Indirect CoS Definition and Template

Example of an Indirect CoS Definition and Template

The indirect CoS definition entry names the specifier attribute, which in this example, is the manager attribute. William Holiday’s entry is one of the target entries of this CoS, and his manager attribute contains the DN of uid=cfuentes,ou=people,dc=example,dc=com. Therefore, Carla Fuentes’s entry is the template, which in turn provides the departmentNumber attribute value of 318842.

Classic CoS

Classic CoS combines the pointer and indirect CoS behavior. The classic CoS definition entry identifies the base DN of the template and a specifier attribute. The value of the specifier attribute in the target entries is then used to construct the DN of the template entry as follows:

cn=specifierValue, baseDN

The template containing the CoS values is determined by the combination of the RDN (relative distinguished name) value of the specifier attribute in the target entry and the template’s base DN.

Classic CoS templates are entries of the cosTemplate object class to avoid the performance issue associated with arbitrary indirect CoS templates.

The classic CoS mechanism determines the DN of the template from the base DN given in the definition entry and the specifier attribute in the target entry. The value of the specifier attribute is taken as the cn value in the template DN. Template DNs for classic CoS must therefore have the following structure:

cn=specifierValue,baseDN

The following figure shows a classic CoS definition that generates a value for the postal code attribute.

Figure 9–4 Example of a Classic CoS Definition and Template

Example of a Classic CoS Definition and Template

In this example, the cosSpecifier attribute names the employeeType attribute. The combination of the cosSpecifier attribute and the template DN identifies the template entry as cn=sales,cn=exampleUS,cn=data. The template entry then provides the value of the postalCode attribute to the target entry.

CoS Priorities

It is possible to create CoS schemes that compete with each other to provide an attribute value. For example, you might have a multivalued cosSpecifier in your CoS definition entry. In such a case, you can specify a template priority on each template entry to determine which template provides the attribute value. Set the template priority using the cosPriority attribute. This attribute represents the global priority of a particular template numerically. A priority of zero is the highest possible priority.

Templates that contain no cosPriority attribute are considered the lowest possible priority. In the case where two or more templates are considered to supply an attribute value and they have the same (or no) priority, a value is chosen arbitrarily. Directory Server can be configured to log messages when it is forced to choose a template arbitrarily.

CoS Limitations

The CoS functionality is a complex mechanism which, for performance and security reasons, is subject to the following limitations:

Chapter 10 Directory Server DSMLv2

For information about DSMLv2 in Directory Server, see the following sections:

Introduction to DSML

Directory Services Markup Language version 2, DSMLv2, is a markup language that describes directory operations in an eXtensible Markup Language (XML) document. For information about the DSMLv2 standard, see Directory Services Markup Language (DSML) v2.0 [OASIS 200201] at http://www.oasis-open.org/specs.

The complete DSMLv2 specification and supporting documentation can be found at the following locations:

Directory Server supports DSMLv2 SOAP over HTTP binding. DSML requests and responses are embedded in the body of SOAP v1.1, and transported in an HTTP/1.1 payload.

The Directory Server Resource Kit contains tools for searching and modifying directories using DSMLv2. See dsmlsearch(1) and dsmlmodify(1).

By using DSML, non-LDAP clients can perform directory operations. The following figure shows an example deployment where a non-LDAP client makes a requests to modify data on DSML-enabled directory servers.

Figure 10–1 Sample DSML-Enabled Directory Deployment

Figure shows an example deployment where a non-LDAP client makes modification requests to DSML-enabled directory servers.

In the example deployment, update requests in DSML arrive from non-LDAP client applications cross a firewall over HTTP port 80. The web proxy server enforces the use of secure HTTP over port 443 for the requests to cross a second firewall and enter the intranet domain. The requests are then processed by the two master replicas on Master A and Master B, before being replicated to the non-DSML enabled Consumers C and D.

Implementation of the DSMLv2 Standard

The Directory Server implementation of the DSMLv2 specification has the following restrictions:

Bindings

DSMLv2 defines two normative bindings: a SOAP request/response binding and a file binding that serves as the DSMLv2 analog of LDIF. Directory Server supports the SOAP request/response binding.

Modify DN

Directory Server supports the DSML modDNRequest and modDNResponse operations.

Abandon request

Directory Server does not support the abandonRequest operation, because this operation is of no use over HTTP.

Search operations

Some DSML clients incorrectly send an equality match with value * when a presence match is intended. Directory Server will return zero results from these badly formatted queries. You can detect these incorrect clients by searching for the characters =\2a in the access log.

DSML Security

The DSML front end constitutes a restricted HTTP server; it accepts only DSML post operations, it rejects requests that do not conform to the DSMLv2 SOAP binding specifications.

The security of DSML is configured by the following server properties dsml-client-auth-mode, dsml-port, dsml-secure-port, and dsml-relative-root-url. For information about these properties, see server(5dsconf).

For additional security, consider the following.

DSML Identity Mapping

Identity mapping is required for the following mechanisms: DSML over HTTP, DIGEST-MD5, and GSSAPI SASL. Identity mapping is used to determine a bind DN based on protocol specific credentials provided by the client.

Identity mapping uses the entries in the cn=identity mapping, cn=config configuration branch. This branch includes the following containers for the protocols that perform identity mapping:

cn=HTTP-BASIC, cn=identity mapping, cn=config

Contains the mappings for DSML-over-HTTP connections.

cn=DIGEST-MD5, cn=identity mapping, cn=config

Contains the mappings for client authentication using the DIGEST-MD5 SASL mechanism.

cn=GSSAPI, cn=identity mapping, cn=config

Must be created to contain the mappings for client authentication using the GSSAPI SASL mechanism.

A mapping entry defines how to extract credentials about the protocol to use them in a search operation. If a search returns a single user entry, the mapping has succeeded and the connection uses the mapping entry as the bind DN for all operations. If the search returns zero or more than one entry, the mapping fails and the connection does not use the mapping entry as the bind DN.

The protocols that perform identity mapping must have a default mapping. Additionally, The protocols can have any number of custom mappings. The default mapping has the RDN cn=default, and custom mappings may have any other RDN that uses cn as the naming attribute. All of the custom mappings are evaluated first, in a non deterministic order until one of them succeeds. If all custom mappings fail, the default mapping is applied. If the default mapping fails, authentication of the client fails.

A mapping entry must contain the object classes top, container, and dsIdentityMapping.

The entry can contain the following attributes.

dsMappedDN: DN

A literal string that defines a DN in the directory. This DN will be used for binding if it exists when the mapping is performed. You may also define the following attributes to perform a search in case this DN does not exist.

dsSearchBaseDN: DN

The base DN for a search. If omitted, the mapping will search all root suffixes in the entire directory tree, including all naming contexts, but excluding cn=config, cn=monitor, and cn=schema.

dsSearchScope: base|one|sub

The scope for a search, either the search base itself, one level of children below the base, or the entire subtree below the base. The default scope for mapping searches is the entire subtree when this attribute is omitted.

dsSearchFilter: filterString

A filter string to perform the mapping search. LDAP search filters are defined in RFC 4515 on http://www.ietf.org/rfc/rfc4515.txt.

Additionally, a mapping entry may also contain the dsPatternMatching object class which allows it to use the following attributes:

dsMatching-pattern: patternString

A string on which to perform pattern matching.

dsMatching-regexp: regularExpression

A regular expression to apply to the pattern string.

All of the attribute values above, except for dsSearchScope may contain placeholders of the format ${keyword}, where keyword is the name of an element in the protocol-specific credentials. During mapping, the placeholder is substituted for the actual value of the element provided by the client.

After all of the placeholders have been substituted, the pattern matching is performed. The matching pattern is compared to the regular expression, as follows.

For example, the following mapping could be defined for SASL.

dsMatching-pattern: ${Principal}
dsMatching-regexp: (.*)@(.*)\\.(.*)
dsMappedDN: uid=$1,ou=people,dc=$2,dc=$3

If a client authenticates with the Principal of bjensen@example.com, this mapping will define the following bind DN: uid=bjensen,ou=people,dc=example,dc=com. If this DN exists in the directory, the mapping will succeed, the client will be authenticated, and all operations performed during this connection will use this bind DN.

The dsMatching-pattern is compared to the dsMatching-regexp by using the POSIX regexec(3C) and regcomp(3C) function calls. Directory Server uses extended regular expressions and all comparisons are case insensitive. For more information, refer to the man pages for these functions.

The attribute values that can contain placeholders must encode any $, {, and } characters that are not part of a placeholder, even if no placeholder is used. You must encode these characters with the following values: $ as \\24, { as \\7B, and } as \\7D.

The use of placeholders and substitutions allows you to create mappings that extract a username or any other value from the protocol-specific credentials. The credential can be used to define a mapped DN or perform a search for a corresponding DN anywhere in the directory.

Caution – Caution –

Creating a poorly defined mapping is a security hole. For example, a mapping to a hard coded DN without pattern matching will always succeed, thereby authenticating clients who might not be directory users. It is safer to define several mappings to handle different client credential formats than to create a single, overly generic and permissive mapping. Always try to map client connections to specific users according to the client credentials.

Content of the HTTP Header

Directory Server supports the HTTP POST operation only. The following example shows the minimum fields required to send a DSML request to the server over HTTP:

POST /dsml HTTP/1.1
content-length: 450
HOST: hostname
SOAPAction: ""
Content-Type: text/xml
Connection: close

The Connection field is optional. In HTTP 1.0, the default value of this field is close. In HTTP 1.1, however, the default value is keep-alive. It is therefore recommended that you include this field with a value of close in your last request if you are using HTTP 1.1, to accelerate the dialog.

Additional fields may be included in the HTTP header. If they are supported by Directory Server, their values will override the defaults. If the fields are not supported, the request is not rejected by the server but the fields are ignored.

Accessing the Directory Using DSMLv2

The following examples indicate how to use DSML requests to access and search the directory.

Note that the content-length: header in these examples contains the exact length of the DSMLv2 request. For these examples to function correctly, ensure that the editor you use respects these content lengths, or that you modify them accordingly.

An Empty Anonymous DSML Ping Request

The DSML front end is disabled by default. For information on how to enable it, refer to Configuring DSML in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide. To check whether the DSML front end is enabled, send an empty DSML batch request, as shown in Example 10–1.

Example 10–1 Empty Anonymous DSML Request

POST /dsml HTTP/1.1
 content-length: 451
 HOST: hostname
 SOAPAction: ""
 Content-Type: text/xml
Connection: close
<?xml version=’1.0’ encoding=’UTF-8’?\>
 <soap-env:Envelope
    xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns:soap-env=’http://schemas.xmlsoap.org/soap/envelope/’\>
   <soap-env:Body\>
       <batchRequest
           xmlns=’urn:oasis:names:tc:DSML:2:0:core’           requestID=’Ping!’\>
           <!-- empty batch request --\>
      </batchRequest\>
    </soap-env:Body\>
 </soap-env:Envelope\>

The first section of this DSML request contains the HTTP method line, POST /dsml HTTP/1.1, followed by a number of HTTP headers. The HTTP method line specifies the HTTP method request and URL to be used by the DSML front end. POST is the only HTTP method request accepted by the DSML front end. The /dsml URL is the default URL for Directory Server, but can be configured with any other valid URL. The HTTP headers that follow, specify the remaining details of the DSML request.

Example 10–2 Empty Anonymous DSML Response

HTTP/1.1 200 OK
Cache-control: no-cache
Connection: close
Date: Mon, 11 Dec 2006 13:56:49 GMT
Accept-Ranges: none
Server: Sun-Java(tm)-System-Directory/6.0
Content-Type: text/xml; charset="utf-8"
Content-Length: 500
<?xml version=’1.0’ encoding=’UTF-8’ ?\>
<soap-env:Envelope
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns:soap-env=’http://schemas.xmlsoap.org/soap/envelope/’
   \>
<soap-env:Body\>
<batchResponse
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns=’urn:oasis:names:tc:DSML:2:0:core’
   requestID=’Ping!’
   \>
</batchResponse\>
</soap-env:Body\>
</soap-env:Envelope\>

If nothing is returned, you can conclude that the front end is disabled.

Maximum limits exist for the number of clients connecting simultaneously to the directory and for the size of the DSML requests. The limit for the number of clients is specified by the dsml-max-parser-count and dsml-min-parser-count server properties and the request size limit by the server property dsml-request-max-size. See server(5dsconf).

Issuing a DSML Request to Bind as a Particular User

To issue a DSML request you can bind to the directory as a specified user or anonymously. To bind as a specified user, the request must include an HTTP authorization header containing a UID and a password that are mapped to a DN, as shown in Example 10–3.

Example 10–3 DSML Extended Operation: Bind as a Particular User

POST /dsml HTTP/1.1
content-length: 578
content-Type: text/xml; charset="utf-8"
HOST: hostname
Authorization: Basic ZWFzdGVyOmVnZw==
SOAPAction: ""
Connection: close
<?xml version=’1.0’ encoding=’UTF-8’?\>
<soap-env:Envelope
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns:soap-env=’http://schemas.xmlsoap.org/soap/envelope/’\>
   <soap-env:Body\>
     <batchRequest
        xmlns=’urn:oasis:names:tc:DSML:2:0:core’\>
        <extendedRequest\>
          <requestName\>1.3.6.1.4.1.4203.1.11.3</requestName\>
        </extendedRequest\>
     </batchRequest\>
   </soap-env:Body\>
</soap-env:Envelope\>

In this example the HTTP authorization header transports the user ID easter and the password egg, which, in clear, appears as easter:egg, and encoded in base64 as Authorization: Basic ZWFzdGVyOmVnZw==.

The <extendedRequest\> tag is used to specify an LDAP Extended Operation. The <requestName\> tag is used to specify the OID of the extended operation. In this example, the OID 1.3.6.1.4.1.4203.1.11.3 identifies the whoami extended operation.

The response to the DSML extended operation shows the DN of the user that made the bind request. In Example 10–4, the whoami response, which contains the DN, is shown in the response line.

<response\>dn:uid=easter,ou=people,dc=example,dc=com</response\>
Example 10–4 Response to DSML Extended Operation

HTTP/1.1 200 OK
Cache-control: no-cache
Connection: close
Date: Fri, 15 Dec 2006 09:15:09 GMT
Accept-Ranges: none
Server: Sun-Java(tm)-System-Directory/6.0
Content-Type: text/xml; charset="utf-8"
Content-Length: 697

<?xml version=’1.0’ encoding=’UTF-8’ ?\>
<soap-env:Envelope
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns:soap-env=’http://schemas.xmlsoap.org/soap/envelope/’
   \>
<soap-env:Body\>
<batchResponse
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns=’urn:oasis:names:tc:DSML:2:0:core’
   \>
   <extendedResponse\>
      <resultCode code=’0’ descr=’success’/\>
   <responseName\>1.3.6.1.4.1.4203.1.11.3</responseName\>
   <response\>dn:uid=easter,ou=people,dc=example,dc=com</response\>
   </extendedResponse\>
</batchResponse\>
</soap-env:Body\>
</soap-env:Envelope\>

For anonymous access, no HTTP authorization header is required, although anonymous access is often subject to strict access controls, and possibly to data access restrictions. Similarly, you can issue DSML requests to perform LDAP operations by LDAP proxy.

Because DSML requests are managed on a batch basis, if you issue requests by LDAP proxy, the required DSML proxy authorization request must be the first in a given batch of requests.

A DSML Search Request

Example 10–5 shows a DSML base object search request on the root DSE entry.

Example 10–5 DSML Search Request

POST /dsml HTTP/1.1
HOST: hostname
Content-Length: 1081
Content-Type: text/xml
SOAPAction: ""
Connection: close
<?xml version=’1.0’ encoding=’UTF-8’?\>
<soap-env:Envelope
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns:soap-env=’http://schemas.xmlsoap.org/soap/envelope/’
   \>
   <soap-env:Body\>
      <batchRequest
        xmlns=’urn:oasis:names:tc:DSML:2:0:core’
        requestID=’Batch of search requests’
        \>
        <searchRequest
            dn=""
            requestID="search on Root DSE"
            scope="baseObject"
            derefAliases="neverDerefAliases"
            typesOnly="false"
            \>
            <filter\>
               <present name="objectClass"/\>
            </filter\>
            <attributes\>
               <attribute name="namingContexts"/\>
               <attribute name="supportedLDAPversion"/\>
               <attribute name="vendorName"/\>
               <attribute name="vendorVersion"/\>
               <attribute name="supportedSASLMechanisms"/\>
            </attributes\>
        </searchRequest\>
      </batchRequest\>
   </soap-env:Body\>
</soap-env:Envelope\>
Example 10–6 DSML Search Response

HTTP/1.1 200 OK
Cache-control: no-cache
Connection: close
Date: Fri, 15 Dec 2006 09:21:43 GMT
Accept-Ranges: none
Server: Sun-Java(tm)-System-Directory/6.0
Content-Type: text/xml; charset="utf-8"
Content-Length: 1287

<?xml version=’1.0’ encoding=’UTF-8’ ?\>
<soap-env:Envelope
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns:soap-env=’http://schemas.xmlsoap.org/soap/envelope/’
   \>
<soap-env:Body\>
<batchResponse
   xmlns:xsd=’http://www.w3.org/2001/XMLSchema’
   xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
   xmlns=’urn:oasis:names:tc:DSML:2:0:core’
   requestID=’Batch of search requests’
   \>
   <searchResponse requestID=’search on Root DSE’\>
   <searchResultEntry\>
      <attr name=’namingContexts’\>
      <value\>dc=example,dc=com</value\>
      </attr\>
      <attr name=’supportedLDAPVersion’\>
      <value\>2</value\>
      <value\>3</value\>
      </attr\>
      <attr name=’vendorName’\>
      <value\>Sun Microsystems, Inc.</value\>
      </attr\>
      <attr name=’vendorVersion’\>
      <value\>Sun-Java(tm)-System-Directory/6.0</value\>
      </attr\>
      <attr name=’supportedSASLMechanisms’\>
      <value\>EXTERNAL</value\>
      <value\>GSSAPI</value\>
      <value\>DIGEST-MD5</value\>
      </attr\>
   </searchResultEntry\>
   <searchResultDone\>
      <resultCode code=’0’ descr=’success’/\>
   </searchResultDone\>
   </searchResponse\>
</batchResponse\>
</soap-env:Body\>
</soap-env:Envelope\>

Chapter 11 Directory Server Internationalization Support

Directory Server provides support for storing, managing, and searching for entries and their associated attributes in different languages.

Data inside the internationalized directory is stored in UTF-8 format. Therefore, Directory Server supports all international characters by default. The internationalized directory can be used to specify matching rules and collation orders based on language preferences in search operations. For information about the internationalized directory, see the following sections:

About Locales

A locale identifies language-specific information about how users in a specific region, culture, or custom expect data to be presented. Locales define how data in different languages is interpreted, sorted, and collated.Directory Server supports multiple languages through the use of locales.

A locale specifies the following information.

Code page

The code page is an internal table used by an operating system to relate keyboard keys to character fonts displayed on a screen. A locale can indicate what code page an application should select for interaction with an end user.

Collation order

The collation order provides information about how the characters of a given language should be sorted. The collation order specifies the following information:

  • The sequence of the letters in the alphabet

  • How to compare letters with accents to letters without accents

  • Whether there are characters that can be ignored when comparing strings

  • The direction, left to right, right to left, or up and down, in which the language is read

Character type

The character type distinguishes alphabetic characters from numeric or other characters. It defines the mapping of uppercase letters to lowercase letters. For example, in some languages, the pipe character (|) is considered punctuation, while in other languages it is considered as alphabetic.

Monetary format

The monetary format specifies the following information: the monetary symbol used in a region, whether the symbol goes before or after its value, and how monetary units are represented.

Time and date formats

The time and date formats determine the appearance of times and dates in a region. The time format indicates whether the locale uses a 12–hour clock or 24-hour clock. The date format includes both the short date order and the long date format, and include the names of months and days of the week in each language.

Identifying Supported Locales

When you perform directory operations that require you to specify a locale, such as a search operation, you can use a language tag or a collation order object identifier, OID.

A language tag is a string that begins with the two-character lowercase language code that identifies the language, as defined in ISO standard 639. If necessary to distinguish regional differences in language, the language tag may also contain a country code, which is a two-character string, as defined in ISO standard 3166. The language code and country code are separated by a hyphen. For example, the language tag used to identify the American English locale is en-US.

An OID is a decimal number that uniquely identifies an object, such as an attribute or object class.

When you perform an international search in a directory, use either the language tag or the OID to identify the collation order you want to use. When you set up an international index, use the OIDs.

The following table lists the locales supported by Directory Server. It identifies the associated language tags and OIDs.

Table 11–1 Supported Locales

Locale 

Tag 

Collation Order OID 

Backward Compatible OID 

Afrikaans 

af 

1.3.6.1.4.1.42.2.27.9.4.1.1 

 

Amharic Ethiopia 

am 

1.3.6.1.4.1.42.2.27.9.4.2.1 

 

Arabic 

ar 

1.3.6.1.4.1.42.2.27.9.4.3.1 

2.16.840.1.113730.3.3.2.1.1 

Arabic United Arab Emirates 

ar-AE 

1.3.6.1.4.1.42.2.27.9.4.4.1 

 

Arabic Bahrain 

ar-BH 

1.3.6.1.4.1.42.2.27.9.4.5.1 

 

Arabic Algeria 

ar-DZ 

1.3.6.1.4.1.42.2.27.9.4.6.1 

 

Arabic Egypt 

ar-EG 

1.3.6.1.4.1.42.2.27.9.4.7.1 

 

Arabic India 

ar-IN 

1.3.6.1.4.1.42.2.27.9.4.8.1 

 

Arabic Iraq 

ar-IQ 

1.3.6.1.4.1.42.2.27.9.4.9.1 

 

Arabic Jordan 

ar-JO 

1.3.6.1.4.1.42.2.27.9.4.10.1 

 

Arabic Kuwait 

ar-KW 

1.3.6.1.4.1.42.2.27.9.4.11.1 

 

Arabic Lebanon 

ar-LB 

1.3.6.1.4.1.42.2.27.9.4.12.1 

 

Arabic Libya 

ar-LY 

1.3.6.1.4.1.42.2.27.9.4.13.1 

 

Arabic Morocco 

ar-MA 

1.3.6.1.4.1.42.2.27.9.4.14.1 

 

Arabic Oman 

ar-OM 

1.3.6.1.4.1.42.2.27.9.4.15.1 

 

Arabic Qatar 

ar-QA 

1.3.6.1.4.1.42.2.27.9.4.16.1 

 

Arabic Saudi Arabia 

ar-SA 

1.3.6.1.4.1.42.2.27.9.4.17.1 

 

Arabic Sudan 

ar-SD 

1.3.6.1.4.1.42.2.27.9.4.18.1 

 

Arabic Syria 

ar-SY 

1.3.6.1.4.1.42.2.27.9.4.19.1 

 

Arabic Tunisia 

ar-TN 

1.3.6.1.4.1.42.2.27.9.4.20.1 

 

Arabic Yemen 

ar-YE 

1.3.6.1.4.1.42.2.27.9.4.21.1 

 

Byelorussian 

be 

1.3.6.1.4.1.42.2.27.9.4.22.1 

2.16.840.1.113730.3.3.2.2.1 

Bulgarian 

bg 

1.3.6.1.4.1.42.2.27.9.4.23.1 

2.16.840.1.113730.3.3.2.3.1 

Bengali India 

bn 

1.3.6.1.4.1.42.2.27.9.4.24.1 

 

Catalan 

ca 

1.3.6.1.4.1.42.2.27.9.4.25.1 

2.16.840.1.113730.3.3.2.4.1 

Czech 

cs 

1.3.6.1.4.1.42.2.27.9.4.26.1 

2.16.840.1.113730.3.3.2.5.1 

Danish 

da 

1.3.6.1.4.1.42.2.27.9.4.27.1 

2.16.840.1.113730.3.3.2.6.1 

German 

de or de-DE 

1.3.6.1.4.1.42.2.27.9.4.28.1 

2.16.840.1.113730.3.3.2.7.1 

German Austria 

de-AT 

1.3.6.1.4.1.42.2.27.9.4.29.1 

2.16.840.1.113730.3.3.2.8.1 

German Belgium 

de-BE 

1.3.6.1.4.1.42.2.27.9.4.30.1 

 

German Swiss 

de-CH 

1.3.6.1.4.1.42.2.27.9.4.31.1 

2.16.840.1.113730.3.3.2.9.1 

German Luxembourg 

de-LU 

1.3.6.1.4.1.42.2.27.9.4.32.1 

 

Greek 

el 

1.3.6.1.4.1.42.2.27.9.4.33.1 

2.16.840.1.113730.3.3.2.10.1 

English (US) 

en-US 

1.3.6.1.4.1.42.2.27.9.4.34.1 

2.16.840.1.113730.3.3.2.11.1 

English Australian 

en-AU 

1.3.6.1.4.1.42.2.27.9.4.35.1 

 

English Canada 

en-CA 

1.3.6.1.4.1.42.2.27.9.4.36.1 

2.16.840.1.113730.3.3.2.12.1 

English Great Britain 

en-GB 

1.3.6.1.4.1.42.2.27.9.4.37.1 

2.16.840.1.113730.3.3.2.13.1 

English Hong Kong 

en-HK 

1.3.6.1.4.1.42.2.27.9.4.38.1 

 

English Ireland 

en-IE 

1.3.6.1.4.1.42.2.27.9.4.39.1 

2.16.840.1.113730.3.3.2.14.1 

English India 

en-IN 

1.3.6.1.4.1.42.2.27.9.4.40.1 

 

English Malta 

en-MT 

1.3.6.1.4.1.42.2.27.9.4.41.1 

 

English New Zealand 

en-NZ 

1.3.6.1.4.1.42.2.27.9.4.42.1 

 

English Philippines 

en-PH 

1.3.6.1.4.1.42.2.27.9.4.43.1 

 

English Singapore 

en-SG 

1.3.6.1.4.1.42.2.27.9.4.44.1 

 

English Virgin Island 

en-VI 

1.3.6.1.4.1.42.2.27.9.4.45.1 

 

English South Africa 

en-ZA 

1.3.6.1.4.1.42.2.27.9.4.46.1 

 

English Zimbabwe 

en-ZW 

1.3.6.1.4.1.42.2.27.9.4.47.1 

 

Esperanto 

eo 

1.3.6.1.4.1.42.2.27.9.4.48.1 

 

Spanish 

es or es-ES 

1.3.6.1.4.1.42.2.27.9.4.49.1 

2.16.840.1.113730.3.3.2.15.1 

Spanish Argentina 

es-AR 

1.3.6.1.4.1.42.2.27.9.4.50.1 

 

Spanish Bolivia 

es-BO 

1.3.6.1.4.1.42.2.27.9.4.51.1 

 

Spanish Chile 

es-CL 

1.3.6.1.4.1.42.2.27.9.4.52.1 

 

Spanish Colombia 

es-CO 

1.3.6.1.4.1.42.2.27.9.4.53.1 

 

Spanish Costa Rica 

es-CR 

1.3.6.1.4.1.42.2.27.9.4.54.1 

 

Spanish Dominican Rep. 

es-DO 

1.3.6.1.4.1.42.2.27.9.4.55.1 

 

Spanish Ecuador 

es-EC 

1.3.6.1.4.1.42.2.27.9.4.56.1 

 

Spanish Guatemala 

es-GT 

1.3.6.1.4.1.42.2.27.9.4.57.1 

 

Spanish Honduras 

es-HN 

1.3.6.1.4.1.42.2.27.9.4.58.1 

 

Spanish Mexico 

es-MX 

1.3.6.1.4.1.42.2.27.9.4.59.1 

 

Spanish Nicaragua 

es-NI 

1.3.6.1.4.1.42.2.27.9.4.60.1 

 

Spanish Panama 

es-PA 

1.3.6.1.4.1.42.2.27.9.4.61.1 

 

Spanish Peru 

es-PE 

1.3.6.1.4.1.42.2.27.9.4.62.1 

 

Spanish Puerto Rico 

es-PR 

1.3.6.1.4.1.42.2.27.9.4.63.1 

 

Spanish Paraguay 

es-PY 

1.3.6.1.4.1.42.2.27.9.4.64.1 

 

Spanish El Salvador 

es-SV 

1.3.6.1.4.1.42.2.27.9.4.65.1 

 

Spanish US 

es-US 

1.3.6.1.4.1.42.2.27.9.4.66.1 

 

Spanish Uruguay 

es-UY 

1.3.6.1.4.1.42.2.27.9.4.67.1 

 

Spanish Venezuela 

es-VE 

1.3.6.1.4.1.42.2.27.9.4.68.1 

 

Estonian 

et 

1.3.6.1.4.1.42.2.27.9.4.69.1 

2.16.840.1.113730.3.3.2.16.1 

Basque 

eu 

1.3.6.1.4.1.42.2.27.9.4.70.1 

 

Persian 

fa 

1.3.6.1.4.1.42.2.27.9.4.71.1 

 

Persian India 

fa-IN 

1.3.6.1.4.1.42.2.27.9.4.72.1 

 

Persian Iran 

fa-IR 

1.3.6.1.4.1.42.2.27.9.4.73.1 

 

Finnish 

fi 

1.3.6.1.4.1.42.2.27.9.4.74.1 

2.16.840.1.113730.3.3.2.17.1 

Faeroese 

fo 

1.3.6.1.4.1.42.2.27.9.4.75.1 

 

French 

fr or fr-FR 

1.3.6.1.4.1.42.2.27.9.4.76.1 

2.16.840.1.113730.3.3.2.18.1 

French Belgium 

fr-BE 

1.3.6.1.4.1.42.2.27.9.4.77.1 

2.16.840.1.113730.3.3.2.19.1 

French Canada 

fr-CA 

1.3.6.1.4.1.42.2.27.9.4.78.1 

2.16.840.1.113730.3.3.2.20.1 

French Swiss 

fr-CH 

1.3.6.1.4.1.42.2.27.9.4.79.1 

2.16.840.1.113730.3.3.2.21.1 

French Luxembourg 

fr-LU 

1.3.6.1.4.1.42.2.27.9.4.80.1 

 

Irish 

ga 

1.3.6.1.4.1.42.2.27.9.4.81.1 

 

Galician 

gl 

1.3.6.1.4.1.42.2.27.9.4.82.1 

 

Gujarati 

gu 

1.3.6.1.4.1.42.2.27.9.4.83.1 

 

Manx Gaelic (Isle of Man) 

gv 

1.3.6.1.4.1.42.2.27.9.4.84.1 

 

Hebrew 

he or iw 

1.3.6.1.4.1.42.2.27.9.4.85.1 

2.16.840.1.113730.3.3.2.27.1 

Hindi 

hi 

1.3.6.1.4.1.42.2.27.9.4.86.1 

 

Croatian 

hr 

1.3.6.1.4.1.42.2.27.9.4.87.1 

2.16.840.1.113730.3.3.2.22.1 

Hungarian 

hu 

1.3.6.1.4.1.42.2.27.9.4.88.1 

2.16.840.1.113730.3.3.2.23.1 

Armenian 

hy 

1.3.6.1.4.1.42.2.27.9.4.89.1 

 

Indonesian 

id 

1.3.6.1.4.1.42.2.27.9.4.90.1 

 

Icelandic 

is 

1.3.6.1.4.1.42.2.27.9.4.91.1 

2.16.840.1.113730.3.3.2.24.1 

Italian 

it 

1.3.6.1.4.1.42.2.27.9.4.92.1 

2.16.840.1.113730.3.3.2.25.1 

Italian Swiss 

it-CH 

1.3.6.1.4.1.42.2.27.9.4.93.1 

2.16.840.1.113730.3.3.2.26.1 

Japanese 

ja 

1.3.6.1.4.1.42.2.27.9.4.94.1 

2.16.840.1.113730.3.3.2.28.1 

Greenlandic 

kl 

1.3.6.1.4.1.42.2.27.9.4.95.1 

 

Kannada 

kn 

1.3.6.1.4.1.42.2.27.9.4.96.1 

 

Korean 

ko 

1.3.6.1.4.1.42.2.27.9.4.97.1 

2.16.840.1.113730.3.3.2.29.1 

Konkani 

kok 

1.3.6.1.4.1.42.2.27.9.4.98.1 

 

Cornish 

kw 

1.3.6.1.4.1.42.2.27.9.4.99.1 

 

Lithuanian 

lt 

1.3.6.1.4.1.42.2.27.9.4.100.1 

2.16.840.1.113730.3.3.2.30.1 

Latvian or Lettish 

lv 

1.3.6.1.4.1.42.2.27.9.4.101.1 

2.16.840.1.113730.3.3.2.31.1 

Macedonian 

mk 

1.3.6.1.4.1.42.2.27.9.4.102.1 

2.16.840.1.113730.3.3.2.32.1 

Marathi 

mr 

1.3.6.1.4.1.42.2.27.9.4.103.1 

 

Maltese 

mt 

1.3.6.1.4.1.42.2.27.9.4.104.1 

 

Dutch 

nl or nl-NL 

1.3.6.1.4.1.42.2.27.9.4.105.1 

2.16.840.1.113730.3.3.2.33.1 

Dutch Belgium 

nl-BE 

1.3.6.1.4.1.42.2.27.9.4.106.1 

2.16.840.1.113730.3.3.2.34.1 

Norwegian 

no or no-NO 

1.3.6.1.4.1.42.2.27.9.4.107.1 

2.16.840.1.113730.3.3.2.35.1 

Norwegian Nynorsk 

no-NO-NY 

1.3.6.1.4.1.42.2.27.9.4.108.1 

2.16.840.1.113730.3.3.2.37.1 

Norwegian Nynorsk 

nn 

1.3.6.1.4.1.42.2.27.9.4.109.1 

 

Norwegian Bokmål 

nb or no-NO-B 

1.3.6.1.4.1.42.2.27.9.4.110.1 

2.16.840.1.113730.3.3.2.36.1 

Oromo (Afan) 

om 

1.3.6.1.4.1.42.2.27.9.4.111.1 

 

Oromo Ethiopia 

om-ET 

1.3.6.1.4.1.42.2.27.9.4.112.1 

 

Oromo Kenya 

om-KE 

1.3.6.1.4.1.42.2.27.9.4.113.1 

 

Polish 

pl 

1.3.6.1.4.1.42.2.27.9.4.114.1 

2.16.840.1.113730.3.3.2.38.1 

Portuguese 

pt or pt-PT 

1.3.6.1.4.1.42.2.27.9.4.115.1 

 

Portuguese Brazil 

pt-BR 

1.3.6.1.4.1.42.2.27.9.4.116.1 

 

Romanian 

ro 

1.3.6.1.4.1.42.2.27.9.4.117.1 

2.16.840.1.113730.3.3.2.39.1 

Russian 

ru or ru-RU 

1.3.6.1.4.1.42.2.27.9.4.118.1 

2.16.840.1.113730.3.3.2.40.1 

Russian Ukraine 

ru-UA 

1.3.6.1.4.1.42.2.27.9.4.119.1 

 

Serbo-Croatian 

sh 

1.3.6.1.4.1.42.2.27.9.4.120.1 

2.16.840.1.113730.3.3.2.41.1 

Slovak 

sk 

1.3.6.1.4.1.42.2.27.9.4.121.1 

2.16.840.1.113730.3.3.2.42.1 

Slovenian 

sl 

1.3.6.1.4.1.42.2.27.9.4.122.1 

2.16.840.1.113730.3.3.2.43.1 

Somali 

so or so-SO 

1.3.6.1.4.1.42.2.27.9.4.123.1 

 

Somali Djibouti 

so-DJ 

1.3.6.1.4.1.42.2.27.9.4.124.1 

 

Somali Ethiopia 

so-ET 

1.3.6.1.4.1.42.2.27.9.4.125.1 

 

Somali Kenya 

so-KE 

1.3.6.1.4.1.42.2.27.9.4.126.1 

 

Albanian 

sq 

1.3.6.1.4.1.42.2.27.9.4.127.1 

2.16.840.1.113730.3.3.2.44.1 

Serbian 

sr 

1.3.6.1.4.1.42.2.27.9.4.128.1 

2.16.840.1.113730.3.3.2.45.1 

Swedish 

sv-SE 

1.3.6.1.4.1.42.2.27.9.4.129.1 

2.16.840.1.113730.3.3.2.46.1 

Swedish Finland 

sv-FI 

1.3.6.1.4.1.42.2.27.9.4.130.1 

 

Swahili 

sw 

1.3.6.1.4.1.42.2.27.9.4.131.1 

 

Swahili Kenya 

sw-KE 

1.3.6.1.4.1.42.2.27.9.4.132.1 

 

Swahili Tanzania 

sw-TZ 

1.3.6.1.4.1.42.2.27.9.4.133.1 

 

Tamil 

ta 

1.3.6.1.4.1.42.2.27.9.4.134.1 

 

Telugu 

te 

1.3.6.1.4.1.42.2.27.9.4.135.1 

 

Thai 

th 

1.3.6.1.4.1.42.2.27.9.4.136.1 

 

Tigrinya 

ti 

1.3.6.1.4.1.42.2.27.9.4.137.1 

 

Tigrinya Eritrea 

ti-ER 

1.3.6.1.4.1.42.2.27.9.4.138.1 

 

Tigrinya Ethiopia 

ti-ET 

1.3.6.1.4.1.42.2.27.9.4.139.1 

 

Turkish 

tr 

1.3.6.1.4.1.42.2.27.9.4.140.1 

2.16.840.1.113730.3.3.2.47.1 

Ukrainian 

uk 

1.3.6.1.4.1.42.2.27.9.4.141.1 

2.16.840.1.113730.3.3.2.48.1 

Vietnamese 

vi 

1.3.6.1.4.1.42.2.27.9.4.142.1 

 

Chinese 

zh 

1.3.6.1.4.1.42.2.27.9.4.143.1 

2.16.840.1.113730.3.3.2.49.1 

Chinese China 

zh-CN 

1.3.6.1.4.1.42.2.27.9.4.144.1 

 

Chinese Hong Kong 

zh-HK 

1.3.6.1.4.1.42.2.27.9.4.145.1 

 

Chinese Mongolia 

zh-MO 

1.3.6.1.4.1.42.2.27.9.4.146.1 

 

Chinese Singapore 

zh-SG 

1.3.6.1.4.1.42.2.27.9.4.147.1 

 

Chinese Taiwan 

zh-TW 

1.3.6.1.4.1.42.2.27.9.4.148.1 

2.16.840.1.113730.3.3.2.50.1 

Supported Language Subtypes

Language subtypes can be used by clients to indicate specific attributes in characters of a language other than the default language of a deployment. For example, German users may prefer to see addresses in German when possible. In this case, you can select German as a language subtype for the streetAddress attribute so that users can search for either the English or the German representation of the address. If you specify a language subtype for an attribute, the subtype is added to the attribute name as follows:attribute;lang-subtype.

The following listing shows an English language and German language subtype for the streetAddress attribute:

streetAddress;lang-en: 10 Schlossplatz, 76113, Karlsruhe, Germany
streetAddress;lang-de: Schloßplatz 10, 76113, Karlsruhe, Deutschland

The following table contains the list of supported language subtypes.

Table 11–2 Supported Language Subtypes

Language 

Language Tag 

Afrikaans 

af 

Albanian 

sq 

Amharic Ethiopia 

am 

Arabic 

ar 

Armenian 

hy 

Basque 

eu 

Bengali India 

bn 

Bulgarian 

bg 

Byelorussian 

be 

Catalan 

ca 

Chinese 

zh 

Cornish 

kw 

Croatian 

hr 

Czech 

cs 

Danish 

da 

Dutch 

nl 

English 

en 

Esperanto 

eo 

Estonian 

et 

Faeroese 

fo 

Finnish 

fi 

French 

fr 

Galician 

gl 

German 

de 

Greek 

el 

Greenlandic 

kl 

Gujarati 

gu 

Hebrew 

he or iw 

Hindi 

hi 

Hungarian 

hu 

Icelandic 

is 

Indonesian 

id 

Irish 

ga 

Italian 

it 

Japanese 

ja 

Kannada 

kn 

Konkani 

kok 

Korean 

ko 

Latvian or Lettish 

lv 

Lithuanian 

lt 

Macedonian 

mk 

Maltese 

mt 

Manx (Isle of Man) 

gv 

Marathi 

mr 

Norwegian 

no 

Oromo 

om 

Persian 

fa 

Polish 

pl 

Portuguese 

pt 

Romanian 

ro 

Russian 

ru 

Serbian 

sr 

Serbo-Croatian 

sh 

Slovak 

sk 

Slovenian 

sl 

Somali 

so 

Spanish 

es 

Swahili 

sw 

Swedish 

sv 

Tamil 

ta 

Telugu 

te 

Thai 

th 

Tigrinya 

ti 

Turkish 

tr 

Ukrainian 

uk 

Vietnamese 

vi 

Chapter 12 Directory Server LDAP URLs

One way to express an LDAP query is to use a URL to specify the Directory Server host machine and the DN or filter for the search. Directory Server responds to queries sent as LDAP URLs and returns an HTML page representing the results. In this way, if anonymous searching is permitted, web browsers can perform searches of the directory. You can also use LDAP URLs to specify target entries when you manage Directory Server referrals or when you access control instructions.

For information about LDAP URLs, see the following sections:

Components of an LDAP URL

LDAP URLs have the following syntax:

ldap[s]://hostname:port/base_dn?attributes?scope?filter

When ldap:// is specified, standard LDAP is used to connect to the LDAP servers. When ldaps:// is specified, LDAP over SSL is used to connect to the LDAP server.

Table 12–1 LDAP URL Components

Component 

Description 

hostname

Name (or IP address in dotted format) of the LDAP server. For example: 

ldap.example.com or 192.168.1.100

port

Port number of the LDAP server. 

If no port is specified, the standard LDAP port (389) or LDAPS port (636) is used. 

base_dn

Distinguished name (DN) of an entry in the directory. This DN identifies the entry that is the starting point of the search.  

If no base DN is specified, the search starts at the root of the directory tree. 

attributes

The attributes to be returned. To specify more than one attribute, use commas to separate the attributes. For example, "cn,mail,telephoneNumber".

If no attributes are specified in the URL, all attributes are returned. 

scope

The scope of the search. The scope can be one of these values: 

  • base retrieves information about the distinguished name (base_dn) specified in the URL only.

  • one retrieves information about entries one level below the distinguished name (base_dn) specified in the URL. The base entry is not included in this scope.

  • sub retrieves information about entries at all levels below the distinguished name (base_dn) specified in the URL. The base entry is included in this scope.

    If no scope is specified, the server performs a base search.

filter

Search filter to apply to entries within the specified scope of the search. 

If no filter is specified, the server uses the filter objectClass=*.

The following components are identified by their positions in the URL: attributes, scope, and filter are. If you do not want to specify a component, you must include a question mark to delimit the field. Two consecutive question marks, ??, indicate that no attributes have been specified.

For example, to specify a subtree search starting from "dc=example,dc=com" that returns all attributes for entries matching "(sn=Jensen)", use the following LDAP URL.

ldap://ldap.example.com/dc=example,dc=com??sub?(sn=Jensen)

Because no specific attributes are identified in the URL, all attributes are returned in the search.

Escaping Unsafe Characters

Unsafe characters in a URL must be represented by a special sequence of characters. The following table lists the characters that are unsafe within URLs, and provides the associated escape characters to use in place of the unsafe character.

Table 12–2 Characters That Are Unsafe Within URLs

Unsafe Character 

Escape Characters 

space 

%20 

< 

%3c 

\> 

%3e 

" 

%22 

# 

%23 

% 

%25 

{ 

%7b 

} 

%7d 

| 

%7c 

\\ 

%5c 

^ 

%5e 

~ 

%7e 

[ 

%5b 

] 

%5d 

” 

%60 

Examples of LDAP URLs

The syntax for LDAP URLs does not include any means for specifying credentials or passwords. Search request initiated through LDAP URLs are unauthenticated (anonymous), unless the LDAP client that supports LDAP URLs provides an authentication mechanism. This section gives examples of LDAP URLs.

Example 12–1 Base Search for an Entry

The following LDAP URL specifies a base search for the entry with the distinguished name dc=example,dc=com.

ldap://ldap.example.com/dc=example,dc=com
Example 12–2 Retrieving postalAddress Attribute of an Entry

The following LDAP URL retrieves the postalAddress attribute of the entry with the DN dc=example,dc=com:

ldap://ldap.example.com/dc=example,dc=com?postalAddress
Example 12–3 Retrieving cn and mail Attributes of an Entry

The following LDAP URL retrieves the cn, and mail attributes of the entry for Barbara Jensen.

ldap://ldap.example.com/cn=Barbara%20Jensen,dc=example, dc=com?cn,mail
Example 12–4 Retrieving the Surname Jensen Under dc=example,dc=com

The following LDAP URL specifies a search for entries that have the surname Jensen and are at any level under dc=example,dc=com:

ldap://ldap.example.com/dc=example,dc=com??sub?(sn=Jensen)
Example 12–5 Retrieving the Object Class for all Entries One Level Under dc=example,dc=com

The following LDAP URL specifies a search for the object class for all entries one level under dc=example,dc=com:

ldap://ldap.example.com/dc=example,dc=com?objectClass?one

Chapter 13 Directory Server LDIF and Search Filters

Directory Server uses the LDAP Data Interchange Format (LDIF) to describe a directory and its entries in text format. LDIF can be used to build the initial directory database or to add large numbers of entries to a directory. LDIF can also be used to describe changes to directory entries. Most command-line utilities rely on LDIF for input or output.

All directory data is stored by using the UTF-8 encoding of Unicode, and, therefore, LDIF files must also be UTF-8 encoded.

This chapter also provides information about searching the directory, and LDAP search filters.

For information about LDIF and searching the directory, see the following sections:

LDIF File Format

LDIF files consist of one or more directory entries separated by a blank line. Each LDIF entry consists of the following parts:

The LDIF format is defined in RFC 2849.

The following example shows a basic directory entry in LDIF.

Example 13–1 A Directory Entry in LDIF

dn: distinguished_name
objectClass: object_class
objectClass: object_class
...
attribute_type[;subtype]: attribute_value
attribute_type[;subtype]: attribute_value
...

An LDIF file must contain the following parts:

All other attributes and object classes are optional. Object classes and attributes can be specified in any order. The space after the colon is optional.

The following table describes the fields in a LDIF file.

Table 13–1 LDIF Fields

Field  

Definition  

[id]

Optional. A positive decimal number representing the entry ID. The database creation tools generate this ID for you. Never add or edit this value yourself. 

dn: distinguished_name

The distinguished name for the entry. 

objectClass: object_class

An object class to use with this entry. The object class identifies the types of attributes or schema that are allowed and required for the entry.  

attribute_type

A descriptive attribute to use with the entry. The attribute should be defined in the schema. 

[subtype]

Optional. A subtype of one of the following types: 

  • Language (attribute;lang-subtype) identifies the language in which the corresponding attribute value is expressed

  • Binary (attribute;binary) identifies whether the attribute value is binary

  • Pronunciation (attribute;phonetic) identifies whether the attribute value is a pronunciation of an attribute value

attribute_value

The attribute value to be used with the attribute type. 

The LDIF syntax for representing a change to an entry in the directory is different from the syntax described above.

Continuing Lines in LDIF

When you specify LDIF, you can break and continue a line or fold a line by indenting the continued portion of the line by one space. For example, the following two statements are identical:

dn: cn=Babs Jensen,dc=example,dc=com

dn: cn=Babs J
 ensen,dc=exam
 ple,dc=com

You are not required to break and continue LDIF lines. However, doing so can improve the readability of an LDIF file.

Binary Data in LDIF

You can represent binary data in LDIF by using one of the following methods:

Representing Binary Data by Using Standard LDIF Notation

The following example gives the standard LDIF notation of binary data:

jpegphoto:< file:/path/to/photo

In the example, the path is relative to the client, not to the server. To use standard notation, you do not need to specify the ldapmodify -b parameter. However, you must add the following line to the beginning of your LDIF file or to your LDIF update statements:

version:1

For example, you could use the ldapmodify command, as follows:


$ ldapmodify -D userDN -w passwd
version: 1
dn: cn=Barbara Jensen,ou=People,dc=example,dc=com
changetype: modify
add: userCertificate
userCertificate;binary:< file: BabsCert

Representing Binary Data by Using the ldapmodify -b Command

For backward compatibility with earlier versions of Directory Server, binary data can be represented by using the ldapmodify -b command. However, when possible, use the standard LDIF notation to represent binary data.

Directory Server accepts the ldapmodify command with the -b parameter and the following LDIF notation:

jpegphoto: /path/to/photo

This notation indicates that the ldapmodify command should read the referenced file for binary values if the attribute value begins with a slash.

Representing Binary Data by Using Base 64 Encoding

Base 64 encoded data is represented by the :: symbol, as shown in this example:

jpegPhoto:: encoded_data

In addition to binary data, the following values must be base 64 encoded:

Use the ldif command with the -b parameter to convert binary data to LDIF format, as follows.


$ ldif -b attributeName

For more information about how to use the ldif command, see the ldif(1) man page.

In the above example, attributeName is the name of the attribute to which you are supplying the binary data. The binary data is read from standard input and the results are written to standard output. Use redirection operators to select input and output files.

The command takes any input and formats it with the correct line continuation and appropriate attribute information. The command also assesses whether the input requires base–64 encoding. The following example takes a binary file containing a JPEG image and converts it into LDIF format for the attribute named jpegPhoto. The output is saved to out.ldif:


$ ldif -b jpegPhoto < aphoto.jpg > out.ldif

The -b option specifies that the utility should interpret the entire input as a single binary value. If the -b option is not present, each line is considered as a separate input value.

You can edit the output file to add the LDIF statements required to create or modify the directory entry that will contain the binary value. For example, you can open the file out.ldif in a text editor and add the following lines at the top of the file.

dn: cn=Barbara Jensen,ou=People,dc=example,dc=com
changetype: modify
add: jpegPhoto
jpegPhoto:: encoded_data

In this example, encoded_data represents the contents of the out.ldif file produced by the command.

Directory Entries in LDIF

This section covers the following topics:

Organization Entries in LDIF

Directories often have at least one organization entry. Typically the organization entry is the first, or topmost entry in the directory. The organization entry often corresponds to the suffix set for the directory. For example, a directory defined to use a suffix of o=example.com will probably have an organization entry named o=example.com.

The LDIF that defines an organization entry should appear as follows:

dn: distinguished_name
objectClass: top 
objectClass: organization
o: organization_namelist_of_optional_attributes...

The following is an example organization entry in LDIF format:

dn: o=example.com
objectclass: top
objectclass: organization
o: example.com Corporation
description: Fictional company for example purposes
telephonenumber: 555-5555

The organization name in the following example uses a comma:

dn: o=example.com Chile\, S.A.
objectclass: top
objectclass: organization
o: example.com Chile\, S.A.
description: Fictional company for example purposes
telephonenumber: 555-5556

The following table describes each element of the organization entry.

Table 13–2 Organization Entries in LDIF

LDIF Element  

Description  

dn: distinguished_name

Required. Specifies the distinguished name for the entry.  

objectClass: top

Required. Specifies the top object class. 

objectClass: organization

Specifies the organization object class. This line defines the entry as an organization.  

o: organization_name

Specifies the organization’s name. If the organization name includes a comma, you must escape the comma by a single backslash or the entire organization argument must be enclosed in quotation marks. However, if you are working with a UNIX shell, you must also escape the backslash. Therefore, you must use two back slashes. For example, to set the suffix to example.com Bolivia, S.A. you would enter o: example.com Bolivia\, S.A..

list_of_attributes

Specifies the list of optional attributes that you want to maintain for the entry.  

Organizational Unit Entries in LDIF

In a directory tree, an organizational unit represents a major subdirectory. A directory tree usually contains more than one organizational unit. An LDIF file that defines an organizational unit entry must appear as follows:

dn: distinguished_name
objectClass: top
objectClass: organizationalUnit
ou: organizational_unit_namelist_of_optional_attributes...

The following example shows an organizational unit entry in LDIF format:

dn: ou=people, o=example.com
objectclass: top
objectclass: organizationalUnit
ou: people
description: Fictional organizational unit for example purposes

The following table defines each element of the organizational unit entry.

Table 13–3 Organizational Unit Entries in LDIF

LDIF Element  

Description  

dn: distinguished_name

Required. Specifies the distinguished name for the entry.  

If there is a comma in the DN, the comma must be escaped with a backslash (\). For example: 

dn: ou=people,o=example.com Bolivia\,S.A.

objectClass: top

Required. Specifies the top object class.

objectClass: organizationalUnit

Specifies the organizationalUnit object class. This line defines the entry as an organizationalUnit.

ou: organizational_unit_name

Specifies an attribute containing the name of the organizational unit. 

list_of_attributes

Specifies the list of optional attributes that maintain for the entry.  

Organizational Person Entries in LDIF

The majority of the entries in a directory represent organizational people. In LDIF, the definition of an organizational person is as follows:

dn: distinguished_name
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: common_name 
sn: surname
list_of_optional_attributes

The following example shows an organizational person entry in LDIF format:

dn: uid=bjensen,ou=people,o=example.com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Babs Jensen
sn: Jensen
givenname: Babs
uid: bjensen
ou: Marketing
ou: people
description: Fictional person for example purposes
telephonenumber: 555-5557
userpassword: {sha}dkfljlk34r2kljdsfk9

The following table defines each element of the LDIF person entry.

Table 13–4 Organizational Person Entries in LDIF

LDIF Element  

Description  

dn: distinguished_name

Required. Specifies the distinguished name for the entry. 

If there is a comma in the DN, the comma must be escaped with a backslash (\). For example, dn:uid=bjensen,ou=people,o=example.com Bolivia\,S.A.

objectClass: top

Required. Specifies the top object class.

objectClass: person

Specifies the person object class. This object class specification should be included because many LDAP clients require it during search operations for a person or an organizational person.

objectClass: organizationalPerson

Specifies the organizationalPerson object class. This object class specification should be included because some LDAP clients require it during search operations for an organizational person.

objectClass: inetOrgPerson

Specifies the inetOrgPerson object class. The inetOrgPerson object class is recommended for the creation of an organizational person entry because this object class includes the widest range of attributes. The uid attribute is required by this object class, and entries that contain this object class are named based on the value of the uid attribute.

cn: common_name

Required. Specifies the person’s common name which is the full name commonly used by the person. For example, cn: Bill Anderson.

sn: surname

Required. Specifies the person’s surname, or last name. For example, sn: Anderson.

list_of_attributes

Specifies the list of optional attributes that you maintain for the entry.  

Guidelines for Defining Directories by Using LDIF

Follow these guidelines to create a directory by using LDIF.

The following example shows an LDIF file with one organization entry, two organizational unit entries, and three organizational person entries.

Example 13–2 Example LDIF File With Entries for Organization, Organizational Units, and Organizational Person

dn: o=example.com Corp
objectclass: top
objectclass: organization
o: example.com Corp
description: Fictional organization for example purposes
dn: ou=People,o=example.com Corp
objectclass: top
objectclass: organizationalUnit
ou: People
description: Fictional organizational unit for example purposes
tel: 555-5559

dn: cn=June Rossi,ou=People,o=example.com Corp
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: June Rossi
sn: Rossi
givenName: June
mail: rossi@example.com
userPassword: {sha}KDIE3AL9DK
ou: Accounting
ou: people
telephoneNumber: 2616
roomNumber: 220

dn: cn=Marc Chambers,ou=People,o=example.com Corp
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Marc Chambers
sn: Chambers
givenName: Marc
mail: chambers@example.com
userPassword: {sha}jdl2alem87dlacz1
telephoneNumber: 2652
ou: Manufacturing
ou: People
roomNumber: 167

dn: cn=Robert Wong,ou=People,o=example.com Corp
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Robert Wong
cn: Bob Wong
sn: Wong
givenName: Robert
givenName: Bob
mail: bwong@example.com
userPassword: {sha}nn2msx761
telephoneNumber: 2881
roomNumber: 211
ou: Manufacturing
ou: people

dn: ou=Groups,o=example.com Corp
objectclass: top
objectclass: organizationalUnit
ou: groups
description: Fictional organizational unit for example purposes

Storing Information in Multiple Languages

For directories that contains a single language, it is not necessary to do anything special to add a new entry to the directory. However, for multinational organizations, it can be necessary to store information in multiple languages so that users in different locales can view directory information in their own language.

When information is represented in multiple languages, the server associates language tags with attribute values. When a new entry is added, attribute values used in the RDN (Relative Distinguished Name) must be added without any language codes.

Multiple languages can be stored within a single attribute. The attribute type is the same, but each attribute value has a different language code. The language tag has no effect on how the string is stored within the directory. All object class and attribute strings are stored using UTF-8.

For a list of the languages supported by Directory Server and their associated language tags, refer to Identifying Supported Locales.

For example, the example.com Corporation has offices in the United States and France. The company wants employees to be able to view directory information in their native language. When a directory entry is added for a new employee, Babs Jensen, the administrator creates the entry in LDIF. The administrator creates values for the personalTitle attribute in English and French, as follows:

dn: uid=bjensen,ou=people, o=example.com Corp
objectclass: top
objectclass: person
objectclass: organizationalPerson
name: Babs Jensen
cn: Babs Jensen
sn: Jensen
uid: bjensen
personalTitle: Miss
personalTitle;lang-en: Miss
personalTitle;lang-fr: Mlle
preferredLanguage: fr

Users accessing this directory entry with an LDAP client with the preferred language set to English will see the personal title Miss. Users accessing the directory with an LDAP client with the preferred language set to French will see the title Mlle.

Guidelines for Providing LDIF Input

All directory data is stored using the UTF-8 encoding of Unicode. Therefore, any LDIF input you provide must also be UTF-8 encoded. The LDIF format is described in detail in “LDAP Data Interchange Format Reference” in the Sun Java System Directory Server Enterprise Edition 6.0 Reference.

Consider the following points when you provide LDIF input:

Terminating LDIF Input on the Command Line

The ldapmodify and ldapdelete utilities read the LDIF statements that you enter after the command in exactly the same way as if they were read from a file. When you finish providing input, enter the character that your shell recognizes as the end of file (EOF) escape sequence.

Typically, the EOF escape sequence is Control-D (^D).

The following example shows how to terminate input to the ldapmodify command:

prompt\> ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w -
 dn: cn=Barry Nixon,ou=People,dc=example,dc=com
changetype: modify
delete: telephonenumber
^D
prompt\>

For simplicity and portability, examples in this document do not show prompts or EOF sequences.

Using Special Characters

When entering command options on the command line, you may need to escape characters that have special meaning to the command-line interpreter, such as space ( ), asterisk (*), backslash (\\), and so forth. For example, many DNs contain spaces, and you must enclose the value in double quotation marks ("") for most UNIX shells:

-D "cn=Barbara Jensen,ou=Product Development,dc=example,dc=com"

Depending on your command-line interpreter, you should use either single or double quotation marks for this purpose. Refer to your operating system documentation for more information.

In addition, if you are using DNs that contain commas, you must escape the commas with a backslash (\\). For example:

-D "cn=Patricia Fuentes,ou=People,o=example.com Bolivia\\,S.A."

Note that LDIF statements after the ldapmodify command are being interpreted by the command, not by the shell, and therefore do not need special consideration.

Using Attribute OIDs

Attribute OIDs are by default not supported in attribute names. This was not the case in some previous versions of Directory Server. If you used attribute OIDs as attribute names in a previous version of Directory Server, you must set the attribute nsslapd-attribute-name-exceptions to on for the attribute OIDs to be accepted.

Schema Checking

When adding or modifying an entry, the attributes you use must be required or allowed by the object classes in your entry, and your attributes must contain values that match their defined syntax.

When modifying an entry, Directory Server performs schema checking on the entire entry, not only the attributes being modified. Therefore, the operation may fail if any object class or attribute in the entry does not conform to the schema.

Ordering of LDIF Entries

In any sequence of LDIF text for adding entries, either on the command line or in a file, parent entries must be listed before their children. This way, when the server process the LDIF text, it will create the parent entries before the children entries.

For example, if you want to create entries in a People subtree that does not exist in your directory, then list an entry representing the People container before the entries within the subtree: 

dn: dc=example,dc=com
dn: ou=People,dc=example,dc=com
...
People subtree entries...
dn: ou=Group,dc=example,dc=com
...
Group subtree entries...

You can use the ldapmodify command-line utility to create any entry in the directory, however, the root of a suffix or subsuffix is a special entry that must be associated with the necessary configuration entries.

Managing Large Entries

Before adding or modifying entries with very large attribute values, you may need to configure the server to accept them. To protect against overloading the server, clients are limited to sending data no larger than 2 MB by default.

If you add an entry larger than this, or modify an attribute to a value which is larger, the server will refuse to perform the operation and immediately close the connection. For example, binary data such as multi-media contents in one or more attributes of an entry may exceed this limit.

Also, the entry defining a large static group may contain so many members that their representation exceeds the limit. However, such groups are not recommended for performance reasons, and you should consider redesigning your directory structure.

ProcedureTo Modify the Size Limit Enforced by the Server on Data Sent by Clients

  1. Set a new value for the nsslapd-maxbersize attribute of the cn=config entry.

    • To do this from the command line, use the following command:


      ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=config
changetype: modify
replace: nsslapd-maxbersize
nsslapd-maxbersize: sizeLimitInBytes
 ^D

      For more information, see “nsslapd-maxbersize” in the Sun Java System Directory Server Enterprise Edition 6.0 Reference.

  2. Restart the server.

Error Handling

The command-line tools process all entries or modifications in the LDIF input sequentially. The default behavior is to stop processing when the first error occurs. Use the -c option to continue processing all input regardless of any errors. You will see the error condition in the output of the tool.

In addition to the considerations listed above, common errors are:

Searching the Directory

You can locate entries in a directory using any LDAP client. Most clients provide some form of search interface that enables you to search the directory and retrieve entry information.

The access control that has been set in your directory determines the results of your searches. Common users typically do not “see” much of the directory, and directory administrators have full access to all data, including configuration.

Searching the Directory With ldapsearch

You can use the ldapsearch command-line utility to locate and retrieve directory entries. Note that the ldapsearch utility described in this section is not the utility provided with the Solaris platform, but is part of the Directory Server Resource Kit.

This utility opens a connection to the server with a specified a user identity (usually a distinguished name) and password, and locates entries based on a search filter. Search scopes can include a single entry, an entry’s immediate subentries, or an entire tree or subtree.

Search results are returned in LDIF format.

ldapsearch Command-Line Format

When you use ldapsearch, you must enter the command using the following format:

ldapsearch [optional_options] [search_filter] [optional_list_of_attributes]

where

Note –

If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command. To retrieve regular attributes in addition to explicitly specified operational attributes, use an asterisk (*) in the list of attributes in the ldapsearch command.

Using Special Characters

When using the ldapsearch command-line utility, you may need to specify values that contain characters that have special meaning to the command-line interpreter (such as space [ ], asterisk [*], backslash [\\], and so forth). When you specify special characters, enclose the value in quotation marks (“”). For example:

-D "cn=Charlene Daniels,ou=People,dc=example,dc=com"

Depending on your command-line interpreter, use either single or double quotation marks for this purpose. Refer to your shell documentation for more information.

Commonly Used ldapsearch options

The following lists the most commonly used ldapsearch command-line options. If you specify a value that contains a space [ ], the value should be surrounded by double quotation marks, for example, -b "ou=groups, dc=example,dc=com".

-b

Specifies the starting point for the search. The value specified here must be a distinguished name that currently exists in the database. This option is optional if the LDAP_BASEDN environment variable has been set to a base DN.

The value specified in this option should be provided in double quotation marks. For example:

-b "cn=Charlene Daniels, ou=People, dc=example,dc=com"
-D

Specifies the distinguished name with which to authenticate to the server. This option is optional if anonymous access is supported by your server. If specified, this value must be a DN recognized by Directory Server, and it must also have the authority to search for the entries. For example:

-D "uid=cdaniels, dc=example,dc=com"

-h

Specifies the hostname or IP address of the machine on which Directory Server is installed. If you do not specify a host, ldapsearch uses the localhost. For example, -h myServer.

-l

Specifies the maximum number of seconds to wait for a search request to complete. Regardless of the value specified here, ldapsearch will never wait longer than is allowed by the server’s nsslapd-timelimit attribute (except in the case of a persistent search.)Sun Java System Directory Server Enterprise Edition 6.0 Reference.

For example, -l 300. The default value for the nsslapd-timelimit attribute is 3,600 seconds (1 hour.)

-p

Specifies the TCP port number that Directory Server uses. For example, -p 5201. The default is 389, and 636 when the SSL options are used.

-s

Specifies the scope of the search. The scope can be one of:

  • base—Search only the entry specified in the -b option or defined by the LDAP_BASEDN environment variable.

  • one—Search only the immediate children of the entry specified in the -b option. Only the children are searched; the actual entry specified in the -b option is not searched.

  • sub—Search the entry specified in the -b option and all of its descendants. That is, perform a subtree search starting at the point identified in the -b option. This is the default.

-w

Specifies the password associated with the distinguished name that is specified in the -D option. If you do not specify this option, anonymous access is used. For example, -w diner892.

-x

Specifies that the search results are sorted on the server rather than on the client. This is useful if you want to sort according to a matching rule, as with an international search. In general, it is faster to sort on the server rather than on the client, although server-side sorting uses server resources.

-z

Specifies the maximum number of entries to return in response to a search request. For example, -z 1000.

Normally, regardless of the value specified here, ldapsearch never returns more entries than the number allowed by the server’s nsslapd-sizelimit attribute. However, you can override this limitation by binding as the root DN when using this command-line argument. When you bind as the root DN, this option defaults to zero (0). The default value for the nsslapd-sizelimit attribute is 2,000 entries.

For detailed information on all ldapsearch utility options, refer to ldapmodify(1).

ldapsearch Examples

In the next set of examples, the following assumptions are made:

Returning All Entries

Given the previous information, the following call will return all entries in the directory:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config
 -b "dc=example,dc=com" -s sub "(objectclass=*)"

"(objectclass=*)" is a search filter that matches any entry in the directory.

Specifying Search Filters on the Command Line

You can specify a search filter directly on the command line. If you do this, be sure to enclose your filter in quotation marks (“filter”). Also, do not specify the -f option.

For example:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -b "dc=example,dc=com" "(cn=Charlene Daniels)"

Searching the Root DSE Entry

The root DSE is a special entry that contains information related to the current server instance, such as a list of supported suffixes, available authentication mechanisms, and so forth. You can search this entry by supplying a search base of “”. You must also specify a search scope of base and a filter of "(objectclass=*)".

For example:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -b "" -s base "(objectclass=*)"

Searching the Schema Entry

Directory Server stores all directory server schema in the special cn=schema entry. This entry contains information on every object class and attribute defined for your directory server.

You can examine the contents of this entry as follows:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config
 -b "cn=schema" -s base "(objectclass=*)"
Note –

For strict compliance, the location of the schema subentry for a given entry is specified by the subschemaSubentry operational attribute. In this version of Directory Server, the value of this attribute is always cn=schema.

Using LDAP_BASEDN

To make searching easier, you can set your search base using the LDAP_BASEDN environment variable. Doing this allows you to skip specifying the search base with the -b option (for information on how to set environment variables, see the documentation for your operating system).

Typically, you set LDAP_BASEDN to your directory’s suffix value. Since your directory suffix is equal to the root, or topmost, entry in your directory, this causes all searches to begin from your directory’s root entry.

For example, if you have set LDAP_BASEDN to dc=example,dc=com, you can search for (cn=Charlene Daniels) in your directory using the following command-line call:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(cn=Charlene Daniels)"

In this example, the default scope of sub is used because the -s option was not used to specify the scope.

Displaying Subsets of Attributes

The ldapsearch command returns all search results in LDIF format. By default, ldapsearch returns the entry’s distinguished name and all of the attributes that you are allowed to read. You can set up the directory access control such that you are allowed to read only a subset of the attributes on any given directory entry.) Only operational attributes are not returned. If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command. For more information on operational attributes, refer to the TODO: No more AdminServerAdminGuide.

Suppose you do not want to see all of the attributes returned in the search results. You can limit the returned attributes to just a few specific attributes by specifying the ones you want on the command line immediately after the search filter. For example, to show the cn and sn attributes for every entry in the directory, use the following command:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(objectclass=*)" sn cn

This example assumes you set your search base with LDAP_BASEDN.

Searching Multi-Valued Attributes

During a search, Directory Server does not necessarily return multi-valued attributes in sorted order. For example, suppose you want to search for configuration attributes on cn=config requiring that the server be restarted before changes take effect.

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -b cn=config "(objectclass=*)" nsslapd-requiresrestart

The following result is returned:

dn: cn=config
nsslapd-requiresrestart: cn=config:nsslapd-port
nsslapd-requiresrestart: cn=config:nsslapd-secureport
nsslapd-requiresrestart: cn=config:nsslapd-plugin
nsslapd-requiresrestart: cn=config:nsslapd-changelogdir
nsslapd-requiresrestart: cn=config:nsslapd-changelogsuffix
nsslapd-requiresrestart: cn=config:nsslapd-changelogmaxentries
nsslapd-requiresrestart: cn=config:nsslapd-changelogmaxage
nsslapd-requiresrestart: cn=config:nsslapd-db-locks
nsslapd-requiresrestart: cn=config:nsslapd-return-exact-case
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-allidsthreshold
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-dbcachesize
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-dbncache
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-directory
nsslapd-requiresrestart: cn=encryption,cn=config:nssslsessiontimeout
nsslapd-requiresrestart: cn=encryption,cn=config:nssslclientauth
nsslapd-requiresrestart: cn=encryption,cn=config:nssslserverauth
nsslapd-requiresrestart: cn=encryption,cn=config:nsssl2
nsslapd-requiresrestart: cn=encryption,cn=config:nsssl3
...

As shown here, the nsslapd-requiresrestart attribute takes multiple values. These values are not, however, in sorted order. If you develop an application that requires multi-valued attributes in sorted order, make sure that your application performs the sort.

Using Client Authentication When Searching

This example shows user cdaniels searching the directory using client authentication:

ldapsearch -h myServer -p 636 -b "dc=example,dc=com"
  -N  "cdanielsscertname" -Z -W certdbpassword
  -P /home/cdaniels/certdb/cert.db "(givenname=Richard)"

LDAP Search Filters

Search filters select the entries to be returned for a search operation. They are most commonly used with the ldapsearch command-line utility. When you use ldapsearch, you can place multiple search filters in a file, with each filter on a separate line in the file, or you can specify a search filter directly on the command line.

For example, the following filter specifies a search for the common name Lucie Du Bois:

(cn=Lucie Du Bois)

This search filter returns all entries that contain the common name Lucie Du Bois. Searches for common name values are not case sensitive.

When the common name attribute has values associated with a language tag, all of the values are returned. Thus, the following two attribute values both match this filter:

cn: Lucie Du Bois
cn;lang-fr: Lucie Du Bois

Search Filter Syntax

The basic syntax of a search filter is:

(attribute operator value)

For example:

(buildingname\>=alpha)

In this example, buildingname is the attribute, \>= is the operator, and alpha is the value. You can also define filters that use different attributes combined together with Boolean operators.

Search filters are described in detail in the following sections:

Using Attributes in Search Filters

When searching for an entry, you can specify attributes associated with that type of entry. For example, when you search for people entries, you can use the cn attribute to search for people with a specific common name.

Examples of attributes that people entries might include:

Using Operators in Search Filters

The operators that you can use in search filters are listed in Table 13–5:

Table 13–5 Search Filter Operators

Search Type

Operator  

Description  

Equality

= 

Returns entries containing attribute values that exactly match the specified value. For example, cn=Bob Johnson

Substring

=string*string

Returns entries containing attributes containing the specified substring. For example, 

cn=Bob*cn=*Johnsoncn=*John*cn=B*John

(The asterisk (*) indicates zero (0) or more characters.) 

Greater than or equal to

\>= 

Returns entries containing attributes that are greater than or equal to the specified value. For example, 

buildingname \>= alpha

Less than or equal to

<= 

Returns entries containing attributes that are less than or equal to the specified value. For example, 

buildingname <= alpha

Presence

=* 

Returns entries containing one or more values for the specified attribute. For example, 

cn=*

telephonenumber=*

manager=*

Approximate

~= 

Returns entries containing the specified attribute with a value that is approximately equal to the value specified in the search filter. For example, 

cn~=suret

l~=san fransico

could return 

cn=sarette

l=san francisco

The Approximate operator is experimental and works only with English language strings. It does not work with non-ASCII based strings, such as Ja or Zn. 

Extended operators exist that extend searches to dn attributes (cn:dn:=John, for example) and provide support for internationalized searches.

Using OIDs in Search Filters

LDAPv3 enables you to build match operators and rules for a particular attribute. Matching rules define how to compare attribute values with a particular syntax. In other words, a matching rule defines how potentially matching attributes are compared. For example, a matching rule can define whether or not to take text case into account when comparing attributes.

When the rules are created, they can be referred to in a search filter.

For example, the following search filter compares entries containing the surname “Jensen” by using the matching rule designated by OID 2.5.13.5:

(sn:2.5.13.5:=Jensen)

The following example illustrates the use of the ":dn" notation to indicate that OID 2.5.13.5 should be used when making comparisons, and that the attributes of an entry\qs distinguished name should be considered part of the entry when evaluating the match:

(sn:dn:2.5.13.5:=Jensen)

Using Compound Search Filters

Multiple search filter components can be combined using Boolean operators expressed in prefix notation as follows:

(Boolean-operator(filter)(filter)(filter)...)

where Boolean-operator is any one of the Boolean operators listed in Table 13–6.

Boolean operators can be combined and nested together to form complex expressions, such as:

(Boolean-operator(filter)(Boolean-operator(filter)(filter)))

The Boolean operators available for use with search filters include the following:

Table 13–6 Search Filter Boolean Operators

Operator  

Symbol  

Description  

AND 

& 

All specified filters must be true for the statement to be true.For example, 

(&(filter)(filter)(filter)...)

OR 

| 

At least one specified filter must be true for the statement to be true.For example, 

(|(filter)(filter)(filter)...)

NOT 

! 

The specified statement must not be true for the statement to be true. Only one filter is affected by the NOT operator. For example, 

(!(filter))

Boolean expressions are evaluated in the following order:

Specifying Search Filters Using a File

You can enter search filters into a file instead of entering them on the command line. When you do this, specify each search filter on a separate line in the file. The ldapsearch command runs each search in the order in which it appears in the file.

For example, if the file contains:

(sn=Daniels)
(givenname=Charlene)

then ldapsearch first finds all the entries with the surname Daniels, and then all the entries with the given name Charlene. If an entry is found that matches both search criteria, the entry is returned twice.

For example, suppose you specified the previous search filters in a file named searchdb, and you set your search base using LDAP_BASEDN. The following returns all the entries that match either search filter:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -f searchdb

You can limit the set of attributes returned here by specifying the attribute names that you want at the end of the search line. For example, the following ldapsearch command performs both searches, but returns only the DN and the givenname and sn attributes of each entry:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -f searchdb sn givenname

Specifying Non 7-Bit ASCII Characters in Search Filters

Non 7-bit ASCII characters in search filters must be replaced with a representation of the character, where each byte of the UTF-8 encoding is preceded by a backslash. In UTF-8, characters are represented by a hexadecimal code for each byte.

For example, the character é has UTF-8 representation c3a9. Thus, in a search filter, you represent é as \\c3\\a9. So, to search for cn=Véronique Martin:

ldapsearch -h myServer -b "dc=example,dc=com" "(cn=V\\c3\\a9ronique Martin)"

The special characters listed in Table 13–7 must also be represented in this fashion when used in search filters.

Table 13–7 Special Characters in Search Filters

Special character  

Value With Special Character  

Example Filter  

* 

Five*Star

(cn=Five\\2aStar)

\\ 

c:\\File

(cn=\\5cFile)

() 

John (2nd)

(cn=John \\282nd\\29)

null 

0004

(bin=\\00\\00\\00\\04)

Escaped Characters in Distinguished Names within Search Filters

When using a DN in any part of Directory Server, you must escape commas and certain other special characters with a backslash (\\). If you are using a DN in a search filter, the backslash used for escaping special characters in DNs must be represented by \\5c. For example:

DN: cn=Julie Fulmer,ou=Marketing\\,Bolivia,dc=example,dc=com

DN in a search filter: ldapsearch -h myServer -b "dc=example,dc=com" "(manager=cn=Julie Fulmer,ou=Marketing\\5c,Bolivia,dc=example,dc=com)"

Search Filter Examples

The following filter searches for entries containing one or more values for the manager attribute. This is also known as a presence search:

(manager=*)

The following filter searches for entries containing the common name Ray Kultgen. This is also known as an equality search:

(cn=Ray Kultgen)

The following filter returns all entries that contain a description attribute that contains the substring X.500:

(description=*X.500*)

The following filter returns all entries whose organizational unit is Marketing and whose description field does not contain the substring X.500:

(&(ou=Marketing)(!(description=*X.500*)))

The following filter returns all entries whose organizational unit is Marketing and that have Julie Fulmer or Cindy Zwaska as a manager:

(&(ou=Marketing)(|(manager=cn=Julie Fulmer,ou=Marketing,
 dc=example,dc=com)(manager=cn=Cindy Zwaska,ou=Marketing,
 dc=example,dc=com)))

The following filter returns all entries that do not represent a person:

(!(objectClass=person))

Note that the previous filter will have a negative performance impact and should be used as part of a complex search. The following filter returns all entries that do not represent a person and whose common name is similar to printer3b:

(&(cn~=printer3b)(!(objectClass=person)))

Searching for Operational Attributes

If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command.

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(objectclass=*)" aci

To retrieve regular attributes in addition to explicitly specified operational attributes, specify “*” in addition to the operational attributes. For example:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(objectclass=*)" aci *

Chapter 14 Directory Server Error Log Message Reference

This chapter lists messages logged by Directory Server. While this list is not exhaustive, the information presented in this chapter serves as a good starting point for resolving common problems.

This chapter includes the following sections:

Log messages are defined according to their severity.

Error

The error is severe. Immediate action should be taken to avoid the loss or corruption of directory data.

Warning

Action should be taken at some stage to prevent a severe error occurring in the future.

Info

An informative message, usually describing server activity. No action is necessary.

Note –

When using the error log for debugging, increase the log level progressively until the debugging data you need becomes evident in the log. Do not enable error logging for all Directory Server components at once, especially on a production system, to avoid severely impacting performance.

In the case of internal errors, plug-in writers should check their parameters to slapi_*() functions first.

Common Error Codes

This section describes the error codes displayed in the instance-path/logs/errors log and the appropriate action to take should these errors occur.


4104: No backend has been defined to do the import.

Cause:

The server cannot detect a backend to do the import. This is an internal error and should not occur under normal circumstances.

Solution:

Contact Sun Technical Support.


4105: Bulk import not supported by this backend.

Cause:

The backend will not accept wire import. This is an internal error and should not occur under normal circumstances.

Solution:

Contact Sun Technical Support.


4107: Ignoring extremely large value for configuration attribute attribute_name.

Cause:

The value of the specified configuration attribute is too large.

Solution:

Change the value of the specified configuration attribute. Refer to the attribute description for the acceptable value range.


4108: The given file filename could not be accessed.

Cause:

The server is unable to obtain any information on the specified configuration file.

Solution:

Check that the file exists and that it has the appropriate access rights.


4109: The given file filename could not be opened for reading.

Cause:

The server is unable to open the specified configuration file.

Solution:

Check that the file exists and that it has the appropriate access rights.


4110: Could only read value of value bytes from configuration file filename.

Cause:

The server is unable to read the specified configuration file.

Solution:

Check that the file exists and that it has the appropriate access rights.


4111: The default password storage scheme SSHA could not be read or was not found in the file filename. It is mandatory. Server exiting.

Cause:

The mandatory password storage scheme Salted Secure Hashing Algorithm (SSHA) could not be retrieved from the configuration file.

Solution:

Check that the password storage scheme SSHA exists in the configuration file. If it is not present, add it.


4112: Skipping plugin plugin - no valid signature.

Cause:

The specified plug-in does not have a valid signature.

Solution:

Provide a valid signature for the plug-in or disable the plug-in.


4112: Unable to load plugin plugin_name.

Cause:

An error occurred while loading configuration information for the specified plug-in.

Solution:

Check that the configuration information for the specified plug-in is accurate. For more information, it may be useful to turn debugging on for SLAPI_DEBUG_PLUGIN. Change the configuration information as required and restart the server.


4119: No password storage scheme plug-ins defined in the configuration.

Cause:

No encoding scheme was found in the configuration file.

Under normal circumstances, this error will not occur, because the server cannot start if the mandatory scheme SSHA is not present in the configuration file.

Solution:

Add a password storage scheme plug-in to the configuration file and restart the server.


4120: Invalid scheme to hash password: scheme. Valid values are: scheme values.

Cause:

The tag (algorithm) specified to hash the password is not defined in the configuration file.

Solution:

Add a password storage scheme to the configuration file, or change the specified scheme, and restart the server.


4121: Invalid scheme: scheme. No password storage scheme loaded.

Cause:

The tag (algorithm) specified to hash the password is defined but the server is unable to retrieve the associated information.

Solution:

Check the password storage scheme configuration and its installation and restart the server.


4122: The configuration files in directory directory could not be read or were not found. Please refer to the error log or output for more information.

Cause:

An error occurred reading the configuration files. The specific cause for the error is logged in the log files.

Solution:

Refer to the log files for more information.


4123: The configuration file dse.ldif in directory directory could not be read or was not found. Please refer to the error log or output for more information.

Cause:

An error occurred reading the Directory Server configuration file. The specific cause for the error is logged in the log files.

Solution:

Refer to the log files for more information.


4124: Unknown attribute attribute_name will be ignored

Cause:

An attempt was made to set an unknown attribute in the configuration file.

Solution:

Check and correct the attribute name.


4125: The configuration file filename was not restored from backup.

Cause:

The configuration file backup has failed. The reason for the failed backup is provided in the error message.

Solution:

Correct the error and back up the configuration file manually.


4126: Failed to create lock. Cannot register supported SASL mechanism. Server exiting.

Cause:

This indicates a resource problem on the machine.

Solution:

Restart the server.


4127: Failed to create lock. Cannot register supported extended operations. Server exiting.

Cause:

This indicates a resource problem on the machine.

Solution:

Restart the server.


4128: Could not load configuration file filename.

Cause:

An error occurred when attempting to load the specified configuration file.

Solution:

Check that the configuration file exists and that it has the appropriate access permissions. Refer to the error log for more details.


4129: Bad configuration file. Edit the configuration file to correct the reported problems and then restart the server. Server exiting.

Cause:

There is an error in the configuration file. Details of the error are reported in the error log.

Solution:

Edit the configuration file to correct the reported problems and restart the server.


4130: Cannot copy DSE file filename to path.

Cause:

Several possible causes (file system full, incorrect permissions, etc.). Details of the error are reported in the error log.

Solution:

Check that the configuration file exists and that it has the appropriate access permissions.


4131: The entry entry_name in file filename is invalid.

Cause:

The server cannot read the specified entry. Details of the error are provided in the error message.

Solution:

Check that the entry is valid and change as necessary.


4132: Cannot parse DSE entry entry_name.

Cause:

The server cannot parse the specified entry. There is an error in the LDIF syntax of the entry.

Solution:

Check that the entry is valid and change as necessary.


4133: Cannot write temporary DSE file filename.

Cause:

System error (file system full, incorrect permissions, etc.)

Solution:

Check the log file for more information and restart the server.


4134: Cannot backup DSE file filename.

Cause:

The server cannot write to the specified DSE file.

Solution:

Check the specified path and ensure that you have the appropriate write permissions.


4135: Cannot rename temporary DSE file filename.

Cause:

The server cannot rename the specified DSE file.

Solution:

Check the specified path and ensure that you have the appropriate write permissions.


4136: Invalid plugin action plugin_name.

Cause:

The configuration file contains an invalid value for the specified plug-in.

Solution:

Check the value in the configuration file and set a valid value.


4137: Attempting to delete a child entry whose existence is unknown to the parent. Deletion attempt ignored.

Cause:

An attempt was made to delete a child entry for which there was no subcount on the parent.

Solution:

This error should not occur under normal circumstances.


4138: Failed to start plugin_name plug-in.

Cause:

Plug-in dependencies have not been configured correctly.

Solution:

Check that the dependencies are valid and that they are enabled.


4139: Failed to resolve plug-in dependencies.

Cause:

An error occurred while resolving dependencies (usually the consequence of an earlier problem such as a disabled plug-in, etc.)

Solution:

Check that the dependencies are valid and that they are enabled.


4140: Could not load symbol symbol_name from library library_name for plug-in plugin_name.

Cause:

This may be due to:

  1. Incorrect configuration of the plug-in entry

  2. A plug-in library missing or in the wrong location

  3. The expected symbol corresponding to the init function not found in the plug-in library

Solution:

Perform the following steps:

  1. Check the plug-in configuration.

  2. Check that the library path and the init function name are correct.


4152: Unknown plugin type type.

Cause:

A plug-in configuration entry does not have a recognized plug-in type.

Solution:

Check the configuration and correct the specified plug-in entry.


4153: Only one instance allowed for plugin type type.

Cause:

Multiple plug-ins of the specified type have been defined in the configuration. Only a single plug-in of that type is allowed.

Solution:

Correct the configuration so that there is only a single plug-in of the specified type.


4158: UNBIND

Cause:

Invalid unbind PDU. This is an error in the client code.

Solution:

Correct the error in the client code.


4159: Bad controls in the UNBIND.

Cause:

Invalid controls in an unbind PDU. The control is marked as critical and is unknown to the server or the control is badly encoded. This is an error in the client code.

Solution:

The client should not require critical controls on unbind. Correct the error in the client code.


4160: Cannot retrieve internal operation result for search operation (“operation” subtree subtree)

Cause:

While performing an internal search, Directory Server could not retrieve the operation from the parameter block.

Solution:

Contact Sun Technical Support.


4161: Cannot allocate pblock for an internal search (“baseDN” scope filter)

Cause:

While performing an internal search, Directory Server could not allocate space for the parameter block structure.

Solution:

Check that sufficient memory is available on the system.


4162: ldapu_get_cert_subject_dn_fails

Cause:

The server is unable to obtain the subject in the client certificate.

Solution:

Check the message in the error log for more information.


4163: ldapu_get_cert_issuer_dn_fails

Cause:

The server is unable to obtain the certificate issuer of the client certificate.

Solution:

Check the message in the error log for more information.


4164: Bad BER decoding of an attribute value assertion.

Cause:

An error occurred during the decoding of an attribute value assertion. The format of the attribute value assertion is incorrect.

Solution:

Check the client application making the request.


4165: BER decoding: found id instead of id for MessageId.

Cause:

The Message ID tag was not found in the LDAP request.

Solution:

The request is invalid. Check the application that created the request.


4166: BER decoding: ber_peek_tag returns no Operation tag.

Cause:

An error occurred while decoding the operation tag.

Solution:

The request is invalid. Check the application that created the request.


4167: Load library error.

Cause:

An error occurred while loading the dynamic library. This may be because the library does not exist, the library requires another library that does not exist, or the library could not resolve a symbol.

Solution:

Check that the library exists and is accessible.


4168: Compute hash of a node in a filter but the filter choice is not valid type

Cause:

While attempting to calculate the hash for a filter node, Directory Server encountered an invalid type.

Solution:

Contact Sun Technical Support.


4169: Compare two filters but the filter choice is not valid type

Cause:

While attempting to compare two filters, Directory Server encountered an invalid type.

Solution:

Contact Sun Technical Support.


4170: slapi_filter_test_ext: found unknown filter type type

Cause:

While attempting to test whether an entry matches a filter, Directory Server encountered an invalid type.

Solution:

Contact Sun Technical Support.


4171: slapi_vattr_filter_test_ext: found unknown filter type type

Cause:

While attempting to test whether an entry matches a filter, Directory Server encountered an invalid type.

Solution:

Contact Sun Technical Support.


4173: slapd_init: could not create one or more locks for communication purpose (operations connections...)

Cause:

Directory Server could not create locks due to resource constraints.

Solution:

Check that Directory Server is not having to contend for system resources with other applications.

Restart Directory Server.


4175: FrontendConfig_init: failed to initialize read-write lock structure.

Cause:

Directory Server could not create locks due to resource constraints.

Solution:

Check that Directory Server is not having to contend for system resources with other applications, and that sufficient memory is available on the system.

Restart Directory Server.


4176: config_set: the attribute attribute is read only; ignoring new value value

Cause:

A read-only attribute value has been changed.

Solution:

Do not change the attribute value.


4177: Could not open lockfile filename in write mode.

Cause:

The specified lock file could not be opened.

Solution:

Check that the lock file exists and is accessible.


4178: Could not open file filename in mode mode.

Cause:

The specified file could not be opened.

Solution:

Check that the file exists and is accessible.


4185: Cannot allocate lock and/or conditional variable to handle slapd_started variable.

Cause:

Directory Server could not create locks or conditional variables due to resource constraints.

Solution:

Check that Directory Server is not having to contend for system resources with other applications, and that sufficient memory is available on the system.


4186: *** DISK FULL *** Attempting to shut down gracefully.

Cause:

One of the following:

  • Directory Server ran out of disk space.

  • Directory Server is not properly configured to access data in a backend.

Solution:

Provide more local disk space to Directory Server, if necessary.

Check that nsslapd-backend is correctly set in the appropriate mapping tree entry under cn=config.

Check that the backend state is set correctly.

Check that the backend is not offline.


4187: Trying to get a block element but the element identifier ID is unknown.

Cause:

Directory Server tried to access a parameter block field that does not exist.

Solution:

Unless you are developing a plug-in and broke this yourself, contact Sun Technical Support.


4188: Trying to set a block element but the element identifier ID is unknown.

Cause:

Directory Server tried to modify a parameter block field that does not exist.

Solution:

Unless you are developing a plug-in and broke this yourself, contact Sun Technical Support.


4189: sequence error in error strings at item index.Error error (string) should come after error error (string)

Cause:

Directory Server encountered a problem encoding an error.

Solution:

Contact Sun Technical Support.


4190: Internal search base=”base” scope=scope filter=filter Result: code (message)

Cause:

An internal search used for authentication failed.

Solution:

Check that the client credentials allow it to access the entry to be used for authentication.


4191: Failed to change user and group identity to that of user.

Cause:

The server was unable to change the user and group identity to the specified user.

Solution:

Check the user privileges and correct.


4197: MODRDN invalid new RDN ("RDN")

Cause:

The modify RDN operation on the specified entry did not succeed.

Solution:

Try again with a valid new RDN.


4197: MODRDN invalid new superior ("DN")

Cause:

The modify RDN operation on the specified entry did not succeed.

Solution:

Try again with a valid new parent entry.


4210: Protocol error Account Usable control MUST be marked critical

Cause:

The account usability control was not marked critical.

Solution:

Notify the maintainer of the client application.


4211: error-code occurred while changing state of backend backend-name. Resetting state.

Cause:

An error occurred while putting backends off line.

Solution:

Verify all backends are in a correct and functional state.


4212: Server is already suspending all operations.

Cause:

An administrator tried to put the already frozen server in frozen mode.

Solution:

None.


4213: error-code while stopping databases. Please make sure suffixes are online.

Cause:

An error occurred while putting the server in frozen mode.

Solution:

Check that all suffixes supported by the server respond to read and write operations then try again.


4612: Unable to start slapd because it is already running as process process.

Cause:

Unable to start Directory Server because it is already running.

Solution:

Stop the running server instance before launching a new server.


4613: Unable to start slapd because the process process is importing the database

Cause:

Unable to start Directory Server because a process is currently importing the database.

Solution:

Stop the running import process instance before launching a new server.


4614: Unable to run db2ldif with the -r flag because the database is being used by another slapd process.

Cause:

Unable to run db2ldif with the -r flag because the database is being used by another Directory Server process.

Solution:

If the other process is not an import process, run db2ldif.pl -r instead. If it is an import process, stop the running import process before launching db2ldif.


4615: Unable to run db2ldif because the process process is importing the database

Cause:

Unable to run db2ldif because a process is currently importing the database.

Solution:

Stop the running import process before launching db2ldif.


4616: Unable to run db2bak because the process process is importing the database

Cause:

Unable to run db2bak because a process is importing the database.

Solution:

Stop the running import process before launching db2bak.


4617: Unable to import the database because it is being used by another slapd process

Cause:

Unable to import the database because it is being used by another slapd process.

Solution:

Stop Directory Server before importing.


4618: Unable to create an index because the database is being used by another slapd process

Cause:

Unable to create an index because the database is being used by another slapd process.

Solution:

Stop Directory Server before creating indexes.


4623: Pathname path too long.

Cause:

When trying to convert the absolute path, it was discovered that the pathname is too long.

Solution:

Change the relative path or the absolute path base so that the sum of their length is lower than the maximum allowed length.


4625: Cannot determine current directory.

Cause:

When trying to convert the absolute path, the server was unable to determine the current directory.

Solution:

Contact Sun Technical Support.


4626: slapi_add_internal: add_values for type type failed.

Cause:

Internal error when converting from a set of modifications to an entry.

Solution:

Contact Sun Technical Support.


4627: Unable to test the database because it is being used by another slapd process

Cause:

Unable to test the database because it is being used by another Directory Server process.

Solution:

Stop the running process and retry.


4629: Unable to create directory.

Cause:

System error - the directory could not be created.

Solution:

Check that your file system is valid and retry.


4630: ref_array_init: new lock creation failed

Cause:

Directory Server could not create locks due to resource constraints.

Solution:

Check that Directory Server is not having to contend for system resources with other applications.

Restart Directory Server.


4631: ref_adjust: referrals suppressed (could not get target DN operation or scope from pblock).

Cause:

Referrals have been suppressed. The server was unable to obtain the target DN and operation structure.

Solution:

Contact Sun Technical Support.


4633: Suffix to be imported contains encrypted attributes.

Cause:

No password for the key database has been supplied within the arguments configured for this suffix. The password is required to retrieve the key and proceed with encryption.

Solution:

Use the -Y pwd or -y pwd-file arguments when executing the ldif2db command.


4634: Security initialization for attribute encryption failed.

Cause:

The security initialization required by the attribute encryption feature failed.

Solution:

Make sure that the password supplied is correct and that the password file syntax is correct. Check that SSL has been configured correctly (certificate file ciphers.)


4737: Security Initialization failed: unable to read configuration from dn.

Cause:

Security initialization failed. The server was unable to read the configuration from the specified configuration DN.

Solution:

Check that the configuration DN is valid and retry.


4738: Security Initialization: Failed to retrieve SSL configuration attribute nscertfile from filename

Cause:

Security initialization error. The server was unable to retrieve the SSL configuration attribute nscertfile.

Solution:

Check that the value of the nscertfile attribute is correct and retry.


4739: Security Initialization: Failed to retrieve SSL configuration information (error error): nskeyfile: filename nscertfile: filename

Cause:

Security initialization error. The server was unable to retrieve one of the SSL configuration attributes, nscertfile or nskeyfile.

Solution:

Check that the value of the nscertfile and nskeyfile attributes are correct and retry.


4740: Security Initialization: NSS initialization failed (error error): path: path certdb prefix: prefix keydb prefix: prefix.

Cause:

Security initialization error. NSS initialization failed.

Solution:

Check the NSS configuration and retry.


4741: Security Initialization: NSS initialization failed (error error)

Cause:

Security initialization error. NSS initialization failed.

Solution:

Contact Sun Technical Support.


4742: Security Initialization: Failed to retrieve SSL configuration information (error error): nssslSessionTimeout: variable

Cause:

Security initialization error. The server was unable to retrieve the SSL configuration attribute nssslSessionTimeout.

Solution:

Check that the value of the nssslSessionTimeout attribute is correct and retry.


4744: Security Initialization: Unable to get token for variable cipher family (error error)

Cause:

Security initialization error. The server was unable to obtain the required token (from the nsssltoken attribute).

Solution:

Check that the nsssltoken attribute is present in the cipher family entry, and that it has a valid value.


4745: Security Initialization: Unable to find slot for variable cipher family (error error)

Cause:

Security initialization error. The server was unable to find the required slot.

Solution:

Make sure that the security token (external or internal) is accessible to the server.


4746: slapd_get_tmp_dir mkdir(variable) Error: error

Cause:

System error. The server was unable to create a temporary directory.

Solution:

Check that the current user has sufficient access rights to create the temporary directory and try again.


4747: Security Initialization: Unable to set SSL export policy (error error)

Cause:

Security initialization error. The server was unable to set the SSL export policy.

Solution:

Contact Sun Technical Support.


4748: Security Initialization: Failed to set SSL cipher preference information: cipher (error code - message)

Cause:

Security initialization error. The server was unable to set SSL cipher preference information.

Solution:

Perform the following steps:

  1. Check the syntax of the ciphers in the configuration.

  2. Make sure that all the ciphers are supported by the server.


4749: Security Initialization: Failed to import NSPR fd into SSL (error error)

Cause:

Security initialization error. The server was unable to import the NSPR file descriptor into SSL.

Solution:

Contact Sun Technical Support.


4750: Security Initialization: Unable to get internal slot (error error)

Cause:

Security initialization error. The server was unable to obtain the internal slot.

Solution:

Contact Sun Technical Support.


4751: Security Initialization: Unable to authenticate (error error)

Cause:

Security initialization error. The server was unable to authenticate.

Solution:

Contact Sun Technical Support.


4756: None of the ciphers are valid.

Cause:

The ciphers are invalid.

Solution:

Check the ciphers and retry.


4757: Config of SSL session cache failed: out of disk space! Make more room in the temp directory and try again.

Cause:

The configuration of the SSL session cache failed, due to a disk space problem.

Solution:

Free space in the /tmp directory and try again.


4758: Config of SSL session cache failed (error error).

Cause:

The configuration of the SSL session cache failed.

Solution:

Contact Sun Technical Support.


4759: Security Initialization: Failed to enable security on the imported socket (error error)

Cause:

Security initialization error. The server could not enable security on the imported socket.

Solution:

Contact Sun Technical Support.


4760: Security Initialization: Failed to enable SSLv3 on the imported socket (error error)

Cause:

Security initialization error. The server could not enable SSLv3 on the imported socket.

Solution:

Contact Sun Technical Support.


4761: Security Initialization: Failed to enable TLS on the imported socket (error error)

Cause:

Security initialization error. The server could not enable TLS on the imported socket.

Solution:

Contact Sun Technical Support.


4766: Encryption alias not configured.

Cause:

The encryption alias has not been configured.

Solution:

Contact Sun Technical Support.


4769: Failed to set SSL client ready for client authentication: certificate db: database returned code return_code (error error)

Cause:

The server was unable to set the SSL client ready for client authentication.

Solution:

Check that the certificate and key databases are accessible to the server (acting as an SSL client).


4772: SSL client authentication cannot be used (no password) (error error)

Cause:

SSL client authentication cannot be used because a password has not been defined.

Solution:

Make sure that the server receives the password for the security token, using a pin.txt file option with the start-slapd command.


4773: ldapssl_enable_clientauth (variable) (error error)

Cause:

SSL error - the server cannot enable client authentication.

Solution:

Check that the password given to the server is correct.


4774: ldap_simple_bind_s(variable) (error error)

Cause:

Simple bind over SSL failed. The password may be incorrect.

Solution:

Check that the password for the DN is correct.


4775: ldap_sasl_bind(LDAP_SASL_EXTERNAL) (error error)

Cause:

The bind attempt failed with the SASL EXTERNAL method. The server was unable to find any external credentials.

Solution:

Make sure that the client’s certificate is received by the server before the bind attempt.


4776: sasl error message

Cause:

SASL error. The details of the error are logged in the error log.

Solution:

Check the error log for more information.


4779: Security initialization: Unable to create PinObj (error error.)

Cause:

Security initialization error. The server was unable to create the pin object.

Solution:

Make sure that the server receives the password for the security token, using a pin.txt file option with the start-slapd command.


4780: Security Initialization: Unable to authenticate to slot for variable cipher family (error error)

Cause:

Security initialization error. The server was unable to authenticate to the required slot.

Solution:

The password entered was incorrect. Check the correct password and retry.


4781: SSL is misconfigured. Client authentication is enabled but no certificate authority is trusted for SSL client authentication.

Cause:

The server is configured to allow or require client authentication for SSL. The database contains no CA certificates marked as trusted for issuing client certificates. The server cannot perform SSL client authentication.

Solution:

Install one or more CA certificates using Directory Service Control Center. Ensure that the trust attributes of CA certificates installed with certutil include the T trust attribute.


4782: Failed to create context for cipher operation.

Cause:

NSS context creation failed.

Solution:

Ensure that a valid certificate is available so that the key may be generated.


4783: Out of memory to create a buffer to hold the encrypted output (error code - string).

Cause:

Directory Server could not allocate memory needed to encrypt attributes.

Solution:

Make more memory available to Directory Server.


4784: Out of memory to create a buffer to hold the cleartext input (error code - string).

Cause:

Directory Server could not allocate memory needed to encrypt attributes.

Solution:

Make more memory available to Directory Server.


4785: Cipher operation failed.

Cause:

The server was unable to accomplish the cipher operation.

Solution:

It is likely that the context is incorrect. Restart the server.


4786: Crypto mechanism not supported by this server.

Cause:

The cryptography mechanism is invalid or unsupported.

Solution:

Generate a symmetric key for the cryptography mechanism or choose a supported mechanism.


4787: Out of memory to create a buffer to hold the cleartext output (error code - string).

Cause:

Directory Server could not allocate memory needed to encrypt attributes.

Solution:

Make more memory available to Directory Server.


4788: Out of memory to create a buffer to hold the encrypted input (error code - string).

Cause:

Directory Server could not allocate memory needed to encrypt attributes.

Solution:

Make more memory available to Directory Server.


4789: Out of memory to create a pwd item. (error code - string).

Cause:

Directory Server could not allocate memory needed to encrypt attributes.

Solution:

Make more memory available to Directory Server.


4790: Out of memory to create a buffer to hold the pwd item data (error code - string).

Cause:

Directory Server could not allocate memory needed to encrypt attributes.

Solution:

Make more memory available to Directory Server.


4791: Out of memory to create the salt (error code - string).

Cause:

Directory Server could not allocate memory needed to encrypt attributes.

Solution:

Make more memory available to Directory Server.


4792: Out of memory to create a buffer to hold the salt data (error code - string).

Cause:

Directory Server could not allocate memory needed to encrypt attributes.

Solution:

Make more memory available to Directory Server.


4793: Failed to generate symmetric key.

Cause:

The server was unable to generate the symmetric key.

Solution:

Check that a security token is available to the server (as a certificate.)


4794: Out of memory to create a buffer to hold the parameter data (error code - string).

Cause:

Directory Server could not allocate memory needed to encrypt attributes.

Solution:

Make more memory available to Directory Server.


4795: Failed to map key generation parameters into crypto operation ones.

Cause:

The server was unable to map the key generation mechanism to the cryptography mechanism.

Solution:

Restart the server.


4796: Unable to retrieve private key for certificate.

Cause:

The server was unable to retrieve a private key from the certificate.

Solution:

Ensure that the certificate has been imported into the database with both its private and public keys. (This is usually performed as part of the process beginning with a certificate request.)


4797: Signature failed.

Cause:

The signature required for attribute encryption failed.

Solution:

Restart the server.


4798: Key database password was rejected.

Cause:

The password for the key database has been rejected.

Solution:

Enter a new password and retry.


4799: Couldn’t read key database password.

Cause:

The server was unable to find the key database password. No password was provided, or the password syntax was incorrect.

Solution:

Enter a non-null password or ensure that a valid password file, containing a valid password, is supplied.


4800: No key db password was specified.

Cause:

No key database password was specified (either explicitly or via a password file.)

Solution:

Supply a valid password or the path to a valid password file.


4801: Unable to read key password file from directory.

Cause:

The server was unable to read the key database password from the password file.

Solution:

Check the password file access rights and ensure that the file is of a reasonable size.


4802: Bad password file syntax: missing ”:’ preceding password.

Cause:

The syntax of the password file is incorrect. The colon, :, is missing.

Solution:

Supply a password file with the correct syntax.


4803: Bad token identifier: token.

Cause:

The token identifier in the password file does not match the open token.

Solution:

Supply a token identifier that is consistent with the nsSSLToken attribute value in the configuration.


4804: Missing security initialization required by attribute encryption.

Cause:

Security configuration has not been completed.

Solution:

Make sure certificate and key database security has been enabled, nsslapd-security: on.


4805: Failed to check whether attribute encryption is configured or not.

Cause:

An internal search for attribute encryption configuration elements failed.

Solution:

Make sure attribute encryption is properly configured, then restart Directory Server.


4807: Security Initialization: Unable to register PIN callback(error code - message)

Cause:

Security Initialization: Unable to register PIN callback

Solution:

NSS refused the operation: check library compatibility and requirements.


4808: Security Initialization: certificate database file name should look like 'slapd-[serverId-]cert'

Cause:

Security Initialization: badly formed certificate database name

Solution:

Check the value of the nsCertfile attribute on cn=encryption. It should be of the form nsCertfile: slapd-cert8.db.


4865: Detected virtual attribute loop in get on entry entry attribute attribute.

Cause:

A loop was detected while retrieving the virtual attributes of an entry.

Solution:

Check the virtual attributes configured for this entry and break the loop.


4866: Out of memory to duplicate a type name.

Cause:

There is insufficient memory for the server to allocate a service provider for the virtual attributes map insert.

Solution:

Make more memory available to the server and restart the server.


4867: Detected virtual attribute loop in compare on entry entry attribute attribute.

Cause:

The server detected a virtual attribute loop when comparing virtual attribute service providers.

Solution:

Check the virtual attributes configured for this entry and break the loop.


4868: Out of memory to allocate a service provider.

Cause:

There is insufficient memory for the server to allocate a service provider for the virtual attributes register.

Solution:

Make more memory available to the server and restart the server.


4869: Out of memory to allocate a service provider handle.

Cause:

There is insufficient memory for the server to allocate a service provider handle.

Solution:

Make more memory available to the server and restart the server.


4870: Out of memory to create a map for virtual attributes.

Cause:

There is insufficient memory for the server to allocate a map for virtual attributes.

Solution:

Make more memory available to the server and restart the server.


4871: Out of memory to create a new hash table.

Cause:

There is insufficient memory for the server to allocate a new hash table for virtual attributes.

Solution:

Make more memory available to the server and restart the server.


4872: Failed to create a new lock for virtual attributes map insert.

Cause:

The server was unable to create a new lock for virtual attribute map creation. This is probably due to a memory error.

Solution:

Make more memory available to the server and restart the server.


4994: Multiple backend instances are specified.

Cause:

More than one backend instance has been specified for the attempted task.

Solution:

Contact Sun Technical Support.


4995: Cannot perform an import with pre-V3 backend plugin.

Cause:

You are using a version of the backend plug-in API that is no longer supported and cannot perform the database import.

Solution:

Upgrade to a newer version of the backend plug-in API (at least version 3), recompile, and add the import functionality.


4996: No ldif2db function defined for backend backend

Cause:

No ldif2db function is defined for this backend. This kind of database is unable to perform an import.

Solution:

Use a backend that has the import functionality.


4997: Unable to allocate new task for import.

Cause:

The server is unable to allocated a new task for the import. This is usually due to a resource problem.

Solution:

Free up resources on the machine and restart the server.


4998: Cannot export - backend not found.

Cause:

The database could not be exported because the specified backend could not be found.

Solution:

Check the configuration file and make sure that the correct database and suffix are specified.


4999: ldbm2ldif: backend backend export failed (error)

Cause:

The db2ldif function failed when attempting to export the database.

Solution:

Refer to the error log for more information and contact Sun Technical Support.


5000: No backend instance names are specified.

Cause:

The database could not be exported because no backend instance names were specified.

Solution:

Contact Sun Technical Support.


5003: Cannot perform an import with pre-V3 backend plugin.

Cause:

You are using a version of the backend plug-in API that is no longer supported and cannot perform the database import.

Solution:

Upgrade to a newer version of the backend plug-in API (at least version 3), recompile, and add the import functionality.


5004: No ldif2db function defined for backend backend

Cause:

No ldif2db function is defined for this backend. This kind of database is unable to perform an import.

Solution:

Use a backend that has the import functionality.


5005: Unable to allocate new task.

Cause:

The server is unable to allocated a new task for the export. This is usually due to a resource problem.

Solution:

Free up resources on the machine and restart the server.


5006: Unable to create ldbm2ldif thread for export.

Cause:

The server is unable to create a thread for the export. This is usually due to a resource problem.

Solution:

Free up resources on the machine and restart the server.


5007: db2archive function failed when trying to backup (error error)

Cause:

The db2archive function failed when attempting to backup.

Solution:

Refer to the error log for more information and contact Sun Technical Support.


5008: Unable to process backup when no db2archive function defined

Cause:

The database could not be backed up because the db2archive function was not defined.

Solution:

None - this type of database cannot be backed up.


5009: Cannot perform a backup with pre-V3 backend plugin variable

Cause:

You are using a version of the backend plug-in API that is no longer supported and cannot perform the database backup.

Solution:

Upgrade to a newer version of the backend plug-in API (at least version 3), recompile, and add the backup functionality.


5010: Unable to allocate new task for backup.

Cause:

The server is unable to allocated a new task for the backup. This is usually due to a resource problem.

Solution:

Free up resources on the machine and restart the server.


5011: Unable to create backup thread.

Cause:

The server is unable to create a backup thread. This is usually due to a resource problem.

Solution:

Free up resources on the machine and restart the server.


5012: Restore failed (error error)

Cause:

The restore process failed.

Solution:

Refer to the error log for more information and contact Sun Technical Support.


5014: Cannot perform a restore with pre-V3 backend plugin variable

Cause:

You are using a version of the backend plug-in API that is no longer supported and cannot perform the database restore.

Solution:

Upgrade to a newer version of the backend plug-in API (at least version 3), recompile, and add the restore functionality.


5015: Unable to allocate new task for restore.

Cause:

The server is unable to allocated a new task for the restore. This is usually due to a resource problem.

Solution:

Free up resources on the machine and restart the server.


5016: Unable to create restore thread for restore.

Cause:

The server is unable to create a restore thread. This is usually due to a resource problem.

Solution:

Free up resources on the machine and restart the server.


5017: db2index function failed when trying to restore (error error)

Cause:

The db2index function failed when attempting to restore the database.

Solution:

Refer to the error log for more information and contact Sun Technical Support.


5019: No db2index function defined for backend backend.

Cause:

The database could not be indexed because no db2index() function was defined for the backend.

Solution:

Contact Sun Technical Support.


5020: Unable to allocate new task for index.

Cause:

The server is unable to allocated a new task for the index. This is usually due to a resource problem.

Solution:

Free up resources on the machine and restart the server.


5021: Unable to create index thread.

Cause:

The server is unable to create an index thread. This is usually due to a resource problem.

Solution:

Free up resources on the machine and restart the server.


5023: Cannot create task node (error error)

Cause:

The server is unable to create a task node.

Solution:

Refer to the error log for more information and contact Sun Technical Support.


5024: Unable to create global tasks lock.

Cause:

The server is unable to create a global tasks lock. This is usually due to a resource problem.

Solution:

Free up resources on the machine and restart the server.


5025: Cannot import. Lookup instance name by suffixes failed.

Cause:

The database could not be imported because the server was unable to locate the instance name for the specified suffix.

Solution:

Check that the suffix is specified correctly in the configuration.


5026: Cannot import. Could not find database for suffix.

Cause:

The database could not be imported because the server was unable to locate the database for the specified suffix.

Solution:

Check that the database and the suffix are specified correctly in the configuration.


5027: Cannot import. Backend not found.

Cause:

The database could not be imported because the server was unable to locate the specified backend.

Solution:

Check that the database and the suffix are specified correctly in the configuration.


5028: Cannot import - lookup instance names by suffix failed.

Cause:

The database could not be imported due to a problem with the suffix configuration.

Solution:

Check that the suffix is specified correctly in the configuration.


5029: Could not find database for suffix.

Cause:

The database could not be exported because it could not be found.

Solution:

Check that the database and the suffix are specified correctly in the configuration.


5030: No archive2db function defined.

Cause:

The database could not be restored because the archive2db function was not defined.

Solution:

None - this type of database cannot be restored.


5031: Cannot index - backend not found.

Cause:

The server cannot index the database because the specified backend was not found.

Solution:

Contact Sun Technical Support.


5034: Incompatible options nsExportReplica=true and dsDecryptAttrs=false: cannot dump replica with encrypted attributes.

Cause:

An export has been called with incompatible options nsExportReplica: true and dsDecryptAttrs: false. It is not possible to dump a replica with encrypted attributes.

Solution:

Avoid using both options at the same time. Ensure that attributes are decrypted, dsDecryptAttrs: true, if you want to export the database for replication purposes.


5035: Unknown Password Compatibility task: state

Cause:

Unknown password policy compatibility action.

Solution:

Move the server to the correct compatibility state.


5036: Can not modify Password Policy compatibility state. Task aborted.

Cause:

The server could not move to the specified compatibility state.

Solution:

See additional information returned to the client applicatin.


5036: Password Compatibility task and Password Policy state are incompatible. Can not change Password Policy state.

Cause:

The server could not move to the specified compatibility state.

Solution:

See additional information returned to the client applicatin.


5037: Unable to allocate new task for changing password compatibility state !"

Cause:

Unable to allocate new task for backup.

Solution:

Make more resources available for the server and restart the server.


5038: Unable to create Password Policy compatibility task thread !

Cause:

Unable to create backup thread.

Solution:

Make more resources available to the server and try again.


5039: Password Policy compatibility state is already state. Task aborted.

Cause:

Nothing to do as the action required would not change the compatibility state.

Solution:

Change to a different compatibility state.


5040: Unknown log rotate task: type.

Cause:

The server did not recognize the log type set for the log rotation attribute.

Solution:

Use a valid log type.


5041: Unable to allocate new task for log rotation !

Cause:

The server was unable to allocate a new task for log rotation.

Solution:

Make more system memory available by restarting the server.


5042: Unable to create log rotation task thread!

Cause:

The server was unable to allocate a new task for log rotation.

Solution:

Make more system memory available by restarting the server.


5121: reslimit_init: slapi_register_object_extension() failed.

Cause:

The server cannot register an object extension (during resource limit initialization).

Solution:

Contact Sun Technical Support.


5122: PR_NewRWLock() failed for reslimit.

Cause:

System error - the server cannot create a new lock for the resource limit.

Solution:

Contact Sun Technical Support.


5123: error: Resource limit initialization failed.

Cause:

Resource limit initialization failed. This is likely to be a resource issue.

Solution:

Check the error message in the log file and contact Sun Technical Support.


5124: error: slapi_get_object_extension() returned NULL

Cause:

The server could not obtain the object extension (for the resource limit).

Solution:

Contact Sun Technical Support.


5126: error: parameter error (attribute already registered)

Cause:

A parameter error occurred when registering a new resource to be tracked. The LDAP attribute type that can be consulted in the bound entry to determine the limit’s value is already registered.

Solution:

Check that the attribute provided is registered only once.


5127: error: parameter error

Cause:

A parameter error occurred when registering a new resource to be tracked.

Solution:

Perform the following tasks:

  1. Check that the type is SLAPI_RESLIMIT_TYPE_INT

  2. Check that attrname is an LDAP attribute type that can be consulted in the bound entry to determine the limit’s value.


5127: error: parameter error

Cause:

Internal error. When retrieving the integer limit associated with a connection and a resource, a parameter with a NULL value was found.

Solution:

Contact Sun Technical Support.


5128: error: unknown handle handle

Cause:

Parameter error. The handle used to identify a resource is unknown.

Solution:

Contact Sun Technical Support.


5129: Cannot malloc bytes.

Cause:

An attempt is being made to allocate 0 or a negative number of bytes. This is likely to be a software issue.

Solution:

Contact Sun Technical Support.


5130: malloc of bytes bytes failed; errno error.

Cause:

Memory allocation has failed. This is probably because of a lack of available memory.

Solution:

Increase the virtual memory available to your server, or reduce the size of the server’s maximum entries in cache (cachesize) or maximum database cache size (dbcachesize) parameters.


5131: cannot realloc number bytes; trying to allocate 0 or a negative number of bytes is not portable and gives different results on different platforms. Please check the code and change it to avoid the attempt to allocate number bytes.

Cause:

Memory reallocation of number bytes is not allowed.

Solution:

Unless you are developing a plug-in and broke this yourself, contact Sun Technical Support.


5132: realloc of bytes bytes failed; errno error.

Cause:

Memory reallocation has failed. This is probably because of a lack of available memory.

Solution:

Increase the virtual memory available to your server, or reduce the size of the server’s maximum entries in cache (cachesize) or maximum database cache size (dbcachesize) parameters.


5133: cannot calloc number bytes; trying to allocate 0 or a negative number of bytes is not portable and gives different results on different platforms. Please check the code and change it to avoid the attempt to allocate number bytes.

Cause:

Memory allocation of number bytes is not allowed.

Solution:

Unless you are developing a plug-in and broke this yourself, contact Sun Technical Support.


5134: cannot calloc number elements; trying to allocate 0 or a negative number of elements is not portable and gives different results on different platforms. Please check the code and change it to avoid the attempt to allocate number elements.

Cause:

Memory allocation of number elements is not allowed.

Solution:

Unless you are developing a plug-in and broke this yourself, contact Sun Technical Support.


5135: calloc of bytes bytes failed; errno error.

Cause:

Memory c-allocation has failed. This is probably because of a lack of available memory.

Solution:

Increase the virtual memory available to your server, or reduce the size of the server’s maximum entries in cache (cachesize) or maximum database cache size (dbcachesize) parameters.


5136: strdup of chars chars failed; errno error.

Cause:

String duplication has failed. This is probably because of a lack of available memory.

Solution:

Increase the virtual memory available to your server, or reduce the size of the server’s maximum entries in cache (cachesize) or maximum database cache size (dbcachesize) parameters.


5137: ber_bvdup of bytes bytes failed; errno error.

Cause:

BER value duplication has failed. This is probably because of a lack of available memory.

Solution:

Increase the virtual memory available to your server, or reduce the size of the server’s maximum entries in cache (cachesize) or maximum database cache size (dbcachesize) parameters.


5249: The entry entry in the configfile filename was empty or could not be parsed.

Cause:

An entry in the configuration file was empty or could not be parsed.

Solution:

Check the entry syntax in the configuration file.


5250: Invalid value

Cause:

The specified configuration attribute in the Directory Server configuration file has no value or the value is invalid.

Solution:

Check that the value of the attribute under cn=config in the Directory Server configuration file is either on or off.


5251: Cannot set error log filename.

Cause:

The error log filename could not be set, either because the filename was NULL or the path was invalid.

Solution:

Check that the value of the attribute nsslapd-errorlog under cn=config is valid, and that the path exists.


5252: Undefined value for errorlog level.

Cause:

The error log level could not be set because its value is undefined.

Solution:

Check that the value of the attribute nsslapd-errorlog-level under cn=config is set, and is correct.


5253: Bad value for nsslapd-maxdescriptors.

Cause:

The request to set the maximum number of file descriptors has failed. The value is either NULL, or out of the permitted range [1..max] where max is the maximum number of file descriptors that can be created by a process.

Solution:

Check that the value of the attribute nsslapd-maxdescriptors in the Directory Server configuration is not higher than the RLIMIT_NOFILE parameter, and is not lower than 1.


5254: Ignoring attribute (since -d option was given on the command line) nsslapd-errorlog-level.

Cause:

The attribute nsslapd-errorlog-level in the Directory Server configuration has been ignored, because the -d option was specified at the command line.

Solution:

Do not specify the -d option at the command line if you want the value of this attribute in the configuration file to be taken into account.


5255: The plugin entry entry in the configfile filename was invalid.

Cause:

Failed to load the specified plug-in because the configuration entry of the plug-in in the -d is invalid.

Solution:

Check and correct the faulty plug-in configuration.


5256: file: max_descriptors: error

Cause:

The request to set the maximum number of connections failed either because the value was NULL or the value was not in the allowed range [1..max] where max is the maximum number of file descriptors a process may create.

Solution:

Check nsslapd-maxconnections on cn=config to ensure its value is not higher than the SC_OPEN_MAX system parameter, nor lower than 1.


5385: Convert LDIF entry into LDAP entry fast method. Error: entry has no dn.

Cause:

While attempting to convert an LDIF entry to an LDAP entry, the server found that the entry has no DN.

Solution:

Check the entry and make sure that it has a DN.


5390: str2entry_dupcheck: entry has no dn.

Cause:

While attempting to convert a string entry to an LDAP entry, the server found that the entry has no DN.

Solution:

Check the entry and make sure that it has a DN.


5392: Error occurs while removing attribute values. Possible existing duplicate value for attribute type attribute found in entry entry.

Cause:

An error occurred while attempting to remove attribute values. This may be due to a duplicate attribute value.

Solution:

Check the attribute values being removed.


5393: str2entry_dupcheck: unexpected failure constructing the value tree.

Cause:

The server failed to add a value to the value tree.

Solution:

Check the error log for more information.


5394: Error occurs while removing attribute values. Possible existing duplicate value for attribute type type found in entry DN

Cause:

The entry contains duplicate values for the attribute.

Solution:

Delete the attribute and add a new set of values.


5395: Attribute 'nscpEntryWSI’ can only be computed by root user.

Cause:

The attribute nscpEntryWSI cannot be computed by a user who is not the Directory Manager.

Solution:

Check the client application making the request. The client must bind as root to be able to compute this attribute.


5396: Cannot compute ’nscpEntryWSI’ attribute because there is no pblock in the context

Cause:

A required parameter block structure was not available.

Solution:

Contact Sun Technical Support.


5397: Existing duplicate values found in attribute “type“ of entry “DN”

Cause:

The entry contains duplicate values for the attribute.

Solution:

Delete the attribute and add a new set of values.


5398: Duplicate value addition in attribute “type” of entry “DN”

Cause:

A client is trying to add duplicate values for the attribute.

Solution:

Fix the client application.


5399: occurred while removing attribute values. Could not find value number for attribute type (message).

Cause:

Error occurs while trying to remove attribute values. The value could not be found.

Solution:

Check the attribute values to remove.


5505: Registration of extension failed.

Cause:

A plug-in has attempted to register a new extension to an object type, but the object type is in use, by at least one object.

Solution:

Correct the plug-in code.


5506: Registration of extension extension by plug-in failed: number extensions already registered (max is max_ext).

Cause:

Directory Server tried to register too many object extensions.

Solution:

Unless you are developing a plug-in and broke this yourself, contact Sun Technical Support.


5507: Number of extension users for extension is negative number.

Cause:

Directory Server encountered a negative number of object extensions.

Solution:

Contact Sun Technical Support.


5508: Registration of type object type failed. There is no more free slot in factory array for object type (current in use number max is number).

Cause:

Directory Server tried to register an object type other than Connection, Operation, Entry, or Mapping Tree Node.

Solution:

Unless you are developing a plug-in and broke this yourself, contact Sun Technical Support.


5509: Trying to get extension on unregistered object type (object type identifier ID).

Cause:

Directory Server tried to extend an unregistered object type.

Solution:

Unless you are developing a plug-in and broke this yourself, contact Sun Technical Support.


5510: Release extension on unregistered object type (object type identifier ID).

Cause:

Directory Server tried to release an extension for an unregistered object type.

Solution:

Unless you are developing a plug-in and broke this yourself, contact Sun Technical Support.


5511: Plugin plug-in tries to register extension for object type that does not exist type.

Cause:

Directory Server tried to extend a nonexistent object type.

Solution:

Unless you are developing a plug-in and broke this yourself, contact Sun Technical Support.


5635: Backend backend is already pointed to by another mapping tree node.Only one mapping tree node can point to a backend.

Cause:

Errors exist in the mapping tree node configuration.

Solution:

Check nsslapd-backend values in the mapping tree entry.

Check that the mapping tree node state has a legal value, and that nsslapd-referral is appropriately set if necessary.


5641: Could not find parent node for entry entry. Node parent is defaulting to root node.

Cause:

The parent node for the current mapping tree node could not be located.

Solution:

Check the nsslapd-parent-suffix attribute of the entry in the Directory Server configuration.


5642: Node node is either a 'backend' or 'referral on update' node therefore it must define a backend (attribute 'nsslapd-backend').

Cause:

The new mapping tree node is either a “backend” or “referral on update” node but has no backend defined.

Solution:

Check the nsslapd-backend attribute of the entry in the Directory Server configuration.


5643: Node node is either a 'referral' or 'referral on update' node therefore it must define a referral (attribute 'nsslapd-referral').

Cause:

The new mapping tree node is either a “referral” or “referral on update” node but has no referral defined.

Solution:

Check the nsslapd-referral attribute of the entry in the Directory Server configuration.


5644: Cannot load distribution plugin lib library for node node.

Cause:

The distribution plug-in could not be loaded.

Solution:

Check the error log for more information. The dynamic library may not be present, may be inaccessible, or may be using another library that is not present.


5645: Node node wants to define a distribution plugin but either 'nsslapd-distribution-plugin' or 'nsslapd-distribution-funct' attribute is missing in the configuration file (dse.ldif).

Cause:

The entry is missing either the distribution plug-in or the distribution function name.

Solution:

Check the values for the nsslapd-distribution-plugin and nsslapd-distribution-func attributes in the plug-in configuration entry.


5648: Could not create mapping tree node for entry entry.

Cause:

The mapping tree node could not be created.

Solution:

Check the error log for evidence of the failure, otherwise contact Sun Technical Support.


5650: Modify (add or replace) callback for mapping tree: could not find parent for mapping tree node DN

Cause:

One of the following:

  • The mapping tree parent is not a suffix of a mapping tree child.

  • While modifying the CN or nsslapd-parent-suffix, Directory Server could not find the new parent.

Solution:

If the modification originated in a client request, fix the client. Otherwise, contact Sun Technical Support.


5653: Distribution plugin returned wrong backend: backend index index (range 0..max) for entry DN at node DN

Cause:

One of the following:

  • No attribute value exists for nsslapd-distribution-func.

  • The distribution plug-in returned a bad backend index value.

Solution:

Perform the following steps:

  • Check the configuration for the distribution plug-in.

  • Fix the distribution plug-in.

    If neither remedy works, contact Sun Technical Support.


5654: Distribution plugin not configured for mapping tree node DN

Cause:

Directory Server tried to use a distribution plug-in, but the distribution plug-in was not appropriately configured.

Solution:

Check the configuration for the distribution plug-in.


5659: Cannot find distribution function function in distribution plugin lib library for node node.

Cause:

The distribution function in the plug-in library could not be located.

Solution:

Check the error log for more information. The dynamic library may not be present, may be inaccessible, or may be using another library that is not present.


5889: Could not create lock for Schema DSE

Cause:

Directory Server could not create a lock for the schema subentry.

Solution:

Check that Directory Server is not having to contend for system resources with other applications.


5890: No schema files were found in the directory directory_name.

Cause:

No schema files are present in the schema directory.

Solution:

Restore the default schema files from a backup or CD image.


5891: Could not add attribute type “objectClass” to the schema: message

Cause:

Directory Server could not create the default objectclass schema definition.

Solution:

Contact Sun Technical Support.


5892: Could not add attribute type “aci” to the schema: message

Cause:

Directory Server could not create the default aci schema definition.

Solution:

Contact Sun Technical Support.


5893: Entry entry required attribute objectclass is missing.

Cause:

The specified entry was added without an objectclass attribute.

Solution:

Check the application that added the entry.


5894: Entry entry has unknown objectclass.

Cause:

The entry was added or modified with an unknown objectclass.

Solution:

Check the application that added or modified the entry.


5895: Entry entry single-valued attribute has multiple values.

Cause:

The entry that was added or modified is invalid. A single-valued attribute has multiple values.

Solution:

Check the application that added or modified the entry.


5896: Entry entry attribute attribute required by objectclass objectclass is missing.

Cause:

The entry that was added or modified is missing a required attribute.

Solution:

Check the application that added or modified the entry.


5897: Entry entry attribute attribute is not allowed.

Cause:

The entry that was added or modified contains an invalid attribute.

Solution:

Check the application that added or modified the entry.


5898: No attribute types to iterate through internally

Cause:

Directory Server got an empty attribute type list.

Solution:

Contact Sun Technical Support.


5899: No OID found in schema for syntax syntax

Cause:

Directory Server could not match the OID with any OID in the schema.

Solution:

Fix the schema, or the client. If neither fix solves the problem, contact Sun Technical Support.


5900: Missing value for objectClasses attribute.

Cause:

While parsing the schema LDIF file, no value was specified for the objectClasses attribute.

Solution:

Check the schema LDIF file or the schema modification request.


5901: No name or OID specified for checking schema

Cause:

Internal error

Solution:

Contact Sun Technical Support.


5906: Value has invalid syntax (not syntax): attr=value

Cause:

Entry was added or modified with invalid attribute syntax.

Solution:

Check application that added or modified the entry.


8194: Replication session aborted for agreement agreement_name because consumer replica is disabled.

Cause:

The consumer has returned a disabled error, that is, it is not in a state in which it can receive replication updates.

Solution:

Enable the consumer replica. It may also be necessary to initialize the consumer again.


8195: Pending changes: error value.

Cause:

Looping through the changelog failed.

Solution:

Ensure that replication is working correctly (using the insync utility and checking the replication agreement object).

Check the error code in the error log for more information.


8196: Bad Window size value for agreement agreement_name.

Cause:

The value of the ds5ReplicaTransportWindowSize attribute is invalid.

Solution:

Check the Directory Server configuration defining the Replication Agreement.

Solution:

Check the modification operation attempted on the replication agreement.


8197: Bad Group size value for agreement agreement_name.

Cause:

The value of the ds5ReplicaTransportGroupSize attribute is invalid.

Solution:

Check the Directory Server configuration defining the Replication Agreement.

Solution:

Check the modifications attempted on the replication agreement.


8198: Bad Compression Level value for agreement agreement_name.

Cause:

The value of the ds5ReplicaTransportCompressionLevel attribute is invalid.

Solution:

Check the Directory Server configuration defining the Replication Agreement.

Solution:

Check the modifications attempted on the replication agreement.


8199: Modification of attribute_name attribute is not allowed - agreement agreement_name.

Cause:

The user is not permitted to modify the specified replication agreement attribute.

Solution:

Check the Directory Server configuration defining the Replication Agreement.

Solution:

Check the modifications attempted on the replication agreement.


8200: Failed to update flag to force 5.1 Replication protocol for agreement agreement_name.

Cause:

The replication agreement is being stopped.

Solution:

Wait until the agreement has been stopped and retry.


8201: Failed to update the state (enable/disable) of the agreement agreement

Cause:

Replication is stopping for this agreement.

Solution:

Wait until the agreement has stopped and try again.


8202: Unknown replication agreement

Cause:

A replication agreement with the specified DN could not be found.

Solution:

Check the specified DN and all replication agreements.

Solution:

Check that the error is not in the client application.


8203: Failed to update partial replication checksum for agreement agreement

Cause:

One of the following:

  1. The checksum value provided for partial replication was not valid.

  2. Replication is stopping for this agreement.

Solution:

Wait until the agreement has stopped and try again.


8204: Refusing to update partial replication checksum for agreement agreement_name permission denied.

Cause:

The server received an update operation that is permitted for internal operations only.

Solution:

Check the client that sent the forbidden update operation.


8205: Failed to update Bind Method for agreement agreement

Cause:

The replication agreement is stopping.

Solution:

Wait until the agreement has stopped and try again.


8206: Failed to update Transport Information for agreement agreement

Cause:

The replication agreement is stopping.

Solution:

Wait until the agreement has stopped and try again.


8207: Failed to update Bind DN for agreement agreement

Cause:

The replication agreement is stopping.

Solution:

Wait until the agreement has stopped and try again.


8208: Failed to update TimeOut value for agreement agreement

Cause:

One of the following:

  1. A client attempted to set an invalid attribute type or value.

  2. Replication is stopping for this agreement.

Solution:

Perform the following steps:

  1. Check the client application.

  2. Wait until the agreement has stopped and try again.


8209: Failed to update Credentials for agreement agreement

Cause:

One of the following:

  1. A client attempted to set an invalid attribute type or value.

  2. Replication is stopping for this agreement.

Solution:

Perform the following steps:

  1. Check the client application.

  2. Wait until the agreement has stopped and try again.


8210: No value supplied for attr attribute

Cause:

No value was supplied for the specified attribute.

Solution:

Perform the following steps:

  1. Check the client application.

  2. Wait until the agreement has stopped and try again.


8211: Invalid value value supplied for attr attribute

Cause:

The value supplied for the specified attribute is not a valid value.

Solution:

Perform the following steps:

  1. Check the client application.

  2. Wait until the agreement has stopped and try again.


8212: Failed to update replication schedule for agreement agreement_name.

Cause:

One of the following:

  1. The replication schedule format is invalid.

  2. The replication agreement is stopping.

Solution:

Perform the following steps:

  1. Check the client application.

  2. Wait until the agreement has stopped and try again.


8213: Failed to update Partial Replication Configuration for agreement agreement_name. The agreement needs to be disabled first.

Cause:

An attempt was made to change the configuration for partial replication, on an enabled replication agreement

Solution:

To change the partial replication configuration, disable the replication agreement first.


8215: Partial replication not started for agreement agreement_name.

Cause:

Partial replication has not been started.

Solution:

Check the configuration of this replication agreement (specifically partial configuration entries). Start the partial replication feature for this agreement in Directory Service Control Center.


8216: Partial replication pointed to by this entry has been modified. Please update the current configuration on this supplier or re-initialize consumer accordingly.

Cause:

The partial replication configuration has been modified.

Solution:

Update the current configuration on the supplier, or initialize the consumer again.


8218: Replication protocol v5.0 not supported for consumer.

Cause:

The version 5 replication protocol is not supported for this consumer.

Solution:

Check the version of Directory Server running on the specified consumer.


8219: Could not parse update vector for replica replica_name. The replica must be reinitialized.

Cause:

The server was unable to parse the update vector for the specified replica.

Solution:

Check that the consumer sent the replica update vector (RUV) during the start request.


8220: Too much time skew between replicas for [consumer:port]

Cause:

The time difference between the specified replicas is too great for replication to work correctly.

Solution:

Ensure that the supplier and consumer machines have the same time and date. The use of the Network Time Protocol (NTP) is recommended.


8221: Failed and requires administrator action.

Cause:

A fatal error occurred during an incremental update. Replication on this consumer will be disabled.

Solution:

Check the error log on the consumer for more information. Restart replication by updating the replication agreement and reinitializing updates.


8222: search_in_ruv_storage_entry: replica ruv tombstone entry for replica DN not found

Cause:

Directory Server could not read the replication update vector storage entry in the database for the suffix.

Solution:

Initialize replication for the suffix again.


8223: Invalid value value supplied for attr attribute

Cause:

The value supplied for the specified attribute is not a valid value.

Solution:

Perform the following steps:

  1. Check the client application.

  2. Wait until the agreement has stopped and try again.


8225: Replica_write_partial_repl_checksum: failed to update partial repl checksum with value value for replica replica. LDAP error.

Cause:

An error occurred while writing an attribute value in the replica entry.

Although harmless while the server is up and running, this error may lead to a replication malfunction the next time the server is restarted.

The error occurs when the value of an important replication configuration attribute cannot be stored persistently in the Directory Server configuration.

Solution:

Stop the server immediately and check the cn=replica entry for this suffix in the Directory Server configuration. If the attribute dsfilterspconfigchecksum is present in the entry, set its value to the value included in the error log. If the attribute dsfilterspconfigchecksum is not present in the entry, add it and set its value to the value included in the error log. Restart the server.


8226: replica_write_last_init_time: failed to update last init timestamp with value value for replica replica. LDAP error.

Cause:

An error occurred while writing an attribute value in the replica entry.

Although harmless while the server is up and running, this error may lead to a replication malfunction the next time the server is restarted.

The error occurs when the value of an important replication configuration attribute cannot be stored persistently in the Directory Server configuration.

Solution:

Stop the server immediately and check the cn=replica entry for this suffix in the Directory Server configuration. If the attribute lastInitTimeStamp is present in the entry, set its value to the value included in the error log. If the attribute lastInitTimeStamp is not present in the entry, add it and set its value to the value included in the error log. Restart the server.


8227: Unable to read user schema.

Cause:

The server was unable to access to its own internal schema entry.

Solution:

Stop and restart the server. If this does not solve the problem, contact Sun Technical Support.


8228: Bind error for agreement: .agreement.

Cause:

A replication protocol bind error has occurred.

Solution:

Check that the consumer is up and running.


8229: Failed to start a total update session.

Cause:

The server was unable to start a total replication update session.

Solution:

Check that the consumer is up and running.


8230: Failed to create directory for changelog changelog error error.

Cause:

The pathname is invalid, or there is unsufficient access to create the changelog directory.

Solution:

Check that the path is valid and that there are sufficient access rights to create the directory.


8232: Removal of changelog file filename failed.

Cause:

A database error occurred.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8234: Changelog is not initialized.

Cause:

The changelog is not initialized, or an attempt has been made to configure the changelog cleanup parameters, when the changelog service is not started.

Solution:

Ensure that the changelog service has been enabled.


8235: Failed to initialize the changelog resource, error ID

Cause:

Directory Server could not initialize a critical resource.

Solution:

Check that Directory Server is not having to contend for system resources with other applications.

Restart Directory Server.


8236: Failed to open changelog.

Cause:

This is probably due to a database or file access problem.

Solution:

Enable the replication logs and retry the operation to see if additional reasons are output to the error log.


8237: Changelog is in invalid state (state instead of state)

Cause:

The changelog service has not stopped as expected.

Solution:

Restart Directory Server.


8238: Failed to start changelog monitoring threads (error)

Cause:

Directory Server could not start threads needed to manage the changelog.

Solution:

Check that sufficient threads are available, and that Directory Server is not having to contend for system resources with other applications.


8239: Removal of changelog file filename failed, file not removed

Cause:

Directory Server could not delete the file.

Solution:

Restart Directory Server.


8240: allocation failed while converting entry to data (size size)

Cause:

Directory Server could not allocate enough memory to convert a changelog entry to data.

Solution:

Check that sufficient memory is available to Directory Server.

Restart Directory Server if it stops.


8241: Change record has an invalid data version

Cause:

A change record in the database has an invalid version number.

Solution:

Perform the following steps:

  1. Disable and re-enable replication for this database.

  2. Initialize the server again.

  3. Contact Sun Technical Support.


8242: Change record has an invalid operation type.

Cause:

There is an invalid change record in the changelog.

Solution:

Ordinarily, this error should not occur. If it does, the changelog is likely to be corrupted. In this case, reset the changelog for this database by reloading the data or disabling/enabling replication. If this does not solve the problem, contact Sun Technical Support.


8243: Failed to begin transaction for trimming DB error.

Cause:

A database error occurred while the transaction was starting. This is likely to be a resource problem.

Solution:

Check the database error and take action based on the error code. Directory Server uses Sleepycat Software's Berkeley DB.


8244: Failed to abort transaction for trimming DB error.

Cause:

A database error occurred while the transaction was being aborted. This is likely to be a resource problem.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8245: Failed to commit transaction for trimming DB error.

Cause:

A database error occurred while the transaction was being committed. This is likely to be a resource problem.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8246: Failed to begin transaction for writing changelog changelog RUV DB error.

Cause:

A database error occurred while the transaction was starting. This is likely to be a resource problem.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8247: Failed to abort transaction for writing changelog changelog RUV DB error.

Cause:

A database error occurred. This is likely to be a resource problem.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8248: Failed to commit transaction for writing changelog changelog RUV DB error.

Cause:

A database error occurred while the transaction was being aborted. This is likely to be a resource problem.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8249: Writing the changelog changelog RUV in the file filename failed DB error.

Cause:

A database error occurred while the transaction was being committed. This is likely to be a resource problem.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8250: Failed to begin transaction for writing change count entry DB error.

Cause:

A database error occurred. This is likely to be a resource problem.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8251: Failed to abort transaction for writing change count entry DB error.

Cause:

A database error occurred. This is likely to be a resource problem.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8252: Failed to commit transaction for writing change count entry DB error.

Cause:

A database error occurred. This is likely to be a resource problem.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8253: Failed to write change count entry to the file filename DB error.

Cause:

A database error occurred. This is likely to be a resource problem.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8254: allocation failed while converting change to ldif (size size)

Cause:

Directory Server could not allocate enough memory to convert a change record to LDIF.

Solution:

Check that sufficient memory is available to Directory Server.

Restart Directory Server if it stops.


8255: Change record from LDIF has an invalid data format. Record rejected

Cause:

Directory Server encountered invalid data while loading a changelog record from LDIF.

Solution:

Check that the LDIF file is valid.


8256: Failed to begin transaction for writing change operation DB error.

Cause:

A database error occurred.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8257: Failed to abort transaction for writing change operation DB error.

Cause:

A database error occurred.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8258: Failed to commit transaction for writing change operation DB error.

Cause:

A database error occurred.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8259: Failed to write change operation with CSN number. DB error.

Cause:

A database error occurred.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8260: Failed to create cursor for retrieving first change DB error.

Cause:

A database error occurred.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8261: Failed to retrieve first change DB error.

Cause:

A database error occurred.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8262: Failed to retrieve the next change DB error.

Cause:

A database error occurred.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8263: Failed to delete the current change DB error.

Cause:

A database error occurred.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8264: Failed to position in db at CSN number. DB error.

Cause:

A database error occurred.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8265: allocation failed while creating changelog file for replica replica

Cause:

Directory Server could not allocate enough memory to create the changelog file.

Solution:

Check that sufficient memory is available to Directory Server.

Restart Directory Server if it stops.


8266: Failed to open changelog file for replica replica. DB error.

Cause:

An internal database error occurred.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8267: Failed to retrieve change count from changelog for replica replica.

Cause:

The server was unable to retrieve the number of entries in the changelog.

Solution:

Enable replication logging and check the specific replication error code for more information.


8268: Failed to close changelog file filename. DB error.

Cause:

A database error occurred.

Solution:

Check the corresponding database error code, and take action according to the database problem.


8269: Failed to write content of changelog file filename to ldif file

Cause:

Directory Server failed to export the changelog.

Solution:

Check disk space, then check the file system.


8270: Failed to retrieve change from changelog file filename while exporting to ldif error code

Cause:

Internal error

Solution:

Contact Sun Technical Support.


8271: Consumer replica replica_name has an invalid RUV.

Cause:

The replication update vector returned by the consumer could not be parsed or caused a problem.

Solution:

Check the consumer configuration. It may be necessary to initialize the consumer again.


8272: Replication session aborted for agreement agreement_name because consumer replica is disabled.

Cause:

The consumer returned a disabled error, that is, it is not in a state to receive replication updates.

Solution:

Enable the consumer replica. It may also be necessary to initialize the consumer again.


8276: Failed to start Replication Session for suffix suffix_name.

Cause:

The replica is still being configured. The replication session cannot be accepted yet.

Solution:

Wait until the configuration is complete and restart replication on the supplier.


8277: Failed to start Replication Session for suffix suffix_name.

Cause:

The replication session cannot be accepted because no replica has been defined for the suffix.

Solution:

Check that the supplier replication agreement is correct. Enable replication on the consumer.


8278: Failed to start Replication Session for suffix suffix_name.

Cause:

The consumer is configured as a legacy replica and can therefore not accept multimaster replication.

Solution:

Correct the replication topology.


8279: Failed to start Replication Session for suffix suffix_name.

Cause:

The consumer is denying the right to replicate

Solution:

Check that the replication identity is properly defined and matches the one that the supplier is using.


8280: Failed to start Replication Session for suffix suffix_name.

Cause:

Internal error

Solution:

Contact Sun Technical Support.


8281: Failed to start Replication Session for suffix suffix_name.

Cause:

The consumer is not yet initialized and can therefore not accept changes.

Solution:

Initialize the consumer, either online or offline.


8282: Failed to start Replication Session for suffix suffix_name.

Cause:

The consumer appears to have the same replica ID as the supplier (both are masters).

Solution:

Disable and re-enable replication, providing a different replica ID for one of the servers.


8283: Failed to start Replication Session for suffix suffix_name.

Cause:

The consumer replica is already busy with a replication session.

Solution:

Wait and try later. If this error persists, restart the server.


8284: Failed to start Replication Session for suffix suffix_name.

Cause:

The consumer server is a master and can therefore not accept a partial replica.

Solution:

Make the consumer a read-only server, or eliminate partial replication configuration in the replication agreement.


8285: Failed to start Replication Session for suffix suffix_name.

Cause:

Directory Server encountered an invalid mapping tree state.

Solution:

Check the mapping tree state.


8286: Abort Replication Session for suffix suffix_name.

Cause:

Directory Server encountered a replication protocol violation.

Solution:

Take action based on the full error message.

If necessary, contact Sun Technical Support.


8287: Bad Group Packet size value for agreement agreement_name.

Cause:

The value of the attribute ds5ReplicaTransportGrpPktSize is invalid.

Solution:

Check the Directory Server configuration defining the replication agreement.

Solution:

Check the modifications attempted on the replication agreement.


8288: Bad Concurrency Level value for agreement agreement_name.

Cause:

Value of attribute ds5ReplicaTransportConcurrencyLevel is invalid.

Solution:

Check the Directory Server configuration defining the replication agreement.

Solution:

Check the modifications attempted on the replication agreement.


8292: Total update of a consumer consumer with an empty database is not allowed.

Cause:

Consumer initialization has been requested but the supplier database is empty.

Solution:

Load data onto the supplier before attempting to initialize the consumer with that supplier.


8293: A fatal problem occurred on the consumer side: consumer with error error.

Cause:

A fatal problem has occurred on the remote consumer.

Solution:

Check the error log on the consumer for more information. Once the problem has been solved, you will need to update the replication agreement and initiate updates again.


8294: _cl5TrimFile: Removing changelog file filename as it belongs to an unexisting replica.

Cause:

The changelog file contains data changes from a replica whose configuration has been removed.

Solution:

No action is necessary - this is an informational message.


8296: [S] Unable to start a replication session with MODDN enabled. The consumer name does not support MODDN operations.

Cause:

The modify DN must be supported by all servers in the replication topology in order for it to be used.

Solution:

Upgrade the consumer server or do not activate the modify DN operation.


8297: [C] Start replication request: Unknown tag while decoding tag

Cause:

An incorrectly encoded request caused a protocol error.

Solution:

Contact Sun Technical Support.


8298: [C] Start replication request, failed to decode end of sequence

Cause:

An incorrectly encoded request caused a protocol error.

Solution:

Contact Sun Technical Support.


8299: Internal Error: [C] while decoding optional csn (partial or medium consistency replication)

Cause:

An incorrectly encoded request caused a protocol error.

Solution:

Contact Sun Technical Support.


8300: Internal Error: [C] while parsing optional CSN CSN

Cause:

An incorrectly encoded request caused a protocol error.

Solution:

Contact Sun Technical Support.


8301: Protocol Error: [C] while decoding optional csn, bad end of sequence

Cause:

An incorrectly encoded request caused a protocol error.

Solution:

Contact Sun Technical Support.


8302: Decoding replicate entry failed.

Cause:

A protocol error occurred. The entry was incorrectly encoded.

Solution:

Check the error code and contact Sun Technical Support.


8303: Failed with error code error.

Cause:

Schema replication failed locally on the consumer.

Solution:

Check error code and contact Sun Technical Support.


8304: Protocol Error: [C] Decoding replication control request failed

Cause:

An incorrectly encoded request caused a protocol error.

Solution:

Contact Sun Technical Support.


8305: Protocol Error: [C] Decoding replication control request failed to get control type

Cause:

An incorrectly encoded request caused a protocol error.

Solution:

Contact Sun Technical Support.


8306: Protocol Error: [C] Decoding database entries request failed

Cause:

An incorrectly encoded entry caused a protocol error.

Solution:

Contact Sun Technical Support.


8307: Failed to import database entry.

Cause:

An internal error occurred while adding an entry to the import queue, or while acknowledging the entry to the supplier.

Solution:

Check the error log for a disk space problem and initialize the database again. If the problem persists, contact Sun Technical Support.


8308: Invalid change_operation: entry_UUID entry CSN CSN_value.

Cause:

A badly formed change was received.

Solution:

Contact Sun Technical Support.


8309: [C] Pblock allocation failed while decoding replay changes request for operation-code operation on DN DN

Cause:

The server could not allocate sufficient memory to complete the operation.

Solution:

Make sure enough memory is available, and then restart the server.


8310: Protocol error: [C] Detected unsupported operation (operation) in replay changes request

Cause:

The server received an operation that is not supported for this version.

Solution:

Make sure that the servers in your replication topology use compatible versions of the replication protocol. You may be running a legacy version of the server that uses an outdated version of the replication protocol.


8311: Unexpected operation sequence number value (expecting value).

Cause:

An internal error occurred in the sequencing of replicated operations.

Solution:

Contact Sun Technical Support.


8312: Replay of pending changes failed returning.

Cause:

The replicated change could not be applied on this consumer.

Solution:

Check the error code. A delete operation may generate a return code of 32 - this error code is harmless (a dependency of changes between several masters).

If the error persists, contact Sun Technical Support.


8313: Internal Error: [C] Decoding of group of changes failed, returning error-code

Cause:

An incorrectly encoded group of replication changes caused a protocol error.

Solution:

Contact Sun Technical Support.


8314: Protocol error received a response instead of a request

Cause:

A response was received when a request was expected.

Solution:

Contact Sun Technical Support.


8315: [C] Failed to add op op_num csn CSN to the pending list (err=code)

Cause:

One of the following:

  • The configuration on the consumer is invalid.

  • The consumer is not initialized.

  • An attempt was made to write to a read-only replica.

  • The change involved has already been applied.

Solution:

Verify that the replica is of the proper type.

Solution:

Check the configuration on the consumer replica. Initialize the consumer if necessary.


8318: [S] Bind failed with response: error_code.

Cause:

Authentication failed. This may be due to an invalid host and port combination, an invalid identity, or the fact that the consumer is down.

Solution:

Check the error code and fix the replication agreement. It may be necessary to restart the consumer.


8319: [S] Start Failed with response: error_code.

Cause:

Replication was unable to start. This is likely to be caused by an error in the replication configuration.

Solution:

Check the error log for more information. Also check the error logs on the consumers.


8320: [S] End Failed with response: error_code.

Cause:

Replication was unable to end. This may be because a network outage has occurred, the consumer is down, or the consumer has already dropped the connection.

Solution:

Check the error log for more information. Also check the error logs on the consumers.


8321: Failed to close old changelog file file-name DB error error-code - error-message

Cause:

A database error occurred.

Solution:

Depending on the database error specified, you may need to initialize the replica.


8322: DB error error-code - error-message

Cause:

A database error occurred.

Solution:

Depending on the database error specified, you may need to initialize the replica.


8323: DB error error-code - error-message

Cause:

A database error occurred.

Solution:

Depending on the database error specified, you may need to initialize the replica.


8324: [C] Consumer has decided to prioritize a total update regarding incremental sessions

Cause:

An initialization request has priority over other replication sessions.

Solution:

None.


8325: replica_write_partial_repl_checksum: failed to update partial repl checksum with value (value) (error-message LDAP error - error-code)

Cause:

The server encountered a problem writing an attribute value inside the replica entry.

Solution:

Although possibly harmless while the server is up and running, this might become a serious error that could lead to a break in replication next time the server is restarted. This is because the value of an important replication configuration attribute could not be stored persistently in the Directory Server configuration. To try to work around this issue, stop the server immediately and check the cn=replica entry for this suffix found in the Directory Server configuration file. If the attribute dsfilterspconfigchecksum is already present in the entry, then use the value included in the errors log. If dsfilterspconfigchecksum is not present yet in the entry, use the value suggested in the errors log. Then restart the server.


8326: replica_write_partial_repl_checksum: failed to update last init timestamp with value (value) (error-message LDAP error - error-code)

Cause:

The server encountered a problem writing an attribute value inside the replica entry.

Solution:

Although possibly harmless while the server is up and running, this might become a serious error that could lead to a break in replication next time the server is restarted. This is because the value of an important replication configuration attribute could not be stored persistently in the Directory Server configuration. To try to work around this issue, stop the server immediately and check the cn=replica entry for this suffix found in the Directory Server configuration file. If the attribute dsfilterspconfigchecksum is already present in the entry, then use the value included in the errors log. If dsfilterspconfigchecksum is not present yet in the entry, then use the value suggested in the errors log. Then restart the server.


8327: Changelog directory error-code could not be created

Cause:

The server could not create the replication changelog directory on the file system.

Solution:

Check that the server user has permission to create directories under the instance-path.


8328: invalid priority rule : error-message

Cause:

The prioritized replication configuration is not valid.

Solution:

Make sure you specify a valid replication priority as explained in the error message.


8328: Cannot Delete priority rule : error-message

Cause:

The prioritized replication value could not be deleted.

Solution:

Make sure you specify a valid replication priority as explained in the error message.


8329: Ignored invalid priority rule : error-message

Cause:

The prioritized replication configuration is not valid.

Solution:

Make sure you specify a valid replication priority as explained in the error message.


8330: Failed to write change operation with CSN CSN to database DB error error-code - error-message

Cause:

The server could not write to the replication changelog database.

Solution:

Check the file system permissions and restart the server.


8331: Unable to demote a hub to a read-only replica if some replication agreements are enabled

Cause:

The server could not be demoted to a dedicated consumer role.

Solution:

First eliminate the replication agreements that call for updates from the hub.


12289: PR_Accept() failed error variable (variable)

Cause:

The problem depends on the variable and is based on the Netscape Portable Runtime (NSPR) error layer.

Solution:

If you determine that the cause of the problem is that the TCP port to which you are attempting to bind is already in use, consider the following actions.

  • Restart the server, using a different port.

  • Stop the application bound to that port and restart the server.


12290: PR_GetIPNodeByName(variable) failed errno error (message)

Cause:

There is an error in the naming service configuration.

Solution:

Add listen host (variable) to the naming service.


12291: No port to listen on.

Cause:

The LDAP port is missing from the configuration.

Solution:

Add an LDAP port to the configuration file or use the command line.


12292: Unable to create time thread (variable - variable) - shutting down.

Cause:

System error, probably due to a resource problem.

Solution:

Free up resources on the machine and restart the server.


12293: Too many open file descriptors - not listening on new connection.

Cause:

There is an error in the configuration file. See the reservedfd attribute.

Solution:

Increase the maximum number of file descriptors (in the configuration file) by increasing the value of nsslapd-maxdescriptors. Otherwise, check the Directory Server configuration and reduce the resource usage (number of threads, and number of backends, for example.)


12294: Not enough descriptors to accept any additional connections.

Cause:

There are insufficient file descriptors to accept new connections. This may be because:

  1. the value of the maxdescriptors attribute is too small

  2. the hard limit on descriptors is too small

  3. the value of the reservedescriptors attribute is too large

Solution:

Increase the number of file descriptors available to the slapd process.

The error log displays the number of file descriptors currently available to the slapd process, and the number of descriptors reserved for internal slapd use. The total number of file descriptors available to the process must be greater than variable


12295: Cannot initialize lock. The server is terminating

Cause:

Probably due to a resource problem on the system.

Solution:

Restart Directory Server.


12296: Cannot create lock. The server is terminating.

Cause:

Probably due to a resource problem on the system.

Solution:

Restart Directory Server.


12297: Cannot create condvar. The server is terminating.

Cause:

Probably due to a resource problem on the system.

Solution:

Restart Directory Server.


12298: PR_SetNetAddr(PR_IpAddrAny) failed errno error

Cause:

Internal error.

Solution:

Contact Sun Technical Support.


12299: PR_EnumerateHostEnt() failed.

Cause:

There is an error in the naming service configuration.

Solution:

Add the listen host variable to the naming service. Refer to your operating system documentation for more information.


12300: gethostname host failed error error (variable).

Cause:

There is an error in the naming service configuration.

Solution:

Add the listen host variable to the naming service. Refer to your operating system documentation for more information.


12301: NSS Initialization failed.

Cause:

The server was unable to initialize the security library.

Solution:

Contact Sun Technical Support.


12302: Shutting down due to possible conflicts with other slapd processes.

Cause:

More than one Directory Server is running.

Solution:

Stop Directory Servers that should not be running.


12304: Shutting down due to inability to find user in system account database.

Cause:

The server was unable to locate the specified user in the system account database.

Solution:

Add the user to the system account database and restart the server.


12308: ber encoding failed.

Cause:

This is an internal error, most likely to be related to a memory allocation problem.

Solution:

Increase the virtual memory of the machine and restart Directory Server.


12318: Call to _base64Decode fails.

Cause:

An error occurred during the base64 encoding of a value. This is an internal error with no specific cause. It may be due to a resource problem.

Solution:

Report the error to your administrator.


12319: connection_push_back_data has failed.

Cause:

The request has been aborted due to an internal error.

Solution:

Please contact Sun Technical Support.


12320: Invalid arguments: entry.

Cause:

Configuration error. The server failed to obtain the frontend configuration entry.

Solution:

Correct the frontend configuration entry and restart the server.


12321: Failure during frontend sanity check.

Cause:

Configuration error. The server failed the front end sanity check.

Solution:

Correct the front end declaration and restart the server.


12322: Start parse of DSML operation fails, operation aborted.

Cause:

Internal error occurred during the call to DsmlParser_startParse(). This error has no specific cause but may be related to a resource problem.

Solution:

Report the error to your administrator.


12323: Could not store worker context in Batch operation.

Cause:

This is an internal error with no specific cause. It may be related to a resource problem.

Solution:

Report the error to your administrator.


12324: Can’t register HTTP port port.

Cause:

Internal error. The server failed to register the HTTP port.

Solution:

Check that the specified port is not currently in use and restart the server.


12325: Can’t register HTTPS port port.

Cause:

Internal error. The server failed to register the HTTPS port.

Solution:

Check that the specified port is not currently in use and restart the server.


12326: Max size value of parser pool is lower than current size value.

Cause:

Configuration error: the maximum size of the parser pool is lower than the current size.

Solution:

In the Directory Server configuration, check that the value of the ds-hdsml-poolsize attribute is lower than the value of the ds-hdsml-maxpoolsize attribute.


12327: Cannot create XMLCh to UTF8 Transcoder.

Cause:

An error occurred while trying to create an instance of a UTF8 transcoder. This is an internal error with no specific cause. It may be related to a resource problem.

Solution:

Report the error to your administrator.


12328: Can’t initialize DSML Worker.

Cause:

Internal error. The server failed during the initialization of the DSML worker.

Solution:

Please contact Sun Technical Support.


12329: Extra datacopy failed.

Cause:

A request has not been processed due to a connection closure.

Solution:

Check the connection and retry.


12330: Operation Key creation for HTTP context failed.

Cause:

An internal memory management error has occurred.

Solution:

Please contact Sun Technical Support.


12332: HTTP/DSML frontend initialization failed.

Cause:

Initialization error. The server failed to set the plug-in functions.

Solution:

Correct the front end configuration and restart the server.


12333: HTTP frontend instance creation failed.

Cause:

Internal error. The server failed to instantiate the front end plug-in.

Solution:

Please contact Sun Technical Support.


12334: Unknown internal error has been raised.

Cause:

Unknown internal error.

Solution:

Please contact Sun Technical Support.


12335: Error with config attribute attribute.

Cause:

Configuration error. A configuration attribute is invalid.

Solution:

Correct the specified attribute and restart the server.


12336: Invalid attribute syntax.

Cause:

Configuration error. The syntax of a configuration attribute is invalid.

Solution:

Correct the syntax of the specified attribute and restart the server.


12337: System I/O error.

Cause:

Internal I/O error.

Solution:

Please contact Sun Technical Support.


12338: Memory allocation error.

Cause:

System error, probably due to insufficient resources (lack of memory).

Solution:

Please contact Sun Technical Support.


12339: Memory usage error.

Cause:

Memory management system error.

Solution:

Please contact Sun Technical Support.


12340: DSML schema location is not defined.

Cause:

Configuration error: DSML schema location is not defined. Under normal circumstances, the default value of the DSML schema location is hard coded. However, this default value can be overridden in the Directory Server configuration.

Solution:

Correct the value of the ds-hdsml-schemalocation attribute in the Directory Server configuration, or remove this attribute from the Directory Server configuration.


12341: DSML schema URN is not defined.

Cause:

Configuration error: DSML schema URN is not defined. Under normal circumstances, the default value of the DSML schema URN is hard coded. However, this default value can be overridden in the Directory Server configuration.

Solution:

Correct the value of the ds-hdsml-urn attribute in the Directory Server configuration, or remove this attribute from the Directory Server configuration.


12342: SOAP schema location is not defined.

Cause:

Configuration error. Under normal circumstances, the default value of the SOAP schema location is hard coded. If this error occurs, there is an internal problem.

Solution:

Report the error to your administrator.


12343: SOAP schema URN is not defined.

Cause:

Configuration error. Under normal circumstances, the default value of the SOAP schema URN is hard coded. If this error occurs, there is an internal problem.

Solution:

Report the error to your administrator.


12344: Lock for concurrent access to _freeList does not exist.

Cause:

Internal error: a lock for concurrent access to the specified list is missing. The lock should have been defined previously.

Solution:

Report the error to your administrator.


12345: No more parser in the pool, operation aborted.

Cause:

Internal error that occurs when the pool of parsers is empty and cannot be extended (all the parsers are in use).

Solution:

Increase the value of the maximum pool size, specified by the ds-hdsml-poolmaxsize attribute in the Directory Server configuration.


12346: Bad Dsml request - SOAP fault code.

Cause:

An error occurred during the call to DsmlParser_getNextRequest.

Solution:

None - a SOAP fault is returned to the client with the reason for the failure.


12347: Error with secure identity method.

Cause:

Configuration error. The secure identity method configuration parameter is invalid.

Solution:

Correct this parameter and restart the server. Possible values for the secure identity method parameter are:

clientCertOnly clientCertFirst httpBasicOnly


12348: Exception raised when calling XMLString::transcode.

Cause:

An exception was raised when calling XMLString::transcode. This is an internal error with no specific cause. It may be due to a resource issue.

Solution:

Report the error to your administrator.


12352: Bad Dsml request - SOAP error message.

Cause:

A SOAP/DSML error occurred during a call to DSMLParser_startParse().

Solution:

None - a SOAP/DSML error message is returned to the client with the reason for the failure.


12353: Parse of fake request fails error.

Cause:

This error occurs when a bad request is submitted to the parser. It should not occur in the case of the valid fake request. The DSML/SOAP schema URN and/or location may be invalid.

Solution:

Check the error log for more information. If the schema URN and/or location are invalid, check the following attributes in the Directory Server configuration: ds-hdsml-dsmlurn, ds-hdsml-dsmlschemalocation.


12354: Parse of fake request fails.

Cause:

This error occurs when a bad request is submitted to the parser. It should not occur in the case of the valid fake request. Cause unknown.

Solution:

Please contact Sun Technical Support.


12355: The XML schema file filename is missing.

Cause:

Configuration error: an XML schema is missing.

Solution:

Insert the missing schema in the specified location and restart the server.


12356: SOAPAction header is missing.

Cause:

The client must provide a SOAPAction header. If it is absent, the request is rejected.

Solution:

Provide a SOAPAction header, the contents of which may be set to any value (including an empty value).


12362: PR_Bind() on address host port port failed.

Cause:

It is likely that the port number configured for this server requires that the server be run as root.

Solution:

Restart the server using a port that does not required root access or start the server as a user with root access.


12363: Inconsistency: security is ’off’ while there are attributes configured to be encrypted.

Cause:

Some attributes are configured to be encrypted, and attribute encryption requires that security be on. Yet Directory Server was started with security turned off.

Solution:

Before performing any operation dealing with the encrypted attributes, switch security on, make sure certificate and key databases, certificate names, token name and token names are configured appropriately, and then restart Directory Server.


20490: Database recovery process FAILED. The database is not recoverable.

Cause:

Database recovery has failed.

Solution:

This is a serious database error. Please contact Sun Technical Support.


20492: Failed to create thread (NSPR error).

Cause:

The Netscape Portable Runtime (NSPR) was unable to create one or more threads. This may be due to insufficient resources.

Solution:

Perform the following steps:

  1. Check that there is sufficient available memory and that a sufficient number of threads per process has been set up in the operating system configuration.

  2. Check the error code that appears in the log against the NSPR error codes (refer to http://www.mozilla.org/projects/nspr/reference/html/prerr.html).


20494: Instance instance_name does not have the expected version version_number.

Cause:

An attempt was made to open a database with a different database version. This is probably a migration issue.

Solution:

Export the database from the old server and import it to the new server.


20499: dblayer_instance_start_fail: backend instance_name has no IDs left. Database must be rebuilt.

Cause:

The internal NEXTID counter has reached the limit.

Solution:

Rebuild the database.


20501: Serious failure in dblayer_txn_begin. Err=value.

Cause:

The database has reported an error. If the printed value is positive, this is a system error. If the printed value is negative, the database has not been recognized or must be recovered.

Solution:

This is a serious database error. Please contact Sun Technical Support.


20502: Serious failure in dblayer_txn_commit. Err=value.

Cause:

The database has reported an error. If the printed value is positive, this is a system error. If the printed value is negative, the database has not been recognized or must be recovered.

Solution:

This is a serious database error. Please contact Sun Technical Support


20503: Serious failure in dblayer_txn_abort. Err=value.

Cause:

The database has reported an error. If the printed value is positive, this is a system error. If the printed value is negative, the database has not been recognized or must be recovered.

Solution:

This is a serious database error. Please contact Sun Technical Support


20504: Serious failure in deadlock detect (aborted at address). Err=value.

Cause:

The database has reported an error. If the printed value is positive, this is a system error. If the printed value is negative, the database has not been recognized or must be recovered.

Solution:

This is a serious database error. Please contact Sun Technical Support


20505: Serious failure during database checkpointing. Err=value.

Cause:

The database has reported an error other than an inability to write pages to the disk immediately. If the printed value is positive, this is a system error. If the printed value is negative, the database has not been recognized or must be recovered.

Solution:

This is a serious database error. Please contact Sun Technical Support


20506: Serious failure during trickle. Err=value.

Cause:

The database has reported an error. If the printed value is positive, this is a system error. If the printed value is negative, the database has not been recognized or must be recovered.

Solution:

This is a serious database error. Please contact Sun Technical Support


20507: Failed to create guardian file. Database corruption possible.

Cause:

This is a file system error. The server was unable to create the required guardian file.

Solution:

Check that the user specified at installation has the appropriate permissions to write to the database directory.


20508: Database database is corrupt and being marked unavailable. Either re-import or delete the database.

Cause:

The database is corrupt. This is most likely to be the result of a previously aborted database import.

Solution:

Import from LDIF or delete the database.


20512: Failed to write guardian file. Database corruption possible.

Cause:

This is a file system error. The server was unable to write to or close the guardian file.

Solution:

Check that the user specified at installation has the appropriate permissions to write to the database directory. Ensure that the file system is not full.


20513: Failed to delete guardian file. Database corruption possible.

Cause:

This is a file system error. The server was unable to delete the guardian file.

Solution:

Check that the user specified at installation has the appropriate permissions to write to the database directory.


20517: open or creation of file: filename failed

Cause:

Directory Server failed to create the specified file during backup.

Solution:

Check disk space, then check permissions on the file system before attempting backup again.


20518: write to file: filename failed

Cause:

Directory Server failed to write to the specified file during backup.

Solution:

Check disk space, then check permissions on the file system before attempting backup again.


20519: open of file: filename failed

Cause:

Directory Server failed to read from the specified file during restore.

Solution:

Check permissions on the file system before attempting restore again.


20520: Wrong index definitions for backend backend: the index index is not part of backuped data

Cause:

The index definitions in the backup do not match the current configuration.

Solution:

Change the current configuration to match that of the backup before attempting to restore again.


20521: backend backend is included in backup but not in current configuration

Cause:

A backend specified in the backup does not match the current configuration.

Solution:

Add a backend to the current configuration with the same indexes configured as in the backup before attempting to restore again.


20522: backend backend is included in current configuration but not in backup

Cause:

A backend specified in the current configuration does not match the backup.

Solution:

Add a backend to the current configuration with the same indexes configured as in the backup before attempting to restore again.


20737: ldbm backend instance: nextid not initialized.

Cause:

This is a software problem.

Solution:

Please contact Sun Technical Support.


20738: ldbm backend instance: FATAL ERROR: backend name has no IDs left. DATABASE MUST BE REBUILT.

Cause:

The limit for the database internal identifier has been reached. This is probably due to several adds and deletes being performed on the local database.

Solution:

Rebuild the database, using db2ldif, then ldif2db.


20739: ldbm backend instance: WARNING: backend backend_name may run out of IDs.

Cause:

The limit for the database internal identifier is close to being reached. This is probably due to several adds and deletes being performed on the local database

Solution:

If the limit has been reached, rebuild the database, using db2ldif, then ldif2db.


20740: Numsubordinates assertion failure.

Cause:

The database is not coherent. There is a child entry that is unknown to the parent entry and the numsubordinates attribute is absent in the parent entry.

Solution:

Rebuild the database, using db2ldif, then ldif2db.


20745: ldbm_back_seq: id2entry err error.

Cause:

An entry could not be located during an ldbm_back_seq operation. The database is incoherent.

Solution:

Rebuild the database, using db2ldif, then ldif2db.


20746: ldbm_back_seq: could not open index file for attribute attribute.

Cause:

An index file could not be located during an ldbm_back_seq operation. The database is incoherent.

Solution:

Rebuild the database, using db2ldif, then ldif2db.


20747: compare_entries db err error_number while loading entry entry.

Cause:

Certain entries were deleted while the server was attempting to sort them. This is probably due to a VLV or SORT control in a search.

Solution:

Create a VLV index to avoid “on the fly” sorting.


20748: start : Resource limit registration failed.

Cause:

The local database could not be started because the limit subsystem did not allow it to register.

Solution:

Check the resource limit configuration and restart the server.


20749: start : Failed to init database err=error.

Cause:

The local database could not be started because the underlying database component did not start.

Solution:

Check that the database configuration is correct, and that there is enough disk space available.


20750: start : Failed to start databases err=error.

Cause:

The local database instances could not be started.

Solution:

Check that the database configuration is correct, and that there is enough disk space available.


20751: Database version mismatch (expecting version but found version in directory directory.)

Cause:

The binary code for one version of Directory Server was started on a database with a different version.

Solution:

Check the versions and ensure that the same binary and database versions are used.


20752: VLV : can’t get index file file (err error).

Cause:

The server could not locate the file used for the virtual list view (VLV) index during an update.

The database is inconsistent.

Solution:

Rebuild the database, using db2ldif, then ldif2db.


20753: vlv_build_idl: can’t follow db cursor (err error).

Cause:

The database is incoherent.

Solution:

Rebuild the database, using db2ldif, then ldif2db.


20754: nomem: wants value key value data.

Cause:

The system is out of memory

Solution:

Check the configuration.


20755: VLV : can’t get index file file (err error).

Cause:

The server could not locate the file used for virtual list view (VLV) indexes.

The database is inconsistent.

Solution:

Rebuild the database, using db2ldif, then ldif2db.


20756: VLV : couldn’t get cursor (err error).

Cause:

The server could not locate a cursor used for virtual list view (VLV) indexes.

The database is inconsistent.

Solution:

Rebuild the database, using db2ldif, then ldif2db.


20757: vlv_filter_candidates: Candidate id not found err=error.

Cause:

The server could not locate an entry that is present in the virtual list view (VLV) index.

The database is inconsistent.

Solution:

Rebuild the database, using db2ldif, then ldif2db.


20758: vlv_trim_candidates_byvalue: Candidate ID id not found err error.

Cause:

The server could not locate an entry that is referenced in a virtual list view (VLV) index.

The database is inconsistent.

Solution:

Rebuild the database, using db2ldif, then ldif2db.


20759: vlv find index: err error.

Cause:

The server could not locate an index used in virtual list view (VLV).

Solution:

Check the VLV configuration.


20760: Couldn’t generate valid filename from Virtual List View Index Name name. Need some alphabetical characters.

Cause:

An LDAP client attempted to create a virtual list view (VLV) index with an invalid name. This should not harm Directory Server.

Solution:

Change the LDAP client so that it uses a valid name.


20761: Add: maximum ID reached cannot add entry to backend backend.

Cause:

The limit for the database internal identifier has been reached. This is probably because several adds and deletes have been performed on the local database.

Solution:

Regenerate the database using ldif2db and db2ldif.


20762: Add: attempt to index entry failed.

Cause:

The server was unable to index the entry being added.

Solution:

Check the previous errors in the log for additional information.


20763: Retry count exceeded in add.

Cause:

The acceptable number of add retry counts was exceeded without success. Another operation may be ongoing, resulting in a conflict when trying to access that part of the database.

Solution:

Wait until other operations have ended and retry the add operation.


20764: Line line_number: Fatal Error: Failed to initialize attribute structuring.

Cause:

The server was unable to initialize the attribute structure. This is probably a memory error.

Solution:

Check the available memory.


20765: Attempt to delete a non-tombstone entry entry.

Cause:

An attempt was made to delete an entry that was not a tombstone entry.

Solution:

Please contact Sun Technical Support.


20766: Attempt to tombstone again a tombstone entry entry.

Cause:

An attempt was made to tombstone an entry that is already a tombstone entry.

Solution:

Please contact Sun Technical Support.


20768: Retry count exceeded in delete.

Cause:

The acceptable number of delete retry counts was exceeded without success. Another operation may be ongoing, resulting in a conflict when trying to access that part of the database.

Solution:

Wait until other operations have ended and retry the delete operation.


20772: Retry count exceeded in modify.

Cause:

The acceptable number of modify retry counts was exceeded without success. Another operation may be ongoing, resulting in a conflict when trying to access that part of the database.

Solution:

Wait until other operations have ended and retry the modify operation.


20773: Retry count exceeded in modrdn.

Cause:

The acceptable number of retry counts was exceeded without success. Another operation may be ongoing, resulting in a conflict when trying to access that part of the database.

Solution:

Wait until other operations have ended and retry the modrdn operation.


20774: modrdn: could not add new value to index err=error

Cause:

The server was unable to add a new value to the index.

Solution:

Check the error log for more information and contact Sun Technical Support.


20775: Database error error.

Cause:

A database error occurred while trying to build the list of possible candidate entries. The index files may be corrupt.

Solution:

Re-index and try again.


20776: Null referral in entry.

Cause:

The candidate entry has a NULL referral.

Solution:

Update the referral in the entry or remove the ref attribute.


20777: Filter bypass error on entry entry.

Cause:

The server failed to bypass the filter test.

Solution:

Please contact Sun Technical Support.


20778: Unable to add config entries to the DSE.

Cause:

The server was unable to add configuration entries to the DSE.

Solution:

Ensure that there is no inconsistency within the entries.


20779: ERROR: ldbm plugin unable to read cn=config.

Cause:

The configuration information under cn=config could not be read.

Solution:

Please contact Sun Technical Support.


20780: ERROR: ldbm plugin unable to read attribute nsslapd-instancedir from cn=config.

Cause:

The nsslapd-instancedir attribute under cn=config could not be read. The attribute may be missing.

Solution:

Ensure that the nsslapd-instancedir attribute is present and has an appropriate value.


20786: Invalid value for attribute. Must be between 0 and 100.

Cause:

An invalid value was provided for the nsslapd-db-trickle-percentage attribute. The value should be between 0 and 100.

Solution:

Check and correct the value provided for the nsslapd-db-trickle-percentage attribute


20787: Attribute can’t be modified while the server is running.

Cause:

An attempt was made to modify a configuration attribute while the server was running. This attribute cannot be changed online.

Solution:

Stop the server before modifying the attribute.


20788: Value value for attribute attribute is not a number.

Cause:

The attribute value must be numerical.

Solution:

Ensure that the attribute has a numerical value.


20789: Value value for attribute attribute is greater than the maximum value.

Cause:

The value specified for the attribute is greater than the maximum permitted.

Solution:

Ensure that the attribute value is smaller than or equal to the maximum value.


20790: Value value for attribute attribute is less than the minimum value.

Cause:

The value specified for the attribute is smaller than the minimum permitted.

Solution:

Ensure that the attribute value is greater than or equal to the minimum value.


20791: Value value for attribute attribute is outside the range of representable values.

Cause:

The value specified for the attribute is outside the permissible range.

Solution:

Ensure that the attribute value is within the representable range.


20792: Could not set instance config attr attribute to value.

Cause:

The server failed to set the instance configuration attribute.

Solution:

Ensure that both the syntax and the value of the attribute are correct.


20793: Could not retrieve ldbm config info from DSE.

Cause:

The server was unable to access the ldbm configuration in the DSE.

Solution:

Check that the Directory Server configuration file has not been corrupted and restart the server.


20795: ldbm: instance instance does not exist!

Cause:

The specified instance was not found because no such instance exists.

Solution:

Verify that the instance name is correct and corresponds to an existing instance.


20796: ldbm: instance is in the middle of a task. Cancel the task or wait for it to finish then try again.

Cause:

The specified instance is currently processing a task.

Solution:

Cancel the current task or wait for it to finish and retry.


20797: ldbm: modify attempted to change the root suffix of a backend (which is not allowed).

Cause:

An attempt was made to change the suffix associated with an ldbm database.

Solution:

Do not modify the nsslapd-suffix attribute of an existing instance.


20806: System info mismatch (expecting variable but found variable in directory directory_name).

Cause:

The system information from the backend’s DBVERSION file did not match the server information.

Solution:

Edit the backend’s DBVERSION file to match the server information.


20807: Failed to read server system information

Cause:

The server was unable to obtain the system information. This is possibly a permissions or NSPR compilation issue.

Solution:

Check that the user specified at installation has the appropriate permissions.


20994: Disk full under variable.

Cause:

The available space on a disk used by Directory Server has dropped below the value of the disk-full-threshold attribute.

Solution:

Increase the available disk space.


20996: Cannot parse entry from database for id id string =variable.

Cause:

The wrong file system permissions or ownership can prevent proper access to database files.

Solution:

Verify that file system permissions and ownership allow read and write access for the user and group of the user who runs Directory Server. The directory containing the files should also allow access.

If your database is split across multiple locations, verify the access rights in each location.

Cause:

The database may be corrupt.

Solution:

Restore the database from a backup.


20997: Inconsistent database: entrydn for entry refers to id id missing from id2entry.

Cause:

Database corruption.

Solution:

Restore the database from a backup.


21005: Could not open index index for update.

Cause:

An attribute index is configured but the corresponding database index file could not be opened.

Solution:

Check whether the file exists and/or rebuild it using db2index.


21006: Could not open index index for range query.

Cause:

An attribute index has been configured but the corresponding database index file could not be opened.

Solution:

Check whether the file exists and/or rebuild it using db2index.


21008: Backend initialization failed: could not allocate a lock.

Cause:

Insufficient system resources.

Solution:

Check the available memory.


21009: Backend initialization failed: could not allocate a condition variable.

Cause:

Insufficient system resources.

Solution:

Check the available memory.


21010: Backend initialization failed: could not set plugin functions.

Cause:

Insufficient system resources.

Solution:

Check the available memory.


21011: Backend initialization failed on instance instance: could not allocate a lock.

Cause:

Insufficient system resources.

Solution:

Check the available memory.


21012: Backend initialization failed on instance instance: could not allocate a condition variable.

Cause:

Insufficient system resources.

Solution:

Check the available memory.


21016: Failed to create ancestorid index.

Cause:

An index could not be created on the disk.

Solution:

Check the error log for previous messages that should isolate the problem.


21017: Incomplete parentid index suspected (value extra keys in ancestorid)

Cause:

Database corruption.

Solution:

Rebuild the parentid index or restore the database from a backup.


21018: Entry cache initialization failed: could not allocate lock.

Cause:

Insufficient system resources.

Solution:

Check the system free memory.


21022: variable is configured to use more than the available physical memory.

Cause:

The cachesize as defined in the configuration file exceeds database limits.

Solution:

Lower the value of the cachesize attribute in the configuration file.


21023: Index index is inconsistent.

Cause:

Database corruption.

Solution:

Rebuild the affected index or restore the database from a backup.


21024: ldbm be malloc fail: Unable to create db name

Cause:

Insufficient system resources.

Solution:

Check the system free memory, then restart Directory Server.


21249: Failed to encrypt some attribute inside the entry entry before writing it to the database.

Cause:

The server was unable to encrypt the specified attribute inside the entry.

Solution:

Check the attribute encryption configuration.


21250: Failed to decrypt some attribute inside the entry entry when reading it from the database.

Cause:

The server was unable to decrypt the specified attribute inside the entry.

Solution:

Check the attribute encryption configuration.


21251: Encrypted value’s prefix doesn’t match the corresponding algorithm algorithm in the attribute encryption configuration.

Cause:

The value is already encrypted or does not match the algorithm specified in the configuration.

Solution:

Check that the attribute encryption configuration is correct.


21252: Server didn’t find plug-in for algorithm algorithm.

Cause:

The server was unable to locate the plug-in for the specified algorithm.

Solution:

Enable the encryption plug-in.


21253: Failed to encrypt index keys.

Cause:

The server was unable to encrypt the specified values.

Solution:

Check that the values are not already encrypted and that the cipher with which they are being encrypted match the configuration settings.


21254: Attribute encryption: failed to encrypt/decrypt attribute attribute with algorithm algorithm.

Cause:

The server was unable to encrypt/decrypt the attribute’s values. The attribute may already be encrypted with an incorrect algorithm or the algorithm plug-in may be missing.

Solution:

Check for inconsistencies in the attribute encryption configuration.


21255: Encryption plugin (plugin): failed to encrypt.

Cause:

An error occurred during the plug-in’s encryption function.

Solution:

Check the plug-in traces. Ensure that the plug-in itself has not been corrupted.


21256: Encryption plugin (plugin): failed to decrypt.

Cause:

An error occurred during the plug-in’s decryption function.

Solution:

Check the plug-in traces. Ensure that the plug-in itself has not been corrupted.


24577: Bulk import process failed: state=state, error code=error.

Cause:

The bulk import has been aborted.

Solution:

Ensure that the bulk import is started or previously suspended before attempting an update or restart.


28673: filter_sp_replace_or_add_checksum: failed to update attribute attribute from entry entry; LDAP error - errnum.

Cause:

The attribute filterspconfchecksum could not be updated with a new value.

Solution:

Perform the following steps:

  1. Check whether the attribute already exists in the entry.

  2. Check whether the attribute is present in the Directory Server configuration.


32769: Unable to allocate memory. Cannot start Roles plugin.

Cause:

There is not enough memory to register the roles plug-in into the service provider broker.

Solution:

Restart the server.


32770: Unable to allocate memory. Cannot start Roles plugin.

Cause:

There is not enough memory to register the nsrole attribute.

Solution:

Restart the server.


32771: Unable to allocate memory. Cannot create Roles cache.

Cause:

This error indicates a resource problem on the machine.

Solution:

Restart the server.


32772: Lock creation failed. Cannot create Roles cache.

Cause:

This error indicates a resource problem on the machine.

Solution:

Restart the server.


32773: Conditional variable creation failed. Cannot create Roles cache.

Cause:

This error indicates a resource problem on the machine.

Solution:

Restart the server.


32774: Thread creation failed. Cannot create Roles cache.

Cause:

This error indicates a resource problem on the machine.

Solution:

Restart the server.


32775: Failed to get objectclass from entry.

Cause:

The specified entry does not contain an objectclass.

Solution:

Check the entry and add the required objectclass.


32776: Unsupported operation operation.

Cause:

An unknown operation has been performed on the server and is triggering a role cache update.

Solution:

Check that the specified operation is valid.


32778: Maximum number of nested roles exceeded (max value current value). Not retrieving roles from entry entry. Probable circular definition.

Cause:

The maximum number of nested roles has been exceeded. This is probably due to a circular role definition.

Solution:

Check the role definitions. The maximum number of nested roles permitted is defined by MAX_NESTED_ROLES.


32779: Nested role entry does not exist.

Cause:

The entry corresponding to the DN does not exist.

Solution:

Check the role definition.


32780: Cannot initialize Roles plugin.

Cause:

The server is unable to update the pblock parameters.

Solution:

Restart the server.


32781: Unknown role type type.

Cause:

The role type is unknown. Valid role types are : managed, filtered, or nested.

Solution:

Check the role definition and amend the type as necessary.


33025: Could not allocate PB.

Cause:

Internal error, probably due to insufficient available memory.

Solution:

Free up some memory. If the error continues, please contact Sun Technical Support.


33026: Internal PBG error.

Cause:

Internal error.

Solution:

Please contact Sun Technical Support.


33027: Internal search error in Attribute Uniqueness plugin.

Cause:

Internal error.

Solution:

Please contact Sun Technical Support.


33028: Internal PB error.

Cause:

Internal error.

Solution:

Please contact Sun Technical Support.


33029: Could not find plugin argument number.

Cause:

Memory corruption or invalid configuration.

Solution:

Check the plug-in configuration. If it is valid, please contact Sun Technical Support.


33030: Could not find plugin arguments.

Cause:

Memory corruption or invalid configuration.

Solution:

Check the plug-in configuration. If it is valid, please contact Sun Technical Support.


33031: Could not find a valid argument.

Cause:

Configuration error.

Solution:

Check the plug-in configuration parameters in the Directory Server configuration. Make sure that the syntax and values are correct.


33032: ADD/MOD/MODRDN: unable to get replication flag.

Cause:

Internal error.

Solution:

Please contact Sun Technical Support.


33033: ADD/MOD/MODRDN: unable to get target DN.

Cause:

Internal error.

Solution:

Please contact Sun Technical Support.


33034: Unable to get entry data.

Cause:

Internal error.

Solution:

Contact Sun Technical Support.


33035: Could not get MODIFY data.

Cause:

Internal error.

Solution:

Please contact Sun Technical Support.


33036: Error while retrieving mod values.

Cause:

Internal error.

Solution:

Please contact Sun Technical Support.


33037: Unable to get new superior DN.

Cause:

The new superior DN does not exist.

Solution:

Check the validity of the intended operation.


33038: Unable to get new DN.

Cause:

The new DN is invalid or is not correctly specified.

Solution:

Check the validity of the intended operation.


33039: Unable to allocate a new entry.

Cause:

Internal error.

Solution:

Please contact Sun Technical Support.


33040: ADD parameter untagged: error.

Cause:

Configuration error.

Solution:

Check the plug-in configuration parameters in the Directory Server configuration. Make sure that the syntax and values are correct.


33041: ADD result result.

Cause:

An error occurred during an internal search while performing an ADD operation.

Solution:

Ensure that the database is not corrupt and contact Sun Technical Support.


33042: MODIFY result result.

Cause:

An error occurred during an internal search while performing a MOD operation.

Solution:

Ensure that the database is not corrupt and contact Sun Technical Support.


33043: MODRDN bad rdn value=value.

Cause:

Internal error.

Solution:

Please contact Sun Technical Support.


33044: MODRDN result result

Cause:

An error occurred during an internal search while performing a modrdn operation.

Solution:

Ensure that the database is not corrupt and contact Sun Technical Support.


33045: NSUniqueAttr_Init Error: error

Cause:

Configuration error.

Solution:

Check the plug-in configuration parameters in the Directory Server configuration.


33046: Fatal error Initializing plugin. Disabling.

Cause:

A plug-in failed to initialize.

Solution:

Restart the server.


33059: Cannot get plugin identity.

Cause:

Plug-in identity information could not be determined.

Solution:

Restart the server.


33069: Sorry cannot do it but given the chance you just incurred in you may consider playing at the next lottery the number number successively reduced mod [your lottery maximum]

Cause:

Your lucky number came up.

Solution:

Contact Sun Technical Support.


33793: cos_cache_init: cannot create mutexes

Cause:

The server was unable to allocate mutexes for the CoS plug-in. This is probably due to a memory problem.

Solution:

Free up resources on the machine and restart the server.


33794: cos_cache_init: cannot register as service provider

Cause:

The server was unable to register a virtual attribute service provider.

Solution:

Free up resources on the machine and restart the server.


33795: cos_cache_init: PR_CreateThread failed

Cause:

The server was unable to create a CoS thread.

Solution:

Free up resources on the machine and restart the server.


33796: cos_cache_create: failed to cache the schema

Cause:

The server was unable to create the CoS schema cache.

Solution:

Follow these steps.

  1. Free up resources on the machine.

  2. “Touch” a CoS definition to trigger CoS cache building.

  3. Restart the server.


33797: cos_cache_create: failed to index cache

Cause:

The server was unable to index the CoS cache.

Solution:

Follow these steps.

  1. Free up resources on the machine.

  2. “Touch” a CoS definition to trigger CoS cache building.

  3. Restart the server.


33798: COS memory allocation failure: variable

Cause:

The server was unable to allocate memory for the CoS cache.

Solution:

Follow these steps.

  1. Free up resources on the machine.

  2. “Touch” a CoS definition to trigger CoS cache building.

  3. Restart the server.


33799: cos_cache_build_definition_list: failed to find suffixes in the rootDSE.

Cause:

The server was unable to read the suffix list from the rootDSE entry.

Solution:

Restart the server.


33801: COS Definition error error

Cause:

There is an error in the definition of the specified CoS.

Solution:

Check and correct the CoS definition. Note that a definition cannot supply its own specifier. The DN of the CoS template may be incorrect.


33802: cos_cache_add_dn_tmpls: could not cache cos template variable

Cause:

The server was unable to add the specified template to the CoS cache.

Solution:

Follow these steps.

  1. Free up resources on the machine.

  2. “Touch” a CoS definition to trigger CoS cache building.

  3. Restart the server.


33803: cos_cache_query_atr: failed to get entry dn

Cause:

The server was unable to locate the dn of the target entry during a search operation. This error should not occur under normal circumstances.

Solution:

Follow these steps.

  1. Retry the search operation.

  2. Restart the server.


33804: COS failed to get objectclass from entry (entry)

Cause:

The server was unable to locate the objectClass of the target entry during a search or update operation. This error should not occur under normal circumstances.

Solution:

Follow these steps.

  1. Retry the search or update operation.

  2. Restart the server.


33806: cos_start: failed to initialise

Cause:

The server was unable to start the CoS plug-in. This is probably due to a memory problem.

Solution:

Follow these steps.

  1. Check the CoS plug-in configuration in the Directory Server configuration.

  2. Check the CoS definitions and templates.

  3. Check the error log for a more specific error message.

  4. Restart the server.


33807: cos_init: failed to register plugin

Cause:

The server was unable to register the CoS plug-in. This is probably due to a memory problem.

Solution:

Follow these steps.

  1. Check the CoS plug-in configuration in the Directory Server configuration.

  2. Check the error log for a more specific error message.

  3. Restart the server.


33808: COS Definition error (no DN)

Cause:

There is an error in the definition of the specified CoS.

Solution:

Check and correct the CoS definition.


33809: cos_cache_change_notify: failed to get dn of changed entry

Cause:

The server was unable to obtain the dn of the target entry during an update operation. This error should not occur under normal circumstances.

Solution:

Follow these steps.

  1. Retry the update operation.

  2. Restart the server.


34307: Request OID (OID) doesn’t match Who Am I? Extended Op OID

Cause:

Internal error

Solution:

Contact Sun Technical Support.


34817: ACL library initialization failed.

Cause:

The server is unable to initialize the ACL plug-in. This is usually an indication of memory problems.

Solution:

Follow these steps.

  1. Check the ACL plug-in configuration in the Directory Server configuration.

  2. Check the error log for other, more specific error messages.

  3. Restart the server.


34818: ACL failed to allocate locks.

Cause:

The server is unable to allocate mutex or reader/writer locks for the ACL plug-in at initialization time.

Solution:

Follow these steps.

  1. Check the OS configuration and increase the file descriptors limit, if possible.

  2. Check the Directory Server configuration and reduce the resource usage.


34819: ACL malloc fail: error.

Cause:

The server is unable to allocate sufficient aclpb pool memory for the ACL plug-in.

Solution:

Free up resources on the machine and restart the server.


34820: ACL internal error: error.

Cause:

This is an internal error and should not occur under normal circumstances.

Solution:

Perform the following steps:

  1. Attempt the LDAP operation again.

  2. Restart the server.

  3. Copy the errors log file and contact Sun Technical Support.


34822: Unable to initialize the plugin: plugin_name

Cause:

The server is unable to allocate sufficient ACL parameter block pool memory for the ACL plug-in.

Solution:

Free up resources on the machine and restart the server.


34823: Error: ACIs not deleted from entry.

Cause:

The server was unable to remove the specified ACIs from the entry. Refer to the error log for more information.

Solution:

Attempt the modify operation again.


34824: ACL internal init fail: error.

Cause:

Initialization error. The server was unable to register the specified attributes with libaccess. Refer to the error log for more information.

Solution:

Verify the configuration and installation of the ACL plug-in.


34826: ACL error adding aci: aci.

Cause:

There is an error (possibly invalid ACI syntax) in the ACI attribute being updated.

Solution:

Correct the error in the ACI and attempt the ACI update operation again.


34827: ACL parsing error: error.

Cause:

ACL parsing error for a macro ACI. Refer to the log file for the exact cause of the error.

Solution:

Correct the error in the ACI and attempt the ACI update operation again.


34828: ACL parsing error: failed to make filter for string string.

Cause:

ACL parsing error. The server was unable to construct an LDAP filter for the specified string.

Solution:

Correct the error in the ACI and attempt the ACI update operation again.


34829: ACL PARSE ERR(rv=error_code): aci.

Cause:

ACL parsing error. Refer to the log file for the exact cause of the error.

Solution:

Correct the error in the ACI and attempt the ACI update operation again.


34830: Can’t add the rest of the acls for entry: entry after delete.

Cause:

The server failed to update ACIs in the specified entry, when an ACI was deleted.

Solution:

Follow these steps.

  1. Attempt the update operation again.

  2. Restart the server.


34831: ACL failed to allocate locks.

Cause:

The server is unable to allocate mutex or reader/writer locks for the ACL plug-in at operation time.

Solution:

Follow these steps.

  1. Free up resources on the machine.

  2. Attempt the LDAP operation again.

  3. Restart the server.


34832: Operation extension allocation failed.

Cause:

The server is unable to get/create an operation extension structure at operation time.

Solution:

Follow these steps.

  1. Free up resources on the machine.

  2. Attempt the LDAP operation again.

  3. Restart the server.


34834: acl_get_aclpb: Invalid aclpb type

Cause:

An invalid ACL operation extension was found. This is an internal error and should not occur under normal circumstances

Solution:

Follow these steps.

  1. Attempt the LDAP operation again.

  2. Restart the server.

  3. Copy the errors log file and contact Sun Technical Support.


34835: ACLPB parameter parameter value value exceeded allowed value value.

Cause:

This is an internal error and should not occur under normal circumstances.

Solution:

Follow these steps.

  1. Attempt the LDAP operation again.

  2. Restart the server.


34838: ACL parent[ ] exceeded the levels limit max_limit: function.

Cause:

ACL parsing error: the parent keyword has been used with more than ten levels. Check the log file to see the type of ACI in which the keyword was used incorrectly.

Solution:

Correct the error in the ACI and attempt the operation again.


34842: getRightsControl: insufficient access

Cause:

User is not allowed to use the getRights control.

Solution:

Check whether user should be granted access to get effective rights.


34844: getRights control parsing:error parsing control paramters

Cause:

Directory Server found invalid request parameters in the request to get effective rights.

Solution:

Check how the client is using the control. If necessary, contact Sun Technical Support.


34846: ACL INTERNAL REFERENTIAL INTEGRITY ERR: message

Cause:

Not enough memory could be allocated to complete ACL processing.

Solution:

Restart the server.


36865: collation_unlock: PR_ExitMonitor (variable)=variable; collation_monitor = variable

Cause:

An error occurred while releasing the collation lock.

Solution:

Restart the server.


36866: collation_init: PR_NewMonitor failed

Cause:

An error occurred while creating the collation lock.

Solution:

Restart the server.


36867: variable: line line_no: missing directory name in directory directory (ignored)

Cause:

No argument was provided for the NLS parameter.

Solution:

Check the configuration variable.


36868: variable: line line_no ignored: only variable arguments (expected collation language country variant strength decomposition oid...)

Cause:

Insufficient arguments were provided for the collation parameter.

Solution:

Check the configuration variable.


36869: variable: line line_no: strength value not supported (will use 2)

Cause:

An invalid value was specified for the collation strength.

Solution:

Check the configuration variable.


36870: variable: line line_no: decomposition value not supported (will use 2)

Cause:

An invalid value was specified for the collation decomposition.

Solution:

Check the configuration variable.


36871: Too many tokens (max max_tokens)

Cause:

Too many items have been specified on the configuration line.

Solution:

Check the configuration variable.


36872: Could not open config file filename - absolute path.

Cause:

The server was unable to open the collation configuration file.

Solution:

Check the path to the collation configuration file.


36873: variable: line line_no: bad config line (ignored)

Cause:

The server was unable to parse a line in the collation configuration file.

Solution:

Check the collation configuration file.


36874: Unable to retrieve slapd configuration pathname; using default.

Cause:

The location of the collation configuration file was not provided to the plug-in.

Solution:

Check the path to the collation configuration file.


36875: while reading configuration entry (DN) for Internationalization plugin, error code

Cause:

Directory Server encountered an error while searching for the internationalization plug-in.

Solution:

Fix the Internationalization plug-in configuration entry, then restart Directory Server.


36876: Missing Internationalization plugin configuration entry DN

Cause:

Directory Server encountered an error while searching for the internationalization plug-in.

Solution:

Fix the Internationalization plug-in configuration entry, then restart Directory Server.


36877: Missing “Collation” attribute in Internationalization plugin configuration entry DN

Cause:

Directory Server encountered an error while reading the configuration entry.

Solution:

Fix the Internationalization plug-in configuration entry, then restart Directory Server.


36878: DN: value index: bad collation config data (ignored)

Cause:

Directory Server encountered an error while reading the collation configuration file.

Solution:

Fix the Internationalization plug-in configuration entry, then restart Directory Server.


37121: Not enough pattern space.

Cause:

The regular expression being constructed for the DN substring filter could not be stored in the memory allocated.

Solution:

Check the DN substring filter being provided to the server.


37122: re_comp filter failed.

Cause:

The regular expression being constructed for the substring filter could not be compiled.

Solution:

Check the substring filter being provided to the server.


37123: dn_assertion2keys_ava: unknown ftype.

Cause:

A filter containing an unknown type was provided to the server.

Solution:

Check the filter being provided to the server.


37377: statechange_init: failed to register plugin.

Cause:

The state change plug-in could not be registered with the server.

Solution:

Restart the server.


37378: statechange: failed to create lock.

Cause:

The server was unable to create a mutex for the state change subsystem.

Solution:

Restart the server.


37379: statechange: failed to publish state change interface.

Cause:

The server was unable to publish the interface to the state change plug-in API.

Solution:

Restart the server.


37380: statechange_post_op: failed to get dn of changed entry.

Cause:

The server was unable to determine the DN of the modified entry.

Solution:

Restart the server.


37633: Only one pass through plugin instance can be used

Cause:

An attempt was made to configure multiple instances of the pass through authentication plug-in.

Solution:

Check the pass-through authentication plug-in configuration.


37634: No pass through servers found in configuration (at least one must be listed)

Cause:

An attempt was made to use the pass through authentication plug-in without specifying any remote servers.

Solution:

Check the pass-through authentication plug-in configuration.


37635: Server parameters should be in the form “maxconnections maxconcurrency timeout ldapversion connlifetime” (got “error”)

Cause:

The set of parameters specified for the remote server was invalid.

Solution:

Check the pass-through authentication plug-in configuration.


37636: LDAP protocol version should be version or version (got error)

Cause:

The LDAP version specified for the remote server was invalid.

Solution:

Check the pass-through authentication plug-in configuration.


37637: Maximum connections must be greater than zero (got error)

Cause:

The maximum number of connections to the remote server is specified as less than or equal to zero.

Solution:

Check the pass-through authentication plug-in configuration.


37638: Maximum concurrency must be greater than zero (got error)

Cause:

The maximum concurrency is specified as less than or equal to zero.

Solution:

Check the pass-through authentication plug-in configuration.


37639: Unable to parse LDAP URL “url” (error)

Cause:

An error occurred while parsing the LDAP URL.

Solution:

Check the pass-through authentication plug-in configuration.


37640: Missing suffix in LDAP URL “url”

Cause:

The pass-through suffix was not specified in the LDAP URL.

Solution:

Check the pass-through authentication plug-in configuration.


37641: Unable to parse suffix string “suffix” within variable

Cause:

An error occurred while splitting the list of suffixes for which authentication is to be passed through.

Solution:

Check the pass-through authentication plug-in configuration.


37642: Suffix “suffix” is handled by a database backend and therefore will not be subject to pass through authentication

Cause:

One of the suffixes for which pass-through authentication is configured exists in the local directory.

Solution:

Check the pass-through authentication plug-in configuration.


37644: ldap_charray_add() failed when building suffix list

Cause:

An error occurred while adding a suffix to the list of suffixes handled by backends in the server.

Solution:

Restart the server.


37645: No active suffixes found

Cause:

No active suffixes could be located in the local server.

Solution:

Check the server configuration and/or restart the server.


37646: passthruauth_init failed

Cause:

The pass-through authentication plug-in could not be registered.

Solution:

Restart the server.


37647: Unable to get arguments

Cause:

The server was unable to locate the list of arguments to the pass-through authentication plug-in.

Solution:

Check the pass-through authentication plug-in configuration.


37648: configuration failed (variable)

Cause:

The pass-through authentication plug-in could not be configured based on the arguments provided.

Solution:

Check the pass-through authentication plug-in configuration.


37649: Operation not handled (unable to retrieve bind parameters)

Cause:

The server was unable to determine the required information regarding the bind operation.

Solution:

Check the bind request.


37650: error

Cause:

The server was unable to retrieve the set of controls associated with the bind request.

Solution:

Check the bind request.


37651: error

Cause:

The server was unable to set the DN or authentication type associated with this connection.

Solution:

Restart the server.


37889: referint_postop_init failed

Cause:

A failure occurred while registering the referential integrity plug-in.

Solution:

Restart the server.


37890: referint_postop_del: could not get parameters

Cause:

The server was unable to retrieve the required information about a delete operation.

Solution:

Check the delete request.


37891: referint_postop failed to get argc

Cause:

The server was unable to determine the number of parameters to the referential integrity plug-in.

Solution:

Restart the server.


37892: referint_postop failed to get argv

Cause:

The server was unable to retrieve the parameters associated with the referential integrity plug-in.

Solution:

Restart the server.


37893: referint_postop_del args are NULL

Cause:

No arguments were provided for the referential integrity plug-in.

Solution:

Check the configuration of the referential integrity plug-in.


37894: referint_postop insufficient arguments supplied

Cause:

Insufficient arguments were provided for the referential integrity plug-in.

Solution:

Check the configuration of the referential integrity plug-in.


37895: referint_postop_modrdn: could not get parameters

Cause:

The server was unable to retrieve the required information about a modrdn operation.

Solution:

Check the delete request.


37896: referint_postop failed to get argc

Cause:

The server was unable to determine the number of parameters to the referential integrity plug-in.

Solution:

Restart the server.


37897: referint_postop failed to get argv

Cause:

The server was unable to retrieve the parameters associated with the referential integrity plug-in.

Solution:

Restart the server.


37898: referint_postop_modrdn args are NULL

Cause:

No arguments were provided for the referential integrity plug-in.

Solution:

Check the configuration of the referential integrity plug-in.


37899: referint_postop_modrdn insufficient arguments supplied

Cause:

Insufficient arguments were provided for the referential integrity plug-in.

Solution:

Check the configuration of the referential integrity plug-in.


37900: update_integrity required config file arguments missing

Cause:

No arguments were provided for the referential integrity plug-in.

Solution:

Check the configuration of the referential integrity plug-in.


37901: referint_postop search (base=base filter=filter) returned error error.

Cause:

An error occurred while searching for references to the deleted/renamed entry.

Solution:

Follow these steps.

  1. Check the error log for details of the error.

  2. Restart the server.


37902: referint_postop failed to get argc

Cause:

The server was unable to determine the number of parameters to the referential integrity plug-in.

Solution:

Restart the server.


37903: referint_postop failed to get argv

Cause:

The server was unable to retrieve the parameters associated with the referential integrity plug-in.

Solution:

Restart the server.


37904: args were null in referint_postop_start

Cause:

No arguments were provided for the referential integrity plug-in.

Solution:

Check the configuration of the referential integrity plug-in.


37905: referint_postop_start PR_CreateThread failed.

Cause:

The server was unable to create the thread to perform integrity updates.

Solution:

Restart the server.


37906: referint_postop_start insufficient arguments supplied

Cause:

Insufficient arguments were provided to the referential integrity plug-in to determine the update delay.

Solution:

Check the configuration of the referential integrity plug-in.


37907: referint_thread_func could not get args

Cause:

The server was unable to retrieve the parameters associated with the referential integrity plug-in.

Solution:

Restart the server.


37908: referint_postop_close could not delete filename

Cause:

The referential integrity log file could not be deleted.

Solution:

Check the permissions on the specified file and restart the server.


37909: referint_postop could not open integrity log filename

Cause:

The referential integrity log file could not be opened for writing.

Solution:

Check the permissions on the specified file and restart the server.


37910: referint_postop could not write integrity log: line length exceeded. It will not be able to update references to the entry entry.

Cause:

The change to be written to the integrity log file was longer than the maximum length allowed.

Solution:

Check for references to the specified entry and update manually if necessary.


37911: writeintegritylog: PR_Write failed : The disk may be full or the file is unwritable :: NSPR error - error.

Cause:

The server was unable to write data to the integrity log file.

Solution:

Follow these steps.

  1. Check the integrity log file.

  2. Check the filesystem status.


37912: writeintegritylog: failed to close the file descriptor prfd; NSPR error - error.

Cause:

An error occurred while closing the integrity log file.

Solution:

Follow these steps.

  1. Check the integrity log file.

  2. Check the filesystem status.


38402: Invalid mapping: DN

Cause:

The ID mapping configuration is invalid.

Solution:

Check on the entry specified by DN in the error message that:

  • dsSearchFilter and dsSearchBaseDN are not NULL

  • dsSearchScope is either sub, base or onelevel

  • dsMatching_regexp conforms to regular expression syntax

  • dsMatching_pattern and dsMatching_regexp are either both are NULL or both not NULL


38403: attribute syntax error: value in mapping entry: DN

Cause:

The ID mapping configuration is invalid as specified.

Solution:

Fix the syntax error in the value of the attribute specified, keeping in mind the following issues.

If you refer to an input variable, use the syntax ${...}

If you refer to a sub-expression use $i where i is in [1..N]

The characters $, {, and } are reserved. Use their hexadecimal forms when using them as values.


38404: Identity Mapping configuration is missing

Cause:

Directory Server could not find any ID mapping configuration entries.

Solution:

Update the identity mapping configuration by doing the following.

  • Adding protocol entries under cn=identity mapping, cn=config

  • Adding identity mapping entries under protocol entries with DNs cn=protocol,cn=identity mapping, cn=config


38405: Authentication protocol name missing

Cause:

Directory Server could not find the ID mapping protocol.

Solution:

Update the CN attribute of the identity mapping entry.


38407: There are no identity mapping entries for authentication protocol: protocol

Cause:

Directory Server could not find any entries corresponding to the specified ID mapping protocol.

Solution:

Add an ID mapping entry under at least one protocol entry, where the ID mapping DN is cn=protocol,cn=identity mapping, cn=config


38408: There are no valid identity mapping entries for authentication protocol: protocol

Cause:

Directory Server could not find any valid entries corresponding to the specified ID mapping protocol.

Solution:

Check the syntax of the ID mapping entries for the protocol.


38409: There are no identity mapping configuration for authentication protocol: protocol

Cause:

The ID mapping service does not support the specified authentication protocol.

Solution:

Follow these steps.

  1. Create a protocol entry under cn=identity mapping, cn=config

  2. Create an identity mapping entry under the protocol entries with DNs cn=protocol,cn=identity mapping, cn=config


38410: Can’t add default identity mapping entry for authentication protocol: protocol

Cause:

Internal error

Solution:

Check that sufficient memory is available. If adding memory does not solve the problem, contact Sun Technical Support.


38913: The default SASL configuration entry could not be read or was not found in the dse.ldif file. It is mandatory.

Cause:

The mandatory SASL configuration entry, cn=SASL,cn=security,cn=config, could not be retrieved from the configuration file.

Solution:

Check the existence of this entry in the configuration file and add it if it is not present. The entry contains the dsSaslConfig object class.


38914: Out of memory to create the SASL configuration structure.

Cause:

Memory allocation problem.

Solution:

Increase the amount of memory available.


38915: The SASL mandatory attribute dsSaslPluginsPath is missing in the dse.ldif file. Some SASL authentication mechanisms will not be available

Cause:

A required attribute is missing.

Solution:

Fix the configuration on cn=SASL, cn=security, cn=config, then restart Directory Server.


38916: The SASL mandatory attribute dsSaslPluginsEnable is missing in the dse.ldif file. Some SASL authentication mechanisms will not be available

Cause:

A required attribute is missing.

Solution:

Fix the configuration on cn=SASL, cn=security, cn=config, then restart Directory Server.


38917: Can’t find localhost name.

Cause:

The local host name is absent from the naming service.

Solution:

Add the local host name to the naming service.


38918: SASL initialization failed.

Cause:

Incorrect or missing information in the SASL configuration entry in the Directory Server configuration under cn=sasl.

Solution:

Follow these steps.

  1. Check that the entry exists in the configuration file.

  2. Check that the information in the configuration entry is valid. That is, that the authentication mechanism names are correct.


38919: SASL Layer encoding return error error-code

Cause:

SASL Layer encode method failed.

Solution:

Contact Sun Technical Support.


38920: Write with SASL security enabled failed with error error-code

Cause:

A write operation failed with the SASL security layer enabled. This could be a network issue.

Solution:

Verify that the problem was not due to network conditions or to the behavior of the client application.


38921: SASL Layer decoding return error error-code

Cause:

SASL Layer decode method failed.

Solution:

Contact Sun Technical Support.


38922: Read with SASL security enabled failed with error error-code

Cause:

A read operation failed with the SASL security layer enabled. This could be a network issue.

Solution:

Verify that the problem was not due to network conditions or to the behavior of the client application.


38923: Size of packet read with SASL security enabled (size) is larger than our buffersize (size)

Cause:

The server encountered an encoded packet from a SASL client larger than the maximum buffer size value of dsSaslMaxBufSize.

Solution:

Verify that the SASL client application can negotiate a buffer size no larger than the value of dsSaslMaxBufSize.


49153: Cannot initialize memberOf plugin.

Cause:

Could not register the isMemberOf plug-in with the server.

Solution:

Restart the server.


49154: Unable to allocate memory. Cannot start memberOf plugin.

Cause:

The server could not allocate enough memory for the MemberOf plug-in to generate virtual attributes.

Solution:

Restart the server.


49155: Unable to allocate memory. Cannot start memberOf plugin.

Cause:

The server could not allocate enough memory for the MemberOf plug-in to generate virtual attributes.

Solution:

Restart the server.


49156: Maximum number of nested groups exceeded (max number current number) not retrieving member from entry DN -- probable circular definition.

Cause:

The MemberOf Plugin does not allow more than the specified number of levels of group nesting.

Solution:

Make sure no groups are nested more than the specified number of levels deep.


49157: Unable to preload memberOf attributes for groups!

Cause:

The server could not create a thread needed to build a cache for isMemberOf attribute values.

Solution:

Make more resource available to the server and restart the server.


53516: Cannot initialize Monitoring plugin.

Cause:

The monitoring plug-in parameter block could not be updated.

Solution:

Restart the server.

Common Warning Codes

This section describes the warning codes displayed in the instance-path/logs/errors log and the appropriate action to take should these warnings occur.


4155: Cannot modify password history error error-code on entry DN

Cause:

Cannot modify password history in the entry. An internal modify operation failed.

Solution:

If you cannot determine the cause and resolve the issue using information in the log files, contact Sun Technical Support.


4157: passwordPolicy modify error error-code on entry DN

Cause:

The password modifications could not be applied due to entry modify error. An internal modify operation failed.

Solution:

If you cannot determine the cause and resolve the issue using information in the log files, contact Sun Technical Support.


4193: Plugin 'name' (op-type plug-in-type) signaled an error (error-code)

Cause:

An external or internal post-op plugin signaled an error.

Solution:

If you cannot determine the cause and resolve the issue using information in the log files, contact Sun Technical Support.


4194: Password value from history is being reused by Directory Manager for user DN

Cause:

Directory Manager set the user password to a value that was already in the user password history.

Solution:

Have the user change the password.


4195: Short password value set by Directory Manager for user DN

Cause:

Directory Manager set the user password to a value that is shorter than the minimum length specified in the password policy.

Solution:

Have the user change the password.


4196: Trivial password value set by Directory Manager for user DN

Cause:

The password value for Directory Manager is too easy to guess.

Solution:

Use a stronger Directory Manager password.


4201: Password already hashed. Cannot check quality.

Cause:

The client application provided a hashed password. The server cannot read the hashed password and so does not check the password quality.

Solution:

None.


4202: Trivial password value set

Cause:

The password value used is too easy to guess.

Solution:

Use a stronger user password.


4214: Server is now [frozen|thawed].

Cause:

The server has been successfully placed in frozen mode or has returned from frozen mode.

Solution:

None.


4215: The default password policy object has not been initialized

Cause:

Internal error: No entry was supplied to mpp_init_policy.

Solution:

Contact Sun Technical Support.


4216: The default password policy object has not been initialized.

Cause:

Internal error: No default password policy object available to mpp_get_policy.

Solution:

Contact Sun Technical Support.


4217: (Password Policy: migration-operation) reports LDAP result (error-code) for suffix "dn=DN".

Cause:

Cannot migrate attributes in the password policy entry.

Solution:

If you cannot determine the cause and resolve the issue using information in the log files, contact Sun Technical Support.


4217: ldap-error-msg Entry "dn=DN".

Cause:

Cannot migrate attributes in the password policy entry. Attribute migration or internal modify has failed.

Solution:

If you cannot determine the cause and resolve the issue using information in the log files, contact Sun Technical Support.


4217: ldap-error-msg Rejecting add of entry "dn=DN".

Cause:

Cannot migrate attributes in the password policy entry.

Solution:

If you cannot determine the cause and resolve the issue using information in the log files, contact Sun Technical Support.


4217: ldap-error-msg Rejecting modify of entry "dn=DN".

Cause:

Cannot migrate attributes in the password policy update.

Solution:

If you cannot determine the cause and resolve the issue using information in the log files, contact Sun Technical Support.


4219: ldap-error-msg. Entry "dn=DN". Value ignored; replaced by default.

Cause:

Invalid password policy entry.

Solution:

If you cannot determine the cause and resolve the issue using information in the log files, contact Sun Technical Support.


4219: ldap-error-msg Entry "dn=DN".

Cause:

Invalid password policy entry discovered. Pre-migration validation of password policy entry failed. The server attempts entry migration attempted anyway.

Solution:

If you cannot determine the cause and resolve the issue using information in the log files, contact Sun Technical Support.


4220: While a passwordExpirationTime far in the future implies "never expires" in previous versions of Directory Server, this DSA supports multiple password policies, and this feature feature should be used instead.

Cause:

Password policy state attribute passwordExpirationTime migration would result in an invalid pwdChangedTime value.

Solution:

If the passwordExpirationTime value was set far into the future with the intention of preventing the account from expiring, use a specialized password policy (subentry) for this purpose. Otherwise, change the account password to clean up the passwordExpirationTime value.


4221: Password policy migration: The entry "dn:DN" contains "passwordExpirationTime: time" , which results in a migrated pwdChangedTime value in the future. Setting pwdChangedTime to the current time, which will expire in seconds seconds.

Cause:

Password policy state attribute passwordExpirationTime migration would result in a pwdChangedTime value far in the future.

Solution:

If the passwordExpirationTime value was intended to prevent the account from expiring, use a specialized password policy (subentry) for this purpose. Otherwise, change the account password to clean up the passwordExpirationTime value.


4609: Unable to create file

Cause:

Cannot create the process ID file for the instance.

Solution:

Check the file system to make sure the file can be created under the instance directory.


4611: Couldn't set the ownership to user for directory

Cause:

Cannot own the directory containing the process ID file for the instance.

Solution:

Check the file system to make sure the user has the right to change the ownership of the directory.


4611: Couldn't set the ownership for file

Cause:

Cannot own the process ID file for the instance.

Solution:

Check the file system to make sure user has the right to take ownership of the process ID file.


4748: "Security Initialization: Failed to set SSL cipher preference information: cipher (error error-code - error-message)

Cause:

Security Initialization: Failed to set SSL cipher preference information.

Solution:

Check the syntax of the ciphers in the configuration. Make sure all ciphers are supported by the server.


4752: Security Initialization: Failed to parse cipher family information entry DN because at least one of the attributes nsSSLToken or nsSSLPersonalitySSL are absent.

Cause:

Security Initialization: Failed to parse cipher family information entry.

Solution:

Check the cipher family information entry and fix the configuration.


4753: Security Initialization: Can't find certificate (name) for family family (error error-code - error-message)

Cause:

Security Initialization: Cannot find the certificate for the specified family.

Solution:

Make sure the certificate exists within the certificate database. If not, use the correct certificate name in the configuration, or else import the certificate into the database and try again.


4754: Security Initialization: Unable to retrieve private key for cert name of family family (error error-code - error-message)

Cause:

Security Initialization: Unable to retrieve private key from cert of family.

Solution:

Make sure the certificate has been imported into the database with both its public and private keys. This is usually done as a result of a whole process begining with your certificate request.


4755: ConfigSecureServer: Server key/certificate is bad for cert name of family family (error error-code - error-message)

Cause:

ConfigSecureServer: Server key/certificate is bad for cert of family.

Solution:

Check the validity of the server key/certificate and retry.


4762: Security Initialization: Cannot get SSL Client Authentication status. No nsslclientauth in DN (error error-code - error-message).

Cause:

Security Initialization: Cannot get SSL Client Authentication property from the configuration. nsslclientauth attribute missing.

Solution:

Add nsslclientauth attribute to the configuration if you want something other than the default value.


4763: Security Initialization: Cannot set SSL Client Authentication status to "status" error (error-message). Supported values are "off" "allowed" and "required". (error error-code - error-message).

Cause:

Security Initialization: Cannot set SSL Client Authentication property. Probable invalid value of nssslclientauth attribute.

Solution:

Make sure nssslclientauth takes valid value.


4764: SSL_OptionSet(SSL_REQUIRE_CERTIFICATE PR_FALSE) return-code error error-code (error-message)

Cause:

Failed to set the Client Authentication Allowed property.

Solution:

If you cannot determine the cause and resolve the issue using information in the log files, contact Sun Technical Support.


4765: SSL_OptionSet(SSL_REQUEST_CERTIFICATE PR_TRUE) return-code error error-code (error-message)

Cause:

Failed to set the Client Authentication Required property.

Solution:

If you cannot determine the cause and resolve the issue using information in the log files, contact Sun Technical Support.


4767: Security Initialization: Cannot get SSL Server Authentication status. No nsslserverauth in DN (error error-code - error-message).

Cause:

Security Initialization: Cannot get SSL Server Authentication status. nsslserverauth not found.

Solution:

Add nsslserverauth attribute to the configuration if you want something other than the default value.


4768: Security Initialization: Cannot set SSL Server Authentication status to "value" error (error-message). Supported values are "weak" "cert" and "cncheck". (error error-code - error-message).

Cause:

Security Initialization: Cannot set SSL Server Authentication status. Probable invalid value of nssslserverauth attribute.

Solution:

Make sure nssslserverauth has a valid value.


4770: Security Initialization: Failed to get cipher family information. Missing nsssltoken or nssslpersonalityssl in DN (error error-code - error-message).

Cause:

Security Initialization: Failed to get cipher family information. Missing nsssltoken or nssslpersonalityssl attribute.

Solution:

Update your configuration information and try again.


4771: Security Initialization: Failed to get cipher family information. Missing nsssltoken or nssslpersonalityssl in DN (error error-code - error-message).

Cause:

Security Initialization: Failed to get cipher family information. Missing nsssltoken or nssslpersonalityssl attribute.

Solution:

Update your configuration information and try again.


4993: Can't find task entry 'DN'

Cause:

The entry related to that task is not found in the directory.

Solution:

Make sure that an entry exists for that task and try again.


5022: Can't modify task entry 'DN'

Cause:

An error occurred when modifying the entry related to that task in order to update the task status.

Solution:

Check the task entry and try again.


5032: Entire cn=tasks tree not found.

Cause:

An error occurred when modifying the entry related to that task in order to update the task status.

Solution:

Check the task entry and try again.


5033: Entries in cn=tasks tree not found.

Cause:

An error occurred when modifying the entry related to that task in order to update the task status.

Solution:

Check the task entry and try again.


5125: funtion-name: ignoring multiple values for attribute in entry DN

Cause:

Resource limit. Multiple values found when setting new limit.

Solution:

Check that the entry used to set the limit contains only one value.


5902: Removed option "option" from allowed attribute type "attribute" in object class "object-class"

Cause:

The specified schema definition has a problem.

Solution:

Fix the schema definition.


5903: Removed option "option" from required attribute type "attribute" in object class "object-class"

Cause:

The specified schema definition has a problem.

Solution:

Fix the schema definition.


5904: X-ORIGIN contains no value (schema-definition)

Cause:

The specified schema definition has a problem.

Solution:

Fix the schema definition.


5905: X-DS-USE contains no value (schema-definition)

Cause:

The specified schema definition has a problem.

Solution:

Fix the schema definition.


8193: ruv_to_values: NULL argument

Cause:

It is likely that either the replication configuration is broken or the consumer is not initialized.

Solution:

Verify the replica object and the replication agreement.


10242: Value value invalid (Range is 1..65535).

Cause:

The replication window size is incorrect.

Solution:

Fix the configuration.


10243: Value value invalid (Range is 1..255)

Cause:

The replication group size is incorrect.

Solution:

Fix the configuration.


10244: Value value invalid (Range is 1..255)

Cause:

The replication compression level is incorrect.

Solution:

Fix the configuration.


10245: Deletion of the name attribute is not allowed

Cause:

The specified attribute cannot be deleted.

Solution:

None.


10246: Event event should not occur in state state; going to sleep

Cause:

The replica is waiting for a replication protocol window to open.

Solution:

None.


10246: Event event should not occur in state state

Cause:

The replica is waiting for a replication protocol window to open.

Solution:

None.


10247: Unable to replicate schema to host host port number. Closing this replication session.

Cause:

Replication is proceeding normally. A timeout temporarily prevented replication from continuing.

Solution:

None.


10250: Warning number during acquire for [replica]

Cause:

The consumer was busy when this supplier tried to perform replication.

Solution:

None.


10251: Failed to release the current replication session [host:port]

Cause:

The supplier could not release locked consumer replica IDs at this time.

Solution:

None.


10252: Failed to end the current replication session [host:port]

Cause:

The supplier failed to end a replication session at this time.

Solution:

None.


10252: Failed to end the current replication session (nothing to acquired) [host:port]

Cause:

Replication is proceeding normally.

Solution:

None.


10252: Failed to end the current replication session (no lock acquired) [host:port]

Cause:

The supplier could not lock consumer replica IDs at this time.

Solution:

None.


10258: Invalid parameter passed to cl5CreateReplayIterator while servicing replication agreement "DN"

Cause:

An internal error occurred.

Solution:

Initialize the replica again.


10258: Unexpected format encountered in changelog database while servicing replication agreement "DN"

Cause:

An internal error occurred.

Solution:

Initialize the replica again.


10258: Changelog database is in an incorrect state while servicing replication agreement "DN" (cl5CreateReplayIterator)

Cause:

An internal error occurred.

Solution:

Initialize the replica again.


10258: Incorrect dbversion found in changelog database while servicing replication agreement "DN"

Cause:

An internal error occurred.

Solution:

Initialize the replica again.


10258: A database error is encountered while servicing replication agreement "DN"

Cause:

An internal error occurred.

Solution:

Initialize the replica again.


10258: Internal error (error-code) while servicing replication agreement "DN"

Cause:

An internal error occurred.

Solution:

Initialize the replica again.


10261: Deletion of the name attribute is not allowed

Cause:

The specified attribute cannot be deleted.

Solution:

None.


10263: overwrite referral flag is set for replica "replica" but no referral is configured. Using default computed referrals

Cause:

The nsDS5Flags is set to overwrite default referrals but no referral was configured.

Solution:

Check the configuration.


10264: This server will be referring client updates for replica name during the following seconds s

Cause:

This supplier was recently initialized for this replica. As a preventive measure, it refers client updates to make sure that it is updated by all other masters in the topology with any missing changes before starting to accept updates.

Solution:

No action needed. The server starts accepting client updates after the Referral Period specified in the warning message is elapsed. If you want your server to receive client updates from now on instead of waiting for the Referral Period to expire, set the ds5BeginReplicaAcceptUpdates attribute inside the cn=replica entry for this replica to the value start. Before making the change, verify that the server is up to date in terms of replication and that it has not missed any change previously originated in this server before it was initialized.


10265: This server will be referring client updates for replica name indefinitely

Cause:

This supplier was recently initialized for this replica. As a preventive mesure, it refers client updates to make sure that it is updated by all other masters on the topology with any missing changes before starting to accept updates.

Solution:

The server will not start accepting client updates until you add or replace the ds5BeginReplicaAcceptUpdates attribute inside the cn=replica entry for this replica with the value start. Before making the change, verify that the server is up to date in terms of replication and that it has not missed any change previously originated in this server before it was initialized.


10266: replica_write_ruv: failed to update RUV tombstone for replica (name LDAP error - error-code

Cause:

Problem writing an attribute value inside the replica update vector storage entry.

Solution:

If the problem persists, restart Directory Server.


10267: search_in_ruv_storage_entry: replica ruv tombstone entry for replica name not found

Cause:

Problem reading the RUV storage entry stored inside the suffix DB.

Solution:

If the replica is still participating in replication, initialize it again.


10268: The agreement DN was disabled the consumer has no more data

Cause:

A consumer initialization was ongoing while the replication agreement got aborted.

Solution:

restart the total update after enabling the replication agreement.


10273: Changelog was already opened

Cause:

The server tried to open the changelog though it was already open.

Solution:

None.


10274: Failed to parse ldif line

Cause:

The server could not read an LDIF entry.

Solution:

See the errors log for more information.


10278: Value value invalid (Range is 1..65535)

Cause:

The replication group packet size is incorrect.

Solution:

Fix the configuration.


10279: Value value invalid (Range is 0..3)

Cause:

The replication concurrency level is incorrect.

Solution:

Fix the configuration.


10280: An entry has been converted into a glue entry with DN DN

Cause:

An entry has been converted as part of multimaster replication conflict resolution.

Solution:

None.


10281: A tombstone entry has been resurrected as a glue entry with DN DN

Cause:

An entry has been resurrected as part of multimaster replication conflict resolution.

Solution:

None.


10282: [C] Invalid state of replication connection extension : Not started

Cause:

The server noticed it tried to initiate a replication session without starting it.

Solution:

None.


10282: [C] Invalid state of replication connection extension : Suspended

Cause:

The server noticed it tried to initiate a replication session that was suspended.

Solution:

None.


10283: [C] Session detected to be busy (state state number threads used number operations)

Cause:

The server noticed the replication session was busy.

Solution:

None.


10284: [C] Unable to release replica

Cause:

The server was not able to release replica ID locks.

Solution:

None.


10285: Replication already started for agreement "DN"

Cause:

An attempt was made to start replication although replication had already been initialized.

Solution:

None.


10286: Supplier has a new replication version (version) than us (version)

Cause:

The supplier replica uses a more recent (but backward compatible) version of the replication protocol than the consumer.

Solution:

None.


10287: [C] No extension data while cleaning session connection extension

Cause:

The server found no data in the extension when closing the session.

Solution:

None.


10288: csn CSN sequence number number ignoring it

Cause:

The server found a change sequence number that does not affect its replication operation.

Solution:

None.


10289: Removing dependency op=number

Cause:

The server is cleaning up dependencies left over from earlier replication sessions.

Solution:

None.


10306: Incremental update session aborted : Timeout while waiting for change acknowledgement [host:port]

Cause:

Timeout while waiting for change acknowledgement.

Solution:

Check the consumer errors log for more information.


10307: DB ruv could not be recreated

Cause:

The server could not create the replication update vector from the database, and may reinitialize the changelog.

Solution:

None.


10308: Unable to reinitialize changelog file

Cause:

The changelog could not be reinitialized or removed.

Solution:

None.


10309: Fractional Replication configuration for DN can not define both include and exclude attributes. Include attributes are taken into account by default.

Cause:

The fractional replication configuration is broken.

Solution:

Fix the configuration.


10309: Fractional Replication configuration for replica can not define both include and exclude attributes.

Cause:

The fractional replication configuration is broken.

Solution:

Fix the configuration.


12303: SLAPI_DESTROY_CONTENT field obsolete.

Cause:

A plug-in uses the deprecated SLAPI_DESTROY_CONTENT field.

Solution:

Fix the plug-in.


33810: Failed to index classic cos scheme Def(DN) Template(DN) Attr(name) reason(message)

Cause:

Failed to add the indicated classic COS template to a fast lookup hash table for the reason given.

Solution:

Check the indicated COS definition and template for configuration errors. Check the syntax and value of the indicated attribute for errors.


33814: Definition DN and definition DN compete to provide attribute 'name' at priority number

Cause:

CoS processing is resolving competing definitions.

Solution:

None.


33815: Definition DN and definition DN compete to provide attribute 'name' at priority number Templates 'DN' 'DN'

Cause:

CoS processing is resolving competing definitions.

Solution:

None.


34821: Error: This (ACI) ACL will not be considered for evaluation because of syntax errors.

Cause:

Ignoring this access control instruction due to errors.

Solution:

Try again with a correct aci.


34825: ACL internal db error detected: exiting acllist list evaluation at aci ACI

Cause:

ACL detected internal database error.

Solution:

None: server should recover itself and execute operation correctly.


34837: ACL syntax error: operation (message)

Cause:

ACL parsing error: the reason and the string containing the error is logged.

Solution:

Correct the error in the aci and try the aci update operation again.


34839: ACL internal db error detected: exiting userattr (name) evaluation at level number

Cause:

ACL detected internal database error.

Solution:

None: server should recover itself and execute operation correctly.


34840: ACL internal db error detected: exiting group evaluation (acllas_user_is_member_of_group) at group DN

Cause:

ACL detected internal database error.

Solution:

None: server should recover itself and execute operation correctly.


34841: ACL internal db error detected: exiting ACI evaluation

Cause:

ACL detected internal database error.

Solution:

None: server should recover itself and execute operation correctly.


37975: dictionary htable is full last number words not inserted

Cause:

The server could not load the entire dictionary file used by the password check plug-in.

Solution:

None.


37977: Invalid Policy Value. Setting to default

Cause:

The value provided to the password check plug-in to specify the character set requirements is not correct.

Solution:

Provide an acceptable value for pwd-strong-check-require-charset using the dsconf command.


38924: The value of SASL attribute dsSaslMinSSF in dse.ldif is not in the correct range. Default value of 0 will be used instead

Cause:

Value for SASL attribute dsSaslMinSSF is not in the valid range.

Solution:

Configure a value between 0 and 32767.


38925: The value of SASL attribute dsSaslMaxSSF in dse.ldif is not in the correct range. Default value of 32767 will be used instead

Cause:

Value for SASL attribute dsSaslMaxSSF is not in the valid range.

Solution:

Configure a value between 0 and 32767.

Verifying Plug-In Signatures

Plug-ins provided with Directory Server each have a digital signature which may be verified by the server at startup. By default, the server verifies plug-in signatures, but proceeds to load every plug-in regardless of the presence or validity of a signature.

Verifying signatures has the following advantages.

ProcedureTo Force Directory Server to Verify Plug-Ins are Signed

  1. Set the ds-verify-plugin-signature in cn=config to on.

  2. Restart Directory Server.

    The server logs an error message if any plug-in does not have a signature.

ProcedureTo Force Directory Server to Validate Plug-In Signatures

  1. Set the ds-verify-plugin-signature in cn=config to on.

  2. Set the ds-require-valid-plugin-signatures in cn=config to on.

  3. Restart Directory Server.

    The server does not start if any plug-in is not signed or a signature is invalid.

Chapter 15 Directory Server File Reference

This chapter describes the files found after you install Directory Server, and after you create server instances.

The examples shown in this chapter are for Solaris systems. File extensions and path separators may differ for your operating system. This chapter includes the following sections.

If you installed software from native packages, you may also use the packaging commands on your system to list the files installed. For example, after installing from native packages on Solaris systems, you can obtain a full list for a particular package using the pkgchk -v package-name command.

If you installed software from a zip distribution, find lists of installed files in the install-path/dsee6/data/ directory.

Software Layout for Directory Server

This section describes the file layout you find after installing Directory Server from the zip distribution. All files locations are relative to the path where you installed the product. For information on default native package installation locations, see Default Paths and Command Locations.

install-path/ds6/

Directory Server files shared by server instances. This directory houses the following files of interest.

install-path/ds6/bin/dsadm

Directory Server command for local administration. See dsadm(1M).

install-path/ds6/bin/dsconf

Directory Server command for configuration over LDAP. See dsconf(1M).

install-path/ds6/bin/dsmig

Directory Server command for migration to this version of Directory Server. See dsmig(1M).

install-path/ds6/bin/dsrepair

Directory Server command for repairing replicated directory entries, not intended for use without help for qualified support personnel. See dsrepair(1M).

install-path/ds6/bin/entrycmp

Directory Server command for comparing directory entries across replica. See entrycmp(1).

install-path/ds6/bin/fildif

Directory Server command for filtering LDIF content. See fildif(1).

install-path/ds6/bin/insync

Directory Server command for examining replica synchronization. See insync(1).

install-path/ds6/bin/mmldif

Directory Server command for combining LDIF content. See mmldif(1).

install-path/ds6/bin/ns-accountstatus

Directory Server command for examining whether an account is locked. See ns-accountstatus(1M).

install-path/ds6/bin/ns-activate

Directory Server command for activating a locked account. See ns-activate(1M).

install-path/ds6/bin/ns-inactivate

Directory Server command for explicitly locking an account. See ns-inactivate(1M).

install-path/ds6/bin/pwdhash

Directory Server command for displaying the hashed form of a password value. See pwdhash(1).

install-path/ds6/bin/repldisc

Directory Server command for discovering a replication topology. See repldisc(1).

install-path/ds6/bin/schema_push

Directory Server command for pushing schema updates to replicas. See schema_push(1M).

install-path/ds6/etc/

Registration configuration for Directory Server monitoring agents, not intended to be used directly.

install-path/ds6/examples/

Sample Directory Server plug-ins.

install-path/ds6/include/

Directory Server plug-in header files.

install-path/ds6/install/

Directory Server instance installation templates, not intended to be used directly.

install-path/ds6/ldif/Example.ldif

Sample Directory Server LDIF content.

install-path/ds6/ldif/Example-roles.ldif

Sample Directory Server LDIF content with grouping based on roles.

install-path/ds6/lib/

Shared Directory Server libraries, not intended for use directly.

install-path/ds6/plugins/

Directory Server plug-in configuration files, not intended to be used directly.

install-path/ds6/resources/

Directory Server resource files, not intended to be used directly.

install-path/ds6/schema/

Directory Server instance LDAP schema templates, not intended to be used directly.

install-path/dscc6/

Directory Service Control Center agent files shared by multiple Directory Server Enterprise Edition component products. This directory houses the following files of interest.

install-path/dscc6/bin/dsccmon

Command to monitor servers managed through Directory Service Control Center. See dsccmon(1M).

install-path/dscc6/bin/dsccreg

Command to manage the Directory Service Control Center registry. See dsccreg(1M).

install-path/dscc6/bin/dsccsetup

Command to set up Directory Service Control Center. See dsccsetup(1M).

install-path/dscc6/etc/

Directory Service Control Center agent configuration information, not intended to be used directly.

install-path/dscc6/lib/

Shared libraries, not intended to be used directly.

install-path/dsee6/

Files shared by multiple Directory Server Enterprise Edition component products. This directory houses the following files of interest.

install-path/dsee6/bin/certutil

NSS certificate manipulation command used by other tools, not intended to be used directly.

install-path/dsee6/bin/dsee_deploy

Command to install and remove software. See dsee_deploy(1M).

install-path/dsee6/bin/ldif

Command to base64 encode LDIF attribute values. See ldif(1)

install-path/dsee6/cacao_2.0/

Common agent container files shared by Directory Server Enterprise Edition component products, not intended to be used directly.

install-path/dsee6/data/

Lists of installed files used by the dsee_deploy command, not intended to be used directly.

install-path/dsee6/lib/

Libraries shared by Directory Server Enterprise Edition component products, not intended to be used directly.

install-path/dsee6/man/

Directory Server Enterprise Edition online reference manual pages. See also Sun Java System Directory Server Enterprise Edition 6.0 Man Page Reference.

install-path/dsee6/SUNWmfwk/

Monitoring framework files shared by Directory Server Enterprise Edition component products, not intended to be used directly.

install-path/dsee6/private/include/

Directory SDK for C header files used by Directory Server Enterprise Edition component products.

install-path/dsee6/private/lib/

Directory SDK for C shared libraries used by Directory Server Enterprise Edition component products.

install-path/dsrk6/bin/ldapcmp

Directory Server Resource Kit command to compare LDAP entries from two directories. See ldapcmp(1).

install-path/dsrk6/bin/ldapcompare

Directory Server Resource Kit command to perform LDAP compare operations. See ldapcompare(1).

install-path/dsrk6/bin/ldapdelete

Directory Server Resource Kit command to delete directory entries. See ldapdelete(1).

install-path/dsrk6/bin/ldapmodify

Directory Server Resource Kit command to update entries over LDAP. See ldapmodify(1).

install-path/dsrk6/bin/ldappasswd

Directory Server Resource Kit command to change user passwords. See ldappasswd(1).

install-path/dsrk6/bin/ldapsearch

Directory Server Resource Kit command to search a directory. See ldapsearch(1).

install-path/dsrk6/lib/

Libraries used by Directory Server Resource Kit commands, not intended to be used directly.

install-path/etc/

Container for configuration files.

install-path/jre/

Java Runtime Environment, not intended to be used directly.

install-path/var/

Container for runtime files, not intended to be used directly.

Directory Server Instance Default Layout

This section describes the file layout you find after creating a Directory Server instance. The instance-path is the file system path where you created the instance.

This section does not cover the following deprecated scripts, generated for backwards compatibility:

If you do not use the scripts, you can safely remove them.

instance-path/alias/

NSS certificate database directory.

instance-path/alias/certmap.conf

NSS certificate mapping configuration file.

instance-path/bak/

Default data backup directory.

Each directory database backup is held in its own file system directory. The name of the backup directory corresponds to the time and date of the backup.

instance-path/confbak/

Default configuration backup directory provided for you to backup up versions of your configuration.

instance-path/conf_bk/

Default server configuration backup directory.

This directory contains a backup copy of the original Directory Server configuration file, dse.ldif, generated when the server instance was created. This copy can be compared with the current configuration file for troubleshooting.

instance-path/config/

Server configuration directory.

instance-path/config/dse.ldif

Server configuration file, not intended to be edited directly.

instance-path/config/schema/

LDAP schema configuration files. See dirserv(5dssd).

instance-path/db/

Default server database files directory. When a suffix has been created, the following database files are stored in this file system directory.

__db.00x

Files used internally by the database. Do not move, delete, or modify these files.

DBVERSION

File that identifies the version of the database.

guardian

File used to store information about the state of the database, used to determine whether database recovery is required.

log.xxxxxxxxxx

Files used to store the database transaction logs.

suffix

Files that store your directory suffix information. The directory name is derived from the suffix name, such that the database for a suffix identified by DN dc=example,dc=com is stored in a file system directory named example.

For every index defined in the database, the suffix directory contains a file with a name of the form suffix_indexedAttr.db3, such that an index of CNs for dc=example,dc=com has file name example_cn.db3.

Suffix directories also contain a file named suffix_id2entry.db3. The suffix_id2entry.db3 file contains the directory database entries.

If necessary, all index files can be rebuild from the suffix_id2entry.db3 file. To recreate the index files, reindex the suffix.

instance-path/locks/

Lock files directory.

Lock files stored here in subdirectories exports/, imports/, and server/ prevent simultaneous operations from conflicting with each other. The lock mechanisms allow one server instance to run at a time. The lock mechanisms also permit only one dsadm import (offline import) operation at a time. As a result, no export or server instance operations can be run during import.

The lock restriction does not however apply to dsconf import (online import) operations. Multiple online imports can run at the same time.

instance-path/logs/

Default server logs directory. The following files are stored here.

access logs

This file records information about client access to Directory Server. For detail about access logs, see Access Logs.

audit logs

This file records information about modifications to Directory Server data. For detail about audit logs, see Audit Logs.

core files

By default, server core files are dumped here during a crash.

errors logs

This file records errors, warnings, and informational messages logged during Directory Server operation. For detail about errors logs, see Error Logs. See also Chapter 14, Directory Server Error Log Message Reference.

pid file

This file holds the process identifier of the running server.

slapd.stats file

This memory mapped-file cannot be read in an editor. The slapd.stats file contains data collected for SNMP, which is communicated to the agent responsible for handling SNMP requests.

instance-path/plugins/signatures/

Plug-in signatures directory, not intended to be used directly.

instance-path/tmp/

Server runtime files directory, not intended to be used directly.