LDIF

LDAP Data Interchange Format is a standard text-based format for describing directory entries, defined in RFC 2849. LDIF allows you to export your directory data and import it into another directory server, even if the two servers use different internal database formats. In the database/spreadsheet world, the tab-delimited format performs a similar function: It provides a simple format that virtually all spreadsheets and databases can import and export.

There are two different types of LDIF files. The first type describes a set of directory entries, such as your entire corporate directory, or perhaps a subset of it. The other type of LDIF file is a series of LDIF update statements that describe changes to be applied to directory entries. In the following sections we'll look at both types in detail.

LDIF Representation of Directory Entries

Listing 2.1 shows two directory entries in LDIF format.

Listing 2.1 A Typical LDIF File

 version: 1 dn: uid=bjensen, ou=people, dc=example, dc=com objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: Barbara Jensen cn: Babs Jensen givenName: Barbara sn: Jensen uid: bjensen mail: [e-mail] telephoneNumber: [phone] description: Manager, Switching Products Division dn: uid=ssmith, ou=people, dc=example, dc=com objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: Steve Smith cn: Stephen Smith givenName: Stephen sn: Smith uid:ssmith mail: [e-mail] telephoneNumber: [phone] description: Member of Technical Staff. 

An individual entry expressed in LDIF format consists of two parts : a DN and a list of attribute values. The DN, which must be the first line of the entry, is composed of the string "dn" followed by a colon ( : ) and the distinguished name of the entry. After the DN come the attributes of the entry. Each attribute value is composed of an attribute type, a colon ( : ), and the attribute value. Attribute values may appear in any order; for readability, however, we suggest that you list the objectclass values for the entry first and group multiple values for the same attribute type together, as in Listing 2.1.

Any line in an LDIF file may be folded into multiple lines, which is typically done when an individual line is extremely long. To fold a line, insert a newline character and a space character into the value. Folding is not required, but some editors cannot handle extremely long lines. Listing 2.2 shows an entry with a folded line; note how the description attribute is folded into four lines.

Listing 2.2 An LDIF File with a Folded Attribute Value

 version: 1 dn: uid=bjensen, ou=people, dc=example, dc=com objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: Barbara Jensen cn: Babs Jensen givenName: Barbara sn: Jensen uid: bjensen mail: [e-mail] telephoneNumber: [phone] description: I will be out of the  office from August 12, 2001, to September 10, 2001. If you need  assistance with the Ostrich project, please contact Steve Smith  at extension 7226. 

If an LDIF file contains an attribute value or a DN that is not ASCII, that value or DN must be encoded in a special format called base 64 . This encoding method can represent any arbitrary data as a series of printable characters . When an attribute is base 64 “encoded, the attribute type and value are separated by two colons instead of a single colon. Listing 2.3 shows an entry in LDIF format that contains a base 64 “encoded binary attribute ( jpegPhoto ). Notice that, in addition to being base 64 “encoded, the attribute is folded.

Listing 2.3 An Entry in LDIF Format Containing a Base 64 “Encoded Attribute Value

 dn: uid=bjensen, ou=people, dc=example, dc=com objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: Barbara Jensen cn: Babs Jensen givenName: Barbara sn: Jensen uid: bjensen mail: [e-mail] telephoneNumber: [phone] jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALDA4MChAODQ4  SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQERXRTc4UG1RV19iZ2hnP  k1xeXBkeFxlZ2P/2wBDARESEhgVGC8aGi9jQjhCY2NjY2NjY2NjY2NjY2N  jY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2P/wAARCACcA  LgDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQo  L/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBk  aEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUp  TVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjp  KWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6er  x8vP09fb3+ 

More formally , the syntax of an entry represented in LDIF format is as follows :

 ("dn:" <DN of entry>  "dn::" <base 64-encoded DN of entry>) <attribute type> (":" <attribute value> "::" <base 64 attribute value>) ... 

A complete formal definition of the LDIF syntax is available in RFC 2849.

LDIF Update Statements

The second type of LDIF file describes a set of changes to be applied to one or more directory entries. An individual LDIF update statement consists of a DN, a change type, and possibly a set of modifications. Typically you will use this type of LDIF file as input to a command-line utility such as the ldapmodify program, which is included with Netscape Directory Server and the Netscape LDAP SDK. The ldapmodify program reads the update statements, converts those statements to LDAP protocol operations, and sends them to a server for processing. For more information on using ldapmodify to apply updates to a directory server, see the section titled The ldapmodify Command-Line Utility later in this chapter.

Four types of changes can be described by an LDIF update statement. These change types correspond exactly to the types of update operations that can be performed over the LDAP protocol: add a new entry, delete an existing entry, modify an existing entry, and rename an existing entry. Although the examples in the following sections do not show either folding or base 64 encoding, both are permitted in LDIF update statements.

Adding a New Entry

The add changetype statement indicates that an entry is to be added to the directory. The syntax of this update statement is

 dn: dn of entry to be added changetype: add attribute type: value ... 

For example, you would use the following to add a new entry to the directory:

 dn: uid=bjensen, ou=people, dc=example, dc=com changetype: add objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: Barbara Jensen cn: Babs Jensen givenName: Barbara sn: Jensen uid: bjensen mail: [e-mail] telephoneNumber: [phone] 

