Chapter 8. LDAP LDIF and DSML

This chapter describes various method for importing and exporting LDAP entries and complete DIT using either LDIF or DSML.

LDAP Data Interchange Files (LDIF) formats are defined in RFC 2849 and updated to cover modify-increment by RFC 4245.

8.1 LDIF Overview

LDIF files are used in five general cases:

To initially construct the DIT structure.
To add (import) bulk records into a directory.
To restore (import) a directory.
To archive (export) a directory.
To apply bulk edits to a directory.

OpenLDAP provides a number of tools to import and export LDIF files.

LDIF files are simple text files and can be created and edited with any suitable text editor. Since each line is terminated with EITHER <LF> (unix format) OR <CR><LF> (windows format) these files may be created on virtually any OS platform.

8.2 LDIF General Format

8.2.1 LDIF Format

LDIF can be pretty picky - with spaces (or a lack of) - being particularly important. An LDIF consists of an number of LINE TYPES some of which can contain LDIF directives and which may be organized into ENTRY sequences and OPERATOR sequences. Each line is terminated with EITHER <LF> (unix format) OR <CR><LF> (windows format). To try and simplify further explanations we categorise the following LINE TYPES that we will refer to in the subsequent directive descriptions.

8.2.1.1 LDIF Terminology and Line Types

The following section defines some terminology that we use when describing LDIF files. This terminology was created to simplify explanation of some of the more arcane features of LDIF files.

LDIF Line Types
1. DIRECTIVE LINE - a line which starts (in column 1) with any character EXCEPT SPACE or # (hash)
2. CONTINUATION LINE - a line which follows a DIRECTIVE LINE and starts (in column 1) with a SPACE - subsequent characters are assumed to be part of the previous line. Any number of CONTINUATION lines may exist up to any size limit imposed by the attribute.
3. BLANK LINE - a line which consists of no characters in column 1 (typically created with the ENTER key). BLANK LINES are typically used to separate ENTRY sequences.
4. COMMENT LINE - a line which starts (in column 1) with a # (hash) character.
5. SEPARATOR LINE - a line which starts (in column 1) with a - (dash) character. SEPARATOR LINES are typically used to terminate OPERATOR sequences.
LDIF Sequences
1. ENTRY sequence - a group of directives which normally start with a dn: directive and all of which apply to a single entry in the DIT. An ENTRY sequence normally starts and finishes with a BLANK line.
2. OPERATOR sequence - a group of directives used with a changetype: modify directive, and all of which apply to a single add, delete or replace operation. An OPERATOR sequence normally terminates with either a SEPARATOR line or a BLANK line.

8.2.1.1 LDIF Sample

This sample LDIF illustrates creation of a DIT using the standard sample file and shows the most commonly used syntax. This file would typically be loaded using the ldapadd utility:

## DEFINE DIT ROOT/BASE/SUFFIX ####
## uses RFC 2377 format
## replace example and com as necessary below
## or for experimentation leave as is

## dcObject is an AUXILLIARY objectclass and MUST
## have a STRUCTURAL objectclass (organization in this case)
# this is an ENTRY sequence and is preceded by a BLANK line

dn: dc=example,dc=com
dc: example
description: My wonderful company as much text as you want to place 
 in this line up to 32K continuation data for the line above must 
 have <CR> or <CR><LF> i.e. ENTER works 
 on both Windows and *nix system - new line MUST begin with ONE SPACE
objectClass: dcObject
objectClass: organization
o: Example, Inc.

## FIRST Level hierarchy - people 
## uses mixed upper and lower case for objectclass
# this is an ENTRY sequence and is preceded by a BLANK line

dn: ou=people, dc=example,dc=com
ou: people
description: All people in organisation
objectclass: organizationalunit

## SECOND Level hierarchy
## ADD a single entry under FIRST (people) level
# this is an ENTRY sequence and is preceded by a BLANK line
# the ou: Human Resources is the department name

dn: cn=Robert Smith,ou=people,dc=example,dc=com
objectclass: inetOrgPerson
cn: Robert Smith
cn: Robert J Smith
cn: bob  smith
sn: smith
uid: rjsmith
userpassword: rJsmitH
carlicense: HISCAR 123
homephone: 555-111-2222
mail: r.smith@example.com
mail: rsmith@example.com
mail: bob.smith@example.com
description: swell guy
ou: Human Resources

Notes:

