Chapter 7 LDAP Data Interchange Format Reference

Directory Server uses the LDAP Data Interchange Format (LDIF) to describe a directory and directory entries in text format. LDIF is commonly used to build the initial directory database or to add large numbers of entries to the directory simultaneously. LDIF is also used to describe changes to directory entries. For this reason, most of Directory Server's command-line utilities rely on LDIF for either input or output.

Because LDIF is a text file format, you can create LDIF files using virtually any language. All directory data is stored using the UTF-8 encoding of Unicode. Therefore, the LDIF files you create must also be UTF-8 encoded.

LDIF File Format

LDIF consists of one or more directory entries separated by a blank line. Each LDIF entry consists of an optional entry ID, a required distinguished name, one or more object classes, and multiple attribute definitions.

The LDIF format is defined in RFC 2849 The LDAP Data Interchange Format (LDIF). Sun Java System Directory Server is compliant with this standard.

dn: distinguished_name
objectClass: object_class
objectClass: object_class
...
attribute_type[;subtype]:attribute_value
attribute_type[;subtype]:attribute_value
...

You must supply the DN and at least one object class definition. In addition, you must include any attributes required by the object classes that you define for the entry. All other attributes and object classes are optional. You can specify object classes and attributes in any order. The space after the colon is also optional. For information on standard object classes and attributes, refer to Chapter 9, "Object Class Reference," and Chapter 10, "Attribute Reference."

Table 7-1 LDIF Fields
Field	Definition
[id]	Optional. A positive decimal number representing the entry ID. The database creation tools generate this ID for you. Never add or edit this value yourself.
dn: distinguished_name	Specifies the distinguished name for the entry. For a complete description of distinguished names, refer to the Directory Server Deployment Planning Guide.
objectClass: object_class	Specifies an object class to use with this entry. The object class identifies the types of attributes, or schema, allowed and required for the entry. Refer to Chapter 9, "Object Class Reference," for a list of standard object classes.
attribute_type	Specifies a descriptive attribute to use with the entry. The attribute should be defined in the schema. Refer to Chapter 10, "Attribute Reference," for a list of standard attributes.
[subtype]	Optional. Specifies a subtype, which may be one of: language (attribute;lang-subtype) binary (attribute;binary) pronunciation (attribute;phonetic) Use this tag to identify the language in which the corresponding attribute value is expressed, or whether the attribute value is binary or a pronunciation of an attribute value. For more information, refer to "Adding an Attribute Subtype" in the Directory Server Administration Guide.
attribute_value	Specifies the attribute value to be used with the attribute type.

The LDIF syntax for representing a change to an entry in the directory is different from the syntax described above. For information on using LDIF to modify directory entries, refer to "Creating Directory Entries" in the Directory Server Administration Guide.

Continuing Lines in LDIF

When you specify LDIF, you can break and continue, or fold, a line by indenting the continued portion of the line by exactly one space. For example, the following two statements are identical:

You are not required to break and continue LDIF lines. However, doing so may improve the readability of an LDIF file.

Representing Binary Data

You can represent binary data, such as a JPEG image, in LDIF using one of the following methods:

Using Standard LDIF Notation

Note that this path is relative to the client, not to the server. If you use this standard notation, you do not need to specify the ldapmodify -b parameter. However, you must add the following line to the beginning of your LDIF file, or your LDIF update statements:

version: 1
dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
add: userCertificate
userCertificate;binary:< file: BarneysCert

Using ldapmodify -b

Whenever possible, you should use the standard notation described above. The method described in this section is supported only for reasons of backward compatibility with earlier versions of Directory Server.

Sun Java System Directory Server accepts the ldapmodify command with the -b parameter and the following LDIF notation:

This notation indicates that ldapmodify should read the referenced file for binary values if the attribute value begins with a slash.

Using Base 64 Encoding


Note	This behavior is not supported by the Directory Server console. In the console, values that begin with a slash are added literally to the directory.

Use the directoryserver ldif command-line utility with the -b parameter to convert binary data to LDIF format:

where attributeName is the name of the attribute to which you are supplying the binary data. The binary data is read from standard input and the results are written to standard output. Thus, you should use redirection operators to select input and output files.

The command takes any input and formats it with the correct line continuation and appropriate attribute information. It also assesses whether the input requires base 64 encoding. For example:

This example takes a binary file containing a JPEG-formatted image and converts it into LDIF format for the attribute named jpegPhoto. The output is saved to out.ldif.

The -b option specifies that the utility should interpret the entire input as a single binary value. If -b is not present, each line is considered to be a separate input value.

You can then edit the output file to add the LDIF statements required to create or modify the directory entry that will contain the binary value. For example, you can open the file out.ldif in a text editor and add the following lines (shown in bold) at the top of the file:

dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
add: jpegPhoto
jpegPhoto:: encoded_data

In this example, encoded_data represents the contents of the out.ldif file produced by the command.

Specifying Directory Entries Using LDIF

You can store many types of entries in a directory. This section concentrates on three of the most common types of entries used in a directory: organization, organizational unit, and organizational person entries.

