| Administrator’s Guide Red Hat Directory Server |
| Previous |
Contents |
Index |
Next |
Appendix A
LDAP Data Interchange Format
Red Hat Directory Server (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:
- LDIF File Format (page 575)
- Specifying Directory Entries Using LDIF (page 579)
- Defining Directories Using LDIF (page 583)
- Storing Information in Multiple Languages (page 586)
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). 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 Red Hat Directory Server Schema Reference.
Table A-1 describes the LDIF fields shown in the previous definition.
Table A-1 LDIF Fields
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=example,dc=com dn: cn=Jake Lup inski, dc=exa mple,dc=comYou 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:
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_password >version: 1 >dn: cn=Barney Fife,ou=People,dc=example,dc=com changetype: modify add: userCertificate userCertificate;binary:< file: BarneysCertjpegPhoto:: encoded_dataIn addition to binary data, other values that must be base 64-encoded include:
- Any value that begins with a colon (:) 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:
ldif -b attribute_namewhere 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 assesses whether the input requires base 64-encoding. For example:
ldif -b jpegPhoto < mark.jpg > out.ldifThis 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.
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 Red Hat 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 Red Hat 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=example,dc=com, then you will probably have an organization entry in your directory named dc=example,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=example,dc=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 A-2.
Table A-2 LDIF Elements in Organization Entries
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 Red Hat 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=example,dc=com objectclass: top objectclass: organizationalUnit ou: people description: Fictional organizational unit for example purposesTable A-3 defines each element of the LDIF-formatted organizational unit entry.
Table A-3 LDIF Elements in Organizational Unit Entries
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_attributesThe following is an example organizational person entry in LDIF format:
dn: uid=bjensen,ou=people,dc=example,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}dkfljlk34r2kljdsfk9Table A-4 defines each aspect of the LDIF person entry.
Table A-4 LDIF Elements in Person Entries
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:
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," on page 579.
The root entry must represent the suffix or sub-suffx contained by the database. For example, if your database has the suffix dc=example,dc=com, the first entry in your directory must be
For information on suffixes, see the "Suffix" parameter described in the Red Hat 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:
- Use this method if you have a small database to import (less than 1000 entries). See "Importing a Database from the Console," on page 152.
- Use this method if you have a large database to import (more than 1,000 entries). See "Importing Using the ldif2db Command-Line Script," on page 155.
- 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. See "Adding and Modifying Entries Using ldapmodify," on page 60.
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,dc=example,dc=com objectclass: top objectclass: organization o: example.com Corp description: Fictional organization for example purposes dn: ou=People,o=example.com Corp,dc=example,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=example.com Corp,dc=example,dc=com objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson cn: June Rossi sn: Rossi givenName: June mail: [email protected] userPassword: {sha}KDIE3AL9DK ou: Accounting ou: people telephoneNumber: 2616 roomNumber: 220 dn: cn=Marc Chambers,ou=People,o=example.com Corp,dc=example,dc=com objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson cn: Marc Chambers sn: Chambers givenName: Marc mail: [email protected] userPassword: {sha}jdl2alem87dlacz1 telephoneNumber: 2652 ou: Manufacturing ou: People roomNumber: 167 dn: cn=Robert Wong,ou=People,example.com Corp,dc=example,dc=com objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson cn: Robert Wong cn: Bob Wong sn: Wong givenName: Robert givenName: Bob mail: [email protected] userPassword: {sha}nn2msx761 telephoneNumber: 2881 roomNumber: 211 ou: Manufacturing ou: people dn: ou=Groups,o=example.com Corp,dc=example,dc=com objectclass: top objectclass: organizationalUnit ou: groups description: Fictional organizational unit for example purposesStoring 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 617.
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,dc=example,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: frUsers 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é.
| Previous |
Contents |
Index |
Next |