<warning> We incorrectly defined dn: dc=example,dc=com above as dn: dc=example.com in versions of this guide prior to 0.1.2 which successfully loaded in OpenLDAP 2.0 and 2.1 but was rejected by OpenLDAP 2.2 (error 64). </warning>
When entries are added they commence with the line starting 'dn:'. In general, any attribute may be used for this purpose as long as 'dn:' is unique and, to save excessive searching, it will typically be the DN most frequently used to access the entry. In the case of the last entry in the above LDIF the value cn=Robert Smith,ou=people,dc=example,dc=com is used implying that cn= will be the most frequently used DN to access entries. However, if the entry will be used for authentication then this DN MUST be that used with any secure Bind Operation. In this case a DN of uid=rjsmith,ou=people,dc=example,dc=com may be more appropriate. While this initial or 'creation' DN has no special terminology within the LDAP standards, when used for authentication it is sometimes referred to as the Principal DN. For more on this topic.
We use some terminology to simplify the description of certain LDIF concepts.
As noted in the comments version: is not strictly necessary. If present it must be (currently) set to 1 to indicate version 1 of the LDIF format. It was included in the orginal version (ouch!) simply because it should be a Good Thing™. Future versions may be not be compatible or may impose stricter validation - it's best to get into good habits. During our testing we noticed that certain brain-dead versions of OpenLDAP choked on the version statement with failure messages suggesting that no DN exists and it was removed.
Comments are indicated by a # in the first column only. The following line interprets # as content:
```
cn: my name #this is my name
```
The resulting cn attribute will contain 'my name #this is my name'.
There must be at LEAST one BLANK line between entries (before the lines starting with dn:). This is VERY important - strange errors will result otherwise.
CONTINUATION lines are assumed if the line finishes with a line separator (a <CR> or <Cr><LF> sequence) and the next line starts with EXACTLY ONE SPACE.
The above file uses attribute names that inconsistently use upper and lower case letters - specifically, that ghastly pseudo-hungarian (CamelCase or even Camel case) notation for objectClass and all lower case letters for objectclass. Both work. Which style you adopt is up to you.
The line cn: bob smith contains multiple apparent errors. There are two spaces between 'bob' and 'smith' and both use lower case. Neither apparent error has any effect on the effectiveness of the directory because the attribute cn (child of the name attribute) uses a case insensitive matchingrule and LDAP does some interesting things on searching.
In a lot of documentation you will see objectclass: top, as well as an insistence on defining all the objectclasses in the hierarchy. Since OpenLDAP 2.0 this has not been necessary whether you continue to do it will be defined by your system requirements or the buzz you get from typing lots of stuff.
The space following the : (colon) on each line is VITAL.

The majority of directory systems can be constructed using the above subset of the LDIF directives.

8.2.2 LDIF Directives

The following LDIF directives are described in alphabetic order.

8.2.2.1 add Directive

Format:

add: attributename

The add directive follows a changetype: modify directive and defines the name of the attribute(s) to be added to an existing entry. Multiple values for the same attributename may be added if the atribute is MULTI-VALUED.

Notes:

To add an AUXILIARY object class to an existing entry see the examples at changetype: modify.

Examples:

# adding single attribute value to MULTI-VALUE attribute
# current attribute values unchanged

dn: cn=Robert Smith,ou=people,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: 123-111

# adding single attribute with multiple values to MULTI-VALUE attribute
# current attribute values unchanged

dn: cn=Robert Smith,ou=people,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: 555-123-1111
telephonenumber: 111

Note: If multiple values are added to a SINGLE-VALUE attribute the results are undefined but in most implementations the last value only is added.

8.2.2.2 attributename Directive

Format:

attributename: value

The attributename directive allows a value to be defined for an attribute.

Notes:

If the attribute is multi-valued any number of attributename directives may be supplied in the LDIF file.
The attributename directive may be used with changetype add or replace
The value may be:
1. A string
2. A Base 64 string.
3. A file URL in which case it takes the form < file://path/to/file.

Examples:

# adding attributes to new entry

dn: cn=Robert Smith,ou=people,dc=example,dc=com
changetype: add
objectclass: inetorgperson
cn: Robert smith
cn: Robert J Smith
cn: Bob Smith
telephonenumber: 123-111
...

# adding multiple attributes to exiting entry

dn: cn=Robert Ssmith,ou=people,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: 555-123-1111
telephonenumber: 111

# using a file URL

dn: cn=Robert Ssmith,ou=people,dc=example,dc=com
changetype: modify
add: jpegphoto
# no space between : and < below
jpegphoto:< file://tmp/my.jpg

8.2.2.3 changetype Directive

Format:

changetype: type

The changetype directive immediately follows a dn: directive and defines the operation to be performed on the entry.

type may take one of the following values:

