Sun Java(TM) System Directory Server 5.2 2005Q1 Administration Reference |
Chapter 7
LDAP Data Interchange Format ReferenceDirectory 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 simultaneously. 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 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 appendix provides information about LDIF in the following sections:
LDIF File FormatLDIF 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). Sun Java System 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 Chapter 9, "Object Class Reference," and Chapter 10, "Attribute Reference."
Table 7-1 describes the LDIF fields shown in the previous definition.
Table 7-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 Directory Server Deployment Planning 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. Refer to Chapter 9, "Object Class Reference," for a list of standard object classes.
attribute_type
Specifies a descriptive attribute to use with the entry. The attribute should be defined in the schema.
Refer to Chapter 10, "Attribute Reference," for a list of standard attributes.
[subtype]
Optional. Specifies a subtype, which may be one of:
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 more information, refer to "Adding an Attribute Subtype" in the Directory Server Administration Guide.
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, refer to "Creating Directory Entries" in the Directory Server Administration Guide.
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=exam
ple,dc=comYou are not required to break and continue LDIF lines. However, doing so may improve the readability of an 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
Note that this path is relative to the client, not to the server. 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: BarneysCertUsing 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.
Sun Java System 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 the Directory Server 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:
Use the directoryserver ldif command-line utility with the -b parameter to convert binary data to LDIF format:
/usr/sbin/directoryserver 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 command takes any input and formats it with the correct line continuation and appropriate attribute information. It also assesses whether the input requires base 64 encoding. For example:
/usr/sbin/directoryserver 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 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=example,dc=com
changetype: modify
add: jpegPhoto
jpegPhoto:: encoded_dataIn this example, encoded_data represents the contents of the out.ldif file produced by the command.
Specifying Directory Entries Using LDIFYou can store many types of entries in a 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 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 a directory, refer to the Directory Server Deployment Planning Guide. For a complete list of the default object classes and a list of the most commonly used attributes, refer toChapter 9, "Object Class Reference," and Chapter 10, "Attribute Reference."
Specifying Organization Entries
Directories often have at least one organization entry. Typically this is the first, or topmost entry in the directory. The organization entry often corresponds to the suffix set for the directory. For example, if your directory is defined to use a suffix of o=example.com, you will probably have an organization entry named o=example.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=example.com
objectclass: top
objectclass: organization
o: example.com Corporation
description: Fictional company for example purposes
telephonenumber: 555-5555The 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-5556Each element of the LDIF-formatted organization entry is defined in Table 7-2.
Table 7-2 LDIF Elements in Organization Entries
LDIF Element
Description
dn: distinguished_name
Specifies the distinguished name for the entry. DNs are described in the Directory Server Deployment Planning Guide A DN is required.
objectClass: top
Required. Specifies the top object class.
objectClass:
organizationSpecifies the organization object class. This line defines the entry as an organization. See Chapter 10, "Attribute Reference," for a list of the attributes you can use with this object class.
o: organization_name
Specifies the organization's name. If the organization name includes a comma, you must escape the comma by a single backslash or 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.".
list_of_attributes
Specifies the list of optional attributes that you want to maintain for the entry. Refer to Chapter 10, "Attribute 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 the directory tree. They correspond to major, reasonably static entities within an 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 the 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, refer to the Directory Server Deployment Planning 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, o=example.com
objectclass: top
objectclass: organizationalUnit
ou: people
description: Fictional organizational unit for example purposesTable 7-3 defines each element of the LDIF-formatted organizational unit entry.
Table 7-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:
organizationalUnitSpecifies the organizationalUnit object class. This line defines the entry as an organizationalUnit. Refer to Chapter 10, "Attribute 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. Refer to Chapter 10, "Attribute 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,o=example.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}dkfljlk34r2kljdsfk9Table 7-4 defines each aspect of the LDIF person entry.
Table 7-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:
organizationalPersonSpecifies 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. Refer to Chapter 10, "Attribute 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. Refer to Chapter 10, "Attribute Reference," for a list of the attributes you can use with this object class.
Defining Directories Using LDIFYou 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. The first line of the file must not be blank (otherwise the ldapmodify utility will exit). For more information, refer to 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=example,dc=com, the first entry in the directory must be
dn: dc=example,dc=com
For information on suffixes, refer to Suffix Configuration Attributes Under cn="suffixName".
- 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:
Use this method if you have a small database to import (less than 1000 entries). Refer to "Importing LDIF From the Console" in the Directory Server Administration Guide.
Use this method if you have a large database to import (more than 1,000 entries). Refer to "Importing Using the ldif2db Command" in the Directory Server Administration Guide.
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. Refer to "Adding and Modifying Entries Using ldapmodify" in the Directory Server Administration Guide.
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
objectclass: top
objectclass: organization
o: example.com Corp
description: Fictional organization for example purposesdn: ou=People,o=example.com Corp
objectclass: top
objectclass: organizationalUnit
ou: People
description: Fictional organizational unit for example purposes
tel: 555-5559dn: cn=June Rossi,ou=People,o=example.com Corp
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: 220dn: cn=Marc Chambers,ou=People,o=example.com Corp
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: 167dn: cn=Robert Wong,ou=People,o=example.com Corp
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: peopledn: ou=Groups,o=example.com Corp
objectclass: top
objectclass: organizationalUnit
ou: groups
description: Fictional organizational unit for example purposes
Storing Information in Multiple LanguagesIf 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, refer to 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, o=example.com Corp
objectclass: top
objectclass: person
objectclass: organizationalPerson
name: Babs Jensen
cn: Babs Jensen
sn: Jensen
uid: bjensen
personalTitle: Miss
personalTitle;lang-en: Miss
personalTitle;lang-fr: Mlle
preferredLanguage: frUsers accessing this directory entry with an LDAP client with the preferred language set to English will see the personal title Miss. Users accessing the directory with an LDAP client with the preferred language set to French will see the title Mlle.