Previous      Contents      Index      Next
Sun Java(TM) System Directory Server 5.2 2005Q1 Administration Guide

Chapter 2
Managing Directory Entries

This chapter discusses how to use Directory Server Console and the command-line utilities to manage the contents of your directory. It also describes how attributes can be stored with the attribute encryption feature, and how to access your directory using DSML. When planning a directory deployment, you should characterize the types of data that the directory will contain. Read the relevant chapters in the Directory Server Deployment Planning Guide before creating entries and modifying the default schema.

This chapter assumes some knowledge of LDAP schema and the object classes and attributes it defines. For an introduction to the schema and the definition of all object classes and attributes provided in Directory Server, refer to the Directory Server Administration Reference. In addition, you cannot modify your directory unless the appropriate access control instructions (ACIs) have been defined. For further information, see Chapter 6, "Managing Access Control".

This chapter contains the following sections:

Configuration Entries
Managing Entries Using the Console
Managing Entries From the Command Line
Renaming and Moving Entries
Setting Referrals
Encrypting Attribute Values
Maintaining Referential Integrity
Searching the Directory
Searching an Internationalized Directory
Accessing the Directory Using DSMLv2

---

Configuration Entries

Directory Server stores all of its configuration information in the following file:

ServerRoot/slapd-serverID/config/dse.ldif

