Sun ONE logo     Previous     Contents     Index     Next    
Sun ONE Directory Server Administration Guide



Chapter 2   Creating Directory Entries

This chapter discusses how to use the Directory Server console and the ldapmodify and ldapdelete command-line utilities to modify the contents of your directory, including the basic types of structural entries, user entries and referrals. It also covers how attributes are stored with the optional attribute encryption feature, new in Directory Server 5.2.

During the planning phase of your directory deployment, you should characterize the types of data that your directory will contain. You should read Chapter 2, "Designing and Accessing Directory Data," in the Sun ONE Directory Server Deployment 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 Part 4, "Directory Server Schema," in the Sun ONE Directory Server Reference Manual.


Note

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

The 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) to describe LDAP entries, attributes, and their values as text. The directory server configuration in this 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 the 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 Sun ONE Directory Server Reference Manual.

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 to the system user defined during installation.

Modify the configuration by editing directly the contents of this file 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. Therefore, modifications to the file after startup will not be taken into account until the next restart.

  • 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 the 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 the Directory Server console and navigating the user interface, refer to "Using the 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

  1. On the top-level Directory tab of the Directory Server console, expand the directory tree to display the entry that you wish to be the parent of the new entry.

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

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

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

    2. 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 "Advanced Entry Management." For instructions on creating password policies, see Chapter 7 "User Account Management. For instructions on creating referrals, see "Setting Referrals".

  2. Click OK to create your new entry and close the custom editor dialog. The new entry appears in the directory tree.

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

  1. On the top-level Directory tab of the Directory Server console, expand the directory tree to display the entry that you wish to be the parent of the new entry.

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

    3. The New Object dialog will be displayed.

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

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

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

  5. To define other attributes that are allowed on the chosen object class, you must add them explicitly. To provide values for optional attributes:

    1. Click the Add Attribute button to display a list of allowed attributes.

    2. Select one or more attributes from the Add Attribute dialog and click OK.

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

  6. 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:

    1. Click the Change button to display the Change Naming Attribute dialog.

    2. In the table of attributes, select the checkbox beside one or more attributes you wish to use in the DN of your new entry.

    3. Click OK in the Change Naming Attribute dialog. The DN in the generic editor shows the new DN using the selected naming attributes.

  7. Click OK in the generic editor to save the new entry.

    8. 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 "Object Classes" in Chapter 9 of the Sun ONE Directory Server Reference Manual.

Invoking the Custom Editor

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

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

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

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

    4. 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 "User Account Management." 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 "Advanced Entry Management." For instructions on modifying password policies, see Chapter 7 "User Account Management. For instructions on modifying referrals, see "Setting Referrals".

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

  1. Open the custom editor for your entry as described in "Invoking the Custom Editor".

  2. Click on the Languages tab in the left-hand column.

  3. For user entries, you may set a preferred language using the drop-down list.

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

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

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

Modifying Entries With the Generic Editor

