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.

During the planning phase of your directory deployment, you should characterize the types of data that your directory will contain. You should read Netscape Directory Server Deployment Guide before creating entries and modifying the default schema.

This chapter consists of the following sections:

Managing Entries from the Directory Console

You can use the Directory tab and the Property Editor on the Directory Server Console to add, modify, or delete entries individually.

If you want to add several entries simultaneously, you can use the command-line utilities described in Managing Entries from the Command-Line.

This section provides information about:

This section assumes some basic knowledge of object classes and attributes. For an introduction to object classes and attributes, refer to Netscape Directory Server Deployment Guide. For information on the definition and use of all schema provided with Netscape server products, refer to the Netscape Directory Server Schema Reference.


Note	You cannot modify your directory unless the appropriate access control rules have been set. For information on creating access control rules for your directory, see chapter 6, "Managing Access Control."

Creating a Root Entry

Each time you create a new database, you associate it with the suffix that will be stored in the database. The directory entry representing that suffix is not automatically created.

To create a root entry for a database:

In the Directory Server Console, select the Configuration tab.

For information on starting the Directory Server Console, refer to Using the Directory Server Console.
Create a new database, as explained in Creating and Maintaining Databases.
In the Directory tab, right-click the top object representing the Directory Server, and choose New Root Object.

The secondary menu under New Root Object displays a list of suffixes that do not have a corresponding entry.
Choose the suffix corresponding to the entry that you want to create.

The New Object window is displayed.
In the New Object window, select the object class corresponding to the new entry.

The object class you select must contain the attribute you used to name the suffix. For example, if you are creating the entry corresponding to the suffix ou=people,dc=example,dc=com, then you can choose the organizationalUnit object class or another object class that allows the ou attribute.
Click OK in the New Object window.

The Property Editor for the new entry is displayed. You can either accept the current values by clicking OK or modify the entry, as explained in Modifying Directory Entries.

Creating Directory Entries

Directory Server Console offers several predefined templates for creating directory entries. Templates are available for the following types of entries:

User
Group
Organizational Unit
Role
Class of Service

Table 2-1 shows what type of object class is used for each template.

Table 2-1 Entry Templates and Corresponding Object Classes


Template	Object Class
User	inetOrgPerson
Group	groupOfUniqueNames
Organizational Unit	organizationalUnit
Role	nsRoleDefinition
Class of Service	cosSuperDefinition

These templates contain fields representing all the mandatory attributes and some of the commonly used optional attributes. To create an entry using one of these templates, refer to Creating an Entry Using a Predefined Template. To create any other type of entry, refer to Creating Other Types of Entries.

Creating an Entry Using a Predefined Template

In the Directory Server Console, select the Directory tab.

For information on starting the Directory Server Console, refer to Using the Directory Server Console.
Right-click the entry in the left pane under which you want to add the new entry, and select the appropriate type of entry: User, Group, Organizational Unit, Role, Class of Service, or Other.

The corresponding Create window is displayed.
Supply values for all of the mandatory attributes (identified by an asterisk), and, if you want, for any of the optional attributes.

The Create window does not provide fields for all optional attributes.
To display the full list of attributes, click the Advanced button.The Property Editor is displayed. Refer to Modifying Directory Entries for information on using the Property Editor.
Click OK to dismiss the Create window.

The new entry is displayed in the right pane.

Creating Other Types of Entries

In the Directory Server Console, select the Directory tab.

For information on starting the Directory Server Console, refer to Using the Directory Server Console.
Right-click the entry in the left pane under which you want to add the new entry, and select Other.
The New Object window is displayed.
In the object class list, select an object class that defines your new entry.
Click OK.

If you selected an object class related to a type of entry for which a predefined template is available, the corresponding Create window is displayed. (See Creating an Entry Using a Predefined Template).

In all other cases, the Property Editor is displayed. It contains a list of mandatory attributes.
Supply a value for all the listed attributes.

Some fields are empty, but some might have a generic placeholder value (such as New), which you should replace with a meaningful value for your entry.

Some object classes can have several naming attributes. Remember to select the naming attribute you want to use to name your new entry.

To provide values for optional attributes that are not listed, refer to Modifying Directory Entries.
Click OK to save the new entry and dismiss the Property Editor window.

The new entry is displayed in the right pane.

Modifying Directory Entries

To modify directory entries from Directory Server Console, you must start the Property Editor. The Property Editor contains the list of object classes and attributes belonging to an entry.

From the Property Editor, you can:

Add an object class to an entry.
Remove an object class from an entry.
Add an attribute to an entry.
Add an attribute value to an entry.
Remove an attribute value from an entry.
Add an attribute subtype to an entry.

This section describes how to start the Property Editor and how to use it to modify an entry's attributes and attribute values.

Displaying the Property Editor

You can start the Property Editor in several ways:

From the Directory tab, by right-clicking an entry in the left or right pane, and selecting Properties from the pop-up menu.
From the Directory tab, by double-clicking an entry in the left or right pane.
From the Create User, Group, Organizational Unit, Role, and Class of Service templates, by clicking the Advanced button (see Creating an Entry Using a Predefined Template).
From the New Object window, by clicking OK (see Creating Other Types of Entries).

Adding an Object Class to an Entry

To add an object class to an entry:

In the Directory tab of the Directory Server Console, right-click the entry you want to modify, and select Advanced from the pop-up menu.

You can also double-click the entry. The Property Editor is displayed; click on the Advanced button.
Select the object class field, and click Add Value.

The Add Object Class window is displayed. It shows a list of object classes that you can add to the entry.
Select the object class you want to add, and click OK.

The object class you selected appears in the list of object classes in the Advanced Property Editor. To dismiss the Add Object Class window, click Cancel.
Click OK in the Advanced Property Editor when you have finished editing the entry. The Advanced Property Editor is dismissed.

Click OK in the Property Editor. The Property Editor is dismissed.

Removing an Object Class

To remove an object class from an entry:

In the Directory tab of the Directory Server Console, right-click the entry you want to modify, and select Advanced from the pop-up menu.

You can also double-click the entry. The Property Editor is displayed; click on the Advanced button.
Click the cursor in the text box that shows the object class you want to remove, and click Delete Value.
Click OK in the Advanced Property Editor when you have finished editing the entry. The Advanced Property Editor is dismissed.

Click OK in the Property Editor. The Property Editor is dismissed.

Adding an Attribute to an Entry

Before you can add an attribute to an entry, the entry must contain an object class that either requires or allows the attribute. See Adding an Object Class to an Entry and chapter 9, "Extending the Directory Schema," for more information.

To add an attribute to an entry:

In the Directory tab of the Directory Server Console, right-click the entry you want to modify, and select Advanced from the pop-up menu.

You can also double-click the entry. The Property Editor is displayed; click on the Advanced button.
Click Add Attribute.

The Add Attribute dialog box is displayed.
Select the attribute you want to add from the list, and click OK.

The Add Attribute window is dismissed, and the attribute you selected appears in the list of attributes in the Advanced Property Editor.
Type in the value for the new attribute in the text box to the right of the attribute name.
Click OK in the Advanced Property Editor when you have finished editing the entry. The Advanced Property Editor is dismissed.

Click OK in the Property Editor. The Property Editor is dismissed.

Adding Very Large Attributes

The configuration attribute nsslapd-maxbersize sets the maximum size limit for LDAP requests. The default configuration of Directory Server sets this attribute at 2Mbytes. LDAP add or modify operations will fail when attempting to add very large attributes that result in a request that is larger than 2Mbytes.

To add very large attributes, you must first change the setting for the nsslapd-maxbersize configuration attribute to a value larger than the largest LDAP request you will make.

When determining the value to set, you must consider all elements of the LDAP add and modify operations used to add the attributes, not just the single attribute. The list of what is included in determining this size is as follows:

The size of each attribute name in the request.
The size of the values of each of the attributes in the request.
The size of the DN in the request.
Some overhead (10Kbytes should be sufficient).

For further information about the nsslapd-maxbersize attribute and for information about setting this attribute, see the section "nsslapd-maxbersize (Maximum Message Size)" in Netscape Directory Server Configuration, Command, and File Reference.

Adding Attribute Values

When an entry contains multi-valued attributes, you can supply multiple values for these attributes.

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

In the Directory tab of the Directory Server Console, right-click the entry you want to modify, and select Advanced from the pop-up menu.

You can also double-click the entry. The Property Editor is displayed; click on the Advanced button.
Select the attribute to which you want to add a value, and then click Add Value.

A new blank text field is displayed in the right column.
Type in the name of the new attribute value.
Click OK in the Advanced Property Editor when you have finished editing the entry. The Advanced Property Editor is dismissed.

Click OK in the Property Editor. The Property Editor is dismissed.

Removing an Attribute Value

To remove an attribute value from an entry:

In the Directory tab of the Directory Server Console, right-click the entry you want to modify, and select Advanced from the pop-up menu.

You can also double-click the entry. The Property Editor is displayed; click on the Advanced button.
Click the cursor in the text box that contains the attribute value you want to remove, and click Delete Value.

If you want to remove the entire attribute and all its values from the entry, select Delete Attribute from the Edit menu.
Click OK in the Advanced Property Editor when you have finished editing the entry. The Advanced Property Editor is dismissed.

Click OK in the Property Editor. The Property Editor is dismissed.

Adding an Attribute Subtype

You can add three different kinds of subtypes to attributes contained within an entry: language, binary, and pronunciation.

Language Subtype

Sometimes a user's name can be more accurately represented in characters of a language other than the default language. For example, Noriko's name is Japanese, and she prefers that her name be represented by Japanese characters when possible. You can select Japanese as a language subtype for the givenname attribute so that other users can search for her Japanese name.

