2.4. LDIF Update Statements

2.4. LDIF Update Statements

LDIF update statements define how ldapmodify changes the directory entry. In general, LDIF update statements contain the following information:

A change type is required unless ldapmodify is run 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: 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.

2.4.1. Adding an Entry Using LDIF

changetype: add adds an entry to the 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, 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. For example:

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

2.4.2. Renaming an Entry Using LDIF

changetype: modrdn changes an entry's relative distinguished name (RDN). An entry's RDN is the left-most element in the distinguished name. The RDN for cn=Barry Nixon,ou=People,dc=example,dc=com is cn=Barry Nixon, and the RDN for ou=People,dc=example,dc=com is ou=People. A changetype: modrdn operation changes that left-most value in an entry's DN.

The modrdn change type only changes teh RDN; it cannot change other parts of a DN. For example, the entry cn=Sue Jacobs,ou=People,dc=example,dc=com can be changed to cn=Susan Jacobs,ou=People,dc=example,dc=coma, but it cannot be modified to be cn=Sue Jacobs,ou=old employees,dc=example,dc=com.

The following command renames 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, using the following command causes the server to delete cn=Sue Jacobs, so that only cn=Susan Jacobs remains in the entry:

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

2.4.2.1. A Note on Renaming Entries

The modrdn change type cannot move an entry 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, only the last two entries can be renamed:

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

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

2.4.3. Modifying an Entry Using LDIF

changetype: modify can add, replace, or remove attributes or attribute values in an 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 values. 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:

2.4.3.1. Adding Attributes to Existing Entries Using LDIF

Using changetype: modify with the add operation cam 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 viewed in the Directory Server Gateway. In order to add this attribute to the directory, use the -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

Using the standard notation means that the -b parameter does not need to be used withldapmodify. However, you must add version:1 to the beginning of the LDIF file or with LDIF update statements. For example:

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

Standard LDIF notation can only be used with the ldapmodify command, not with other command-line utilities.

2.4.3.2. Changing an Attribute Value Using LDIF

changetype: modify with the replace operation changes 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 first and then add the replacement value. For example, this entry has two telephone nubmers:

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

The 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

2.4.3.3. Deleting All Values of an Attribute Using LDIF

changetype: modify with the delete operation deletes an attribute from an entry. If the entry has more than one instance of the attribute, you must indicate which of the attributes 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

To delete just a specific instance of the telephonenumber attribute, simply delete that specific attribute value, as described in the next section.

2.4.3.4. Deleting a Specific Attribute Value Using LDIF

Running changetype: modify with the delete operation can delete a single value for an attribute value from an entry, as well as deleting all instances of the attribute. 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

2.4.4. Deleting an Entry Using LDIF

changetype: delete is the change type which deletes an entire entry from the directory.

NOTE

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, only the last two entries can be deleted:

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

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 Administration Server uses this suffix to store information about installed Directory Servers. Deleting this suffix could force you to reinstall the Directory Server.

2.4.5. Modifying an Entry in an Internationalized Directory

If the attribute values in the directory are associated with 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, to modify an attribute value that has a language tag of lang-fr, include 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

Note: This documentation is provided {and copyrighted} by Red Hat®, Inc. and is released via the Open Publication License. The copyright holder has added the further requirement that Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. The CentOS project redistributes these original works (in their unmodified form) as a reference for CentOS-5 because CentOS-5 is built from publicly available, open source SRPMS. The documentation is unmodified to be compliant with upstream distribution policy. Neither CentOS-5 nor the CentOS Project are in any way affiliated with or sponsored by Red Hat®, Inc.