Previous Next Contents Index


Chapter 2 LDAP Data Interchange Format

The directory server uses the LDAP Data Interchange Format (LDIF) to describe a directory and directory entries in text format. LDIF is commonly used to initially build a 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 the 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:

For information on using LDIF to modify directory entries, see Chapter  9, "Managing 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 basic form of a directory entry represented in LDIF is

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

Table  2.1 describes the LDIF fields shown in the previous definition.

Table 2.1 LDIF fields  

Field
Definition
[<id>]
Optional 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 Manual.
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 Guide for a list of standard object classes, and Chapter  3, "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 slapd.at.conf or with the attribute parameter in slapd.conf. See the Netscape Directory Server Schema Reference Guide for a list of standard attributes, and Chapter  3, "Extending the Directory Schema," for information on customizing the schema.
[subtype]
Optional. Specifies a subtype, either 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 a complete list of the supported subtypes tags, see Table  B.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  9, "Managing Directory Entries."

Continued Lines

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, o=airius.com

dn: cn=Jake Lup
 inski, o=air
 ius.com

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

Base 64 Encoding

You can represent Binary data, such as a JPEG image, in LDIF by 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

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 senses whether the input requires base 64 encoding.

LDIF Parameter

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

LDIF Example

The following 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:

ldif -b jpegPhoto < mark.jpg > out.ldif

For information on where to find command-line utilities in your directory server installation, see "Finding the Command-Line Utilities".


Creating Directory Entries Using LDIF
There are many types of entries that you can store 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 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 Guide.

Specifying Organization Entries

Directories often have at least one organization entry. Typically this is the first, or root, 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 o=airius.com, then you will probably have an organization entry in your directory named o=airius.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: o=airius.com
objectclass: top
objectclass: organization
o: Airius Corporation
description: Fictional company for example purposes
telephonenumber: 555-5555

The organization name in the following example uses a comma:

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

Each element of the LDIF-formatted organization entry is defined in Table  2.2.

Table 2.2 LDIF elements in organization entries  

LDIF Element
Description
dn: <distinguished name>
Specifies the DN for the entry. DNs are described in the Netscape Directory Server Deployment Manual. 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 Guide 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 (on NT) or two backslashes (on Unix) and the entire organization argument must be enclosed in quotation marks. For example, to set the suffix to Airius Bolivia, S.A. you would enter "o:  Airius Bolivia\\, S.A." on Unix or "o:  Airius Bolivia\, S.A." on Windows NT.
<list of attributes>
Specifies the list of optional attributes that you want to maintain for the entry. See the Netscape Directory Server Schema Reference Guide 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 Manual.

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, o=airius.com
objectclass: top
objectclass: organizationalUnit
ou: people
description: Fictional organizational unit for example purposes

Table  2.3 defines each element of the LDIF-formatted organizational unit entry.

Table 2.3 LDIF elements in organizational unit entries  

LDIF Element
Description
dn: <distinguished name>
Specifies the DN for the entry. DNs are described in the Netscape Directory Server Deployment Manual. 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=airius 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 Guide 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 Guide for a list of the attributes you can use with this object class.

Specifying Organizational Person Entries

The most common type of entry that you will include in your directory will probably describe a person within your organization. The majority of the entries in your directory will represent organizational people.

The LDIF you specify to define an organizational person should appear 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, o=airius.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  2.4 defines each aspect of the LDIF-formatted person entry.

Table 2.4 LDIF elements in person entries  

LDIF Element
Description
dn: <distinguished name>
Specifies the DN for the entry. DNs are described in the Netscape Directory Server Deployment Manual. 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=airius  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 Guide for a list of the attributes you can use with this object class.
cn: <common name>
Specifies the person's common name. That 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 want to maintain for the entry. See the Netscape Directory Server Schema Reference Guide 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. Use this method of directory creation when you have many entries to add to the directory.

In general, to create a directory using LDIF, follow these steps:

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

    2. Make sure each entry is separated from the next by an empty line. For more information, see "Creating Directory Entries Using LDIF".

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

    3. The root point of the directory must represent a suffix you have set for your server. For example, if your server has the suffix o=airius.com, then the first entry in your directory must be

    dn: o=airius.com

    If the suffix contains a comma, the comma must be preceded by two backslashes (\\), to serve as escape characters, and the entire organization argument must be enclosed in quotation marks. For example, if your server has the suffix o=Airius Bolivia, S.A., then the corresponding suffix entry must be

    dn: "o=airius bolivia\\, S.A."

    For information on suffixes, see the Suffix parameter in Chapter  17, "Configuration Parameters."

  3. Make sure that you create an entry representing a branch point before you create new entries under that branch.

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

    dn: o=airius.com
    <list of attributes and object classes>

    dn: ou=people, o=airius.com
    <list of attributes and object classes>

    ...

    <People subtree entries.>

    ...

    dn: ou=groups, o=airius.com
    <list of attributes and object classes>

    ...

    <Groups subtree entries.>

    ...

    If an entry's DN contains a comma, the comma must be preceded by a backslash (\). For example:

    dn: ou=people, o=airius bolivia\, S.A.

  4. Create the directory from the LDIF file using one of the following methods:
LDIF File Example

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

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

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

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

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

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

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


Storing Information in Multiple Languages
If your directory contains entry and attribute information in 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 type are the same, but each value has a different language code.

For a list of the languages supported by the 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 Airius 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, o=airius.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 University
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 University.
 

© Copyright 1999 Netscape Communications Corporation, a subsidiary of America Online, Inc. All Rights Reserved.