The object classes defined for an entry indicate whether the entry represents an organization, an organizational unit, an organizational person, or some other type of entry. For a general discussion of the types of entries you can create in a directory, refer to the Directory Server Deployment Planning Guide. For a complete list of the default object classes and a list of the most commonly used attributes, refer toChapter 9, "Object Class Reference," and Chapter 10, "Attribute Reference."

Specifying Organization Entries

Directories often have at least one organization entry. Typically this is the first, or topmost entry in the directory. The organization entry often corresponds to the suffix set for the directory. For example, if your directory is defined to use a suffix of o=example.com, you will probably have an organization entry named o=example.com.

The LDIF that you specify to define an organization entry should appear as follows:

dn: distinguished_name
objectClass: top
objectClass: organization
o: organization_name
list_of_optional_attributes
...

dn: o=example.com
objectclass: top
objectclass: organization
o: example.com Corporation
description: Fictional company for example purposes
telephonenumber: 555-5555

dn: o="example.com Chile\\, S.A."
objectclass: top
objectclass: organization
o: example.com Chile\\, S.A.
description: Fictional company for example purposes
telephonenumber: 555-5556

Table 7-2 LDIF Elements in Organization Entries
LDIF Element	Description
dn: distinguished_name	Specifies the distinguished name for the entry. DNs are described in the Directory Server Deployment Planning Guide A DN is required.
objectClass: top	Required. Specifies the top object class.
objectClass: organization	Specifies the organization object class. This line defines the entry as an organization. See Chapter 10, "Attribute Reference," for a list of the attributes you can use with this object class.
o: organization_name	Specifies the organization's name. If the organization name includes a comma, you must escape the comma by a single backslash or the entire organization argument must be enclosed in quotation marks. However, if you are working with a UNIX shell, this backslash will also need escaping which means that you will have to use two backslashes. For example, to set the suffix to example.com Bolivia, S.A. you would enter "o: example.com Bolivia\\, S.A.".
list_of_attributes	Specifies the list of optional attributes that you want to maintain for the entry. Refer to Chapter 10, "Attribute Reference," for a list of the attributes you can use with this object class.

Specifying Organizational Unit Entries

Organizational unit entries are often used to represent major branch points, or subdirectories, in the directory tree. They correspond to major, reasonably static entities within an enterprise, such as a subtree that contains people, or a subtree that contains groups. However, the organizational unit attribute that is contained in the entry may also represent a major organization within the enterprise, such as marketing or engineering.

There is usually more than one organizational unit, or branch point, within a directory tree. For information on how to design your directory tree, refer to the Directory Server Deployment Planning Guide.

The LDIF that you specify to define an organizational unit entry must appear as follows:

dn: distinguished_name
objectClass: top
objectClass: organizationalUnit
ou: organizational_unit_name
list_of_optional_attributes
...

dn: ou=people, o=example.com
objectclass: top
objectclass: organizationalUnit
ou: people
description: Fictional organizational unit for example purposes

Table 7-3 LDIF Elements in Organizational Unit Entries
LDIF Element	Description
dn: distinguished_name	Specifies the distinguished name for the entry. A DN is required. If there is a comma in the DN, the comma must be escaped with a backslash (\). For example: dn: ou=people,o=example.com Bolivia\,S.A.
objectClass: top	Required. Specifies the top object class.
objectClass: organizationalUnit	Specifies the organizationalUnit object class. This line defines the entry as an organizationalUnit. Refer to Chapter 10, "Attribute Reference," for a list of the attributes you can use with this object class.
ou: organizational_unit_name	Attribute that specifies the organizational unit's name.
list_of_attributes	Specifies the list of optional attributes that you want to maintain for the entry. Refer to Chapter 10, "Attribute Reference," for a list of the attributes you can use with this object class.

Specifying Organizational Person Entries

dn: distinguished_name
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: common_name
sn: surname
list_of_optional_attributes

dn: uid=bjensen,ou=people,o=example.com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Babs Jensen
sn: Jensen
givenname: Babs
uid: bjensen
ou: Marketing
ou: people
description: Fictional person for example purposes
telephonenumber: 555-5557
userpassword: {sha}dkfljlk34r2kljdsfk9

Table 7-4 LDIF Elements in Person Entries
LDIF Element	Description
dn: distinguished_name	Specifies the distinguished name for the entry. A DN is required. If there is a comma in the DN, the comma must be escaped with a backslash (\). For example, dn:uid=bjensen,ou=people,o=example.com Bolivia\,S.A.
objectClass: top	Required. Specifies the top object class.
objectClass: person	Specifies the person object class. This object class specification should be included because many LDAP clients require it during search operations for a person or an organizational person.
objectClass: organizationalPerson	Specifies the organizationalPerson object class. This object class specification should be included because some LDAP clients require it during search operations for an organizational person.
objectClass: inetOrgPerson	Specifies the inetOrgPerson object class. The inetOrgPerson object class is recommended for the creation of an organizational person entry because this object class includes the widest range of attributes. The uid attribute is required by this object class, and entries that contain this object class are named based on the value of the uid attribute. Refer to Chapter 10, "Attribute Reference," for a list of the attributes you can use with this object class.
cn: common_name	Specifies the person's common name which is the full name commonly used by the person. For example, cn: Bill Anderson. At least one common name is required.
sn: surname	Specifies the person's surname, or last name. For example, sn: Anderson. A surname is required.
list_of_attributes	Specifies the list of optional attributes that you maintain for the entry. Refer to Chapter 10, "Attribute Reference," for a list of the attributes you can use with this object class.

