http://download.oracle.com/docs/cd/E19199-01/816-6400-10/lmodify.html
|
|
 |
| Sun ONE Directory Server Resource Kit 5.2 Tools Reference | |
Chapter 4
The ldapmodify tool edits the contents of a Lightweight Directory Access Protocol (LDAP) directory, either by adding new entries or modifying existing ones. This chapter provides instructions on how to use the ldapmodify tool. It contains the following sections:
Overview
The ldapmodify tool takes entry updates, defined using the LDAP Data Interchange Format (LDIF), as input and issues a corresponding LDAP request to the designated directory server. The LDIF information can be configured in a file or directly at the command-line.
Tip
By placing all entry update statements in a file, ldapmodify can be used to process large numbers of modifications as well as transferring entries between directories.
ldapmodify is also provided with Sun™ ONE Directory Server in the DirectoryServer_base/shared/bin directory. However, the DSRK and its updates should include the latest version of the tool in the DSRK_base/bin/dsrk52 directory.
Caution
If you use the Solaris™ operating environment, there may be an older version of ldapmodify in /usr/bin. Be sure your path is set to use the latest version in DSRK_base/bin/dsrk52.
Command Usage
The ldapmodify tool processes entry update statements, or change records, defined by the LDIF . A change record contains the DN (distinguished name) of the target entry, the operation to perform, and any data needed to complete the operation. Code Example 4-1 is a change record configured to change Barbara Jensen’s surname [sn] attribute to Morris. In addition, it will change all values of the multi-valued cn attribute. (When using the replace syntax, all current values of the specified attribute will be removed and all given values will be added.)
Code Example 4-1 Entry Update Statement or Change Record
ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
replace: sn
sn: Morris
-
replace: cn
cn: Barbara Morris
cn: Babs Morris
ldapmodify reads any number of these change records from the command-line or from a file, modifying the corresponding entries according to the LDIF instructions. For each DN in the LDIF file, the tool will perform the requested LDAP operation (defined by changetype) on the designated entry. ldapmodify supports the following operations:
Syntax
The syntax of the ldapmodify tool on the command-line can take any of these forms:
ldapmodify [ options ]
ldapmodify [ options ] < LDIFfile
ldapmodify [ options ] -f LDIFfile
Where:
In its first form (without LDIFfile), ldapmodify takes one or more LDIF update statements configured at the command-line, and ends the input with an end-of-file (EOF) marker. Once you enter all update statements and the EOF marker, ldapmodify will process the input and perform all operations.
The next two syntaxes take an LDIF file as input. The second syntax uses < (the less than symbol) to take the input from the specified file instead of the keyboard. The final syntax does the same by using the -f option. Some samples of syntax and update statements are given in Command-Line Examples.
Note
For general information on LDIF, see Appendix E, “LDAP Data Interchange Format,” in the Sun ONE Directory Server Reference Manual). Additional information on LDIF and update statements is in “Managing Entries From the Command Line” in Chapter 2 of the Sun ONE Directory Server Administration Guide.
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 being performed. (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".) Second, if schema checking is active in your directory, Directory Server will check the contents of new and modified entries against the object class definition in the LDAP schema. All attributes of an entry, even those not being modified, are checked against the schema 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 even occur if you run 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 Sun ONE Directory Server Administration Guide.
Finally, you must ensure the coherent placement of entries in the LDIF input. Updates are performed 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, 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 tool has three types of options:
The following sections detail these options. The ldapmodify -H command and option when run on the command-line will display text that briefly describes all of the command-line options.
Common Options
The common options listed in Table 4-1 control the binding and general behavior of the ldapmodify command.
Table 4-1 Common Options for ldapmodify
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. 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 it. This option is mutually exclusive with the -w option.
-f
LDIFfile
Give the name of a file containing LDIF update statements or new entries. (See Syntax.) 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 (command-line).
-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 Sun ONE Directory Server Administration 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 “Creating Smart Referrals” in Chapter 2 of the Sun ONE Directory Server Administration 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 Sun ONE LDAP SDK for C Programming Guide.)
-H
Display the usage help text that briefly describes all options.
Input And Output Options
The input and output options listed in Table 4-2 control how ldapmodify processes input files and handles errors.
Table 4-2 Input and Output Options for ldapmodify
Option
Parameter
Purpose
-a
The add entry mode provides an easy way to add entries in LDIF. All input entries that do not contain an LDIF changetype statement and keyword are processed as adds; entries with a defined changetype statement are processed accordingly. In particular, this option 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 to specify a locale that is not supported by default by your directory server. For more information, see Appendix C, “Directory Internationalization” in the Sun ONE Directory Server Reference Manual.
-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:
The ldapmodify tool also supports the LDIF : < URL notation for directly including file contents. For example:
If all of your input entries use this notation, you do not need to specify the -b option. This option also allows you to process entries from the output files of the ldapsearch tool when it uses the -t 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.
SSL (Secure Socket Layer) Options
The options in Table 4-3 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 enabled 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, “Implementing Security,” in the Sun ONE Directory Server Administration Guide. See Using Authentication for examples using the SSL options.
Note
Only the -P option is required for server authentication. For the more secure client authentication, the -P, -N, -K and -W options are required.
Table 4-3 SSL Options for ldapmodify
Return Values
The ldapmodify tool is based on the Sun ONE 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. Table 4-4 shows the possible return values when the directory is hosted on a Sun ONE Directory Server. Other LDAP servers may send these values under different circumstances or may send different values. They may also send other result codes entirely; for example, custom result codes from a custom plug-in. For further information about result codes, see the Sun ONE LDAP SDK for C Programming Guide.
Table 4-4 Return Values of ldapmodify
Command-Line Examples
The examples in this section demonstrate common uses of the ldapmodify tool to update the contents of a directory. All examples assume the following:
- 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 the default port number 389 so you do not have to specify the port number on the search request.
- SSL is enabled for the server on the default SSL port number 636.
Adding an Entry
This example uses the -a option for bulk addition, so the changetype: add statement and keyword are not needed in the input. Instead, it contains standard LDIF entries to be added. Code Example 4-2 is the input file called newEntry.ldif which defines only one entry to add.
Code Example 4-2 newEntry.ldif Input File
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=example,dc=com" -w bindPasswordModifying an Entry
The update statement for a modification includes change records that specify the attributes to change and their new values. (See “Managing Entries From the Command Line” in Chapter 2 of the Sun ONE Directory Server Administration Guide for a description of this syntax.) Code Example 4-3 is the modifyEntry.ldif file which 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.
Code Example 4-3 modifyEntry.ldif Input File
dn: cn=Pete Minsky,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: (40
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 modifyEntry.ldif \
-D "uid=bjensen,dc=example,dc=com" -w bindPasswordDeleting 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 on the command-line:
$ ldapmodify -h hostname \
-D "uid=bjensen,dc=example,dc=com" \
-w bindPassword \
dn: cn=Pete Minsky,ou=People,dc=example,dc=com \
changetype: delete ^DUsing Authentication
There are two levels of authentication that the directory server may enforce on clients such as the ldapmodify tool: server authentication and client authentication. In server authentication, the server accepts connections only from clients that have a trusted certificate. In the stronger client authentication the client must sign the certificate with a password-protected private key.
Note
In both cases, use the -p option to specify the directory server’s SSL port. All other non-SSL options retain their original meaning and may be used as necessary.
Using Server Authentication
To run the ldapmodify tool with server authentication, use only the -P SSL option [as discussed in SSL (Secure Socket Layer) Options] on the command-line, in addition to other common options.
$ ldapmodify -h hostname -p 636 -f LDIFfile \
-D "uid=bjensen,dc=example,dc=com" -w bindPassword \
-P /home/bjensen/certs/cert.dbUsing Client Authentication
To perform an update with client authentication, you must give all SSL options [as discussed in SSL (Secure Socket Layer) Options] on the command-line, in addition to other common options.
$ ldapmodify -h hostname -p 636 -f LDIFfile \
-Z -P /home/bjensen/security/cert.db -N "bjscert" \
-K /home/bjensen/security/key.db -W KeyPassword
Caution
Do not use the -D and -w common options with client authentication, as the bind operation will use the authentication credentials specified with -D and -w instead of the certificate credentials desired.