Appendix A
LDAP Data Interchange Format
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:
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). iPlanet 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 iPlanet 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 iPlanet 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 iPlanet 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 iPlanet 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, 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 information on attribute subtypes, see "Adding an Attribute Subtype," on page 50. For a complete list of the supported subtypes tags, see Table D-2 on page 533.
|
|
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=siroe,dc=com
dn: cn=Jake Lup
inski, dc=sir
oe,dc=comcom
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:
Using Standard LDIF Notation
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=siroe,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.
iPlanet Directory Server accepts the ldapmodify command with the -b parameter and the following LDIF notation:
jpegphoto: /path/to/photo
This notation indicates that ldapmodify should read the referenced file for binary values if the attribute value begins with a slash.
|
Note
|
This behavior is not supported by Directory Console. In the Console, values that begin with a slash are added literally to the directory.
|
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:
|
Solaris 9 platform
|
# /usr/sbin/directoryserver ldif -b attributeName
|
|
Other platforms
|
# installDir/bin/slapd/server/ldif -b attributeName
|
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 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.
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=siroe,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 ldif command.
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 can create in your directory, see the iPlanet 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 iPlanet 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=siroe,dc=com, then you will probably have an organization entry in your directory named dc=siroe,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=siroe,dc=com
objectclass: top
objectclass: organization
o: siroe.com Corporation
description: Fictional company for example purposes
telephonenumber: 555-5555
The organization name in the following example uses a comma:
dn: o="siroe.com Chile\\, S.A."
objectclass: top
objectclass: organization
o: "siroe.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 iPlanet 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 iPlanet 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 siroe.com Bolivia, S.A. you would enter "o: siroe.com Bolivia\\, S.A." on UNIX machines or "o: siroe.com 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 iPlanet 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 iPlanet 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=siroe,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=siroe.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 iPlanet 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 iPlanet 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=siroe,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=siroe.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 iPlanet 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 iPlanet 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-suffix contained by the database. For example, if your database has the suffix dc=siroe,dc=com, the first entry in your directory must be
-
dn: dc=siroe,dc=com
-
For information on suffixes, see the "Suffix" parameter described in the iPlanet 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:
LDIF File Example
The following example shows an LDIF file that contains one organization, two organizational units, and three organizational person entries:
dn: o=siroe.com Corp,dc=siroe,dc=com
objectclass: top
objectclass: organization
o: siroe.com Corp
description: Fictional organization for example purposes
dn: ou=People,o=siroe.com Corp,dc=siroe,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=siroe.com Corp,dc=siroe,dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: June Rossi
sn: Rossi
givenName: June
mail: rossi@siroe.com
userPassword: {sha}KDIE3AL9DK
ou: Accounting
ou: people
telephoneNumber: 2616
roomNumber: 220
dn: cn=Marc Chambers,ou=People,o=siroe.com Corp,dc=siroe,dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Marc Chambers
sn: Chambers
givenName: Marc
mail: chambers@siroe.com
userPassword: {sha}jdl2alem87dlacz1
telephoneNumber: 2652
ou: Manufacturing
ou: People
roomNumber: 167
dn: cn=Robert Wong,ou=People,o=siroe.com Corp,dc=siroe,dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Robert Wong
cn: Bob Wong
sn: Wong
givenName: Robert
givenName: Bob
mail: bwong@siroe.com
userPassword: {sha}nn2msx761
telephoneNumber: 2881
roomNumber: 211
ou: Manufacturing
ou: people
dn: ou=Groups,o=siroe.com Corp,dc=siroe,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," on page 531.
|
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 siroe.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=siroe,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é.