Chapter 4
ldapmodify
The ldapmodify tool edits the contents of an LDAP directory, either by adding new entries or by modifying existing ones. The tool takes update statements in LDIF as input and issues the corresponding LDAP request to the designated directory server. By placing all update statements in a file, ldapmodify can be used to process large numbers of modifications and transfer entries between directories.
The ldapmodify tool is also provided with iPlanet Directory Server in the /usr/iplanet/servers/shared/bin directory. However, iPlanet DSRK and its updates include the latest version of the tool. If you use the Solaris operating environment, you may have an older version of ldapmodify in /usr/bin. Be sure your path is set to use the latest version in /opt/iPlanet/bin/idsrk51.
This chapter contains the following sections:
Command Usage
The ldapmodify tool processes update statements, also known as change records, defined by the LDIF standard. An update statement contains the DN of the target entry for the update, the operation to perform, and any data for the entry's attributes. The operation to perform is given by the changetype keyword, and the ldapmodify tool supports the following operations:
-
add delete modify modrdn moddn rename
The syntax for each of these update statements is described in "LDIF Update Statements," in Chapter 2 of the iPlanet Directory Server Administrator's Guide. Some sample update statements are given in "Command-Line Examples".
The ldapmodify tool reads any number of update statements from the standard input or from a file, and it modifies the corresponding entries according to the LDIF instructions. For each DN in the LDIF file, the tool will perform the requested LDAP operation on the designated entry.
The ldapmodify tool also has a special option (-a) for adding entries in bulk. In this case, the input should not contain the changetype keyword, and each of the given DNs will be added as a new entry. Using this feature, the output of the ldapsearch tool may be used as input to the ldapmodify command.
Syntax
The syntax of the ldapmodify command line has three forms:
-
ldapmodify [ options
]
-
ldapmodify [ options
] < LDIFfile
-
ldapmodify [ options
] -f LDIFfile
Where:
In the first form without any LDIFfile
input, the tool will expect you to type one or more LDIF update statements to the standard input. Once you enter all update statements and the EOF (end-of-file) marker, ldapmodify will process your input and perform all operations. The EOF marker is platform dependent:
The ldapmodify -H command will display a usage help text that briefly describes all options.
Modification Prerequisites
When modifying the contents of a directory, you must satisfy several prerequisite conditions. First, the bind DN and password used for authentication must have the appropriate permissions for the operations you perform. Many high level directory operations, such as creating a database suffix, may only be performed by the Directory Manager with a bind DN of "cn=directory manager".
Then, if schema checking is active in your directory, the server will check the contents of new and modified entries against the definition of their object class in the schema. All attributes of an entry, even those not being modified, are checked against their definition and must meet the following conditions:
The value and value type of all attributes being added or modified must conform to their definition in the entry's object class. When this is not the case, the modification of this entry will fail.
Attributes and values not being modified must also conform to the schema. The modification of the entry will fail even if the offending attribute is not being modified. This situation can occur if you run the directory server with schema checking turned off, remove a required attribute or set an illegal value, and then turn schema checking on. For more information, see Chapter 9, "Extending the Directory Schema," in the iPlanet Directory Server Administrator's Guide.
When a modification fails, only the operation on the faulty entry is affected, but ldapmodify will stop processing further input. All entries that were processed before the error was encountered will be successfully added or modified. Use the -c option to specify that the tool should continue processing input after any failed modification.
Finally, you must ensure the coherence of the entries in the LDIF input. Updates are performed on entries in the order they are given in the input, allowing you to manage dependencies between operations. For example, if you want to add entries to a subtree that doesn't exist yet, your LDIF input must first give the update statement for adding the subtree entry, before the update statements for adding entries under the subtree.
Options
The ldapmodify command has three types of options:
Common options.
Input and output options.
SSL (Secure Socket Layer) options.
The common options listed in the following table control the binding and general behavior of the ldapmodify command.
Table 4-1 Common Options of the ldapmodify Command
|
Option
|
Parameter
|
Purpose
|
|
-h
|
hostname
|
Specify the hostname of the directory server. When this option is omitted, the default is localhost.
|
|
-p
|
port
|
Specify the port number for accessing the directory server host. The default is 389 normally and 636 when the SSL options are used.
|
|
-D
|
bindDN
|
Specify a bind DN for accessing your directory, usually in double quotes ("") for the shell. If the bind DN and its password are omitted, the tool will use anonymous binding. The bind DN determines what entries and attributes may be modified, according to the DN's access permissions.
|
|
-w
|
password
|
Specify the password for the bind DN. CAUTION: Specifying the password on the command line is a possible security risk.
|
|
-w
|
-
|
Type the password for the bind DN when prompted in the terminal window. This is the most secure way of specifying the password.
|
|
-j
|
filename
|
Specify a file containing the password for the bind DN. Use this option in scripts and place the password in a secure file to protect the password. This option is mutually exclusive with the -w option.
|
|
-f
|
LDIFfile
|
Give the name of a file containing LDIF update statements (see "LDIF Update Statements," in Chapter 2 of the iPlanet Directory Server Administrator's Guide). The tool will perform each of the update operations (add, modify, or delete) in the order given in the file. When this option is omitted, ldapmodify will read LDIF update statements from the standard input.
|
|
-B
|
baseDN
|
Specify the base DN when performing additions, usually in double quotes ("") for the shell. All entries will be placed under this suffix, thus providing bulk import functionality.
|
|
-V
|
version
|
Specify the LDAP protocol version number to be used for the modify operation, either 2 or 3. LDAP v3 is the default; only specify LDAP v2 when connecting to servers that do not support v3.
|
|
-Y
|
proxyDN
|
Specify the proxy DN to use for the modify operation, usually in double quotes ("") for the shell. For more information about proxy authorization, see Chapter 6, "Managing Access Control," in the iPlanet Directory Server Administrator's Guide.
|
|
-M
|
|
Manage smart referrals: when they are the target of the update, modify the actual entry containing the referral instead of the entry obtained by following the referral. For more information, see "Smart Referrals" in Chapter 5 of the iPlanet Directory Server Deployment Guide.
|
|
-O
|
hopLimit
|
(Capital letter O) Specify the maximum number of referral hops to follow while finding an entry to modify. By default, there is no limit.
|
|
-R
|
|
Specify that referrals should not be followed. By default, referrals are followed automatically.
|
|
-q
|
|
Quiet output mode: the tool will not display any output about the operations it performs.
|
|
-v
|
|
Verbose output mode: the tool will display additional information about the operations it performs.
|
|
-n
|
|
No-op mode: use with the -v option to show what the tool would do with the given input but do not perform any operations.
|
|
-0
(zero)
|
|
Allow runtime library version mismatches. When this option is omitted, the default behavior is to assert that the revision number of the LDAP API is greater than or equal to that used to compile the tool. Also, if the API library and the tool have the same vendor name, the tool will also assert that the vendor version number of the API is greater than or equal to that used to compile the tool. This information is based on the contents of the LDAPAPIInfo structure (see the iPlanet LDAP SDK for C Programming Guide).
|
|
-H
|
|
Display the usage help text that briefly describes all options.
|
The input and output options given in the following table control how ldapmodify processes input files and handles errors.
Table 4-2 Input and Output Options of the ldapmodify Command
|
Option
|
Parameter
|
Purpose
|
|
-a
|
|
Add entry mode: all input entries that do not contain an LDIF changetype statement are processed as add operations. Entries given with a changetype statement are processed accordingly.
The add entry mode provides an easy way to add entries in LDIF. In particular, it allows you to directly add entries from the output files of the ldapsearch tool.
|
|
-F
|
|
Force the application of all updates, regardless of the replica status.
|
|
-i
|
locale
|
Specify the character set to use for the -f LDIFfile
or standard input. The default is the character set specified in the LANG environment variable. You might want to use this option to perform the conversion from the specified character set to UTF8, thus overriding the LANG setting.
|
|
-k
|
path
|
Specify the path to a directory containing conversion routines. These routines are used if you wish to specify a locale that is not supported by default by your directory server. For more information, see "Searching an Internationalized Directory" in Appendix B of the iPlanet Directory Server Administrator's Guide.
|
|
-b
|
|
Handle binary files: the ldapmodify tool will scan every attribute value in the input to determine whether it is a valid file reference, and if so, it will use the contents of the file as the attribute's value. This option is used to input binary data for an attribute, such as a JPEG image. For example, the corresponding LDIF input would be:
This option allows you to directly process entries from the output files of the ldapsearch tool when it uses the -t option.
The ldapmodify tool also supports the LDIF :< URL
notation for directly including file contents. For example:
jpegPhoto:< file:///tmp/photo.jpg (on all platforms)
If all of your input entries use this notation, you do not need to specify the -b option.
|
|
-A
|
|
Non-ASCII mode: display non-ASCII values, in conjunction with the -v option.
|
|
-c
|
|
Continuous mode: errors are reported but the ldapmodify tool will continue processing input and performing operations. When this option is omitted, the default is to quit after reporting an error.
|
|
-e
|
errorFile
|
Invalid update statements in the input will be copied to the errorFile
for debugging. Use with the -c option to correct errors when processing large LDIF input.
|
The SSL (Secure Socket Layer) options listed in the following table allow you to use LDAPS (LDAP over SSL) to establish a secure connection for the update operation. These options are valid only when LDAPS has been turned on and configured in your SSL-enabled directory server. For information on certificate-based authentication and creating a certificate database for use with LDAP clients, see Chapter 11, "Managing SSL" in the iPlanet Directory Server Administrator's Guide.
Only the -P option is required for server authentication. For the more secure client authentication, the -P, -N, -K and -W options are required. See "Using Authentication" for examples using the SSL options.
Table 4-3 SSL Options of the ldapmodify Command
|
Option
|
Parameter
|
Purpose
|
|
-P
|
path
|
Specify the path and filename of the client's certificate database. This file may be the same as the certificate database for an SSL-enabled version of Netscape™ Communicator, if available; for example: -P /home/uid
/.netscape/cert7.db. When using the command on the same host as the directory server, you may use the server's own certificate database, for example:
-P installDir
/slapd-serverID
/alias/cert7.db.
Use the -P option alone to specify server authentication only.
|
|
-Z
|
|
Specify that SSL be used to provide certificate-based client authentication. This option requires the -N and -W options and any other of the SSL options needed to identify the certificate and the key database.
|
|
-N
|
certificate
|
Specify the certificate name to use for certificate-based client authentication, for example: -N "Directory-Cert".
|
|
-m
|
path
|
Specify the path to the security module database. For example, /usr/iplanet/servers/slapd-serverID
/secmodule.db. You need to specify this option only if the security module database is in a different directory from the certificate database itself.
|
|
-K
|
keyFile
|
Specify the file and path name of the client's private key database. This option may be omitted if the key database is in the location already given by the -P option.
|
|
-W
|
password
|
Specify the password for the client's key database given in the -K or -P options. This option is required for certificate-based client authentication.
|
Return Values
The ldapmodify tool is based on the iPlanet LDAP SDK for C and its return values are those of the functions it uses, such as ldap_simple_bind_s(), ldap_add_ext_s(), ldap_modify_ext_s(), and ldap_delete_ext_s(). These functions return both client-side and server-side errors and codes.
The following table shows the possible return values when the directory is hosted on an iPlanet Directory Server. Other LDAP servers may send these values under different circumstances or may send different values. The directory server responding to the ldapmodify tool may also send other result codes in addition to those described here, for example, custom result codes from a custom plug-in.
For further information about result codes, see the iPlanet LDAP SDK for C Programming Guide.
Table 4-4 Return Values of the ldapmodify Command
|
Return Value
|
Result Code
and Explanation
|
|
0 (0x00)
|
LDAP_SUCCESS: the operation was successful.
|
|
1 (0x01)
|
LDAP_OPERATIONS_ERROR: sent by the Directory Server for general errors encountered by the server when processing the request.
|
|
2 (0x02)
|
LDAP_PROTOCOL_ERROR: the modify request did not comply with the LDAP protocol. The Directory Server may set this error code in the results for a variety of reasons, such as encountering an error when decoding the BER-encoded request.
|
|
10 (0x0a)
|
LDAP_REFERRAL: sent by the Directory Server if the specified DN is an entry not handled by the current server and if the referral URL identifies a different server to handle the entry.
|
|
16 (0x10)
|
LDAP_NO_SUCH_ATTRIBUTE: sent by the Directory Server if the attribute that you want to modify (add, replace, or delete) does not exist.
|
|
19 (0x13)
|
LDAP_CONSTRAINT_VIOLATION: sent by the Directory Server when improperly modifying the userpassword attribute, for example if the new value is shorter than the allowed minimum length.
|
|
20 (0x14)
|
LDAP_TYPE_OR_VALUE_EXISTS: sent by the Directory Server when attempting to add an attribute to an entry in which the attribute already exists with the given value.
|
|
21 (0x15)
|
LDAP_INVALID_SYNTAX: sent by the Directory Server if your client is modifying the schema entry and no object class or attribute type is specified.
|
|
32 (0x20)
|
LDAP_NO_SUCH_OBJECT: sent by the Directory Server if the entry that you want to modify or delete does not exist.
|
|
50 (0x32)
|
LDAP_INSUFFICIENT_ACCESS: sent by the Directory Server if the DN used for authentication does not have permission to write to the entry.
|
|
53 (0x35)
|
LDAP_UNWILLING_TO_PERFORM: sent by the Directory Server when:
- The directory is read-only.
- Attempting to add attributes to the special directory configuration entry.
- Attempting to modify attributes in the special schema entry.
|
|
65 (0x41)
|
LDAP_OBJECT_CLASS_VIOLATION: sent by the Directory Server if the modified entry does not comply with the directory schema (for example, if one or more required attributes are not specified).
|
|
67 (0x43)
|
LDAP_NOT_ALLOWED_ON_RDN: sent by the Directory Server if the modified entry no longer contains attributes for each DN component.
|
|
68 (0x44)
|
LDAP_ALREADY_EXISTS: sent by the Directory Server if the DN of the entry that you want add is already present in the directory.
|
|
81 (0x51)
|
LDAP_SERVER_DOWN: the LDAP server did not receive the request or the connection to the server was lost.
|
|
82 (0x52)
|
LDAP_LOCAL_ERROR: an error occurred when receiving the results from the server.
|
|
83 (0x53)
|
LDAP_ENCODING_ERROR: BER-encoding the request is not possible.
|
|
84 (0x54)
|
LDAP_DECODING_ERROR: an error occurred when decoding the BER-encoded results from the server.
|
|
89 (0x59)
|
LDAP_PARAM_ERROR: one of the options or parameters is invalid.
|
|
90 (0x5a)
|
LDAP_NO_MEMORY: memory cannot be allocated as needed.
|
|
91 (0x5b)
|
LDAP_CONNECT_ERROR: the specified hostname or port is invalid.
|
|
92 (0x5c)
|
LDAP_NOT_SUPPORTED: the -V 2 option is needed to access a server that only supports LDAP v2.
|
Command-Line Examples
The examples in this section demonstrate common uses of the ldapmodify tool to update the contents a directory. All examples assume the following context:
The given bind DN has the permission to perform all operations on the selected entries.
The directory server is located on a machine with the given hostname
.
The server uses port number 389. Because this is the default port, you do not have to specify the port number on the search request.
SSL is enabled for the server on port 636 (the default SSL port number).
Adding an Entry
This example uses the -a option for bulk addition, so the changetype: add is not needed in the input. Instead, the input contains standard LDIF entries to be added. The input file is called newEntry.ldif and contains only one entry to add:
-
dn: cn=Pete Minsky,ou=People,dc=siroe,dc=com
changetype: add
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Pete Minsky
givenName: Pete
sn: Minsky
ou: People
ou: Marketing
uid: peterm
To perform this addition, launch the ldapmodify tool with the -a option and specify the input file with the -f option:
-
$ ldapmodify -h hostname
-a -f newEntry.ldif \
-D "uid=bjensen,dc=siroe,dc=com" -w bindPassword
Modifying an Entry
The update statement for a modification includes statements for specifying the attributes to change and their new values. See "LDIF Update Statements," in Chapter 2 of the iPlanet Directory Server Administrator's Guide for a description of this syntax.
In this example, the mofifyEntry.ldif file includes statements for adding a new attribute and modifying an existing one. The line with a single dash (-) is a separator for multiple modifications in the same entry:
-
dn: cn=Pete Minsky,ou=People,dc=siroe,dc=com
changetype: modify
add: telephonenumber
telephonenumber: (408) 555-2468
-
replace: uid
uid: pminsky
To perform the operation, launch the ldapmodify tool and specify the filename on the command line.
-
$ ldapmodify -h hostname
-f mofifyEntry.ldif \
-D "uid=bjensen,dc=siroe,dc=com" -w bindPassword
Deleting an Entry
The update statement for a deletion requires only the DN and the changetype. This example shows how to enter this information as standard input:
-
$ ldapmodify -h hostname
\
-D "uid=bjensen,dc=siroe,dc=com" -w bindPassword
-
dn: cn=Pete Minsky,ou=People,dc=siroe,dc=com
changetype: delete
^D
Using Authentication
There are two levels of authentication that the directory server may enforce on clients such as the ldapmodify tool: server and client authentication. In server authentication, the server accepts only connections from clients that have a trusted certificate. In the stronger client authentication, the certificate is not assumed to be trusted, so the client must sign it with a password-protected private key.
To run the ldapmodify tool with server authentication, give only the -P option on the command line, in addition to other options. For example:
-
$ ldapmodify -h hostname
-p 636 -f LDIFfile
\
-D "uid=bjensen,dc=siroe,dc=com" -w bindPassword
\
-P /home/bjensen/certs/cert.db
To perform an update with client authentication, you must give all SSL options on the command line, in addition to other options. However, do not use the -D and -w options with client authentication, otherwise the bind operation will use the authentication credentials specified with -D and -w instead of the certificate credentials. For example:
-
$ ldapmodify -h hostname
-p 636 -f LDIFfile
\
-Z -P /home/bjensen/security/cert.db -N "bjscert" \
-K /home/bjensen/security/key.db -W KeyPassword
In either case, use the -p option to specify your directory server's SSL port. All other options remain the same and may be used as necessary.