mail us  |  mail this page

products  |  company  |  support  |  training  |  contact us

ZYTRAX OPEN LOGO

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.

Contents

8.1 LDIF Overview
8.2 LDIF Format & Directives

8.2.1 LDIF File Format

8.2.1.1 LDIF Terminology and Line Types
8.2.1.2 LDIF Sample

8.2.2 LDIF Directives

8.2.2.1 add Directive
8.2.2.2 attributename Directives
8.2.2.3 changetype Directives
8.2.2.4 control Directives
8.2.2.5 delete Directives
8.2.2.6 deleteoldrdn Directives
8.2.2.7 dn Directives
8.2.2.8 newrdn Directives
8.2.2.9 newsuperior Directives
8.2.2.10 objectclass Directives
8.2.2.11 replace Directives
8.2.2.12 version Directives

8.3 LDIF Handling Binary (including Passwords)
8.4 LDIF Importing Files
8.5 LDIF Samples

8.1 LDIF Overview

LDIF files are used in five general cases:

  1. To initially construct the DIT structure.
  2. To add (import) bulk records into a directory.
  3. To restore (import) a directory.
  4. To archive (export) a directory.
  5. 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.

UP Arrow

8.2 LDIF General Format

8.2.1 LDIF Format

LDIF can be pretty picky - with spaces or their lack 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.

UP Arrow

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:

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

  2. 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 frquently 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.

  3. We use some terminology to simplify the description of certain LDIF concepts.

  4. As noted in the comments version: is not strictly necessary. If present must be (currently) set to 1 to indicate version 1 of the LDIF format. It is included simply because it is a Good Thing™ to do. Future versions may be not be compatible or may impose stricter validation - it's best get into good habits now. During our testing we noticed that certain versions of OpenLDAP may choke on the version statement with failure messages suggesting that no DN exists. If this occurs delete the version line and all associated comments.

  5. 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'.

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

  7. CONTINUATION lines are assumed if the line finishes with a line separator and the next line starts with EXACTLY ONE SPACE.

  8. The above file uses attribute names that inconsistently use upper and lower case letters - specifically, that ghastly pseudo-hungarian notation for objectClass and all lower case letters for objectclass. Both work. Which style you adopt is up to you.

  9. 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 name attribute) uses a case insensitive matchingrule and LDAP does some interesting things on searching.

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

  11. The space following the : on each line is VITAL.

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

UP Arrow

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 entries of the same attributename may be added.

Notes:

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

Examples:

# adding single attribute
# current attribute values unchanged

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

# adding multiple attributes
# current attribute values unchanged

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

UP Arrow

8.2.2.2 attributename Directive

Format:

attributename: value

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

Notes:

  1. If the attribute is multi-valued any number of attributename directives may be supplied in the LDIF file.

  2. The attributename directive may be used with changetype add or replace

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

UP Arrow

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:

  1. 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
    ...
    
  2. 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
    
  3. 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:

    1. Multiple modify operations may be carried in a OPERATOR sequence by using a SEPARATOR line.

    2. 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
    ...
    
  4. 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
    

UP Arrow

8.2.2.4 control Directive

One day Real Soon Now™

UP Arrow

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

Up Arrow

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

Up Arrow

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

UP Arrow

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

UP Arrow

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

UP Arrow

8.2.2.10 objectclass Directive

Format:

objectclass: objectclassname

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

Notes:

  1. There must be at least one STRUCTURAL object class in an entry.

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

UP Arrow

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

UP Arrow

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

UP Arrow

8.3 LDIF Handling Binary (including password)

UP Arrow

8.4 LDIF Importing Files

UP Arrow

8.5 LDIF Samples

UP Arrow

Copyright © 1994 - 2014 ZyTrax, Inc.
All rights reserved. Legal and Privacy
site by zytrax
Hosted by super.net.sg
web-master at zytrax
Page modified: September 17 2013.

Contents

tech info
guides home
intro
contents
1 objectives
big picture
2 concepts
3 ldap objects
quickstart
4 install ldap
5 samples
6 configuration
7 replica & refer
reference
8 ldif
9 protocol
10 ldap api
operations
11 howtos
12 trouble
13 performance
14 ldap tools
security
15 security
appendices
notes & info
ldap resources
rfc's & x.500
glossary
ldap objects
change log

Creative Commons License
This work is licensed under a Creative Commons License.

If you are happy it's OK - but your browser is giving a less than optimal experience on our site. You could, at no charge, upgrade to a W3C STANDARDS COMPLIANT browser such as Firefox

web zytrax.com

Share Page

share page via facebook tweet this page submit page to stumbleupon submit page to reddit.com

Page Features

Page comment feature Send to a friend feature print this page Decrease font size Increase font size

RSS Feed Icon RSS Feed

Resources

Systems

FreeBSD
NetBSD
OpenBSD
DragonFlyBSD
Linux.org
Debian Linux

Applications

LibreOffice
OpenOffice
Mozilla
SourceForge
GNU-Free SW Foundation

Organisations

Open Source Initiative
Creative Commons

Misc.

Ibiblio - Library
Open Book Project
Open Directory
Wikipedia

SPF Resources

Draft RFC
SPF Web Site
SPF Testing
SPF Testing (member only)

Display full width page Full width page

Print this page Print this page

SPF Record Conformant Domain Logo