If you specify a language subtype for an attribute, the subtype is added to the attribute name as follows:

attribute;lang-subtype

attribute is the attribute you are adding to the entry and subtype is the two character abbreviation for the language. See Table D-2 for a list of supported language subtypes. For example:

givenname;lang-ja

You can assign only one language subtype per attribute instance in an entry. To assign multiple language subtypes, add another attribute instance to the entry, and then assign the new language subtype. For example, the following is illegal:

cn;lang-ja;lang-en-GB:Smith

Instead, use:

cn: lang-ja: ja_value
cn: lang-en-GB: en-GB_value

Binary Subtype

Assigning the binary subtype to an attribute indicates that the attribute value is binary. For example, usercertificate;binary.

Although you can store binary data within an attribute that does not contain the binary subtype (for example, jpegphoto), the binary subtype indicates to clients that multiple variants of the attribute type may exist.

Pronunciation Subtype

Assigning the pronunciation subtype to an attribute indicates that the attribute value is a phonetic representation. The subtype is added to the attribute name as follows: attribute;phonetic.

This subtype is commonly used in combination with a language subtype for languages that have more than one alphabet, where one is a phonetic representation.

You might want to use this with attributes that are expected to contain user names, such as cn or givenname. For example, givenname;lang-ja;phonetic indicates that the attribute value is the phonetic version of the entry's Japanese name.

To Add a Subtype Using the Property Editor

In the Directory tab of the Directory Server Console, right-click the entry you want to modify, and select Advanced from the pop-up menu.

You can also double-click the entry. The Property Editor is displayed; click on the Advanced button.
Click Add Attribute.

The Add Attribute dialog box displays.
Select the attribute you want to add from the list.
To assign a language subtype to the attribute, select it from the Language drop-down list.
From the Subtype drop-down list, you can also assign one of two other subtypes, binary or pronunciation.
Click OK.

The Add Attribute window is dismissed.
When you have finished defining the information for the entry, click OK in the Advanced Property Editor. The Advanced Property Editor is dismissed.

Click OK in the Property Editor. The Property Editor is dismissed.

Deleting Directory Entries

To delete entries using the Directory Server Console:

In the Directory Server Console, select the Directory tab.

For information on starting the Directory Server Console, refer to Using the Directory Server Console.
Right-click the entry you want to delete in the navigation tree or in the right pane, and select Delete from the pop-up menu.

To select multiple entries, use Ctrl+click or Shift+click, and then select Delete from the Edit menu.

The server deletes the entry or entries immediately. There is no undo.

Managing Entries from the Command-Line

The command-line utilities allow you to manipulate the contents of your directory. They can be useful if you want to write scripts to perform bulk management of your directory or to test your Directory Server. For example, you might want to ensure that it returns the expected information after you have made changes to access control information.

Using the command-line utilities, you can provide information directly from the command-line or through an input file in LDIF.

This section provides information about:


Note	You cannot modify your directory unless the appropriate access control rules have been set. For information on creating access control rules for your directory, see chapter 6, "Managing Access Control."

Providing Input from the Command-Line

When you provide input to the ldapmodify and ldapdelete utilities directly from the command-line, you must use LDIF statements. For detailed information on LDIF statements, refer to LDIF Update Statements.

The ldapmodify and ldapdelete utilities read the statements that you enter 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. The utility then begins operations based on the input you supplied.

Typically, the EOF escape sequence is one of the following, depending upon the type of machine you use:

UNIX -- Almost always control-D (^D).
Windows -- Usually control-Z followed by a carriage return (^Z<return>)

For example, suppose you want to input some LDIF update statements to ldapmodify. Then, on a UNIX system, you would do the following:

prompt> ldapmodify -D bindDN -w password -h hostname
> dn: cn=Barry Nixon, ou=people, dc=example,dc=com
> changetype: modify
> delete: telephonenumber
> -
> add: manager
> manager: cn=Harry Cruise, ou=people, dc=example,dc=com
> ^D
prompt>

When you add an entry from the command-line or from LDIF, make sure that an entry representing a subtree is created before new entries are created under that branch. For example, if you want to place an entry in a People subtree, then create an entry representing that subtree before creating entries within the subtree.

For example:

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

Creating a Root Entry from the Command-Line

You can use the ldapmodify command-line utility to create a new root entry in a database. For example, you might add the new root entry as follows:

prompt> ldapmodify -a -D bindDN -w password

The ldapmodify utility binds to the server and prepares it to add an entry.

You create the new root object as follows:

dn: Suffix_Name
objectclass: newobjectclass

The DN corresponds to the DN of the root or sub-suffix contained by the database. The newobjectclass value depends upon the type of object class you are adding to the database. You may need to specify additional mandatory attributes depending upon the root object you add.


Note	You can use this method only if you have one database per suffix. If you create a suffix that is stored in several databases, you must use the ldif2db utility with the -n option to specify the database that will hold the new entries. For information, refer to Importing from the Command-Line.