The generic editor allows you to see all readable attributes of an entry and edit its writable attributes, according to the bind DN used to log into the console. It allows 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:

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

  2. 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 will immediately remove 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

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

    2. Scroll through the list of attributes and click on the value you wish to modify.

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

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

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

    4. 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:

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

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

    3. Click the Add Value button. A new blank text field is displayed beside the attribute name in the list.

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

    5. 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:

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

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

    3. Click the Delete Value button. The text field containing the selected value is removed.

    4. 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:

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

    2. Make sure that the Show only Attributes with Values option is checked.

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

    4. In the Add Attribute dialog, select the one or more attribute you wish to add.

    5. 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 attribute value is binary data. Although you may store binary data in an attribute without the binary subtype, it indicates to clients that multiple variants of the attribute type may exist.

    6. Click OK once you have selected an attribute and its optional subtypes. The attribute is added alphabetically to the list in the generic editor.

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

    8. 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:

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

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


      3. 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 object class, the server will respond with an object class violation. Make sure your entry includes the required attributes for all object classes it defines.

    3. Click the Delete Attribute button. The attribute and all of its text field values are removed.

    4. 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:

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

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

    3. Click the Add Value button.

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

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

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

    6. 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:

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

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

    3. Click the Delete Value button. The specific object class is removed.

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

    4. 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:

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

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

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

      3. The Change Naming Attribute dialog is displayed.

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

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

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

    5. 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 the Directory Server console:

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

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

    2. 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 the Directory Server console, you may select multiple entries for deletion using Control+click or Shift+click combinations.

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

      4. 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 the Directory Server console:

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

    2. Import the LDIF file from the Directory Server console. See "Importing LDIF Files" for more information.

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

    Input to the command-line utilities is always in LDAP Data Interchange Format (LDIF) that you can provide either directly from the command-line or through an input file. LDIF is a textual representation of entries, attributes and their values. LDIF is a standard format described in RFC 2849 (http://www.ietf.org/rfc/rfc2849.txt). 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.

    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 one of the following, depending on your operating system:

    • UNIX - Almost always Control-D (^D).

    • Windows - Usually Control-Z followed by a carriage return (^Z<Return>).

    The following example shows how to terminate input to the ldapmodify command on a UNIX system:

    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.

    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:

    1. Set a new value for the nsslapd-maxbersize attribute of the cn=config entry.

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

    3. To do this from the command line, use the following command:

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

      For more information, see "nsslapd-maxbersize" in Chapter 4 of the Sun ONE Directory Server Reference Manual.

    4. Restart the server as described in "Starting and Stopping the 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 and how to avoid them, see Chapter 4, "ldapmodify," and Chapter 5, "ldapdelete," of the Sun ONE Directory Server Resource Kit Tools 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 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.

    Adding a Binary Attribute Value

    Binary attribute values are marked with the attribute;binary subtype. While the subtype is not required, it helps users and clients determine the contents of an attribute. 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: jpegphoto;binary
    jpegphoto;binary: < file:///path/filename.jpg

    The spaces before and after < are significant and must be used exactly as shown. 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 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.


    Caution

    Do not delete the suffix o=NetscapeRoot. The Sun ONE Administration Server uses this suffix to store information about installed Sun ONE servers. Deleting this suffix could force you to reinstall all of your Sun ONE servers, including the 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

    Setting Referrals

    You can use referrals to tell client applications which server to contact 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 server when a client requests a write operation.

    • You can create entries that are known as smart referrals. When a client specifically access a smart referral, the server will instead return the referral it defines. The Directory Server console automatically follows smart referrals, so 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 Appendix D, "LDAP URLs," in the Sun ONE Directory Server Reference Manual. For conceptual information on how you can use referrals in your directory deployment, see the Sun ONE Directory Server Deployment 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

    1. On the top-level Configuration tab of the Directory Server console, select the server node at the root of the configuration tree, and select the Network tab in the right-hand panel.

    2. Select the Return Referral checkbox and enter an LDAP URL in the text field. Alternatively, click Contstruct URL to be guided through the definition of an LDAP URL. An example of an LDAP URL to a secure port is:

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

    3. 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 referrals 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

    1. On the top-level Directory tab of the Directory Server console, expand the directory tree to display the entry that you wish to be the parent of the smart referral.

    2. Right-click the parent entry, 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.

      3. The custom editor for referrals is displayed.

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

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

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

    5. Click OK in the LDAP URL construction dialog. The URL is displayed in the new referral text box.

    6. Click Add beside the new referral text box to add the referral to the list.

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

    8. Click the Referral Authentication button to display a dialog where you may set the credentials that the 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.

    9. Use the Add, Edit, and Delete buttons to manage the list of servers and corresponding credentials. Then click OK when you are done.

    10. In the custom editor for referrals, click OK to save your smart referral entry.

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

    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 is a new feature in Sun ONE Directory Server 5.2 that 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 and decrypted before being returned in the clear. You should use other mechanisms such as ACIs to prevent LDAP clients from accessing forbidden data and SSL to encrypt communications. For an architectural overview of data security in general and attribute encryption in particular, please see Chapter 7, "Designing a Secure Directory," in the Sun ONE Directory Server Deployment 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 is 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.

    Configuring Attribute Encryption Using the Console

    1. Select the Configuration tab in the 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.

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

    2. To enable encryption for an attribute:

      1. Click the Add Attribute button to display a list of attributes.

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

      3. Select the Encryption Scheme for this attribute from the drop-down list next to the attribute name.

    3. To make an attribute no longer encrypted, select the attribute name from the table and click the Delete Attribute button.

    4. Click Save. You will be prompted to export the contents of the suffix to an LDIF file before the configuration change is made.

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

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

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

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

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

      1. Stop the directory server as described in "Starting and Stopping the Directory Server".

      2. As root or having administrator privileges, delete the database cache files from your file system:

        3. ServerRoot/slapd-serverID/db/__db.*

      3. Start the directory server again. The server will automatically new database cache files.

    Configuring Attribute Encryption From the Command Line

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

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

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

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

    3. To make an attribute no longer encrypted, use the ldapmodify command to modify the following configuration entry:

      4. 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 that the suffix is initialized.

    4. 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:

      1. Stop the directory server as described in "Starting and Stopping the Directory Server".

      2. As root or having administrator privileges, delete the database cache files from your file system:

        3. ServerRoot/slapd-serverID/db/__db.*

      3. Start the 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.

    5. Initialize the suffix with an LDIF file as described in "Importing Data". If you exported your suffix in Step 1, use that file to ensure your suffix has the latest contents. If you exported your suffix with encrypted attributes in Step 1, you must use that file to initialize now, because the encrypted values will be unretrievable once the suffix is reinitialized.

      6. 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 the directory server with other Sun ONE 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:

    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 or rename 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 the Directory Server console:

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

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

    2. Check the Enable plug-in check box to enable the plug-in, clear it to disable it.

    3. Set the value of Argument 1 to modify the update interval in seconds. Common values are:

      • 0 - Update immediately after every operation. Be advised that immediate referential integrity checks after every delete an modify operation may 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

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

      5. Argument 3 is not used but it must be present.

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


      6. Note

      For best performance, the attributes updated by the referential integrity plug-in should also be indexed. For information, see Chapter 10 "Managing Indexes."

    6. Click Save to save your changes.

    7. For your changes to be taken into account, you must restart the Directory Server.

    Using Referential Integrity with Replication

    There are certain limitations associated with the use of the referential integrity plug-in when it is needed 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:

    1. Make sure all replicas are configured and all replication agreements are defined.

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

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

    4. Ensure that the referential integrity plug-in is disabled on all consumer servers.

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