Guidelines for Providing LDIF Input

All directory data is stored using the UTF-8 encoding of Unicode. Therefore, any LDIF input you provide must also be UTF-8 encoded. The LDIF format is described in detail in “LDAP Data Interchange Format Reference” in the Sun Java System Directory Server Enterprise Edition 6.0 Reference.

Consider the following points when you provide LDIF input:

• An object is a blank line followed by a line that starts with dn:. This line is the distinguished name of the object. All other lines are the object’s attributes.

• Comments start with # (and end with the EOL.)

• Lines starting with a single space continue the previous line.

• Binary values are base-64 encoded, and represented with a double colon (::) after the attribute name.

• Carriage returns and line feeds unsafe in LDIF values, and should be base-64 encoded.

• Do not unintentionally leave trailing spaces at the end of an attribute value when you change the attribute value by using the ldapmodify command.

Terminating LDIF Input on the Command Line

The ldapmodify and ldapdelete utilities read the LDIF statements that you enter after the command in exactly the same way as if they were read from a file. When you finish providing input, enter the character that your shell recognizes as the end of file (EOF) escape sequence.

Typically, the EOF escape sequence is Control-D (^D).

The following example shows how to terminate input to the ldapmodify command:

prompt\> ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w -
 dn: cn=Barry Nixon,ou=People,dc=example,dc=com
changetype: modify
delete: telephonenumber
^D
prompt\>

For simplicity and portability, examples in this document do not show prompts or EOF sequences.

Using Special Characters

When entering command options on the command line, you may need to escape characters that have special meaning to the command-line interpreter, such as space ( ), asterisk (*), backslash (\\), and so forth. For example, many DNs contain spaces, and you must enclose the value in double quotation marks ("") for most UNIX shells:

-D "cn=Barbara Jensen,ou=Product Development,dc=example,dc=com"

Depending on your command-line interpreter, you should use either single or double quotation marks for this purpose. Refer to your operating system documentation for more information.

In addition, if you are using DNs that contain commas, you must escape the commas with a backslash (\\). For example:

-D "cn=Patricia Fuentes,ou=People,o=example.com Bolivia\\,S.A."

Note that LDIF statements after the ldapmodify command are being interpreted by the command, not by the shell, and therefore do not need special consideration.

Using Attribute OIDs

Attribute OIDs are by default not supported in attribute names. This was not the case in some previous versions of Directory Server. If you used attribute OIDs as attribute names in a previous version of Directory Server, you must set the attribute nsslapd-attribute-name-exceptions to on for the attribute OIDs to be accepted.

Schema Checking

When adding or modifying an entry, the attributes you use must be required or allowed by the object classes in your entry, and your attributes must contain values that match their defined syntax.

When modifying an entry, Directory Server performs schema checking on the entire entry, not only the attributes being modified. Therefore, the operation may fail if any object class or attribute in the entry does not conform to the schema.

Ordering of LDIF Entries

In any sequence of LDIF text for adding entries, either on the command line or in a file, parent entries must be listed before their children. This way, when the server process the LDIF text, it will create the parent entries before the children entries.

For example, if you want to create entries in a People subtree that does not exist in your directory, then list an entry representing the People container before the entries within the subtree:

dn: dc=example,dc=com
dn: ou=People,dc=example,dc=com
...
People subtree entries...
dn: ou=Group,dc=example,dc=com
...
Group subtree entries...

You can use the ldapmodify command-line utility to create any entry in the directory, however, the root of a suffix or subsuffix is a special entry that must be associated with the necessary configuration entries.

Managing Large Entries

Before adding or modifying entries with very large attribute values, you may need to configure the server to accept them. To protect against overloading the server, clients are limited to sending data no larger than 2 MB by default.

If you add an entry larger than this, or modify an attribute to a value which is larger, the server will refuse to perform the operation and immediately close the connection. For example, binary data such as multi-media contents in one or more attributes of an entry may exceed this limit.

Also, the entry defining a large static group may contain so many members that their representation exceeds the limit. However, such groups are not recommended for performance reasons, and you should consider redesigning your directory structure.

To Modify the Size Limit Enforced by the Server on Data Sent by Clients

1. Set a new value for the nsslapd-maxbersize attribute of the cn=config entry.

   • To do this from the command line, use the following command:

     ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w - dn: cn=config changetype: modify replace: nsslapd-maxbersize nsslapd-maxbersize: sizeLimitInBytes ^D

     For more information, see “nsslapd-maxbersize” in the Sun Java System Directory Server Enterprise Edition 6.0 Reference.

2. Restart the server.

Error Handling

The command-line tools process all entries or modifications in the LDIF input sequentially. The default behavior is to stop processing when the first error occurs. Use the -c option to continue processing all input regardless of any errors. You will see the error condition in the output of the tool.

In addition to the considerations listed above, common errors are:

• Not having the appropriate access permission for the operation.

• Adding an entry with a DN that already exists in the directory.

• Adding an entry below a parent that does not exist.