Adding Entries Using LDIF

You can use an LDIF file to add multiple entries or to import an entire database. To add entries using an LDIF file and the Directory Server Console:

Define the entries in an LDIF file.

LDIF is described in Appendix A, "LDAP Data Interchange Format."
Import the LDIF file from the Directory Server Console.

See Importing a Database from the Console, for information. When you import the LDIF file, select "Append to database" on the Import dialog box so that the server will only import entries that do not currently exist in the directory.

You can also add entries described in an LDIF file from the command-line using the ldapmodify command with the -f option.

Adding and Modifying Entries Using ldapmodify

You use the ldapmodify command to add and modify entries in an existing Directory Server database. The ldapmodify command opens a connection to the specified server using the distinguished name and password you supply and modifies the entries based on LDIF update statements contained in a specified file. Because ldapmodify uses LDIF update statements, ldapmodify can do everything that ldapdelete can do.

If schema checking is turned on when you use this utility, then the server performs schema checking for the entire entry when it is modified:

If the server detects an attribute or object class in the entry that is not known to the server, then the modify operation will fail when it reaches the erroneous entry. All entries that were processed before the error was encountered will be successfully added or modified. If you run ldapmodify with the -c option (do not stop on errors), all correct entries processed after the erroneous entry will be successfully added or modified.
If a required attribute is not present, the modify operation fails. This happens even if the offending object class or attribute is not being modified. This situation can occur if you run the Directory Server with schema checking turned off, add unknown object classes or attributes, and then turn schema checking on.

For more information, see Turning Schema Checking On and Off.

To create a database suffix (such as dc=example,dc=com) using ldapmodify, you must bind to the directory as the Directory Manager.

Adding Entries Using ldapmodify

Here is a typical example of how to use the ldapmodify utility to add entries to the directory. Suppose that:

You want to create the entries specified in the file new.ldif.
You have created a database administrator who has the authority to modify the entries and whose distinguished name is cn=Directory Manager,dc=example,dc=com.
The database administrator's password is King-Pin.
The server is located on cyclops.
The server uses port number 845.

In this example, the LDIF statements in the new.ldif file do not specify a change type. They follow the format defined in LDIF File Format.

To add the entries, you must enter the following command:

ldapmodify -a -D "cn=Directory Manager,dc=example,dc=com" -w King-Pin -h cyclops -p 845 -f new.ldif

The following table describes the ldapmodify parameters used in the example:

Table 2-2 Description of ldapmodify Parameters Used for Adding Entries


Parameter Name	Description
-a	Specifies that the modify operation will add new entries to the directory.
-D	Specifies the distinguished name with which to authenticate to the server. The value must be a DN recognized by the Directory Server, and it must also have the authority to modify the entries.
-w	Specifies the password associated with the distinguished name specified in the -D parameter.
-h	Specifies the name of the host on which the server is running.
-p	Specifies the port number that the server uses.
-f	Optional parameter that specifies the file containing the LDIF update statements used to define the modifications. If you do not supply this parameter, the update statements are read from stdin. For information on supplying LDIF update statements from the command-line, refer to Providing Input from the Command-Line.

For full information on ldapmodify parameters, refer to the Netscape Directory Server Configuration, Command, and File Reference.

Modifying Entries Using ldapmodify

Here is a typical example of how to use the ldapmodify utility to modify entries that are present in the directory. Suppose that:

You want to modify entries as specified in the file modify_statements.
You have created a database administrator that has the authority to modify the entries and whose distinguished name is cn=Directory Manager, dc=example,dc=com.
The database administrator's password is King-Pin.
The server is located on cyclops.
The server uses port number 845.

To modify the entries, you must first create the modify_statements file with the appropriate LDIF update statements and then enter the following command:

ldapmodify -D "cn=Directory Manager,dc=example,dc=com" -w King-Pin -h cyclops -p 845 -f modify_statements

The following table describes the ldapmodify parameters used in the example:

Table 2-3 Description of ldapmodify Parameters Used for Modifying Entries


Parameter Name	Description
-D	Specifies the distinguished name with which to authenticate to the server. The value must be a DN recognized by the Directory Server, and it must also have the authority to modify the entries.
-w	Specifies the password associated with the distinguished name specified in the -D parameter.
-h	Specifies the name of the host on which the server is running.
-p	Specifies the port number that the server uses.
-f	Optional parameter that specifies the file containing the LDIF update statements used to define the modifications. If you do not supply this parameter, the update statements are read from stdin. For information on supplying LDIF update statements from the command-line, refer to Providing Input from the Command-Line.

For full information on ldapmodify parameters, refer to the Netscape Directory Server Configuration, Command, and File Reference.

Deleting Entries Using ldapdelete

Use the ldapdelete command-line utility to delete entries from the directory. This utility opens a connection to the specified server using the distinguished name and password you provide and deletes the entry or entries.

You can only delete entries at the end of a branch. You cannot delete entries that are branch points in the directory tree.