Deleting an Entry

The delete changetype statement indicates that an entry is to be removed from the directory. The syntax of this type of update statement is

 dn: dn of entry to be deleted changetype: delete 

For example, you would use the following to delete an entry from the directory:

 dn: uid=bjensen, ou=people, dc=example, dc=com changetype: delete 

Modifying an Entry

The modify changetype statement indicates that an existing entry is to be modified. It also allows you to add new attribute values, remove specific attribute values, remove an attribute entirely, or replace all attribute values with a new set of values. The syntax of the modify update statement is

 dn: dn of entry to be modified changetype: modify modifytype: attribute type [attribute type: attribute value] - ... 

Note that there is an additional operator: modifytype . This operator can be add , delete , or replace , and it is interpreted as follows.

To add one or more new attribute values, use an add modifytype statement and include the attribute values you want to add. The following example adds two new values to the telephoneNumber attribute; if values for this attribute already exist, they are unaffected:

 dn: uid=bjensen, ou=people, dc=example, dc=com changetype: modify add: telephoneNumber telephoneNumber: [phone] telephoneNumber: [phone] 

To delete one or more specific attribute values, use a delete modifytype statement and include the values you want to delete. The following example removes the value [phone] from the telephoneNumber attribute; any other telephoneNumber attribute values are unaffected:

 dn: uid=bjensen, ou=people, dc=example, dc=com changetype: modify delete: telephoneNumber telephoneNumber: [phone] 

To completely remove an attribute, use a delete modifytype statement, but do not include any specific attribute value to be deleted. The following example completely removes the telephoneNumber attribute from the entry:

 dn: uid=bjensen, ou=people, dc=example, dc=com changetype: modify delete: telephoneNumber 

To replace an attribute with a new set of values, use a replace modifytype statement and include the values that should replace any existing attribute values. The following example replaces any existing values of the telephoneNumber attribute with the two given values:

 dn: uid=bjensen, ou=people, dc=example, dc=com changetype: modify replace: telephoneNumber telephoneNumber: [phone] telephoneNumber: [phone] 

Multiple modifytype statements can be combined into a single update statement. Each set of lines constituting one modifytype statement must be separated by a line that contains only a single dash. For example, the following update statement adds a new value to the mail attribute, removes a specific value from the telephoneNumber attribute, completely removes the description attribute, and replaces the givenName attribute with a new set of values:

 dn: uid=bjensen, ou=people, dc=example, dc=com changetype: modify add: mail mail: [e-mail] - delete: telephoneNumber telephoneNumber: [phone] - delete: description - replace: givenName givenName: Barbara givenName: Babs - 

When multiple modifications are included in a single LDIF update statement and the ldapmodify program sends the corresponding LDAP operations to an LDAP server, the server performs the update only if all the individual attribute modifications succeed. In the last example, if the entry did not contain the telephoneNumber attribute value [phone] , it would not be possible to delete that specific value. The server treats each update statement as a single unit, so none of the attribute modifications would be made, and an error would be returned to the client.

Renaming and/or Moving an Entry

The moddn changetype statement indicates that an existing entry is to be renamed and optionally moved to a new location in the directory tree. The syntax of the moddn update statement is

 dn: dn of entry to be modified changetype: moddn [newsuperior: dn of new parent] [deleteoldrdn: ( 0  1 )] [newrdn: new relative distinguished name for the entry] 

If an entry's RDN is to be changed, the newrdn and deleteoldrdn parameters must be provided. If an entry is to be moved to a new location in the tree, the newsuperior parameter must be provided. Both operations can be performed at once; that is, an entry can have its RDN changed at the same time it is moved to a new location in the tree.

For example, to change an entry's name without moving it to a new location in the tree, you'd use the following:

 dn: uid=bjensen, ou=People, dc=example, dc=com changetype: moddn newrdn: uid=babsj deleteoldrdn: 0 

After this update was performed on the server, the entry would look like this:

 dn: uid=babsj, ou=People, dc=example, dc=com [other attributes omitted for brevity] uid: babsj uid: bjensen 

Notice that the old RDN, uid: bjensen , is still present in the entry. When is provided for the deleteoldrdn flag, the old RDN is retained as an attribute of the entry. If you want the old RDN to be removed from the entry, include deleteoldrdn: 1 in your moddn update statement. If this were done, the entry would look like this after being renamed:

 dn: uid=babsj, ou=People, dc=example, dc=com [other attributes omitted for brevity] uid: babsj 

If you want to move an entry to a new location in the tree, you can use the newsuperior parameter to specify the DN of the entry to which you would like the entry to be moved. For example, if you want to move Babs's entry under the Terminated Employees organizational unit, you would use the following LDIF update statement:

 dn: uid=bjensen, ou=People, dc=example, dc=com changetype: moddn newsuperior: ou=Terminated Employees, dc=example, dc=com 

The moddn changetype statement may behave differently depending on whether the server supports LDAPv3. If the server supports only LDAPv2, the newsuperior parameter may not be used; LDAPv2 does not support moving an entry to a new location in the tree.