When the add type is used then subsequent directives will add (create) the entry. If the entry already exists then the changetype: modify form must always be used. add is assumed (defaulted) if no changetype directive is present and the LDIF is being processed using ldapadd.

Examples:
```
dn: cn=Robert Smith,ou=people,dc=example,dc=com
# adds entry of dn above 
changetype: add
objectclass: inetorgperson
cn: Robert Smith
...
```

The delete type will delete the entry pointed to by the preceding dn directive.


dn: cn=Robert Smith,ou=people,dc=example,dc=com
# delete entry pointed to by dn above 
changetype: delete

When the modify type is used then subsequent commands will modify an existing entry pointed to by a preceding dn directive. Following the modify attributes (or object classes) may be added, replaced or deleted.

Notes:

Multiple modify operations may be carried in a OPERATOR sequence by using a SEPARATOR line.
To add a new AUXILIARY objectclass to an existing entry requires that an existing objectclass is defined before the new objectclass (the AUXILIARY objects binds to the existing objectclass) followed by the attributes to be added. See examples:

Examples:


dn: cn=Robert Smith,ou=people,dc=example,dc=com
# modifies entry pointed to by dn above 
changetype: modify
# single operation
add: telephonenumber
telephonenumber: 555

dn: cn=Robert Smith,ou=people,dc=example,dc=com
# modifies entry pointed to by dn above 
changetype: modify
# multiple operations
add: telephonenumber
telephonenumber: 555
# following line is a SEPARATOR line
-
replace: mail
mail: bob.smith@example.com
-
delete: secretary

# to ADD a new AUXILIARY object class 
# to an existing entry

dn: cn=Robert Smith,ou=people,dc=example,dc=com
# modifies entry pointed to by dn above 
changetype: modify
# this objectclass is used for binding
objectclass: inetorgperson
# AUXILIARY objectclass being added
objectclass: posixaccount
# following attributes include MUST attributes
# of new objectclass
uidnumber: 200
gidnumber: 207
homedirectory: /home/rsmith
...

modrdn (moddn is an alias) is used to change the RDN of the entry (rename or copy the entry) defined by the preceding dn: directive. It MUST be followed by a newrdn: directive and may be followed by a deleteoldrdn and a newsuperior directive.

You CANNOT rename the entry if the entry has one or more child entries.

Example:
```
dn: cn=Robert Ssmith,ou=people,dc=example,dc=com
# following sequence renames the above DN to
# cn=Robert Smith,ou=people.dc=example,dc=com
# and deletes the entry
# cn=Robert Ssmith,ou=people,dc=example,dc=com
changetype: modrdn
newrdn: cn=Robert Smith
deleteoldrdn: 1
```

8.2.2.4 control Directive

One day Real Soon Now™

8.2.2.5 delete Directive

Format:

delete: attributename

The delete directive performs operations on attributes and follows a changetype: modify directive and defines the name of the attribute to be deleted. To delete an entry use changetype: delete.

