LDAP Data Interchange Format
he 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:
- The LDIF File Format
- Creating Directory Entries Using LDIF
- Defining Directories Using LDIF
- Specifying LDIF for an Internationalized Directory
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 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 LupYou are not required to break and continue LDIF lines. However, it may improve the readability of your LDIF file.
inski, o=air
ius.com
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 toout.ldif:
ldif -b jpegPhoto < mark.jpg > out.ldifFor information on where to find command-line utilities in your directory server installation, see "Finding the Command-Line Utilities" on page 29.
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" of the online Administrator's Guide. For a definition of the most commonly used attributes, see Appendix B, "Attributes" of the online Administrator's Guide.
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>The following defines each aspect of the LDIF-formatted entry:
objectClass: top
objectClass: organization
o: <organization name>
<list of optional attributes>
...
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" of the online Administrator's
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, 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" of the online Administrator's Guide, 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>The following defines each aspect of the LDIF-formatted entry:
objectClass: top
objectClass: organizationalUnit
ou: <organizational unit name>
<list of optional attributes>
...
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" of the
online Administrator's 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 Appendix A, "Object Classes" of the online Administrator's Guide,
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>The following defines each aspect of the LDIF-formatted entry:
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: <common name>
sn: <surname>
<list of optional attributes>
...
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" of the online Administrator's Guide, 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" of the online Administrator's Guide,
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:- Create an ASCII file containing the entries you want to add in LDIF format. See "Creating Directory Entries Using LDIF" on page 37 for more information. Make sure each entry is separated from the next by an empty line.
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 342.
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.
- Directory Server Manager --Use this method if you currently do not have a directory database for your directory server. See "Importing LDIF Using the Server Manager" on page 60.
ns-slapdcommand-line utility-- Use this method if you currently do not have a directory database for your directory server. See "Importing LDIF from the Command Line" on page 61.ldapmodifycommand-line utility with the -a parameter --Use this method if you currently have a directory database, but you are adding an entire new directory or subdirectory to the database. If you are adding an entire new directory to your database, then make sure that you first define a suffix for your new directory. Unlike the other methods for creating the directory from the LDIF file, the directory server must be on before you can add a directory or subdirectory usingldapmodify. See "Modifying Entries Using ldapmodify" on page 200.
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" on page 499.
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.comUsers 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.
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