Netscape Directory Server Administrator's Guide: Appendix ALDAP Data Interchange Format

Administrator's Guide
Netscape Directory Server

Appendix A LDAP Data Interchange Format

Netscape Directory Server (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 all at once. In addition, 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 your 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.

This chapter provides information about LDIF in the following sections:

LDIF File Format

Specifying Directory Entries Using LDIF

Defining Directories Using LDIF

Storing Information in Multiple Languages

For information on using LDIF to modify directory entries, see Chapter 2 "Creating Directory Entries."

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). Directory Server is compliant with this standard.

The basic form of a directory entry represented in LDIF is as follows:

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 Netscape Directory Server Schema Reference.

Table A-1 describes the LDIF fields shown in the previous definition.

Table A-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 Netscape Directory Server Deployment 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. See the Netscape Directory Server Schema Reference for a list of standard object classes, and Chapter 9 "Extending the Directory Schema" for information on customizing the schema.

attribute_type

Specifies a descriptive attribute to use with the entry. The attribute should be defined either in the schema. See the Netscape Directory Server Schema Reference for a list of standard attributes, and Chapter 9 "Extending the Directory Schema" for information on customizing the schema.

[subtype]

Optional. Specifies a subtype, language, binary, or pronunciation. 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 information on attribute subtypes, see "Adding an Attribute Subtype". For a complete list of the supported subtypes tags, see Table D-2.

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, see Chapter 2 "Creating Directory Entries."

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:

dn: cn=Jake Lupinski,dc=example,dc=com
dn: cn=Jake Lup
inski, dc=exa
mple,dc=com
You are not required to break and continue LDIF lines. However, doing so may improve the readability of your LDIF file.

Representing Binary Data

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

The standard LDIF notation, the lesser than (<) symbol. For example:

jpegphoto: < file:/path/to/photo

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
For example, you could use the following ldapmodify command:

prompt% ldapmodify -D userDN -w user_passwd
>version: 1
>dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
add: userCertificate
userCertificate;binary:< file: BarneysCert

Using base 64 encoding. You identify base 64 encoded data by using the :: symbol. For example:

jpegPhoto:: encoded_data

In addition to binary data, other values that must be base 64-encoded include:

Any value that begins with a semicolon (;) or a space

Any value that contains non-ASCII data, including new lines

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

ldif -b attribute_name
where attribute_name 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 ldif command-line utility will take any input and format it with the correct line continuation and appropriate attribute information. The ldif utility also assesses whether the input requires base 64 encoding. For example:

ldif -b jpegPhoto < mark.jpg > out.ldif
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 ldif 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.

Specifying Directory Entries Using LDIF

You can store many types of entries in your 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 are what 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 canc reate in your directory, see the Netscape Directory Server Deployment Guide. For a complete list of the object classes you can use by default in your directory and a list of the most commonly used attributes, see the Netscape Directory Server Schema Reference.

Specifying Organization Entries

Directories often have at least one organization entry. Typically this is the first, or topmost entry in your directory. The organization entry often corresponds to the suffix set for your directory. For example, if your directory is defined to use a suffix of dc=example,dc=com, then you will probably have an organization entry in your directory named dc=example,dc=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
...
The following is a sample organization entry in LDIF format:

dn: dc=example,dc=com
objectclass: top
objectclass: organization
o: example.com Corporation
description: Fictional company for example purposes
telephonenumber: 555-5555
The organization name in the following example uses a comma:

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
Each element of the LDIF-formatted organization entry is defined in Table A-2.

Table A-2    LDIF Elements in Organization Entries

LDIF Element

Description

dn: distinguished_name

Specifies the distinguished name for the entry. DNs are described in the Netscape Directory Server Deployment 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 the Netscape Directory Server Schema Reference for a list of the attributes you can use with this object class.

o: organization_name

Attribute that specifies the organization's name. If the organization name includes a comma, you must escape the comma by either a single backslash and 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." on UNIX machines or "o: example.com Bolivia\, S.A." on Windows.

list_of_attributes

Specifies the list of optional attributes that you want to maintain for the entry. See the Netscape Directory Server Schema 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 your directory tree. They correspond to major, reasonably static entities within your 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 your 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, see the Netscape Directory Server Deployment 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
...
The following is a sample organizational unit entry in LDIF format:

dn: ou=people, dc=example,dc=com
objectclass: top
objectclass: organizationalUnit
ou: people
description: Fictional organizational unit for example purposes
Table A-3 defines each element of the LDIF-formatted organizational unit entry.

Table A-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. See the Netscape Directory Server Schema 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. See the Netscape Directory Server Schema Reference for a list of the attributes you can use with this object class.

Specifying Organizational Person Entries

The majority of the entries in your directory represent organizational people.

In LDIF, the definition of an organizational person is as follows:

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

The following is an example organizational person entry in LDIF format:

dn: uid=bjensen,ou=people,dc=example,dc=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 A-4 defines each aspect of the LDIF person entry.

Table A-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. See the Netscape Directory Server Schema 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. See the Netscape Directory Server Schema 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.

To create a directory using LDIF, follow these steps:

Create an ASCII file containing the entries you want to add in LDIF format.

Make sure each entry is separated from the next by an empty line. You should use just one line, and the first line of the file must not be blank or else the ldapmodify utility will exit. For more information, see "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-suffx contained by the database. For example, if your database has the suffix dc=example,dc=com, the first entry in your directory must be

dn: dc=example,dc=com

For information on suffixes, see the "Suffix" parameter described in the Netscape Directory Server Configuration, Command, and File Reference.

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). See "Performing an Import From the Console".

ldif2db command-line utility

Use this method if you have a large database to import (more than 1,000 entries). See "Importing Using the ldif2db Command-Line Script".

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. See "Adding and Modifying Entries Using ldapmodify".

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,dc=example,dc=com
objectclass: top
objectclass: organization
o: example.com Corp
description: Fictional organization for example purposes
dn: ou=People,o=example.com Corp,dc=example,dc=com
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,dc=example,dc=com
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,dc=example,dc=com
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,example.com Corp,dc=example,dc=com
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,dc=example,dc=com
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, see "Identifying Supported Locales".

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.

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:

dn: uid=bjensen,ou=people,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
name: Babs Jensen
cn: Babs Jensen
sn: Jensen
uid: bjensen
streetAddress: 1 University Street
streetAddress;lang-en: 1 University Street
streetAddress;lang-fr: 1 rue de l'Université
preferredLanguage: fr
Users accessing this directory entry with an LDAP client with the preferred language set to English will see the address 1 University Street. Users accessing the directory with an LDAP client with the preferred language set to French will see the address 1 rue de l'Université.

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 Netscape Directory Server Deployment 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. See the Netscape Directory Server Schema Reference for a list of standard object classes, and Chapter 9 "Extending the Directory Schema" for information on customizing the schema.
attribute_type	Specifies a descriptive attribute to use with the entry. The attribute should be defined either in the schema. See the Netscape Directory Server Schema Reference for a list of standard attributes, and Chapter 9 "Extending the Directory Schema" for information on customizing the schema.
[subtype]	Optional. Specifies a subtype, language, binary, or pronunciation. 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 information on attribute subtypes, see "Adding an Attribute Subtype". For a complete list of the supported subtypes tags, see Table D-2.
attribute_value	Specifies the attribute value to be used with the attribute type.

LDIF Element	Description
`dn:` distinguished_name	Specifies the distinguished name for the entry. DNs are described in the Netscape Directory Server Deployment 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 the Netscape Directory Server Schema Reference for a list of the attributes you can use with this object class.
o: organization_name	Attribute that specifies the organization's name. If the organization name includes a comma, you must escape the comma by either a single backslash and 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."` on UNIX machines or `"o: example.com Bolivia\, S.A."` on Windows.
list_of_attributes	Specifies the list of optional attributes that you want to maintain for the entry. See the Netscape Directory Server Schema Reference for a list of the attributes you can use with this object class.

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. See the Netscape Directory Server Schema 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. See the Netscape Directory Server Schema Reference for a list of the attributes you can use with this object class.

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. See the Netscape Directory Server Schema 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. See the Netscape Directory Server Schema Reference for a list of the attributes you can use with this object class.

Last Updated August 15, 2002


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.