For example, of the following three entries:

ou=People,dc=example,dc=com
cn=Paula Simon,ou=People,dc=example,dc=com
cn=Jerry O'Connor,ou=People,dc=example,dc=com

you can delete only the last two entries. The entry that identifies the People subtree can be deleted only if there aren't any entries below it. If you want to delete ou=People,dc=example,dc=com, you must first delete Paula Simon and Jerry O'Connor's entries and all other entries in that subtree.

Here is a typical example of how to use the ldapdelete utility. Suppose that:

You want to delete the entries identified by the distinguished names cn=Robert Jenkins,ou=People,dc=example,dc=com and cn=Lisa Jangles,ou=People,dc=example,dc=com.
You have created a database administrator that has the authority to modify the entries, and whose distinguished name is cn=Directory Manager,dc=example,dc=com.
The database administrator's password is King-Pin.
The server is located on cyclops.
The server uses port number 845.

To delete the entries for users Robert Jenkins and Lisa Jangles, enter the following command:

ldapdelete -D "cn=Directory Manager,dc=example,dc=com" -w King-Pin -h cyclops -p 845 "cn=Robert Jenkins,ou=People,dc=example,dc=com" "cn=Lisa Jangles,ou=People,dc=example,dc=com"

The following table describes the ldapdelete parameters used in the example:

Table 2-4 Description of ldapdelete Parameters Userd for Deleting Entries


Parameter Name	Description
-D	Specifies the distinguished name with which to authenticate to the server. The value must be a DN recognized by the Directory Server, and it must also have the authority to modify the entries.
-w	Specifies the password associated with the distinguished name specified in the -D parameter.
-h	Specifies the name of the host on which the server is running.
-p	Specifies the port number that the server uses.

For full information on ldapdelete parameters, refer to the Netscape Directory Server Configuration, Command, and File Reference.

Using Special Characters

When using the Directory Server command-line client tools, 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 this situation occurs, enclose the value in quotation marks (""). For example:

-D "cn=Barbara Jensen,ou=Product Development,dc=example,dc=com"

Depending on the command-line utility you use, 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."

To delete user Patricia Fuentes from the example.com Bolivia, S.A. tree, you would enter the following command:

ldapdelete -D "cn=Directory Manager,dc=example,dc=com" -w King-Pin -h cyclops -p 845 "cn=Patricia Fuentes,ou=People,o=example.com Bolivia\,S.A."

LDIF Update Statements

Use LDIF update statements to define how ldapmodify should change your directory. In general, LDIF update statements are a series of statements that:

Specify the distinguished name of the entry to be modified.
Specify a change type that defines how a specific entry is to be modified (add, delete, modify, modrdn).
Specify a series of attributes and their changed values.

A change type is required unless you use ldapmodify with the -a parameter. If you specify the -a parameter, then an add operation (changetype: add) is assumed. However, any other change type overrides the -a parameter.

If you specify a modify operation (changetype: modify), a change operation is required that indicates how the entry should be changed.

If you specify changetype: modrdn, change operations are required that specify how the relative distinguished name (RDN) is to be modified. A distinguished name's RDN is the left-most value in the DN. For example, the distinguished name uid=ssarette,dc=example,dc=com has an RDN of uid=ssarette.

The general format of LDIF update statements is as follows:

dn: distinguished_name
changetype_identifier
change_operation_identifier
list_of_attributes

change_operation_identifier
list_of_attributes
-

A dash (-) must be used to denote the end of a change operation if subsequent change operations are specified. For example, the following statement adds the telephone number and manager attributes to the entry:

dn: cn=Lisa Jangles,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: (408) 555-2468
-
add: manager
manager: cn=Harry Cruise,ou=People,dc=example,dc=com

In addition, the line continuation operator is a single space. Therefore, the following two statements are identical:

dn: cn=Lisa Jangles,ou=People,dc=example,dc=com

dn: cn=Lisa Jangles,
ou=People,
dc=example,dc=com

The following sections describe the change types in detail.

Adding an Entry Using LDIF

Use changetype: add to add an entry to your directory. When you add an entry, make sure to create an entry representing a branch point before you try to create new entries under that branch. That is, if you want to place an entry in a People and a Groups subtree, then create the branch point for those subtrees before creating entries within the subtrees.

The following LDIF update statements can be used to create the People and the Groups subtrees and then to create entries within those trees:

dn: dc=example,dc=com
changetype: add
objectclass: top
objectclass: organization
o: example.com

dn: ou=People, dc=example,dc=com
changetype: add
objectclass: top
objectclass: organizationalUnit
ou: People
ou: Marketing

dn: cn=Pete Minsky,ou=People,dc=example,dc=com
changetype: add
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Pete Minsky
givenName: Pete
sn: Minsky
ou: People
ou: Marketing
uid: pminsky

dn: cn=Sue Jacobs,ou=People,dc=example,dc=com
changetype: add
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Sue Jacobs
givenName: Sue
sn: Jacobs
ou: People
ou: Marketing
uid: sjacobs

