[Contents] [Previous] [Next] [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 either for input or output.

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

This chapter describes the following:

For information on using LDIF to modify directory entries, see Chapter 9, "Changing Directory Server Entries."

The LDIF File Format

LDIF consists of one or more 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 is

   [<id>]
   dn: <distinguished name>
   objectClass: <object class>
   objectClass: <object class>
   ...
   <attribute type>[;lang-TAG]:<attribute value>
   <attribute type>[;lang-TAG]:<attribute value>
   ...
Note Only the DN and at least one object class definition are required. In addition, any attributes required by the object classes that you define for the entry must also be defined in 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 optional.
The following table describes the LDIF fields shown in the previous definition:

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

<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 Appendix B, "Attributes" for a list of standard attributes.

[lang-TAG]

 Optionally specifies a language subtype. Use this tag to identify the language in which the corresponding attribute value is expressed. For a complete list of the supported language tags, see Table 14.4 on page 340.

<attribute value>

 Specifies the attribute value to be used with the attribute type.

The LDIF syntax for representing a directory change is different. For information on using LDIF to modify directory entries, see Chapter 9, "Changing Directory Server Entries."

Continued Lines

When you specify LDIF, you can break and continue 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, it may improve the readability of your LDIF file.

Base 64 Encoding

Binary data, such as a JPEG image, can be represented 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 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 name 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 something else entirely different from these types of entries. For a complete list of the object classes you can use by default in your directory, see Appendix A, "Object Classes". For a definition of the most commonly used attributes, see Appendix B, "Attributes".

Specifying Organization Entries

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

That is, 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 defines each aspect of the LDIF-formatted entry:

dn: <distinguished name>

Specifies the DN for the entry. DNs are described in the Netscape Directory Server Deployment Guide. A DN is required.
objectClass: top

Specifies the top object class. This object class specification is optional. Some older LDAP clients require the existence of object class top during search operations.
objectClass: organization

Specifies the organization object class. This line defines the entry as an organization. See Appendix A, "Object Classes" 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, the comma must be escaped 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 NT. 
<list of attributes>
Specifies the list of optional attributes that you want to maintain for the entry. See Appendix A, "Object Classes" for a list of the attributes you can use with this object class.

Organization Example

 The following is an example 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

Organization Name With a Comma Example

 The following is an example organization entry in LDIF format. The organization name in this example uses a comma:

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

Specifying Organizational Unit Entries

 Organizational unit entries are often used to represent major branch points, or subdirectories, in your directory tree. As such, 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 actually contained on the entry usually also represents a major organization within your enterprise, such as marketing, engineering, or the humanities.

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 should appear as follows:

   dn: <distinguished name>
   objectClass: top
   objectClass: organizationalUnit
   ou: <organizational unit name>
   <list of optional attributes>
   ...
The following defines each aspect of the LDIF-formatted entry:

dn: <distinguished name>

Specifies the DN for the entry. DNs are described in the Netscape Directory Server Deployment Guide. 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

Specifies the top object class. This object class specification is optional. Some older LDAP clients require the existence of object class top during search operations.
objectClass: organizationalUnit

Specifies the organizationalUnit object class. This line defines the entry as an organizationalUnit. See Appendix A, "Object Classes" 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 Appendix A, "Object Classes" for a list of the attributes you can use with this object class.

Organizational Unit Example

 The following is an example 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

Specifying Organizational Person Entries

 The most common type of entry that you will include in your directory will 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 defines each aspect of the LDIF-formatted entry:

dn: <distinguished name>

Specifies the DN for the entry. DNs are described in the Netscape Directory Server Deployment Guide. 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

Specifies the top object class. This object class specification is optional. Some older LDAP clients require the existence of object class top during search operations.
objectClass: person

Specifies the person object class. This object class specification should be included because many LDAP clients will require the existence of object class person 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 the existence of object class organizationalPerson 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. See Appendix A, "Object Classes" for a list of the attributes you can use with this object class.
cn: <common name>

Specifies the common name for the person. 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 Appendix A, "Object Classes" for a list of the attributes you can use with this object class.

OrganizationalPerson Example

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

   dn: uid=bjensen, ou=people, o=airius.com
   objectclass: top
   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

Defining Directories Using LDIF

 You can create an entire directory using LDIF. This method of directory creation is best used 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. See "Creating Directory Entries Using LDIF" on page 33 for more information. Make sure each entry is separated from the next by an empty line.

  2. Begin each directory in the database with the topmost, or root, entry. 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 escaped by two backslashes (\\) 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 on page 322.

  3. As you proceed with your directory creation, make sure that you create an entry representing a branch point before you create new entries under that branch. 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 escaped 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: ou=People, o=airius.com
   objectclass: top
   objectclass: organizationalUnit
   ou: Accounting
   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

Specifying LDIF for an Internationalized Directory

 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 attribute values are associated with language tags. Keep in mind, however, that when you add a new entry, you must provide attribute values used in the RDN without any language codes.

You can even store multiple languages within a single attribute. In this case, the attribute type and value would be the same, but each would have 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 in France and they want employees to be able to view directory information in their own 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 a browser with the preferred language set to English will see the address 1 University Street. Users accessing the directory with a browser with the preferred language set to French will see an address of 1 rue University.

[Contents] [Previous] [Next] [Index]

Last Updated: 02/12/98 11:36:25

Copyright © 1997 Netscape Communications Corporation