The delete directive MAY be followed by one or more directives defining which attribute to delete. If it is not followed by such a directive (i.e. followed by EOF, a BLANK line or a SEPARATOR line then all attributes with attributename are deleted.

# deleting single attribute value

dn: cn=Robert Ssmith,ou=people,dc=example,dc=com
changetype: modify
# deletes only the attributes with value 123-111 and 111
# all other telephonenumber attributes are unchanged
delete: telephonenumber
telephonenumber: 123-111
telephonenumber: 111

# deleting multiple attributes

dn: cn=Robert Ssmith,ou=people,dc=example,dc=com
changetype: modify
# deletes all telephonenumber attributes
delete: telephonenumber

8.2.2.6 deleteoldrdn Directive

Format:

deleteoldrdn: action

The deleteoldrdn directive defines the action to be taken with the original DN following a changetype: modrdn directive. This directive may take an action of 0 (false) in which case the original entry is retained or 1 in which case the original entry is deleted.

Example:

# fixes error in entry DN and 
# deletes current entry

dn: cn=Robert Ssmith,ou=people,dc=example,dc=com
changetype: modrdn
# create the new name (RDN)
newrdn: cn=Robert Smith
# delete current (Robert Ssmith) entry
deleteoldrdn: 1

8.2.2.7 dn Directive

Format:

dn: DN

The dn directive defines a Distinguished Name (DN) and is used to locate (or address) the entry on which subsequent directives will operate ( an ENTRY sequence).

Unless it is the first entry in the LDIF file the dn directive MUST be preceded by a BLANK line.

Example:

...
# previous sequence - then BLANK line

dn: ou=people,dc=example,dc=com
...

8.2.2.8 newrdn Directive

Format:

newrdn: RDN

The newrdn directive follows a changetype: modrdn (or moddn) directive and creates a copy of the entry pointed to by the preceding dn directive using the RDN specified by this directive.

Would normally be followed by an deleteoldrdn directive.

If used with a newsuperior directive may be used to copy or move an entry in the DIT.

Examples:

# use when correcting an error

dn: cn=Robert Ssmith,ou=people,dc=example,dc=com
changetype: modrdn
# corrected entry
newrdn: cn=Robert Smith
# deletes old entry
deleteoldrdn: 1

8.2.2.9 newsuperior Directive

Format:

newsuperior: DN

The newsuperior directive allows an entry to be moved within the DIT. The directive instructs LDAP to move the current entry to the DN specified by this directive.

This directive is used with the changetype: modrdn, newrdn and deleteoldrdn directives.

Examples:

# moves the entry from people to expeople

dn: cn=Robert Smith,ou=people,dc=example,dc=com
changetype: modrdn
# rdn unchanged
newrdn: cn=Robert Smith
# deletes old entry
deleteoldrdn: 1
# adds to expeople hierarchy
newsuperior: ou=expeople,dc=example,dc=com

# makes a copy of the entry in expeople

dn: cn=Robert Smith,ou=people,dc=example,dc=com
changetype: modrdn
# rdn unchanged
newrdn: cn=Robert Smith
# keeps current entry
deleteoldrdn: 0
# adds to expeople hierarchy
newsuperior: ou=expeople,dc=example,dc=com

8.2.2.10 objectclass Directive

Format:

objectclass: objectclassname

The objectclass directive allows an objectclass to be added to an entry.

Notes:

There must be at least one STRUCTURAL object class in an entry.
Since OpenLDAP 2.0+ is has not been necessary to define all the objectclasses in the objectclass hierarchy it is enough to define the lowest level objectclass in the hierarchy.

Examples:

# adding objectclasses to a new entry

dn: cn=Robert Smith,ou=people,dc=example,dc=com
changetype: add
# inetorgperson is lowest level in hierarchy
objectclass: inetorgperson
cn: Robert smith
cn: Robert J Smith
cn: Bob Smith
telephonenumber: 123-111
...

# adding objectclasses to a new entry

dn: cn=Robert Smith,ou=people,dc=example,dc=com
changetype: add
# inetorgperson is lowest level in hierarchy
objectclass: inetorgperson
# both objectclasses must be present here
# because posixaccount is an AUXILIARY
objectclass: posixaccount
cn: Robert smith
cn: Robert J Smith
cn: Bob Smith
telephonenumber: 123-111
...

# to ADD a new AUXILIARY object class 
# to an existing entry

dn: cn=Robert Smith,ou=people,dc=example,dc=com
# modifies entry pointed to by dn above 
changetype: modify
# this objectclass is used for binding
objectclass: inetorgperson
# AUXILIARY objectclass being added
objectclass: posixaccount
# following attributes include MUST attributes
# of new objectclass
uidnumber: 200
gidnumber: 207
homedirectory: /home/rsmith
...

8.2.2.11 replace Directive

Format:

replace: attributename

The replace directive follows a changetype: modify directive and defines the name of the attribute to be replaced.

If the attribute is multi-valued then ALL the current values are replaced with one or more attributes following this directive.

If only a single value of a multi-valued attribute needs to be replaced use delete then add. See example below.

Examples:

# replace single attribute value

dn: cn=Robert Ssmith,ou=people,dc=example,dc=com
changetype: modify
replace: uid
uid: bill


# replace multi attribute value

dn: cn=Robert Smith,ou=people,dc=example,dc=com
changetype: modify
# replaces ALL telephonenumber attributes
# with 555-111-1212
replace: telephonenumber
telephonenumber: 555-111-1212

# replace a single value of a multi attribute value
# delete then add
# example replaces 555-111-1212 with 555

dn: cn=Robert Smith,ou=people,dc=example,dc=com
changetype: modify
# first delete the required attribute
delete: telephonenumber
telephonenumber: 555-111-1212
# SEPARATOR line essential
-
# add new value
add: telephonenumber
telephonenumber: 555

8.2.2.12 version Directive

Format:

version: number

The version directive defines the version format of the LDIF file directives. This directive is not mandatory and due to inconsistencies of implementation we suggest it is not used.

The directive, if present, should be the first directive in the file (some brain-dead implementation seem to take this literaly and will reject it if a comment line precedes the version line) and currently only accepts a version number of 1.

# should be first entry in LDIF file
version: 1

8.3 LDIF Handling Binary (including password)

8.4 LDIF Importing Files

8.5 LDIF Samples

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.