dn: ou=Groups,dc=example,dc=com
changetype: add
objectclass: top
objectclass: organizationalUnit
ou: Groups

dn: cn=Administrators,ou=Groups,dc=example,dc=com
changetype: add
objectclass: top
objectclass: groupOfNames
member: cn=Sue Jacobs,ou=People,dc=example,dc=com
member: cn=Pete Minsky,ou=People,dc=example,dc=com
cn: Administrators

dn: ou=example.com Bolivia\, S.A.,dc=example,dc=com
changetype: add
objectclass: top
objectclass: organizationalUnit
ou: example.com Bolivia\, S.A.

dn: cn=Carla Flores,ou=example.com Bolivia\, S.A.,dc=example,dc=com
changetype: add
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Carla Flores
givenName: Carla
sn: Flores
ou: example.com Bolivia\, S.A.
uid: cflores

Renaming an Entry Using LDIF

Use changetype:modrdn to change an entry's relative distinguished name (RDN). An entry's RDN is the left-most element in the distinguished name. Therefore, the RDN for

cn=Barry Nixon,ou=People,dc=example,dc=com

cn=Barry Nixon

And the RDN for

ou=People,dc=example,dc=com

ou=People

Therefore, this rename operation allows you to change the left-most value in an entry's distinguished name.

For example, the entry

cn=Sue Jacobs,ou=People,dc=example,dc=com

can be modified to be

cn=Susan Jacobs,ou=People,dc=example,dc=com

but it cannot be modified to be

cn=Sue Jacobs,ou=old employees,dc=example,dc=com

The following example can be used to rename Sue Jacobs to Susan Jacobs:

dn: cn=Sue Jacobs,ou=Marketing,dc=example,dc=com
changetype: modrdn
newrdn: cn=Susan Jacobs
deleteoldrdn: 0

Because deleteoldrdn is 0, this example retains the existing RDN as a value in the new entry. The resulting entry would therefore have a common name (cn) attribute set to both Sue Jacobs and Susan Jacobs, in addition to all the other attributes included in the original entry. However, if you used

dn: cn=Sue Jacobs,ou=Marketing,dc=example,dc=com
changetype: modrdn
newrdn: cn=Susan Jacobs
deleteoldrdn: 1

the server would delete cn=Sue Jacobs, and only cn=Susan Jacobs would remain within the entry.

A Note on Renaming Entries

You cannot rename an entry with the modrdn change type such that the entry moves to a completely different subtree. To move an entry to a completely different branch, you must create a new entry in the alternative subtree using the old entry's attributes, and then delete the old entry.

Also, for the same reasons that you cannot delete an entry if it is a branch point, you cannot rename an entry if it has any children. Doing so would orphan the children in the tree, which is not allowed by the LDAP protocol. For example, of the following three entries:

ou=People,dc=example,dc=com
cn=Paula Simon,ou=People,dc=example,dc=com
cn=Jerry O'Connor,ou=People,dc=example,dc=com

you can rename only the last two entries. The entry that identifies the People subtree can be renamed only if no other entries exist below it.

Modifying an Entry Using LDIF

Use changetype:modify to add, replace, or remove attributes and/or attribute values to the entry. When you specify changetype:modify, you must also provide a change operation to indicate how the entry is to be modified. Change operations can be as follows:

add: attribute

Adds the specified attribute or attribute value. If the attribute type does not currently exist for the entry, then the attribute and its corresponding value are created. If the attribute type already exists for the entry, then the specified attribute value is added to the existing value. If the particular attribute value already exists for the entry, then the operation fails, and the server returns an error.

replace: attribute

The specified values are used to entirely replace the attribute's value(s). If the attribute does not already exist, it is created. If no replacement value is specified for the attribute, the attribute is deleted.

delete: attribute

The specified attribute is deleted. If more than one value of an attribute exists for the entry, then all values of the attribute are deleted in the entry. To delete just one of many attribute values, specify the attribute and associated value on the line following the delete change operation.

This section contains the following topics:

Adding Attributes to Existing Entries Using LDIF

You use changetype:modify with the add operation to add an attribute and an attribute value to an entry.

For example, the following LDIF update statement adds a telephone number to the entry:

dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: 555-1212

The following example adds two telephone numbers to the entry:

dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: 555-1212
telephonenumber: 555-6789

The following example adds two telephonenumber attributes and a manager attribute to the entry:

dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: 555-1212
telephonenumber: 555-6789
-
add: manager
manager: cn=Sally Nixon,ou=People,dc=example,dc=com

The following example adds a jpeg photograph to the directory. The jpeg photo can be displayed by Directory Server Gateway. In order to add this attribute to the directory, you must use the ldapmodify -b parameter, which indicates that ldapmodify should read the referenced file for binary values if the attribute value begins with a slash:

dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
add: jpegphoto
jpegphoto: /path/to/photo