This file is in the LDAP Data Interchange Format (LDIF). LDIF is a textual representation of entries, attributes, and their values, and is a standard format described in RFC2849 (http://www.ietf.org/rfc/rfc2849.) The Directory Server configuration in the dse.ldif file consists of:

The attributes and values of the cn=config entry.
All of the entries in the subtree below cn=config and their attributes and values. Often, the presence of an entry or attribute is significant.
The object classes and access control instructions (ACIs) of the root entry ("") and cn=monitor entry. The other attributes of these entries are generated by the server.

Directory Server makes all configuration settings readable and writable through LDAP. By default, the cn=config branch of the directory is accessible only to the directory administrators defined in the Administration Server and to the directory manager. These administrative users can view and modify the configuration entries just like any other directory entry.

You should avoid creating entries under the cn=config entry because they will be stored in the dse.ldif file, which is not the same highly scalable database as regular entries. As a result, if many entries, and particularly entries that are likely to be updated frequently, are stored under cn=config, performance will probably suffer. However, it can be useful to store special user entries such as the Replication Manager (supplier bind DN) entry under cn=config, in order to centralize configuration information.

Modifying the Configuration Using the Console

The recommended method for modifying the configuration is to use the top-level Configuration tab of Directory Server Console. The panels and dialogs of this tab provide task-based controls to help you set up your configuration quickly and efficiently. In addition, the console interface manages the complexity and interdependence of the configuration for you.

The console interface to the configuration is described in the procedures of this document that are titled "...Using the Console." These procedures explain how to use the panels and dialogs of the Configuration tab to achieve the specific management task. The interface itself makes it clear how to save your configuration and when you need to restart the server for your changes to take effect.

Modifying the Configuration From the Command Line

Because the cn=config subtree is accessible through LDAP, the ldapsearch, ldapmodify and ldapdelete commands can be used to view and modify the server configuration. The cn=config entries and all entries below it may be modified using the procedures and LDIF format described in Managing Entries From the Command Line.

However, you must know the meaning of these entries, the purpose of their attributes and the values which are allowed. These important considerations are explained in the procedures of this document that are titled "...From the Command Line." These procedures will show you an example of the configuration entries and attributes that you may set. For the complete description of all configuration entries and attributes, including the range of allowed values, see the Directory Server Administration Reference.

Modifying the configuration from the command line is thus not as straightforward as using the console. However, a few rare configuration settings are not available through the console, and only the command-line procedure will be given. You may also use the command-line procedures to automate your configuration tasks by writing scripts that use the command-line tools.

Modifying the dse.ldif File

The dse.ldif file contains the configuration that the server will read and use when it is started or restarted. The LDIF contents of this file are the cn=config entry and its subtree. The file is readable and writable only by the system user defined during installation.

Modifying the configuration by editing the contents of this file directly is more prone to error and is therefore not recommended. You should be aware of the following behavior:

The dse.ldif file is read only once at startup. Thereafter, the server configuration is based on the in-memory LDAP image of the configuration entries. Modifications to the file while the server is running will be erased.
Modifying the configuration using the console or from the command line changes the LDAP image of the configuration. Some directory features read the current configuration when invoked and do not require restarting the server.
The server will write the dse.ldif file whenever the LDAP image of the configuration is changed. Some directory features only read their configuration when the server starts, and writing the file ensures the change will be present.

The existing dse.ldif file will be copied to dse.ldif.bak, and the existing dse.ldif.bak will be overwritten. Therefore, any manual changes to the dse.ldif file will be lost if the configuration is changed through LDAP before the server is restarted.

After every successful startup of the directory, the dse.ldif file is copied to dse.ldif.startOK in the same location. If your server cannot start because of a faulty configuration change, you will need to restore the dse.ldif from this file.

---

Managing Entries Using the Console

You can use the Directory tab and the entry editor dialogs on Directory Server Console to add, modify, or delete entries individually. If you want to operate on several entries simultaneously, see Bulk Operations Using the Console.

For information on starting Directory Server Console and navigating the user interface, refer to Using Directory Server Console.

Creating Directory Entries

Directory Server Console offers several custom templates for creating directory entries. Each template is a custom editor for a specific type of object class. Table 2-1 shows the object class that is used for each custom editor.

Table 2-1 Entry Templates and Corresponding Object Classes 

Template	Object Classes
User	inetOrgPerson (for creation and editing) organizationalPerson (for editing) person (for editing)
Group	groupOfUniqueNames and possibly others for dynamic groups and certificate groups
Organizational Unit	organizationalUnit
Role	nsRoleDefinition, and others depending on choice of managed, filtered or nested role
Class of Service	cosSuperDefinition, and others depending on type of class of service
Password Policy	passwordPolicy
Referral	referral

These custom editors contain fields representing all the mandatory attributes, and some of the commonly used optional attributes of their respective object class. To create an entry using one of these templates, follow the instructions in Creating an Entry Using a Custom Editor. To create any other type of entry, refer to Creating Other Types of Entries.

Creating an Entry Using a Custom Editor

On the top-level Directory tab of Directory Server Console, expand the directory tree to display the entry that you wish to be the parent of the new entry.
Right-click the parent entry, select the New menu item, and then select the type of entry from the submenu: User, Group, Organizational Unit, Role, Class of Service, Password Policy, or Referral. Alternatively, you may left-click the parent entry to select it and then choose the type of entry from the Object>New menu. The custom editor dialog for the entry type you selected is displayed.

The custom editor has a list of tabs in the left-hand column and the fields of each tab is displayed on the right. By default, all custom editors open with the topmost User or General tab selected, which contains the fields to name and describe the new entry.

For example, the following figure shows the custom editor for user entries:

Figure 2-1 Directory Server Console - Custom Editor for User Entries



Enter values in the fields of the custom editor for the attributes you wish to provide. You must enter a value for all of the mandatory attributes that are identified by an asterisk (*) beside the field name. You may leave any of the other fields blank. In fields that allow multiple values, you my type Return to separate the values.

Click the Help button for further assistance with specific fields in the custom editor for your entry type. For an explanation of the Languages tab of the User and Organizational Unit editors, see Setting Attributes for Language Support.

For further instructions on creating groups, roles, and class of service entries, see Chapter 5, "Managing Identity and Roles." For instructions on creating password policies, see Chapter 7, "Managing User Accounts and Passwords." For instructions on creating referrals, see Setting Referrals.

Click OK to create your new entry and close the custom editor dialog. The new entry appears in the directory tree.
Custom editor dialogs do not provide fields for all optional attributes of their respective object classes. If you wish to add optional attributes that are not displayed in the custom editor, follow the instructions in Modifying Entries With the Generic Editor.

Creating Other Types of Entries

Follow these steps to create an entry of any object class other than those listed in Table 2-1. You may also use this procedure to create an entry of any custom object classes you may have defined in the directory schema:

On the top-level Directory tab of Directory Server Console, expand the directory tree to display the entry that you wish to be the parent of the new entry.
Right-click the parent entry and select the New>Other item from the submenu. Alternatively, you may left-click the parent entry to select it and then select the Object>New>Other menu item.

The New Object dialog will be displayed.

In the object class list of the New Object dialog, select an object class that defines your new entry, then click OK.

If you selected an object class listed in Table 2-1, the corresponding custom editor will be displayed (see Creating an Entry Using a Custom Editor). In all other cases, the generic editor is displayed.

When creating a new entry, the generic editor contains a field for each required attribute of the object class you selected. You must enter a value for all the required attributes. Some fields have a generic placeholder value such as New, which you should replace with a meaningful value for your entry.
To define other attributes that are allowed on the chosen object class, you must add them explicitly. To provide values for optional attributes:
Click the Add Attribute button to display a list of allowed attributes.
Select one or more attributes from the Add Attribute dialog and click OK.
Enter values beside the new attribute name in the generic editor.

For further details about other controls in this dialog, see Modifying Entries With the Generic Editor.

By default, one of the required attributes is selected as the naming attribute and appears in the entry DN displayed in the generic editor. To change the naming attribute:
Click the Change button to display the Change Naming Attribute dialog.
In the table of attributes, select the checkbox beside one or more attributes you wish to use in the DN of your new entry.
Click OK in the Change Naming Attribute dialog. The DN in the generic editor shows the new DN using the selected naming attributes.
Click OK in the generic editor to save the new entry.

The new entry is displayed as a child of the parent entry in the directory tree.

Modifying Entries With a Custom Editor

For object classes listed in Table 2-1, you have the option of editing the entry with either the corresponding custom editor or the generic editor. When using a custom editor, the most common fields are easily accessible, and the interface helps you define values for complex attributes such as those in a role or class of service definition.

The generic editor allows more advanced operations on an entry, such as adding object classes, adding allowed attributes, and handling multivalued attributes. To edit an entry with the generic editor, see Modifying Entries With the Generic Editor.

Note	The custom editors can be used to edit only the object classes listed in Table 2-1. Entries that contain other structural object classes, for example a custom class that inherits from inetorgperson, can only be edited through the generic editor. Entries that contain auxiliary object classes in addition to one of the listed object classes can be managed with the custom editor. However, none of the attributes defined by the auxiliary class will be visible in the custom editor. For a definition of an auxiliary object class, see the Directory Server Administration Reference.

Invoking the Custom Editor

To edit an entry whose object class is listed in Table 2-1:

On the top-level Directory tab of Directory Server Console, expand the directory tree to display the entry that you wish edit.
Double-click on the entry. Several alternate actions also invoke the custom editor of an entry:
Right-click the entry and select the "Edit With Custom Editor" item.
Left-click the entry to select it, then select the Object>Edit With Custom Editor menu item.
Left-click the entry to select it, then use the keyboard shortcut Control-P.

The custom editor for the object class of your entry will be displayed. For example, the custom editor for User entries is shown in Figure 2-1.

By default, all custom editors open with the topmost User or General tab selected, which contains the fields to name and describe the new entry. Edit or remove values in the fields of the custom editor for the attributes you wish to modify. You may modify but not remove the value of mandatory attributes that are identified by an asterisk (*) beside the field name. You may leave any of the other fields blank. In fields that allow multiple values, you my type Return to separate the values.

Select the other tabs in the left-hand column to modify the values on the corresponding panel. Click the Help button for further assistance with specific fields in the custom editor for your entry type.

For an explanation of the Languages tab of the User and Organizational Unit editors, see Setting Attributes for Language Support. The fields of the Account tab of user and group entries are described in Chapter 7, "Managing User Accounts and Passwords." The NT User and Posix User tabs are provided for Directory Server Synchronization Services, please see your Sun representative for details.

For further instructions on modifying groups, roles and class of service entries, see Chapter 5, "Managing Identity and Roles." For instructions on modifying password policies, see Chapter 7, "Managing User Accounts and Passwords." For instructions on modifying referrals, see Setting Referrals.

Click OK to save your changes to the entry and close the custom editor dialog. If you modified the naming attribute, for example the common name of a user entry, the change will be reflected in the directory tree.

Setting Attributes for Language Support

The custom editors for both user and organizational unit entries provide language support for internationalized directories.

Open the custom editor for your entry as described in Invoking the Custom Editor.
Click on the Languages tab in the left-hand column.
For user entries, you may set a preferred language using the drop-down list.
For both user and organizational unit entries, you may enter localized values in the given fields for any of the languages shown in the list. Select a language and then enter one or more values in that language. The language name appears in bold in the list when localized values are defined.

Certain languages also have pronunciation fields where you may enter phonetical representation of the localized values.

Click OK to save your changes to the entry and close the custom editor dialog.

Modifying Entries With the Generic Editor

The generic editor enables you to view all readable attributes of an entry and to edit its writable attributes, according to the bind DN used to log into the console. It also enables you add and remove attributes, set multivalued attributes, and manage the object classes of the entry. When adding attributes, you may define subtypes for binary attributes and language support.

Invoking the Generic Editor

To Invoke the Generic Editor for Any Entry in the Directory

On the top-level Directory tab of Directory Server Console, expand the directory tree to display the entry that you wish edit.
Right-click the entry and select the "Edit With Generic Editor" item. Several alternate actions also invoke the generic editor:
Left-click the entry to select it, then select the Object>Edit With Generic Editor menu item.
Double-click on the entry if its object class is not listed in Table 2-1. The generic editor will be used by default for object classes that do not have a custom editor.

The generic editor is displayed, as shown in the following figure.

Figure 2-2 Directory Server Console - Generic Editor



In the generic editor, the entry's attributes are listed alphabetically with a text box containing the value of each one. All attributes, including read-only and operational attributes are shown. The controls on the right allow you to modify the display in the editor and edit the list of attributes.

Optionally, you may modify the display of the generic editor using the controls in the View box:
Select the Show Attribute Names option to view the names of attributes as they are first defined in the schema. The list of attributes will be rearranged so that they are listed alphabetically by name.
Select the Show Attribute Description option to list attributes by their alternate name, if one is defined in the schema. The alternate name is usually a more explicit description of the attribute. The list of attributes will be rearranged so that they are listed alphabetically by description.
Deselect the Show only Attributes with Values checkbox to list all attributes that are explicitly allowed by the schema for the entry's object classes. If the entry includes the extensibleObject object class, all attributes are implicitly allowed, but they are not listed. By default, only the attributes with a defined value are shown.
Select or deselect the Show DN checkbox to toggle the display of the entry's distinguished name beneath the list of attributes.
The Refresh button will access the server to update the values of all attributes according to the current contents of the entry.

Caution	Clicking the Refresh button immediately removes any modifications you have made in the generic editor without saving them.

The controls for setting attribute values, managing object classes and changing the naming attribute of an entry are described in the following sections.

Modifying Attribute Values

To Modify Attribute Values

Open the generic editor as described in Invoking the Generic Editor.
Scroll through the list of attributes and click on the value you wish to modify.

The selected attribute is highlighted and an editing cursor appears in the text field containing the selected value.

Use the mouse and the keyboard to edit the text to the desired value. You may use your system's clipboard to copy, cut, and paste text in this field.

If you cannot edit the contents of the text field, that attribute is read-only, or you do not have write permissions to modify it.

Edit any other values or perform other modifications as desired to this entry, then click OK to save your changes and close the generic editor.

Editing Multi-Valued Attributes

Attributes which are defined to be multi-valued in your directory schema may have more than one value field in the generic editor. See Chapter 9, "Extending the Directory Schema" for more information.

To add a new value to a multi-valued attribute:

Open the generic editor as described in Invoking the Generic Editor.
Scroll through the list of attributes and click on the attribute or one of its values. The selected attribute is highlighted and the Add Value button is activated. If this button is not activated, the selected attribute is not defined to be multi-valued, or it is read-only, or you do not have write permission to modify it.
Click the Add Value button. A new blank text field is displayed beside the attribute name in the list.
Enter a new value for this attribute in the new text field. You may use your system's clipboard to copy, cut, and paste text in this field.
Edit any other values or perform other modifications as desired to this entry, then click OK to save your changes and close the generic editor.

To remove a value of a multi-valued attribute:

Open the generic editor as described in Invoking the Generic Editor.
Scroll through the list of attributes and click on the specific value you wish to remove. The selected attribute is highlighted and the Delete Value button is activated. If this button is not activated, the selected attribute is read-only, or you do not have write permission to modify it.
Click the Delete Value button. The text field containing the selected value is removed.
Edit any other values or perform other modifications as desired to this entry, then click OK to save your changes and close the generic editor.

Adding an Attribute

Before you can add an attribute to an entry, the entry must contain an object class that either requires or allows the attribute. For more information, see Managing Object Classes and Chapter 9, "Extending the Directory Schema."

To add an attribute to an entry:

Open the generic editor as described in Invoking the Generic Editor.
Make sure that the Show only Attributes with Values option is checked.
Click the Add Attribute button to display a dialog with a list of attributes. This list contains only attributes that are allowed by the object classes defined for the entry.
In the Add Attribute dialog, select the one or more attribute you wish to add.
Optionally, you may select either or both of the following subtypes from the drop-down lists at the top of the dialog:
Language subtype - Use this subtype to indicate the language used in the value of the attribute. You may add an attribute multiple times with a different languages to store localization information in your directory.

Optionally, you may select the Pronunciation subtype in addition to a language to indicate that the value of this attribute contains a phonetic equivalent for the value in the given language.

Binary subtype - Assigning the binary subtype to an attribute indicates that the values should be transported over LDAP as binary data (opaque chunks of data) regardless of their actual syntax. This option should be used with caution. It is designed for complex syntaxes that do not have LDAP string representations, such as userCertificate. Do not use the binary subtype with attributes whose values are already considered binary.
Click OK once you have selected an attribute and its optional subtypes. The attribute is added alphabetically to the list in the generic editor.
Enter a new value for this attribute in the empty text field beside the new attribute name. You may use your system's clipboard to copy, cut, and paste text in this field.
Edit any other values or perform other modifications as desired to this entry, then click OK to save your changes and close the generic editor.

Removing an Attribute

To remove an attribute and all of its values from an entry:

Open the generic editor as described in Invoking the Generic Editor.
Scroll through the list of attributes and click on the attribute name you wish to remove. The selected attribute is highlighted and the Delete Attribute button is activated. If this button is not activated, the selected attribute is read-only, or you do not have write permission to modify it.

Note	The generic editor allows you to remove attributes that are required by object classes that may be defined for this attribute. If you try to save the entry without a required attribute, the server will respond with an object class violation. Make sure your entry includes the required attributes for all object classes it defines.

Click the Delete Attribute button. The attribute and all of its text field values are removed.
Edit any other values or perform other modifications as desired to this entry, then click OK to save your changes and close the generic editor.

Managing Object Classes

The object classes of an entry are defined by the multi-valued objectclass attribute. The generic editor provides special dialogs when modifying this attribute to help you manage the defined object classes.

To add an object class to an entry:

Open the generic editor as described in Invoking the Generic Editor.
Scroll through the list of attributes and select the objectclass attribute. The Add Value button is activated. If this button is not activated, you do not have permission to modify this entry's object class.
Click the Add Value button.

The Add Object Class dialog is displayed. It shows a list of object classes that you can add to the entry.

Select one or more object classes that you want to add to this entry and click OK. The object classes you selected will appear in the list of values for the objectclass attribute.
If the new object class has required attributes that did not already exist in your entry, the generic editor will add them automatically. You must provide a value for all of the required attributes.
Edit any other values or perform other modifications as desired to this entry, then click OK to save your changes and close the generic editor.

To remove an object class from an entry:

Open the generic editor as described in Invoking the Generic Editor.
Scroll through the list of attributes and click on the specific value of the objectclass attribute you wish to remove. The Delete Value button is activated if removing the selected object class is allowed by the schema and you have permission to modify this entry's object class.
Click the Delete Value button. The specific object class is removed.

When you remove an object class, the generic editor will automatically remove any attributes that are not allowed or required by the remaining object classes. If one of the naming attributes was removed, another one will be selected automatically, and the console will inform you of this change.

Edit any other values or perform other modifications as desired to this entry, then click OK to save your changes and close the generic editor.

Deleting Directory Entries

To delete entries using Directory Server Console:

On the top-level Directory tab of Directory Server Console, expand the directory tree to display the entry that you wish to remove.

You may also delete entire branches of the directory by selecting the root node of the subtree.

Right-click the entry and select the Delete item. Several alternate actions will also delete the entry:
Left-click the entry to select it, then select the Edit>Delete menu item. You may also use the Edit>Cut menu item if you wish to paste this entry elsewhere in the directory.
Left-click the entry to select it, then use the keyboard shortcut Control-D.

When you have selected the View>Layout option to display children in the right-hand panel of Directory Server Console, you may select multiple entries for deletion using Control+click or Shift+click combinations.

Confirm that you wish to delete the entry or the subtree and all of its contents.

The server deletes the entry or entries immediately. There is no undo. If you deleted more than one entry, the console will display an information dialog with the number of entries deleted and any errors that may have occurred.

Bulk Operations Using the Console

You can use an LDIF file to add multiple entries, to perform a mix of operations or to import an entire suffix. To add entries using an LDIF file and Directory Server Console:

Define the entries or operations in an LDIF file using the syntax shown in the previous sections. If you are only adding entries or initializing a suffix, you do not need changetype keywords, and your LDIF file may contain just entries. If you are performing a mix of operations, every DN should be followed by a changetype and, if applicable, the specific operation or attribute values.
Import the LDIF file from the Directory Server console. See Importing LDIF Files for more information.

If you are performing a mix of operations, be sure to deselect "Add only" on the Import LDIF dialog so that the server will perform all LDIF operations.

---

Managing Entries From the Command Line

The ldapmodify and ldapdelete command-line utilities provide full functionality for adding, editing, and deleting your directory contents. You can use them to manage both the configuration entries of the server and the data in the user entries. The utilities can also be used to write scripts to perform bulk management of one or more directories.

The ldapmodify and ldapdelete commands are used in procedures throughout this book. The following sections describe all basic operations you will need to perform these management procedures. For more information about the ldapmodify and ldapdelete commands, see the Directory Server Man Page Reference.

Input to the command-line utilities is always in LDIF, and can be provided either directly from the command-line or through an input file. The following section provides information about LDIF input, and subsequent sections describe the LDIF for each type of modification.

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 Directory Server Administration Reference.

Consider the following points when you provide LDIF input:

An object is a blank line followed by a line that starts with dn:. This line is the distinguished name of the object. All other lines are the object's attributes.
Comments start with # (and end with the EOL.)
Lines starting with a single space continue the previous line.
Binary values are base-64 encoded, and represented with a double colon (::) after the attribute name.
Carriage returns and line feeds unsafe in LDIF values, and should be base-64 encoded.
Do not unintentionally leave trailing spaces at the end of an attribute value when you change the attribute value by using the ldapmodify command. For more information, see Modifying Attribute Values.

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 always Control-D (^D).

The following example shows how to terminate input to the ldapmodify command:

prompt> ldapmodify -h host -p port -D bindDN -w password
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. For more information, see Schema Checking.

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. See Creating Suffixes From the Command Line, to add a new root suffix or subsuffix and its associated 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. See Managing Groups for more information.

To modify the size limit enforced by the server on data sent by clients:

Set a new value for the nsslapd-maxbersize attribute of the cn=config entry.
To do this using the console, log on as Administrator or Directory Manager, and edit the cn=config entry according to the procedure in Modifying Entries With the Generic Editor. Set the nsslapd-maxbersize attribute to the maximum number of bytes that a client may send at once.
To do this from the command line, use the following command:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=config
changetype: modify
replace: nsslapd-maxbersize
nsslapd-maxbersize: sizeLimitInBytes
^D

For more information, see "nsslapd-maxbersize" in the Directory Server Administration Reference.

Restart the server as described in Starting and Stopping Directory 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:

Not having the appropriate access permission for the operation.
Adding an entry with a DN that already exists in the directory.
Adding an entry below a parent that does not exist.

For more information about error conditions that occur with the and how to avoid ldapmodify and ldapdelete commands, see the Directory Server Man Page Reference.

Adding Entries Using ldapmodify

You can add one or more entries to the directory by using the -a option of ldapmodify. The following example creates an structural entry to contain user and then creates a user entry:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: ou=People,dc=example,dc=com
objectclass: top
objectclass: organizationalUnit
ou: People
description: Container for user entries

dn: uid=bjensen,ou=People,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetorgPerson
uid: bjensen
givenName: Barbara
sn: Jensen
cn: Babs Jensen
telephoneNumber: (408) 555-3922
facsimileTelephoneNumber: (408) 555-4000
mail: bjensen@example.com
userPassword: clearPassword

The -D and -w options give the bind DN and password, respectively, of a user with permissions to create these entries. The -a option indicates that all entries in the LDIF will be added. Then each entry is given by its DN and its attribute values, with a blank line between each entry. The ldapmodify utility will create each entry after it is entered and report any errors.

By convention, the LDIF of an entry lists the attributes in the following order:

The list of object classes.
The naming attribute or attributes. This is the attribute used in the DN, and it is not necessarily one of the required attributes.
The list of required attributes for all object classes.
Any allowed attributes that you wish to include.

When entering a value for the userpassword attribute, give the clear text version of the password. The server will encrypt this value and store only the encrypted value. Be sure to limit read permissions to protect clear passwords that appear in LDIF files.

You may also use an alternate form of the LDIF that does not require the -a option on the command line. The advantage of this form is that you may combine entry addition with entry modification statements shown in the next section.

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: ou=People,dc=example,dc=com
changetype: add
objectclass: top
objectclass: organizationalUnit
ou: People
description: Container for user entries

dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: add
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetorgPerson
uid: bjensen
givenName: Barbara
sn: Jensen
cn: Barbara Jensen
telephoneNumber: (408) 555-3922
facsimileTelephoneNumber: (408) 555-4000
mail: bjensen@example.com
userPassword: clearPassword

The changetype: add keywords indicate that the entry with the given DN should be created with all of the subsequent attributes. All other options and LDIF conventions are the same.

In both examples you may use the -f filename option to read the LDIF from a file instead of from the terminal input. The LDIF file must contain the same format as used for the terminal input, according to the use of the -a option.

Modifying Entries Using ldapmodify

Use changetype: modify keywords to add, replace, or remove attributes and their values in an existing entry. When you specify changetype: modify, you must also provide one or more change operations to indicate how the entry is to be modified. The three possible LDIF change operations are shown in the following example:

dn: entryDN
changetype: modify
add: attribute
attribute: value
...
-
replace: attribute
attribute: newValue
...
-
delete: attribute
[attribute: value]
...

Use a hyphen (-) on a line to separate operations on the same entry and a blank line to separate groups of operations on different entries. You may also give several attribute: value pairs for each operation to add, replace with, or delete all of them together.

Adding an Attribute Value

The following example shows how you may use the same add LDIF syntax to add values to existing multivalued attribute and to attributes which do not exist yet:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
add: cn
cn: Babs Jensen
-
add: mobile
mobile: (408) 555-7844
mobile: (408) 555-7845

This operation may fail and the server will return an error if:

The given value already exists for an attribute.
The value does not follow the syntax defined for the attribute.
The attribute type is not required or allowed by the entry's object classes.
The attribute type is not multivalued and a value already exists for it.

Using the Binary Attribute Subtype

The attribute;binary subtype indicates that attribute values should be transported over LDAP as binary data, regardless of their actual syntax. This subtype is designed for complex syntaxes that do not have LDAP string representations, such as userCertificate. The binary subtype should not be used outside of this purpose.

Appropriate subtypes may be added to attribute names in any of the LDIF statements used with the ldapmodify command.

To enter a binary value, you may enter it directly in the LDIF text or read it from another file. The LDIF syntax for reading it from a file is shown in the following example:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
version: 1
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
add: userCertificate;binary
userCertificate;binary:< file:///path/certFile

In order to use the < syntax to specify a filename, you must begin the LDIF statement with the line version: 1. When ldapmodify processes this statement, it will set the attribute to the value read from the entire contents of the given file.

Adding an Attribute with a Language Subtype

Language and pronunciation subtypes of attributes designate localized values. When you specify a language subtype for an attribute, the subtype is added to the attribute name as follows:

attribute;lang-CC

where attribute is an existing attribute type, and CC is the two-letter country code to designate the language. You may optionally add a pronunciation subtype to a language subtype to designate a phonetic equivalent for the localized value. In this case the attribute name becomes:

attribute;lang-CC;phonetic

To perform an operation on an attribute with a subtype, you must explicitly match its subtype. For example, if you want to modify an attribute value that has the lang-fr language subtype, you must include lang-fr in the modify operation as follows:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
replace: homePostalAddress;lang-fr
homePostalAddress;lang-fr: 34\, avenue des Champs-Elysées

Modifying Attribute Values

The following example shows how to change the value of an attribute by using the replace syntax in LDIF:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
replace: sn
sn: Morris
-
replace: cn
cn: Barbara Morris
cn: Babs Morris

All current values of the specified attributes are removed and all given values are added.

After changing an attribute value, you can use the ldapsearch command to verify the change.

Trailing Spaces

When you modify an attribute value, do not unintentionally include trailing spaces at the end of the value. Trailing spaces may result in the value appearing in base-64 encoding (such as 34xy57eg).

If the attribute value ends with a trailing space, the trailing space is encoded as part of the attribute value. When you verify the change using the console or the ldapsearch command, the value you see may be plain text, but it might also appear as base-64 encoded text. This depends on which Directory Server client you use.

Deleting an Attribute Value

The following example shows how to delete an attribute entirely and delete only one value of a multi-valued attribute:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
delete: facsimileTelephoneNumber
-
delete: cn
cn: Babs Morris

When using the delete syntax without specifying an attribute: value pair, all values of the attribute will be removed. If you specify an attribute: value pair, only that value will be removed.

Modifying One Value of a Multi-Valued Attribute

In order to modify one value of a multi-valued attribute with the ldapmodify command, you must perform two operations as shown in the following example:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
delete: mobile
mobile: (408) 555-7845
-
add: mobile
mobile: (408) 555-5487

Deleting Entries Using ldapdelete

Use the ldapdelete command-line utility to delete entries from the directory. This utility binds to the directory server and deletes one or more entries given by their DN. You must provide a bind DN that has permission to delete the specified entries.

You cannot delete an entry that has children. The LDAP protocol forbids the situation where children entries would no longer have a parent. For example, you cannot delete an organizational unit entry unless you have first deleted all the entries that belong to the organizational unit.

Caution	Do not delete the suffix o=NetscapeRoot. Administration Server uses this suffix to store information about installed Sun Java System servers. Deleting this suffix could force you to reinstall all of your Sun Java System servers, including Directory Server.

In the following example, there is only one entry in the organizational unit, so we can delete it and then the parent entry:

ldapdelete -h host -p port -D "cn=Directory Manager" -w password
uid=bjensen,ou=People,dc=example,dc=com
ou=People,dc=example,dc=com

Deleting Entries Using ldapmodify

You may also use the changetype: delete keywords to delete entries using the ldapmodify utility. All of the same limitations apply as when using ldapdelete described above. The advantage of the LDIF syntax for deleting entries is that you may perform a mix of operation in a single LDIF file.

The following example will perform the same delete operations as the previous example:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: delete

dn: ou=People,dc=example,dc=com
changetype: delete

---

Renaming and Moving Entries

This section introduces the modify DN operation, gives guidelines on using the modify DN operation, and describes how to perform modify DN operations by using the console and the command line.

Introduction to the Modify DN Operation

In versions of Directory Server prior to Directory Server 5.2 2005Q1, it was possible to rename an entry. In Directory Server 5.2 2005Q1 and onwards, it is possible to rename an entry and move an entry.

The modify DN operation cannot be used for the following tasks:

Move an entry from one suffix to another suffix
Rename or move the root suffix

Difference Between Rename and Move Operations

This section describes the difference between renaming an entry and moving an entry.

Renaming an Entry

Renaming an entry changes the left-most (least significant) attribute type=value pair in an entry's DN. This attribute type=value pair is the entry's RDN. The attribute type, the attribute value, or both the attribute type and the attribute value can be renamed. For the rename operation to succeed, the new DN must not exist already.

The following examples show how attribute types and attribute values can be changed.

Example 1: To change the attribute type from cn to uid in the following DN:

dn: cn=john,dc=california,dc=sun,dc=com

becomes

dn: uid=john,dc=california,dc=sun,dc=com

Note that uid must be a valid attribute of the entry.

Example 2: To change the attribute value from john to bob in the following DN:

dn: cn=john,dc=california,dc=sun,dc=com

becomes

dn: cn=bob,dc=california,dc=sun,dc=com

Moving an Entry

Moving an entry changes the right-most (most significant) attribute type=value pair in the entry's DN. This action moves an entry to a different subtree. For the move operation to succeed, the DN corresponding to the new location must exist in the same suffix.

Example 3: To move the entry john from california to france in the following DN:

dn: cn=john,dc=california,dc=sun,dc=com

becomes

dn: cn=john,dc=france,dc=sun,dc=com

Guidelines and Limitations for Using the Modify DN Operation

When you are planning to use the modify DN operation, follow the guidelines given in the following sections:

General Guidelines for Using the Modify DN Operation
Guidelines for Using the Modify DN Operation With Replication

General Guidelines for Using the Modify DN Operation

Comply with the following recommendations when you use the modify DN operation.

Do not use the modify DN operation for the following tasks:
To move an entry from one suffix to another suffix
To rename or move the root suffix
Ensure that you are running Directory Server 5.2 2005Q1 or later. You cannot use the modify DN operation on versions of Directory Server prior to Directory Server 5.2 2005Q1. If you are using a replicated topology, ensure that all servers in the topology are running Directory Server 5.2 2005Q1 or later.
Do not use the entryid operational attribute in your application because it is reserved for internal use only. The entryid attribute of an entry can change when an entry is moved.
Enable the modify DN operation globally for all suffixes on a server, or individually on each suffix where you wish to run the operation. By default the modify DN operation is disabled. If you are running a replicated topology, enable the modify DN operation on all servers in the topology. For information about how to enable the modify DN operation, see Enabling the Modify DN Operation by Using the Console or Enabling the Modify DN Operation by Using the ldapmodify Command.
Extend the ACI rights on each suffix where you wish to run the modify DN operation. The Import access right allows an entry to be imported to the specified DN. The Export access right allows an entry to be exported from the specified DN. For information about how to extend ACI rights, see Enabling the Modify DN Operation by Using the Console or Enabling the Modify DN Operation by Using the ldapmodify Command.
Before performing a modify DN operation, ensure that the operation would not break the client authentication. If you move an entry that refers to a client certificate, you break the client authentication. After moving an entry, validate your certificates.
Before performing a modify DN operation, ensure that the operation would not break your application. The rename or move of an entry can affect several suffixes, or can change the following characteristics of the entry:
The scope of a filtered role of an entry
The nested role of an entry, where the nested role contains a filtered role
The dynamic group membership of an entry

Guidelines for Using the Modify DN Operation With Replication

If you use the modify DN operation with replication, your replication topology must comply with the following requirements:

Caution	Using the modify DN operation without complying with the following requirements can break replication and bring down your directory service.

Ensure that all servers in our replication topology are running Directory Server 5.2 2005Q1 or later. You cannot use the modify DN operation on versions of Directory Server prior to Directory Server 5.2 2005Q1.
Enable the modify DN operation on all servers in your replication topology. If the modify DN operation is supported on the master server but not on the consumer server, replication will fail. A message similar to the following will be written to the error log on the supplier server:

Unable to start a replication session with MODDN enabled

To restart replication, perform the following steps:

1. Reconfigure the replication topology to enable the modify DN operation on all servers.

2. Start a replication session in one of the following ways:

By following the instructions in Forcing Replication Updates from the Console, or Forcing Replication Updates from the Command Line
By changing an entry on the supplier server. The change is replicated to the consumer servers.

Enable and configure the referential integrity plug-in on all master replicas in the topology. This action ensures that the server maintains referential integrity for groups and roles. For information about how to enable and configure the referential integrity plug-in, see Configuring Referential Integrity.
After performing a modify DN operation, allow time for the referential integrity plug-in to replicate its changes.

Renaming or Moving an Entry by Using the Console

This section describes how to rename an entry and move an entry by using the console.

Enabling the Modify DN Operation by Using the Console

You cannot perform the modify DN operation on a suffix unless the ACI rights are configured to give you permission. The modify DN operation can be enabled or disabled globally for all suffixes on a server, or it can be enabled or disabled individually for each specified suffix.

The following procedures are examples of how to configure different ACI rights. These procedures might not configure the most appropriate ACI rights for you. For information about how to configure different ACI rights, see information about working with access control instructions in the Administration Server Administration Guide.

To Extend the ACI Rights by Using the Console

This procedure configures the ACI rights so that all users can perform the modify DN operation on the whole suffix.

Open the Directory Server Console on the Directory tab.
On the left-hand side, select the suffix for which you want to extend the ACI permissions.
Right click on the suffix and select "Set Access Permissions" from the pop-up menu.

The Access Control Manager window is displayed. It contains the list of ACIs belonging to the entry.

In the Access Control Manager window, highlight the Anonymous access ACI, and click Edit.

The Access Control Editor is displayed..



Select the check box labeled import to allow child entries to be imported to the specified suffix.
Select the check box labeled export to allow entries to be moved from beneath the specified suffix to another location in the suffix.
Click OK in the Edit ACI window. The window closes.
Click OK in the Access Control Manager window. The window closes.

To Enable or Disable the Modify DN Operation Globally by Using the Console

Open the Directory Server Console on the Configuration tab and the Settings tab.
To allow the modify DN operation globally, select the check box labeled "Allow the modify dn operation".

To disallow the modify DN operation globally, deselect the checkbox labeled "Allow the modify dn operation".



Click Save.
In the pop-up confirmation window, click Yes to confirm your choice.

To Enable the Modify DN Operation for Specified Suffixes by Using the Console

Open the Directory Server Console on the Configuration tab and the Settings tab.
On the left-hand side, select the suffix for which you want to allow or disallow the modify DN operation.
Select the Settings tab.
In the box labeled "Modify DN operation" select an operation from the drop-down menu to allow or disallow the modify DN operation for the suffix.





Click Save.

If the modify DN operation is enabled globally for the server, a confirmation window pops up.

In the pop-up confirmation window, click Yes to confirm your choice.
Repeat Step 4 through Step 6 for each suffix, as required.

Renaming an Entry by Using the Console

This section describes how to rename an entry. This operation is supported by versions of Directory Server prior to Directory Server 5.2 2005Q1. To perform this operation, you do not need to enable the modify DN operation.

To Rename an Entry by Using the Console

Open the Directory Server Console on the Directory tab.
Expand the directory tree to display the entry that you wish edit.
Select the entry to rename, right click and select "Edit With Generic Editor".

The generic editor window opens. The generic editor window is illustrated in Figure 2-2.

Select the attribute that corresponds to the RDN that you want to change.
Change the text in the attribute box from the current name of the entry to the new name of the entry.
Click OK.

Moving an Entry by Using the Console

This procedure is not supported by versions of Directory Server prior to Directory Server 5.2 2005Q1.

To Move an Entry by Using the Console

Ensure that the modify DN operation is enabled globally or for the suffix containing the entry that you wish to move. For information, see Enabling the Modify DN Operation by Using the Console.
Open the Directory Server Console on the Directory tab.
Expand the directory tree to display the entry that you wish to edit.
Select the entry that you wish to move.
Drag the entry and drop it onto the new parent.
In the warning pop-up box, click Continue.

Moving and Renaming an Entry by Using the Console

To rename and move an entry, perform both of the following procedures:

To Rename an Entry by Using the Console
To Move an Entry by Using the Console

Renaming or Moving an Entry by Using the ldapmodify Command

This section describes how to rename an entry and move an entry by using the ldapmodify command.

The following attributes are used with the LDIF statements:

dn - specifies the entry to rename or move.
changetype: modrdn - specifies that a modify DN operation is to be used
newrdn - gives the new naming attribute
deleteoldrdn - indicates whether the previous naming attribute should be removed from the entry (1 is yes, 0 is no)

Note that you cannot remove a naming attribute from the entry if that attribute is obligatory in the entry definition.

newsuperior - specifies the new superior attribute of the entry

For information about the attributes used with the LDIF statement, see "Attribute Reference" in the Directory Server Administration Reference. For information about the ldapmodify command and its options, see the Directory Server Man Page Reference.

Enabling the Modify DN Operation by Using the ldapmodify Command

Before you can use the modify DN operation you must extend the ACI rights and enable the modify DN operation.

For information about how to extend the ACI rights, see Creating ACIs From the Command Line.

This section describes how to enable the modify DN operation.

To Enable the Modify DN Operation Globally by Using the ldapmodify Command

Run the ldapmodify command. For example, the following example enables the modify DN operation:

ldapmodify -h <hostname> -p <port> -D <user> -w <user_password>
dn: cn=config,cn=ldbm database,cn=plugins,cn=config
changetype: modify
replace: nsslapd-moddn-enabled
nsslapd-moddn-enabled: on

To Enable the Modify DN Operation for a Suffix by Using the ldapmodify Command

Run the ldapmodify command. For example, the following example enables the modify DN operation for the suffix called suffix-name:

ldapmodify -h <hostname> -p <port> -D <user> -w <user_password>
dn: cn=<suffix-name>,cn=ldbm database,cn=plugins,cn=config
changetype: modify
replace: nsslapd-moddn-enabled
nsslapd-moddn-enabled: on

Renaming an Entry by Using the ldapmodify Command

This section describes how to rename an entry. This operation is supported by versions of Directory Server prior to Directory Server 5.2 2005Q1. To perform this operation, you do not need to enable the modify DN operation.

To Rename a Leaf Entry by Using the ldapmodify Command

Run the ldapmodify command. For example, the following example renames the entry john to bob:

ldapmodify -h <hostname> -p <port> -D <user> -w <user_password>
dn: cn=john,dc=california,dc=sun,dc=com
changetype: modrdn
newrdn: cn=bob
deleteoldrdn: 1

Moving an Entry by Using the ldapmodify Command

This section describes how to move an entry to another part of the suffix. This operation is not supported by versions of Directory Server prior to Directory Server 5.2 2005Q1.

To Move an Entry by Using the ldapmodify Command

Ensure that the ACI rights are extended for the modify DN operation. For information, see Enabling the Modify DN Operation by Using the ldapmodify Command.
Ensure that the modify DN operation is enabled for the suffix or suffixes affected by the rename and move operation. For information, see Enabling the Modify DN Operation by Using the ldapmodify Command.
Run the ldapmodify command. For example, the following command moves the entry john from the subtree for California to the subtree for France:

ldapmodify -h <hostname> -p <port> -D <user> -w <user_password>
dn: cn=john,dc=california,dc=sun,dc=com
changetype: modrdn
newrdn: cn=john
deleteoldrdn: 0
newsuperior: dc=france,dc=france,dc=sun,dc=com

Renaming and Moving an Entry by Using the ldapmodify Command

This section describes how to rename and move an entry to another part of the suffix. This operation is not supported by versions of Directory Server prior to Directory Server 5.2 2005Q1.

To Rename and Move an Entry by Using the ldapmodify Command

Ensure that the ACI rights are extended for the modify DN operation. For information, see Enabling the Modify DN Operation by Using the ldapmodify Command.
Ensure that the modify DN operation is enabled for the suffix or suffixes affected by the rename and move operation. For information, see Enabling the Modify DN Operation by Using the ldapmodify Command.
Run the ldapmodify command. For example, the following command combines the rename operation and the move operation into one operation:

ldapmodify -h <hostname> -p <port> -D <user> -w <user_password>
dn: cn=john,dc=california,dc=sun,dc=com
changetype: modrdn
newrdn: dc=bob
deleteoldrdn: 1
newsuperior: dc=france,dc=france,dc=sun,dc=com

---

Setting Referrals

You can use referrals to tell client applications which server to contact if the information is not available locally. Referrals are pointers to a remote suffix or entry that Directory Server returns to the client in place of a result. The client must then perform the operation again on the remote server named in the referral. This redirection occurs in three cases:

When a client application requests an entry that does not exist on the local server, the server returns the default referral.
When an entire suffix has been taken offline for maintenance or security reasons, the server will return the referrals defined by that suffix. The suffix-level referrals are described in Setting Access Permissions and Referrals. Read-only replicas of a suffix also return referrals to the master servers when a client requests a write operation.
You can create entries that are known as smart referrals. When a client specifically accesses a smart referral, the server will instead return the referral it defines. Directory Server Console can be configured to follow smart referrals automatically, so that they appear to be local entries on the top-level Directory tab.

In all cases, a referral is an LDAP URL that contains the hostname, port number and optionally a DN on another server. For more information, see the Directory Server Administration Reference. For conceptual information on how you can use referrals in your directory deployment, see the Directory Server Deployment Planning Guide.

The following sections describe the procedures for defining your directory's default referrals and defining smart referrals.

Setting the Default Referrals

Default referrals are returned to client applications that submit operations on a DN not contained within any of the suffixes maintained by your directory. Default referrals are sometimes called global referrals because they apply to all suffixes in the directory. The server will return all referrals that are defined, but the order in which they are returned is not defined.

Setting a Default Referral Using the Console

On the top-level Configuration tab of Directory Server Console, select the server node at the root of the configuration tree, and select the Network tab in the right-hand panel.
Select the Return Referral checkbox and enter an LDAP URL in the text field. Alternatively, click Construct URL to be guided through the definition of an LDAP URL. An example of an LDAP URL to a secure port is:

ldaps://east.example.com:636/dc=example,dc=com

You can enter multiple referral URLs separated by spaces and in quotes as follows:

"ldap://east.example.com:389" "ldap://backup.example.com:389"

Click Save for your changes to take effect immediately.

Setting a Default Referral From the Command Line

Use the ldapmodify command-line utility to add or replace one or more default referrals to the cn=config entry in your directory configuration file. For example:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: cn=config
changetype: modify
replace: nsslapd-referral
nsslapd-referral: ldap://east.example.com:389
nsslapd-referral: ldap://backup.example.com:389

You do not need to restart the server.

Creating Smart Referrals

Smart referrals allow you to map a directory entry or directory tree to a specific LDAP URL. Using smart referrals, you can refer client applications to a specific server or a specific entry on a specific server.

Often, a smart referral points to an actual entry with the same DN on another server. However, you may define the smart referral to any entry on the same server or on a different server. For example, you may define the entry with the following DN:

uid=bjensen,ou=People,dc=example,dc=com

to be a smart referral which points to another entry on the server east.example.com:

cn=Babs Jensen,ou=Sales,o=east,dc=example,dc=com

The way the directory uses smart referrals conforms to the standard specified in section 4.1.11 of RFC 2251 (http://www.ietf.org/rfc/rfc2251.txt).

Creating Smart Referrals Using the Console

On the top-level Directory tab of Directory Server Console, expand the directory tree to display the entry that you wish to be the parent of the smart referral.
Right-click the parent entry, and select the New>Referral menu item. Alternatively, you may left-click the parent entry to select it and then choose the Object>New>Referral menu item.

The custom editor dialog for referral entries is displayed.

On the General tab of the editor, enter a name for the referral and select its naming attribute from the drop-down list. The name will be the value of the naming attribute you select. Optionally, you may enter a description string for this referral.
On the URLs tab of the editor, click the Construct button to define the URL of the smart referral. Enter the elements of an LDAP URL in dialog that appears.

The elements of the URL include the host name and LDAP port number of the directory server that holds the referral entry, and the DN of the target entry on the server. By default, the target DN is the same DN as that of the smart referral entry. However, the target DN can be any suffix, subtree, or leaf entry.

Click OK in the LDAP URL construction dialog. The URL is displayed in the new referral text box.
Click Add beside the new referral text box to add the referral to the list.
You may defined more than one URL to return as referrals for this entry. Use the Construct, Add, Delete, and Change buttons to create and manage the Referral List.
Click the Referral Authentication button to display a dialog where you may set the credentials that Directory Server Console will use to bind when follow the referral to the remote server. You may define the bind DN and password that will be used when accessing a server. All referrals to the same server will use the same credentials.
Use the Add, Edit, and Delete buttons to manage the list of servers and corresponding credentials. Then click OK when you are done.
In the custom editor for referrals, click OK to save your smart referral entry.

In the directory tree of the console, you should see the target subtree or entry in place of the smart referral entry. If you smart referral entry with a yellow warning icon, the URL or the credentials were invalid. Double click the entry, click Continue when you see the Referral Error, and modify the URL or Referral Authentication to fix the error.

Creating Smart Referrals From the Command Line

To create a smart referral, create an entry with referral and extensibleObject object classes. The referral object class allows the ref attribute that is expected to contain an LDAP URL. The extensibleObject object class allows you to use any schema attribute as the naming attribute, in order to match the target entry.

For example, define the following entry to return a smart referral instead of the entry uid=bjensen:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: uid=bjensen,ou=People,dc=example,dc=com
objectclass: top
objectclass: extensibleObject
objectclass: referral
uid: bjensen
ref: ldap://east.example.com/cn=Babs%20Jensen,ou=Sales,
 o=east,dc=example,dc=com

Note	Any information after a space in an LDAP URL is ignored by the server. For this reason, you must use %20 instead of spaces in any LDAP URL you intend to use as a referral. Other special characters must be escaped.

Once you have defined the smart referral, modifications to the uid=bjensen entry will actually be performed on the cn=Babs Jensen entry on the other server. The ldapmodify command will automatically follow the referral, for example:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: replace
replace: telephoneNumber
telephoneNumber: (408) 555-1234

In order to modify the smart referral entry, you must use the -M option of ldapmodify, for example:

ldapmodify -M -h host -p port -D "cn=Directory Manager" -w password
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: replace
replace: ref
ref: ldap://east.example.com/cn=Babs%20Jensen,ou=Marketing,
 o=east,dc=example,dc=com

---

Encrypting Attribute Values

Attribute encryption protects sensitive data while it is stored in the directory. Attribute encryption allows you to specify that certain attributes of an entry be stored in an encrypted format. This prevents data from being readable while stored in database files, backup files, and exported LDIF files.

With this feature, attribute values are encrypted before they are stored in the Directory Server database, and decrypted back to their original value before being returned to the client. You must use access controls to prevent clients from accessing such attributes without permission, and SSL to encrypt the attribute values when in transit between the client and Directory Server. For an architectural overview of data security in general and attribute encryption in particular, see the Directory Server Deployment Planning Guide.

Attribute encryption is active only when SSL is configured and enabled on the server. However, no attributes are encrypted by default. 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. If you want to encrypt an attribute in an entire directory, you must enable encryption for that attribute in every suffix.

Caution	Attribute encryption affects all data and index files associated with a suffix. If you modify the encryption configuration of an existing suffix, you must first export its contents, make the configuration change, and then re-import the contents. The console will help you perform these steps. In addition, when turning on encryption, you must manually delete the database cache files that may still contain unencrypted values. Preferably, you should enable any encrypted attributes before loading or creating data in a new 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.

You may select the userPassword attribute for encryption, however this provides no real security benefit unless the password needs to be stored in the clear (as is the case for DIGEST-MD5 SASL authentication.) If the password already has an encryption mechanism defined in the password policy, further encryption provides little additional security but will impact performance of every bind operation.

When in storage, encrypted attributes are prefaced with a cipher tag that indicates the encryption algorithm used. An encrypted attribute using the DES encryption algorithm would appear as follows:

{CKM_DES_CBC}3hakc&jla+=snda%

Configuring Attribute Encryption Using the Console

Select the Configuration tab in Directory Server Console, expand the Data node, and select the suffix for which you wish to encrypt attribute values. Select the Attribute Encryption tab in the right panel.

This tab contains a table listing the name and encryption scheme of all currently encrypted attributes for this suffix.

To enable encryption for an attribute:
Click the Add Attribute button to display a list of attributes.
Select the attribute you want to encrypt from the list and click OK. The attribute is added to the Attribute Name column of the table.
Select the Encryption Scheme for this attribute from the drop-down list next to the attribute name.
To make an attribute no longer encrypted, select the attribute name from the table and click the Delete Attribute button.
Click Save. You will be prompted to export the contents of the suffix to an LDIF file before the configuration change is made.
Click Export suffix to open the export dialog or click Continue to modify the attribute encryption configuration without exporting. The new configuration will then be saved.

If you have not already exported the suffix, you must do so now in order to save its contents. If the suffix contains encrypted attributes, you may leave them encrypted in the exported LDIF if you plan to reinitialize the suffix using this LDIF file in the next step.

You will now be prompted to initialize the suffix from an LDIF file.

Click Initialize suffix now to open the initialization dialog and then enter the name of an LDIF file to load into the directory.

If you exported your suffix with encrypted attributes in the previous step, you must use that file to initialize now, because the encrypted values will be unrecoverable once the suffix is reinitialized. As it is loaded and the indexes are created, all values of the specified attributes will be encrypted.

Click Close if you do not wish to initialize the suffix at this time. You may import data at a later time using the procedures described in Importing Data.

If you have changed the configuration to encrypt one or more attributes, and these attributes had values before the import operation, some of those unencrypted values may still be visible in the database cache. To clear the database cache:
Stop Directory Server as described in Starting and Stopping Directory Server.
As root or having administrator privileges, delete the database cache files from your file system:

ServerRoot/slapd-serverID/db/__db.*

Start Directory Server again. The server will automatically create new database cache files.

Configuring Attribute Encryption From the Command Line

If the suffix on which you wish to configure attribute encryption contains any entries whatsoever, you must first export the contents of that suffix to an LDIF file. See Exporting Data for more information.

If the suffix contains encrypted attributes, you may leave them encrypted in the exported LDIF if you plan to re-initialize the suffix using this LDIF file in Step 5.

To enable encryption for an attribute, use the ldapmodify command to add the following configuration entry:

ldapmodify -a -h host -p port -D cn=Directory Manager -w password
dn: cn=attributeName, cn=encrypted attributes, cn=databaseName,
 cn=ldbm database, cn=plugins, cn=config
objectclass: top
objectclass: dsAttributeEncryption
cn: attributeName
dsEncryptionAlgorithm: cipherName

where attributeName is the type name of the attribute to encrypt, databaseName is the symbolic name of the database corresponding to the suffix, and cipherName is one of the following:

ckm_des_cbc - DES block cipher
ckm_des3_cbc - Triple-DES block cipher
ckm_rc2_cbc - RC2 block cipher
ckm_rc4 - RC4 stream cipher
To make an attribute no longer encrypted, use the ldapmodify command to modify the following configuration entry:

ldapmodify -h host -p port -D cn=Directory Manager -w password
dn: cn=attributeName, cn=encrypted attributes, cn=databaseName,
 cn=ldbm database, cn=plugins, cn=config
changetype: modify
replace: dsEncryptionAlgorithm
dsEncryptionAlgorithm: clearText

where attributeName is the type name of the attribute to encrypt, and databaseName is the symbolic name of the database corresponding to the suffix.

Note	Do not delete the attribute encryption configuration entry. It will be removed automatically the next time the suffix is initialized.

If you have changed the configuration to encrypt one or more attributes, and these attributes had values before the import operation, some of those unencrypted values may still be visible in the database cache. To clear the database cache:
Stop Directory Server as described in Starting and Stopping Directory Server.
As root or having administrator privileges, delete the database cache files from your file system:

         ServerRoot/slapd-serverID/db/__db.*

Start Directory Server again. The server will automatically create new database cache files. Performance of operations in this suffix may be slightly impacted until the cache is filled again.
Initialize the suffix with an LDIF file as described in Importing Data.

As the file is loaded and the corresponding indexes are created, all values of the specified attributes will be encrypted.

---

Maintaining Referential Integrity

Referential integrity is a plug-in mechanism that ensures relationships between related entries are maintained. Several types of attributes, such as those for group membership contain the DN of another entry. Referential integrity can be used to ensure that when an entry is removed, all attributes which contain its DN are also removed.

For example, if a user's entry is removed from the directory and referential integrity is enabled, the server also removes the user from any groups of which the user is a member. If referential integrity is not enabled, the user must be manually removed from the group by the administrator. This is an important feature if you are integrating Directory Server with other Sun Java System products that rely on the directory for user and group management.

How Referential Integrity Works

When the referential integrity plug-in is enabled it performs integrity updates on specified attributes immediately after a delete, rename, or move operation. By default, the referential integrity plug-in is disabled.

Whenever you delete, rename, or move a user or group entry in the directory, the operation is logged to the referential integrity log file:

ServerRoot/slapd-serverID/logs/referint

After a specified time, known as the update interval, the server performs a search on all attributes for which referential integrity is enabled, and matches the entries resulting from that search with the DNs of deleted or modified entries present in the log file. If the log file shows that the entry was deleted, the corresponding attribute is deleted. If the log file shows that the entry was changed, the corresponding attribute value is modified accordingly.

When the default configuration of the referential integrity plug-in is enabled, it performs integrity updates on the member, uniquemember, owner, seeAlso, and nsroledn attributes immediately after every delete, rename, or move operation. You can, however, configure the behavior of the referential integrity plug-in to suit your own needs:

Record referential integrity updates in a different file.
Modify the update interval. If you want to reduce the impact referential integrity updates has on your system, you may want to increase the amount of time between updates.
Select the attributes to which you apply referential integrity. If you use or define attributes containing DN values, you may want the referential integrity plug-in to monitor them.

Configuring Referential Integrity

Use the following procedure to enable or disable referential integrity and configure the plug-in from Directory Server Console.

Note	All attributes in all databases that are used by the referential integrity plug-in must be indexed. The indexes need to be created in the configuration of all the databases. When the retro change log is enabled, the cn=changelog suffix must be indexed. For information, see Chapter 10, "Indexing Directory Data."

Configuring Referential Integrity From the Console

On the top-level Configuration tab of Directory Server Console, expand the Plugins node, and select the "referential integrity postoperation" plug-in.

The settings for the plug-in are displayed in the right-hand panel.

Check the Enable plug-in check box to enable the plug-in, clear it to disable it.
Set the value of Argument 1 to modify the update interval in seconds. Common values are:
0 - Update immediately after every operation. This is the default value. Be advised that immediate referential integrity checks after every delete and modify operation can significantly impact server performance.
90 - Updates occur every 90 seconds
3600 - Updates occur every hour
10,800 - Updates occur every 3 hours
28,800 - Updates occur every 8 hours
86,400 - Updates occur once a day
604,800 - Updates occur once a week

Set a positive value, based on a compromise between integrity and overall performance.

Set the value of Argument 2 to the absolute path of the referential integrity log file you wish to use.

Argument 3 is not used but it must be present.

The attributes monitored for referential integrity are listed beginning with Argument 4. Click the Add and Delete buttons to manage this list and add your own attributes.
Click Save to save your changes.
For your changes to be taken into account, you must restart Directory Server.

Using Referential Integrity with Replication

There are certain limitations associated with the use of the referential integrity plug-in in a replication environment:

It must be enabled on all servers containing master replicas.
You must enable it with the same configuration on every master.
It is not useful to enable it on servers containing only hub or consumer replicas.

To configure the referential integrity plug-in in a replication topology:

Make sure all replicas are configured and all replication agreements are defined.
Determine the set of attributes for which you will maintain referential integrity. Also determine the update interval you wish to use on your master servers.
Enable the referential integrity plug-in on all master servers using the same set of attributes and the same update interval. This procedure is described in Configuring Referential Integrity.
Ensure that the referential integrity plug-in is disabled on all consumer servers.

Using Referential Integrity With Legacy Replication

When replicating from a 4.x master to a 5.x consumer, with referential integrity enabled, you must reconfigure the referential integrity plug-in on the 4.x master to write referential integrity changes to the 4.x change log. This enables referential integrity changes to be replicated. If you do not reconfigure the plug-in, referential integrity will not work correctly.

To reconfigure the referential integrity plug-in in this environment:

Stop the 4.x server.
Open the slapd.ldbm.conf file located in ServerRoot/slapd-ServerID/config/.
Locate the line that begins

plugin postoperation on "referential integrity postoperation"

Modify this line by changing the argument that appears just before the list of attributes from 0 to 1.

For example, change

plugin postoperation on "referential integrity postoperation" "ServerRoot/lib/referint-plugin.dll" referint_postop_init 0 "ServerRoot/slapd-serverID/logs/referint" 0 "member" "uniquemember" "owner" "seeAlso"

to

plugin postoperation on "referential integrity postoperation" "ServerRoot/lib/referint-plugin.dll" referint_postop_init 0 "ServerRoot/slapd-serverID/logs/referint" 1 "member" "uniquemember" "owner" "seeAlso"

Save the slapd.ldbm.conf file.
Restart the server.
Reinitialize the 5.x consumer from the 4.x supplier.

---

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. For more information on this utility, refer to the Directory Server Resource Kit Tools Reference.

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

optional_options represents a series of command-line options. These must be specified before the search filter, if any.
search_filter represents an LDAP search filter as described in LDAP Search Filters. You must specify a search filter, unless you are supplying search filters in a file using the -f option.
optional_list_of_attributes represents a list of attributes separated by a space. Specifying a list of attributes reduces the number of attributes returned in the search results. This list of attributes must appear after the search filter. For an example, see Displaying Subsets of Attributes. If you do not specify a list of attributes, the search returns values for all attributes permitted by the access control set in the directory (with the exception of operational attributes).

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.) For more information on persistent searches, see the Directory Server Resource Kit Tools 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 the Directory Server Resource Kit Tools Reference.

ldapsearch Examples

In the next set of examples, the following assumptions are made:

You want to perform a search of all entries in the directory.
The server is located on hostname myServer.
The server uses port number 5201.
You are binding to the directory as Directory Manager, with a password of password.
SSL is enabled for the server on port 636 (the default SSL port number).
The suffix under which all data is stored is dc=example,dc=com.

Returning All Entries

Given the previous information, the following call will return all entries in the directory:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password
 -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=directory manager" -w password
 -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=directory manager" -w password
 -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=directory manager" -w password
 -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=directory manager" -w password
 "(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 Directory Server Administration Reference.

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=directory manager" -w password
 "(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=directory manager" -w password
 -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
Using Operators in Search Filters
Using OIDs in Search Filters
Using Compound Search Filters
Specifying Search Filters Using a File
Specifying Non 7-Bit ASCII Characters in Search Filters
Search Filter Examples

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:

cn (the person's common name)
sn (the person's surname, or last name, or family name)
telephoneNumber (the person's telephone number)
buildingName (the name of the building in which the person resides)
l (the locality in which you can find the person)

For a listing of the attributes associated with types of entries, see the Directory Server Administration Reference.

Using Operators in Search Filters

The operators that you can use in search filters are listed in Table 2-2:

Table 2-2 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=*Johnson cn=*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's 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 2-3.

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 2-3 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:

Innermost to outermost parenthetical expressions first
All expressions from left to right

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=directory manager" -w password
 -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=directory manager" -w password
 -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 2-4 must also be represented in this fashion when used in search filters.

Table 2-4 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=directory manager" -w password
 "(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=directory manager" -w password
 "(objectclass=*)" aci *

---

Searching an Internationalized Directory

When you perform search operations, you can request that the directory sort the results based on any language for which the server has a supporting collation order. For a list of the collation orders supported by the directory, see the Directory Server Administration Reference.

This section focuses on the matching rule filter portion of the ldapsearch syntax. For more information on general ldapsearch syntax, see LDAP Search Filters. For information on searching internationalized directories using the Users and Groups portion of the Directory Server Console, refer to the online help or the Administration Server Administration Guide.

This section covers the following topics:

Matching Rule Filter Syntax
Supported Search Types
International Search Examples

Matching Rule Filter Syntax

A matching rule provides special guidelines for how the directory compares strings during a search operation. In an international search, the matching rule tells the system what collation order and operator to use when performing the search operation. The syntax of the matching rule filter is as follows:

attr:matchingRule:=value

where:

attr is an attribute belonging to entries you're searching for, such as cn or mail
matchingRule is a string that identifies either the collation order or the collation order and a relational operator, depending on the format you prefer. For a discussion of matching rule formats, see Matching Rule Formats.
value is either the attribute value for which you want to search or a relational operator plus the attribute value for which you want to search. The syntax of the value portion of the filter depends on the matching rule format you use.

Matching Rule Formats

The matching rule portion of a search filter can be represented in the following ways:

As the OID of the collation order for the locale on which you want to base your search.
As the language tag associated with the collation order on which you want to base your search.
As the OID of the collation order and a suffix that represents a relational operator.
As the language tag associated with the collation order and a suffix that represents a relational operator.

The syntax for each of these options is discussed in the following sections:

Using an OID for the Matching Rule
Using a Language Tag for the Matching Rule
Using an OID and Suffix for the Matching Rule
Using a Language Tag and Suffix for the Matching Rule

Using an OID for the Matching Rule

Each locale supported by Directory Server has an associated collation order OID. For a list of supported locales and their associated OIDs, see the Directory Server Administration Reference.

You can use the collation order OID in the matching rule portion of the matching rule filter as follows:

attr:OID:=(relational_operator value)

The relational operator is included in the value portion of the string, separated from the value by a single space. For example, to search for all departmentNumber attributes that are at or after N4709 in the Swedish collation order, use the following filter:

departmentNumber:1.3.6.1.4.1.42.2.27.9.4.129.1:=>= N4709

Using a Language Tag for the Matching Rule

Each locale supported by Directory Server has an associated language tag. For a list supported locales and their associated language tags, see the Directory Server Administration Reference.

You can use the language tag in the matching rule portion of the matching rule filter as follows:

attr:language-tag:=(relational_operator value)

The relational operator is included in the value portion of the string, separated from the value by a single space. For example, to search the directory for all description attributes with a value of estudiante using the Spanish collation order, use the following filter:

description:es:== estudiante

Using an OID and Suffix for the Matching Rule

As an alternative to using a relational operator-value pair, you can append a suffix that represents a specific operator to the OID in the matching rule portion of the filter. Combine the OID and suffix as follows:

attr:OID+suffix:=value

For example, to search for businessCategory attributes with the value Softwareprodukte in the German collation order, use the following filter:

businessCategory:1.3.6.1.4.1.42.2.27.9.4.28.1.3:=Softwareprodukte

The .3 in the previous example is the equality suffix.

Using a Language Tag and Suffix for the Matching Rule

As an alternative to using a relational operator-value pair, you can append a suffix that represents a specific operator to the language tag in the matching rule portion of the filter. Combine the language tag and suffix as follows:

attr:language-tag+suffix:=value

For example, to search for all surnames that come at or after La Salle in the French collation order, use the following filter:

sn:fr.4:=La Salle

Using Wildcards in Matching Rule Filters

When performing a substring search using a matching rule filter, you can use the asterisk (*) character as a wildcard to represent zero or more characters.

For example, to search for an attribute value that starts with the letter k and ends with the letter n, you would enter a k*n in the value portion of the search filter. Similarly, to search for all attribute values beginning with the letter u, you would enter a value of u* in the value portion of the search filter.

To search for a value that contains the asterisk (*) character, you must escape the asterisk character.

Supported Search Types

The directory server supports the following types of international searches:

equality (=)
substring (*)
greater than (>)
greater than or equal to (>=)
less than (<)
less than or equal to (<=)

Approximate, or phonetic, and presence searches are supported only in English.

As with a regular ldapsearch search operation, an international search uses operators to define the type of search. However, when invoking an international search, you can either use the standard operators (=, >=, >, <, <=) in the value portion of the search string, or you can use a special type of operator, called a suffix (not to be confused with the directory suffix), in the matching rule portion of the filter. Table 2-5 summarizes each type of search, the operator, and the equivalent suffix.

Table 2-5 Search Types, Operators, and Suffixes 

Search Type	Operator	Suffix
Less than	<	.1
Less than or equal to	<=	.2
Equality	=	.3
Greater than or equal to	>=	.4
Greater than	>	.5
Substring	*	.6

International Search Examples

The following sections show examples of how to perform international searches on directory data. Each example gives all the possible matching rule filter formats so that you can become familiar with the formats and select the one that works best for you.

Less Than Example

When you perform a locale-specific search using the less than operator (<) or suffix (.1), you search for all attribute values that come before the given attribute in a specific collation order.

For example, to search for all surnames that come before the surname Marquez in the Spanish collation order, you could use any of the following matching rule filters:

sn:1.3.6.1.4.1.42.2.27.9.4.49.1:=< Marquez
sn:es:=< Marquez
sn:1.3.6.1.4.1.42.2.27.9.4.49.1.1:=Marquez
sn:es.1:=Marquez

Less Than or Equal to Example

When you perform a locale-specific search using the less than or equal to operator (<=) or suffix (.2), you search for all attribute values that come at or before the given attribute in a specific collation order.

For example, to search for all room numbers that come at or before room number CZ422 in the Hungarian collation order, you could use any of the following matching rule filters:

roomNumber:1.3.6.1.4.1.42.2.27.9.4.88.1:=<= CZ422
roomNumber:hu:=<= CZ422
roomNumber:1.3.6.1.4.1.42.2.27.9.4.88.1.2:=CZ422
roomNumber:hu.2:=CZ422

Equality Example

When you perform a locale-specific search using the equal to operator (=) or suffix (.3), you search for all attribute values that match the given attribute in a specific collation order.

For example, to search for all businessCategory attributes with the value Softwareprodukte in the German collation order, you could use any of the following matching rule filters:

businessCategory:1.3.6.1.4.1.42.2.27.9.4.28.1:== Softwareprodukte
businessCategory:de:== Softwareprodukte
businessCategory:1.3.6.1.4.1.42.2.27.9.4.28.1.3:=Softwareprodukte
businessCategory:de.3:=Softwareprodukte

Greater Than or Equal to Example

When you perform a locale-specific search using the greater than or equal to operator (>=) or suffix (.4), you search for all attribute values that come at or after the given attribute in a specific collation order.

For example, to search for all localities that come at or after Québec in the French collation order, you could use any of the following matching rule filters:

locality:1.3.6.1.4.1.42.2.27.9.4.76.1:=>= Québec
locality:fr:=>= Québec
locality:1.3.6.1.4.1.42.2.27.9.4.76.1.4:=Québec
locality:fr.4:=Québec

Greater Than Example

When you perform a locale-specific search using the greater than operator (>) or suffix (.5), you search for all attribute values that come at or before the given attribute in a specific collation order.

For example, to search for all mail hosts that come after host schranka4 in the Czech collation order, you could use any of the following matching rule filters:

mailHost:1.3.6.1.4.1.42.2.27.9.4.26.1 :=> schranka4
mailHost:cs:=> schranka4
mailHost:1.3.6.1.4.1.42.2.27.9.4.26.1.5:=schranka4
mailHost:cs.5:=schranka4

Substring Example

When you perform an international substring search, you search for all values that match the given pattern in the specified collation order.

For example, to search for all user IDs that end in ming in the Chinese collation order, you could use any of the following matching rule filters:

uid:1.3.6.1.4.1.42.2.27.9.4.143.1:=* *ming
uid:zh:=* *ming
uid:1.3.6.1.4.1.42.2.27.9.4.143.1.6:=*ming
uid:zh.6:=*ming

---

Accessing the Directory Using DSMLv2

The following examples indicate how to use DSML requests to access and search the directory. For a complete list of DSML-related attributes and information about the DSMLv2 standard, see the Directory Server Administration Reference.

This section contains the following examples:

An Empty Anonymous DSML "Ping" Request
Issuing a DSML Request to Bind as a Particular User
A DSML Search Request

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 Enabling DSML Requests. To check whether the DSML front end is enabled, send an empty DSML batch request, as shown in Code Example 2-1:

Code Example 2-1 Empty Anonymous DSML Request

POST /dsml HTTP/1.1 content-length: 451 HOST: hostMachine 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.

content-length: 451
specifies the exact length of the SOAP/DSML request
HOST: hostMachine
specifies the name of the host Directory Server being contacted.
SOAPAction:
is mandatory and informs the directory that you want to perform a DSML request on the HTTP/SOAP stack. It may however, be left empty.
Content-Type: text/xml
must have a value of text/xml which defines the content as XML.
Connection: close
specifies that the connection will be closed once the request has been satisfied (the default HTTP/1.1 behavior is to maintain the connection open.)

The remainder of the request is the SOAP/DSML section. The DSML request begins with the XML prolog header:

<?xml version='1.0' encoding='UTF-8'?>

This specifies that the request must be encoded with the UTF-8 character set. The header is followed by the SOAP envelope and body elements that contain the mandatory inclusion of the XML schema, XML schema instance and SOAP namespaces.

The DSML batch request element marks the beginning of the DSML batch request, and is immediately followed by the mandatory inclusion of the DSMLv2 namespace:

xmlns='urn:oasis:names:tc:DSML:2:0:core'.

The request is optionally identified by the following request ID

requestID='Ping!'>

The empty batch request

<!-- empty batch request -->

is XML commented as such, and the SOAP/DSML batch request is closed using the close batch request, close SOAP body, and close SOAP envelope elements.

If the DSML front end is enabled, an empty DSML response is returned, as shown in Code Example 2-2.

Code Example 2-2 Empty Anonymous DSML Response

HTTP/1.1 200 OK Cache-control: no-cache Connection: close Date: Mon, 09 Sep 2002 13:56:49 GMT Accept-Ranges: none Server: Sun-ONE-Directory/5.2 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 ds-dsml-poolsize and ds-dsml-poolmaxsize attributes and the request size limit by the ds-dsml-requestmaxsize attribute. For more information on the DSML-related attributes, see the Directory Server Administration Reference.

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 Code Example 2-3.

Code Example 2-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: hostMachine 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 uid 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 Code Example 2-4, the whoami response (which contains the DN) is shown in the line: <response>dn:uid=easter,ou=people,dc=france,dc=sun,dc=com</response>.

For more information on the whoami extended operation, see http://www.ietf.org/internet-drafts/draft-zeilenga-ldap-authzid-08.txt.

Code Example 2-4 Response to DSML Extended Operation

HTTP/1.1 200 OK Cache-control: no-cache Connection: close Date: Fri, 30 Jul 2004 09:15:09 GMT Accept-Ranges: none Server: Sun-ONE-Directory/5.2 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=france,dc=sun,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

Code Example 2-5 shows a DSML base object search request on the root DSE entry.

Code Example 2-5 DSML Search Request

POST /dsml HTTP/1.1 HOST: hostMachine 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>

In this example:

dn=""
requestID="search on Root DSE"
specifies that the search operation requests data under the root DSE entry (empty DN) and is identified with an optional request ID attribute.
scope="baseObject"
specifies that the search is a base object search.
derefAliases="neverDerefAliases"
specifies that the aliases should not be dereferenced while searching or locating the base object of the search. This is the only derefAliases value supported by Directory Server.
typesOnly="false"
specifies that both the attribute names and their values be returned. typesOnly="true" would return attribute names only. The default value for this attribute is false.

For the entry to match the filter, the presence of objectclass filter is used as follows:

<filter>
   <present name="objectClass"/>
</filter>

This is equivalent to the LDAP filter string (objectclass=*). The filter is followed by the list of desired attributes:

<attributes>
   <attribute name="namingContexts"/>
   <attribute name="supportedLDAPversion"/>
   <attribute name="vendorName"/>
   <attribute name="vendorVersion"/>
   <attribute name="supportedSASLMechanisms"/>
</attributes>

An example DSML search response is shown in Code Example 2-6.

Code Example 2-6 DSML Search Response

HTTP/1.1 200 OK

Cache-control: no-cache

Connection: close

Date: Fri, 30 Jul 2004 09:21:43 GMT

Accept-Ranges: none

Server: Sun-ONE-Directory/5.2

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=france,dc=sun,dc=com</value>

<value>o=NetscapeRoot</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-ONE-Directory/5.2</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>

Previous      Contents      Index      Next

---

Part No: 817-7613-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.