Chapter 2 Managing Directory Entries

This chapter discusses how to use Directory Server Console and the LDAP command-line utilities to manage the contents of your directory. It also describes how attributes are stored with the optional attribute encryption feature, and how to access your directory using DSML. When planning your directory deployment, you should characterize the types of data that the directory will contain. Read Chapter 2, “Planning and Accessing Directory Data,” 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 “Object Class Reference” and “Attribute Reference” chapters in the Directory Server Administration Reference.

You cannot modify your directory unless the appropriate access control instructions (ACIs) have been defined. For further information, see Chapter 6, "Managing Access Control".

Configuration Entries

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

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:

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:

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
Window entitled Create New User showing the fields to enter user information such as name, user ID, password, phone number, and others

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.

Invoking the Custom 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 “Object Classes” in Chapter 8 of the Directory Server Administration Reference.

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.

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

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
Window entitled Generic Editor - uid=bjensen,ou=People,dc=example,dc=com showing the attribute fields for this user entry and controls to modify them

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

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.

Adding an Attribute

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

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.

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.

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.

Renaming an Entry

The naming attributes are the attribute-value pairs of an entry that appear in its distinguished name (DN). The naming attributes are chosen from the existing attributes of an entry. Modify the naming attributes to rename an entry:

Open the generic editor as described in Invoking the Generic Editor.

The text beside the Change button shows the current naming attributes for this entry. If the Show DN checkbox is selected, you can see these attributes in the DN below the list of attribute values.

Click on the Change button. If this button is not activated, you do not have permission to rename this entry.

The Change Naming Attribute dialog is displayed.

Scroll through the list of attributes to choose the ones you wish to have in this entry’s DN. Select or deselect the checkbox beside the attribute to add or remove from the naming attributes, respectively.

DNs of entries beneath the same parent must be unique. Therefore, you must choose naming attributes whose values or combination of values are unique. The server will refuse to save an entry if its DN is not unique. By convention, all entries such as those representing users should use the same naming attributes.

Click OK in the Change Naming Attribute dialog. The display in the generic editor shows the new DN of this entry.

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

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:

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. Further functionality, all command-line options and return values of these commands are described in Chapter 4, “ldapmodify,” and Chapter 5, “ldapdelete,” of the Directory Server Resource Kit Tools Reference.

Input to the command-line utilities is always in LDIF, and can be provided provide 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

When providing LDIF input to the command-line utilities, there are special considerations to remember for command-line input, special characters, schema checking, and the ordering and size of entries. 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 Chapter 7, “LDAP Data Interchange Format Reference“ in the Directory Server Administration Reference.

Terminating LDIF Input on the Command Line


Note	Do not leave white space unintentionally at the end of an LDIF attribute value string. When Directory Server reads an attribute value ending in white space, it base 64 encodes the value.

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.

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:

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:

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.

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.

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 Chapter 2 of 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.

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:

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

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:

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:

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 an Attribute Value

The following example shows how you may modify a single-valued attribute and all values of a multi-valued attribute 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

When using the replace syntax, all current values of the specified attribute will be removed and all given values will be added.

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

Renaming an Entry Using ldapmodify

When you rename an entry, you modify its relative distinguished name (RDN), which is the left-most attribute=value pair in the entry’s DN. This attribute is called the naming attribute and it must also exist with the same value among the entry’s attributes.

When renaming an entry, you cannot change any other part of the DN such that the entry moves to a different subtree. To move an entry to a completely different branch you must create a new entry in the other subtree using the old entry’s attributes, and then delete the old entry.

Also, you cannot rename an entry that has any children because the RDN of a parent is used in the DN of its children, and all entries in a DN must exist. To move an entire tree, you must recreate it in the new location.

Use the changetype: modrdn keywords to rename an entry with an LDIF statement. The following example will rename the uid naming attribute for Barbara Morris:

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

The newrdn line gives the new naming attribute using the attribute=value syntax. The deleteoldrdn line indicates whether the previous naming attribute should be removed from the entry at the same time (1 is yes, 0 is no). In both cases, the new naming attribute will also be added to the entry.

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.

For the same reason you cannot rename a parent entry, 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.

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


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.

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

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:

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 Chapter 6, “LDAP URL Reference,” in the Directory Server Administration Reference. For conceptual information on how you can use referrals in your directory deployment, see Chapter 5, “Distribution, Chaining, and Referrals,” in 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

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

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:

to be a smart referral which points to another entry on the server east.example.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 Chapter 7, “Access Control, Authentication, and Encryption,” in 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.

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.


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.

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:

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 reinitialize 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 -p 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 -p 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.

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 or rename operation. By default, the referential integrity plug-in is disabled.

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

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 or rename operation. You can, however, configure the behavior of the referential integrity plug-in to suit your own needs:

Configuring Referential Integrity

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

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.



Note	For best performance, the attributes updated by the referential integrity plug-in should also be indexed. For information, see Chapter 10, "Indexing Directory Data."

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:

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.

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"

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.

ldapsearch Command-Line Format

ldapsearch [optional_options] [search_filter] [optional_list_of_attributes]

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:

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 Chapter 3 “ldapsearch” in 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.

ldapsearch Examples

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=*)"

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.

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password
-b "cn=schema" -s base "(objectclass=*)"

Using LDAP_BASEDN


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.

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 Chapter 11, “Operational Attributes” in 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

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

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:

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:

Search Filter Syntax

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.

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.

Using Operators in Search Filters

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=BJohn (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 Compound Search Filters

Multiple search filter components can be combined using Boolean operators expressed in prefix notation as follows:

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:

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

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.

then ldapsearch first finds all the entries with the surname Daniels, and then all the entries with the givenname 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 DNs that Contain Commas in Search Filters

When a DN within a search filter contains a comma as part of its value, you must escape the comma with a backslash (\). For example, to find everyone in the example.com Bolivia, S.A. subtree, use the following command:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password -s base -b "o=example.com Bolivia\, S.A.,dc=example,dc=com" "(objectclass=*)"

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:

The following filter searches for entries containing the common name Ray Kultgen. This is also known as an equality search:

The following filter returns all entries that contain a description attribute that contains the substring X.500:

The following filter returns all entries whose organizational unit is Marketing and whose description field does not contain the substring 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)))

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:

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 *

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 “Frontend Plugin Attributes,” in Chapter 3 of the Directory Server Administration Reference.

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:

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.

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

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:

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.

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 “Frontend Plug-In Attributes,” section in Chapter 2 of 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.

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. For more information on the whoami extended operation, see http://www.ietf.org/internet-drafts/draft-zeilenga-ldap-authzid-08.txt.

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

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>

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

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

Previous Contents Index Next
Sun Java(TM) System Directory Server 5 2004Q2 Administration Guide