You can also add a jpeg photograph to the directory using the following standard LDIF notation:

jpegphoto: < file:/path/to/photo

If you use this standard notation, you do not need to specify the ldapmodify -b parameter. However, you must add the following line to the beginning of your LDIF file or your LDIF update statements:

version:1

For example, you could use the following ldapmodify command:

prompt> ldapmodify -D userDN -w user_password

>version: 1
>dn: cn=Barney Fife,ou=People,dc=example,dc=com
>changetype: modify
>add: userCertificate
>userCertificate;binary:< file: BarneysCert

Note

You can use the standard LDIF notation only with the ldapmodify command, not with other command-line utilities.

Changing an Attribute Value Using LDIF

Use changetype:modify with the replace operation to change all values of an attribute in an entry.

For example, the following LDIF update statement changes Barney's manager from Sally Nixon to Wally Hensford:

dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
replace: manager
manager: cn=Wally Hensford, ou=People, dc=example,dc=com

If the entry has multiple instances of the attribute, then, to change one of the attribute values, you must delete the attribute value that you want to change, and then add the replacement value. For example, consider the following entry:

cn=Barney Fife,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
cn: Barney Fife
sn: Fife
telephonenumber: 555-1212
telephonenumber: 555-6789

To change the telephone number 555-1212 to 555-4321, use the following LDIF update statement:

dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
delete: telephonenumber
telephonenumber: 555-1212
-
add: telephonenumber
telephonenumber: 555-4321

Barney's entry is now as follows:

cn=Barney Fife,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
cn: Barney Fife
sn: Fife
telephonenumber: 555-6789
telephonenumber: 555-4321

Deleting All Values of an Attribute Using LDIF

Use changetype:modify with the delete operation to delete an attribute from an entry. If the entry has more than one instance of the attribute, you must indicate which of the attributes you want to delete.

For example, the following LDIF update statement deletes all instances of the telephonenumber attribute from the entry, regardless of how many times it appears in the entry:

dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
delete: telephonenumber

If you want to delete just a specific instance of the telephonenumber attribute, then you simply delete that specific attribute value. The following section describes how to do this.

Deleting a Specific Attribute Value Using LDIF

Use changetype:modify with the delete operation to delete an attribute value from an entry.

For example, consider the following entry:

cn=Barney Fife,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
cn: Barney Fife
sn: Fife
telephonenumber: 555-1212
telephonenumber: 555-6789

To delete the 555-1212 telephone number from this entry, use the following LDIF update statement:

dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
delete: telephonenumber
telephonenumber: 555-1212

Barney's entry then becomes:

cn=Barney Fife,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
cn: Barney Fife
sn: Fife
telephonenumber: 555-6789

Deleting an Entry Using LDIF

Use changetype:delete to delete an entry from your directory. You can only delete leaf entries. Therefore, when you delete an entry, make sure that no other entries exist under that entry in the directory tree. That is, you cannot delete an organizational unit entry unless you have first deleted all the entries that belong to the organizational unit.

For example, of the following three entries:

ou=People,dc=example,dc=com
cn=Paula Simon,ou=People,dc=example,dc=com
cn=Jerry O'Connor,ou=People,dc=example,dc=com

you can delete only the last two entries. The entry that identifies the People subtree can be deleted only if no other entries exist below it.

The following LDIF update statements can be used to delete person entries:

dn: cn=Pete Minsky,ou=People,dc=example,dc=com
changetype: delete

dn: cn=Sue Jacobs,ou=People,dc=example,dc=com
changetype: delete


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

Modifying an Entry in an Internationalized Directory

If the attribute values in your directory are associated with one or more languages other than English, the attribute values are associated with language tags. When using the ldapmodify command-line utility to modify an attribute that has an associated language tag, you must match the value and language tag exactly or the modify operation will fail.

For example, if you want to modify an attribute value that has a language tag of lang-fr, you must include the lang-fr in the modify operation as follows:

dn: bjensen,dc=example,dc=com
changetype: modify
replace: homePostalAddress;lang-fr
homePostalAddress;lang-fr: 34 rue de Seine

Maintaining Referential Integrity

Referential integrity is a database mechanism that ensures relationships between related entries are maintained. In the Directory Server, referential integrity can be used to ensure that an update to one entry in the directory is correctly reflected in any other entries that may refer to the updated entry.

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 remains a member of the group until manually removed by the administrator. This is an important feature if you are integrating the Directory Server with other Netscape products that rely on the directory for user and group management.

How Referential Integrity Works

