5.1 Understanding LDIF

LDIF is a widely used file format that describes directory information or modification operations that can be performed on a directory. LDIF is completely independent of the storage format used within any specific directory implementation, and is typically used to export directory information from and import data to LDAP servers.

LDIF is usually easy to generate. This makes it possible to use tools like awk or perl to move data from a proprietary format into an LDAP directory. You can also write scripts to generate test data in LDIF format.

5.1.1 LDIF File Format

NetIQ Import Conversion Export imports require LDIF 1 formatted files. The following are the basic rules for an LDIF 1 file:

  • The first non-comment line must be version: 1.

  • A series of one or more records follows the version.

  • Each record is composed of fields, one field per line.

  • Lines are separated by either a new line or a carriage return/new line pair.

  • Records are separated by one or more blank lines.

  • There are two distinct types of LDIF records: content records and change records. An LDIF file can contain an unlimited number of records, but they all must be of the same type. You can’t mix content records and change records in the same LDIF file.

  • Any line beginning with the pound sign (#) is a comment and is ignored when processing the LDIF file.

5.1.2 LDIF Content Records

An LDIF content record represents the contents of an entire entry. The following is an example of an LDIF file with four content records:

 1  version: 1
 2  dn: c=US
 3  objectClass: top
 4  objectClass: country
 5  
 6  dn: l=San Francisco, c=US
 7  objectClass: top
 8  objectClass: locality
 9  st: San Francisco
10
11 dn: ou=Artists, l=San Francisco, c=US
12 objectClass: top
13 objectClass: organizationalUnit
14 telephoneNumber: +1 415 555 0000
15 
16 dn: cn=Peter Michaels, ou=Artists, l=San Francisco, c=US
17 sn: Michaels
18 givenname: Peter
19 objectClass: top
20 objectClass: person
21 objectClass: organizationalPerson
22 objectClass: iNetOrgPerson
23 telephonenumber: +1 415 555 0001
24 mail: Peter.Michaels@aaa.com
25 userpassword: Peter123
26

This LDIF file is composed of the following parts:

Component

Description

Version Specifier

The first line of an LDIF file contains the version. Zero or more spaces are allowed between the colon and the version number, which is currently defined to be 1.

If the version line is missing, any application processing the LDIF file is allowed to assume that the file is version 0. It’s also possible that the LDIF file could be rejected as syntactically incorrect. NetIQ utilities that process LDIF assume a file version of 0 when the version line is missing.

Distinguished Name Specifier

The first line of every content record (lines 2, 6, 11, and 16 in the example above) specifies the DN of the entry that it represents.

The DN specifier must take one of the following two forms:

  • dn: safe_UTF-8_distinguished_name

  • dn:: Base64_encoded_distinguished_name

Line Delimiters

The line separator can be either a line feed or a carriage return/line feed pair. This resolves a common incompatibility between Linux and Solaris text files, which use a line feed as the line separator, and MS-DOS* and Windows text files, which use a carriage return/line feed pair as the line separator.

Record Delimiters

Blank lines (lines 5, 10, 15, and 26 in the example above) are used as record delimiters.

Every record in an LDIF file including the last record must be terminated with a record delimiter (one or more blank lines). Although some implementations will silently accept an LDIF file without a terminating record delimiter, the LDIF specification requires it.

Attribute Value Specifier

All other lines in a content records are value specifiers. Value specifiers must take on one of the following three forms:

  • Attribute description: value

  • Attribute description:: Base64_encoded_value

  • Attribute description: < URL

5.1.3 LDIF Change Records

LDIF change records contain modifications to be made to a directory. Any of the LDAP update operations (add, delete, modify, and modify DN) can be represented in an LDIF change record.

LDIF change records use the same format for the distinguished name specifier, attribute value specifier, and record delimiter as LDIF content records. (See LDIF Content Records for more information.) The presence of a changetype field is what distinguishes an LDIF change record from an LDIF content record. A changetype field identifies the operation specified by the change record.

A changetype field can take one of the following five forms:

Form

Description

changetype: add

A keyword indicating that the change record specifies an LDAP add operation.

changetype: delete

A keyword indicating that the change record specifies an LDAP delete operation.

changetype: moddn

A keyword indicating that the change record specifies an LDAP modify DN operation if the LDIF processor is bound to the LDAP server as a version 3 client or a modify RDN operation if the LDIF processor is bound to the LDAP server as a version 2 client.

changetype: modrdn

A synonym for the moddn change type.

changetype: modify

A keyword indicating that the change record specifies an LDAP modify operation.

The Add Change Type

An add change record looks just like a content change record (see LDIF Content Records) with the addition of the changetype: add field immediately before any attribute value fields.

All records must be the same type. You can’t mix content records and change records.

 1 version: 1
 2 dn: c=US
 3 changetype: add
 4 objectClass: top
 5 objectClass: country
 6 
 7 dn: l=San Francisco, c=US
 8 changetype: add
 9 objectClass: top
10 objectClass: locality
11 st: San Francisco
12
14 dn: ou=Artists, l=San Francisco, c=US
15   changetype: add
16 objectClass: top
17 objectClass: organizationalUnit
18 telephoneNumber: +1 415 555 0000
19 
20 dn: cn=Peter Michaels, ou=Artists, l=San Francisco, c=US
21 changetype: add
22 sn: Michaels
23 givenname: Peter
24 objectClass: top
25 objectClass: person
26 objectClass: organizationalPerson
27 objectClass: iNetOrgPerson
28 telephonenumber: +1 415 555 0001
29 mail: Peter.Michaels@aaa.com
30 userpassword: Peter123
31

The Delete Change Type

Because a delete change record specifies the deletion of an entry, the only fields required for a delete change record are the distinguished name specifier and a delete change type.

The following is an example of an LDIF file used to delete the four entries created by the LDIF file shown in The Add Change Type.

IMPORTANT:To delete entries you have previously added, reverse the order of the entries. If you do not do this, the delete operation fails because the container entries are not empty.

 1 version: 1
 2 dn: cn=Peter Michaels, ou=Artists, l=San Francisco, c=US
 3 changetype: delete
 4
 5 dn: ou=Artists, l=San Francisco, c=US
 8   changetype: delete
 9
10 dn: l=San Francisco, c=US
11 changetype: delete
12
13 dn: c=US
14 changetype: delete
15

The Modify Change Type

The modify change type lets you to specify the addition, deletion, and replacement of attribute values for an entry that already exists. Modifications take one of the following three forms:

Element

Description

add: attribute type

A keyword indicating that subsequent attribute value specifiers for the attribute type should be added to the entry.

delete: attribute type

A keyword indicating that values of the attribute type are to be deleted. If attribute value specifiers follow the delete field, the values given are deleted.

If no attribute value specifiers follow the delete field, then all values are deleted. If the attribute has no values, this operation will fail, but the desired effect will still be achieved because the attribute had no values to be deleted.

replace: attribute type

A keyword indicating that the values of the attribute type are to be replaced. Any attribute value specifiers that follow the replace field become the new values for the attribute type.

If no attribute value specifiers follow the replace field, the current set of values is replaced with an empty set of values (which causes the attribute to be removed). Unlike the delete modification specifier, if the attribute has no values, the replace will still succeed. The net effect in both cases is the same.

The following is an example of a modify change type that will add an additional telephone number to the cn=Peter Michaels entry.

 1 version: 1
 2 dn: cn=Peter Michaels, ou=Artists, l=San Francisco, c=US
 3 changetype: modify
 4 # add the telephone number to cn=Peter Michaels
 4 add: telephonenumber
 5 telephonenumber: +1 415 555 0002
 6

Just as you can combine a mixture of modifications in a single LDAP modify request, you can specify multiple modifications in a single LDIF record. A line containing only the hyphen (-) character is used to mark the end of the attribute value specifications for each modification specifier.

The following example LDIF file contains a mixture of modifications:

 1 version: 1
 2
 3 # An empty line to demonstrate that one or more
 4 # line separators between the version identifier 
 5 # and the first record is legal.
 6
 7 dn: cn=Peter Michaels, ou=Artists, l=San Francisco, c=US
 8 changetype: modify
 9 # Add an additional telephone number value.
10 add: telephonenumber
11 telephonenumber: +1 415 555 0002
12 -
13 # Delete the entire fascimiletelephonenumber attribute.
14 delete: facsimileTelephoneNumber
15 -
16 # Replace the existing description (if any exists) 
17 # with two new values.
18 replace: description
19 description: guitar player
20 description: solo performer
21 -
22 # Delete a specific value from the telephonenumber 
23 # attribute.
24 delete: telephonenumber
25 telephonenumber: +1 415 555 0001
26 -
27 # Replace the existing title attribute with an empty 
28 # set of values, thereby causing the title attribute to 
29 # be removed.
30 replace: title
31 -
32

The Modify DN Change Type

The modify DN change type lets you rename an entry, move it, or both. This change type is composed of two required fields and one optional field.

Field

Description

newrdn (required)

Gives the new name for the entry that will be assigned while processing this record. The new RDN specifier must take of the following two forms:

  • newrdn: safe_UTF-8_relative_distinguished_name

  • newrdn:: Base64_encoded_relative_ distinguished_name

The new RDN specifier is required in all LDIF records with a modify DN change type.

deleteoldrdn (required)

The delete old RDN specifier is a flag that indicates whether the old RDN should be replaced by the newrdn or if it should be kept. It takes one of the two following forms:

  • deleteoldrdn: 0

    Indicates that the old RDN value should be kept in the entry after it is renamed.

  • deleteoldrdn: 1

    Indicates that the old RDN value should be deleted when the entry is renamed.

newsuperior (optional)

The new superior specifier gives the name of the new parent that will be assigned to the entry while processing the modify DN record. The new superior specifier must take of the following two forms:

  • newsuperior: safe_UTF-8_distinguished_name

  • newsuperior:: Base64_encoded_distinguished_ name

The new superior specifier is optional in LDIF records with a modify DN change type. It is only given in cases where you want to re-parent the entry.

The following is an example of a modify DN change type that shows how to rename an entry:

 1 version: 1
 2 
 3 # Rename ou=Artists to ou=West Coast Artists, and leave
 4 # its old RDN value.
 5 dn: ou=Artists,l=San Francisco,c=US
 6 changetype: moddn
 7 newrdn: ou=West Coast Artists
 8 deleteoldrdn: 1
 9

The following is an example of a modify DN change type that shows how to move an entry:

 1 version: 1
 2
 3 # Move cn=Peter Michaels from 
 4 # ou=Artists,l=San Francisco,c=US to 
 5 # ou=Promotion,l=New York,c=US and delete the old RDN.
 5 dn: cn=Peter Michaels,ou=Artists,l=San Francisco,c=US
 6 changetype: moddn
 7 newrdn: cn=Peter Michaels
 8 deleteoldrdn: 1
 9 newsuperior: ou=Promotion,l=New York,c=US
10

The following is an example of a modify DN change type that shows how to move an entry and rename it at the same time:

 1 version: 1
 2
 3 # Move ou=Promotion from l=New York,c=US to
 4 # l=San Francisco,c=US and rename it to 
 5 # ou=National Promotion.
 5 dn: ou=Promotion,l=New York,c=US
 6 changetype: moddn
 7 newrdn: ou=National Promotion
 8 deleteoldrdn: 1
 9 newsuperior: l=San Francisco,c=US
10

IMPORTANT:The LDAP 2 modify RDN operation doesn’t support moving entries. If you try to move an entry using the LDIF newsuperior syntax with an LDAP 2 client, the request will fail.

5.1.4 Line Folding within LDIF Files

To fold a line in an LDIF file, simply insert a line separator (a new line or a carriage return/new line pair) followed by a space at the place where you want the line folded. When the LDIF parser encounters a space at a beginning of the line, it knows to concatenate the rest of the data on the line with the data on the previous line. The leading space is then discarded.

You should not fold lines in the middle of a multibyte UTF-8 character.

The following is an example of an LDIF file with a folded line (see lines 13 and 14):

 1 version: 1
 2 dn: cn=Peter Michaels, ou=Artists, l=San Francisco, c=US
 3 sn: Michaels
 4 givenname: Peter
 5 objectClass: top
 6 objectClass: person
 7 objectClass: organizationalPerson
 8 objectClass: iNetOrgPerson
 9 telephonenumber: +1 415 555 0001
10 mail: Peter.Michaels@aaa.com
11 userpassword: Peter123
12 description: Peter is one of the most popular music
13  ians recording on our label. He's a big concert dr
14  aw, and his fans adore him.
15

5.1.5 Hashed Password Representation in LDIF Files

The hashed password is represented as base64 data in the LDIF file. The attribute name userpassword should be followed with the name of the encryption used for hashing the password. This name should be given within a pair of flower brackets “{ }” as shown below:

Example 1

For SHA hashed passwords:

1 version: 1 2 dn: cn=Peter Michaels, ou=Artists, l=San Francisco, c=US 3 sn: Michaels 4 userpassword: {SHA}xcbdh46ngh37jsd0naSFDedjAS30dm5 objectclass: inetOrgPerson

Example 2

For SSHA hashed passwords:

1 version: 1 2 dn: cn=Peter Michaels, ou=Artists, l=San Francisco, c=US 3 sn: Michaels 4 userpassword: {SSHA}sGs948DFGkakdfkasdDF34DF4dS3skl5DFS5 objectclass: inetOrgPerson

Example 3

For Digest MD5 hashed passwords:

1 version: 1 2 dn: cn=Peter Michaels, ou=Artists, l=San Francisco, c=US 3 sn: Michaels 4 userpassword: {MD5}a45lkSDF234SDFG62dsfsf2DG2QEvgdmnk4305 objectclass: inetOrgPerson