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