When the Referential Integrity Plug-in (see Referential Integrity Postoperation 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.


Note	The Referential Integrity Plug-in should only be enabled on one supplier replica in a multi-master replication environment to avoid conflict resolution loops. When enabling the plug-in on servers issuing chaining requests, be sure to analyze your performance resource and time needs, as well as your integrity needs. Integrity checks can be time-consuming and draining on memory/CPU.

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.

By default, when the referential integrity plug-in is enabled, it performs integrity updates on the member, uniquemember, owner, and seeAlso attributes immediately after a delete or rename operation. You can, however, configure the behavior of the referential integrity plug-in to suit your own needs. You can do any of the following:

Record referential integrity updates in the replication change log.
Modify the update interval.
Select the attributes to which you apply referential integrity.
Disable referential integrity.

Using Referential Integrity with Replication

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

You should never enable it on a dedicated consumer server (a server that contains only read-only replicas).
You should never enable it on a server that contains a combination of read-write and read-only replicas.
You can enable it on a supplier server that contains only read-write replicas.
In the context of multi-master replication, you should enable it on just one supplier.

Configuring the Supplier Server

When your replication environment satisfies the conditions listed above, you can enable the Referential Integrity Plug-in.

Enable the Referential Integrity Plug-in.

This task is described in Enabling/Disabling Referential Integrity.
Configure the plug-in to record any integrity updates in the change log.

This task is described in Recording Updates in the Change Log.
Ensure that the Referential Integrity Plug-in is disabled on all consumer servers.


Note	Because the supplier server sends any changes made by the Referential Integrity Plug-in to consumer servers, it is unnecessary to run the Referential Integrity Plug-in on consumer servers.

Enabling/Disabling Referential Integrity

You can enable or disable referential integrity from the Directory Server Console or from the command-line.

From the Directory Server Console

In the Directory Server Console, select the Configuration tab.

For information on starting the Directory Server Console, refer to Using the Directory Server Console.
Expand the Plugins folder in the navigation tree, and select the Referential Integrity Postoperation plugin.

The settings for the plugin are displayed in the right pane.
Check the Enable plugin check box to enable the plugin; clear it to disable it.
Click Save to save your changes.
For your changes to be taken into account, go to the Tasks tab, and select Restart the Directory Server.

Recording Updates in the Change Log

You can decide to record updates in the replication change log instead of recording them in the default location, the referint file in the serverRoot/slapd-serverID/logs directory. You must do this if you want referential integrity updates to be replicated to consumer servers in the context of replication.

You can make this change from the Directory Server Console.

From the Directory Server Console

In the Directory Server Console, select the Configuration tab.

For information on starting the Directory Server Console, refer to Using the Directory Server Console.
Expand the Plugins folder in the navigation tree, and select the Referential Integrity Post-operation plug-in.

The settings for the plug-in are displayed in the right pane.
In the arguments list, replace the referint filename with the absolute path to the change log directory.
Click Save to save your changes.
For your changes to be taken into account, go to the Tasks tab, and select Restart the Directory Server.

Modifying the Update Interval

By default, the server makes referential integrity updates immediately after a delete or a modrdn operation. If you want to reduce the impact this operation has on your system, you may want to increase the amount of time between updates. Although there is no maximum update interval, the following intervals are commonly used:

Update immediately.
90 seconds (updates occur every 90 seconds).
3600 seconds (updates occur every hour).
10,800 seconds (updates occur every 3 hours).
28,800 seconds (updates occur every 8 hours).
86,400 seconds (updates occur once a day).
604,800 seconds (updates occur once a week).

You can modify the update interval from the Directory Server Console.

From the Directory Server Console

In the Directory Server Console, select the Configuration tab.

For information on starting the Directory Server Console, refer to Using the Directory Server Console.
Expand the Plugins folder in the navigation tree, and select the Referential Integrity Post-operation plug-in.

The settings for the plug-in are displayed in the right pane.
In the arguments list, replace the value in the first text box with the appropriate time interval.
Click Save to save your changes.
For your changes to be taken into account, go to the Tasks tab, and select Restart the Directory Server.

Modifying the Attribute List

By default, the referential integrity plug-in is set up to check for and update the member, uniquemember, owner, and seeAlso attributes. You can add or delete attributes to be updated from the Directory Server Console. For example, you may add the nsroledn attribute if roles are being used.

Keep in mind that any attribute specified in referential integrity plug-in parameter list needs to have equality indexing on all databases. Otherwise, the plug-in scans every entry of the databases for matching the deleted or modified DN, degrading performance severely. If you add an attribute, ensure that it is indexed in all the backends.

You can improve the performance by removing any unused attributes from the list.

From the Directory Server Console

In the Directory Server Console, select the Configuration tab.

For information on starting the Directory Server Console, refer to Using the Directory Server Console.
Expand the Plugins folder in the navigation tree, and select the Referential Integrity Postoperation plugin.

The settings for the plug-in are displayed in the right pane.
In the Arguments section, use the Add and Delete buttons to modify the attributes in the list.
Click Save to save your changes.
For your changes to be taken into account, go to the Tasks tab, and select Restart the Directory Server.


Note	For best performance, the attributes set for updating should also be indexed. For information on indexing, see chapter 10, "Managing Indexes."

Contents

Index

DocHome

© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2004 Netscape Communications Corporation. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.

last updated November 26, 2004