Defining Directories Using LDIF

You can define the contents of an entire directory using LDIF. Using LDIF is an efficient method of directory creation when you have many entries to add to the directory.

Make sure each entry is separated from the next by an empty line. You should use just one line. The first line of the file must not be blank (otherwise the ldapmodify utility will exit). For more information, refer to Specifying Directory Entries Using LDIF.

Begin each file with the topmost, or root, entry in the database.

The root entry must represent the suffix or sub-suffix contained by the database. For example, if your database has the suffix dc=example,dc=com, the first entry in the directory must be

dn: dc=example,dc=com

For information on suffixes, refer to Suffix Configuration Attributes Under cn="suffixName".

Make sure that an entry representing a branch point in the LDIF file is placed before the entries that you want to create under that branch.

For example, if you want to place an entry in a people and a group subtree, create the branch point for those subtrees before creating entries within those subtrees.

Create the directory from the LDIF file using one of the following methods:

Directory Server console

Use this method if you have a small database to import (less than 1000 entries). Refer to "Importing LDIF From the Console" in the Directory Server Administration Guide.

ldif2db command-line utility

Use this method if you have a large database to import (more than 1,000 entries). Refer to "Importing Using the ldif2db Command" in the Directory Server Administration Guide.

ldapmodify command-line utility with the -a parameter

Use this method if you currently have a directory database, but you are adding a new subtree to the database. Unlike the other methods for creating the directory from an LDIF file, Directory Server must be running before you can add a subtree using ldapmodify. Refer to "Adding and Modifying Entries Using ldapmodify" in the Directory Server Administration Guide.

LDIF File Example

The following example shows an LDIF file that contains one organization, two organizational units, and three organizational person entries:

dn: o=example.com Corp
objectclass: top
objectclass: organization
o: example.com Corp
description: Fictional organization for example purposes

dn: ou=People,o=example.com Corp
objectclass: top
objectclass: organizationalUnit
ou: People
description: Fictional organizational unit for example purposes
tel: 555-5559

dn: cn=June Rossi,ou=People,o=example.com Corp
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: June Rossi
sn: Rossi
givenName: June
mail: rossi@example.com
userPassword: {sha}KDIE3AL9DK
ou: Accounting
ou: people
telephoneNumber: 2616
roomNumber: 220

dn: cn=Marc Chambers,ou=People,o=example.com Corp
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Marc Chambers
sn: Chambers
givenName: Marc
mail: chambers@example.com
userPassword: {sha}jdl2alem87dlacz1
telephoneNumber: 2652
ou: Manufacturing
ou: People
roomNumber: 167

dn: cn=Robert Wong,ou=People,o=example.com Corp
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Robert Wong
cn: Bob Wong
sn: Wong
givenName: Robert
givenName: Bob
mail: bwong@example.com
userPassword: {sha}nn2msx761
telephoneNumber: 2881
roomNumber: 211
ou: Manufacturing
ou: people

dn: ou=Groups,o=example.com Corp
objectclass: top
objectclass: organizationalUnit
ou: groups
description: Fictional organizational unit for example purposes

Storing Information in Multiple Languages

If your directory contains a single language, you do not need to do anything special to add a new entry to the directory. However, if your organization is multinational, you may find it necessary to store information in multiple languages so that users in different locales can view directory information in their own language.

When information in your directory is represented in multiple languages, the server associates language tags with attribute values. When you add a new entry, you must provide attribute values used in the RDN (Relative Distinguished Name) without any language codes.

You can even store multiple languages within a single attribute. When you do, the attribute types are the same, but each value has a different language code.

For a list of the languages supported by Directory Server and their associated language tags, refer to Identifying Supported Locales.

For example, suppose example.com Corporation has offices in the United States and France and wants employees to be able to view directory information in their native language. When adding directory entries, the directory administrator chooses to provide attribute values in both English and French. When adding a directory entry for a new employee, Babs Jensen, the administrator creates the following LDIF entry:


Note	The language tag has no effect on how the string is stored within the directory. All object class and attribute strings are stored using UTF-8.

dn: uid=bjensen,ou=people, o=example.com Corp
objectclass: top
objectclass: person
objectclass: organizationalPerson
name: Babs Jensen
cn: Babs Jensen
sn: Jensen
uid: bjensen
personalTitle: Miss
personalTitle;lang-en: Miss
personalTitle;lang-fr: Mlle
preferredLanguage: fr

Users accessing this directory entry with an LDAP client with the preferred language set to English will see the personal title Miss. Users accessing the directory with an LDAP client with the preferred language set to French will see the title Mlle.

Previous Contents Index Next
Sun Java(TM) System Directory Server 5.2 2005Q1 Administration Reference