|
| |
| Sun ONE Directory Server Resource Kit 5.2 Tools Reference | |
Chapter 5
The ldapdelete ToolThe ldapdelete tool is a simple command for deleting entries in a Lightweight Directory Access Protocol (LDAP) directory. This chapter provides instructions on how to use the ldapdelete tool. It contains the following sections:
OverviewIn its simplest form, ldapdelete takes distinguished names (DNs), defined using the LDAP Data Interchange Format (LDIF), as input and deletes the corresponding entries. The DNs can be input on the command-line, via standard input or they can be culled from a file for bulk processing. (See Common Use Examples for information on how to use all three options.)
ldapdelete 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 ldapdelete in /usr/bin. Be sure your path is set to use the latest version in DSRK_base/bin/dsrk52.
Command UsageThe ldapdelete command binds to the given directory server and deletes each LDAP entry defined by a DN in the input.
Note
In order to delete an entry in a directory server, the DN used for binding and authentication must have the correct permissions.
Only leaf entries, which do not have any children, may be deleted from a directory using ldapdelete. For example, when deleting a subtree representing an organizational unit, you must first delete all the entries it contains before deleting the entry representing the organizational unit. Thus, when deleting DNs listed in a file, ldapdelete will process each delete operation separately, in the order they are defined in the file. Therefore, DNs representing leaf entries must be listed before the DNs for their parent entries.
Syntax
The syntax of ldapdelete on the command-line can take any of these forms:
ldapdelete [ options ]
ldapdelete [ options ] "DN" ...
ldapdelete [ options ] < DNfile
ldapdelete [ options ] -f DNfile
Where:
- options are the command-line options and their parameters described in Options.
- DN ... is a space-separated list of DNs to delete. Each DN should be enclosed in double quote marks (" ") for the shell interpreter. The list of DNs is not required if you give the DNs in a DNfile.
- DNfile is a text file containing one DN per line. Do not use quote marks in this file because each line is taken literally.
In its first and second forms, the tool will expect you to type one or more DNs to the standard input. Once you enter all DNs and the EOF (end-of-file) marker, ldapdelete will process your input and perform all operations.
The last two forms take a DNfile as input. The first of the two 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 Common Use 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.
Options
The ldapdelete tool has three types of options:
The following sections detail these options. The ldapdelete -H command and option when run on the command-line will display brief descriptions of all the command-line options.
Common Options
The common options listed in Table 5-1 control the binding and general behavior of the ldapdelete command.
Table 5-1 Common Options for ldapdelete
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 may be deleted, 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 the password. This option is mutually exclusive with the -w option.
-f
DNfile
Give the name of a file containing the DNs of entries to be deleted. The DNs should be listed one per line in this file, in the order in which they must be deleted. When this option is omitted, ldapdelete will read DNs directly from the standard input.
-V
version
Specify the LDAP protocol version number to be used for the delete 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 delete 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 operation, delete 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 delete. By default, there is no limit.
-R
Specify that referrals should not be followed. By default, referrals are followed automatically.
-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 the delete 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 5-2 control how ldapdelete processes input files and handles errors.
Table 5-2 Input and Output Options for ldapdelete
Option
Parameter
Purpose
-i
locale
Specify the character set to use for command-line input. The default is the character set specified in the LANG environment variable. This option can be used to convert from the specified character set to UTF8, thus overriding the LANG setting. Using this argument, you can also input the bind DN and target DNs in a specific character set. The ldapdelete tool converts the input before it processes the search request. For example, -i no indicates that the bind DN and target DNs are provided in Norwegian. This option affects only the command-line input; that is, if you specify a file containing DNs (with the -f option), ldapdelete will not convert the data in the file.
-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 Appendix C, “Directory Internationalization” in the Sun ONE Directory Server Reference Manual.
-c
Continuous mode: when errors are reported, the ldapdelete tool will continue processing input and performing operations. When this option is omitted, the default is to quit after reporting an error.
SSL (Secure Socket Layer) Options
The options in Table 5-3 allow you to use LDAPS (LDAP over SSL) to establish a secure connection for the delete 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 a more secure client authentication, the -P, -N, -K and -W options are required.
Return ValuesThe ldapdelete 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() and ldap_delete_ext_s(). These functions return both client-side and server-side errors and codes. Table 5-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.
Common Use ExamplesThe examples in this section demonstrate common uses of the ldapdelete tool. All examples assume the following context:
- The given bind DN has the permission to perform delete 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).
Using the Command Line
The simplest usage of the tool is to specify the target DNs on the command-line, making sure to enclose them in double quote marks for the shell. In addition, special characters such as commas must be escaped with a backslash (\) when they appear in components of a DN on the command-line. In the following example, the user bjensen wishes to delete an entry in the “Company Bolivia, S.A.” subtree of the directory:
$ ldapdelete -h hostname -D "uid=bjensen,dc=Company,dc=com" -w bindPassword "cn=Lucia Fuentes,ou=People,o=Company Bolivia\S.A."
Using the Standard Input
Using the -v and -c options, you can enter DNs interactively through the standard input. In Code Example 5-1, user bjensen wishes to remove an entry but at first enters the DN incorrectly. bjensen is typing the lines in bold.
Using a DN File
For bulk operations, list all of the DNs to delete in a text file. This text file should specify each DN on a separate line. The ldapdelete command will perform a delete operation on each entry, in the order in which they appear in the file. For example:
cn=Pete Minsky,ou=People,dc=example,dc=com
cn=Sue Jacobs,ou=People,dc=example,dc=comUse the -f option to specify this DNfile on the command-line. Use the -c option so that bulk processing will continue even if errors are encountered.
$ ldapdelete -h hostname -c -f DNfile -D "uid=bjensen,dc=example,dc=com" -w bindPassword
Using Authentication
There are two levels of authentication that the directory server may enforce on clients such as the ldapdelete tool: server authentication and client authentication. In server authentication, the server only accepts connections 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 ldapdelete tool with server authentication, give only the -P SSL option [as discussed in SSL (Secure Socket Layer) Options] on the command-line, in addition to other options.
$ ldapdelete -h hostname -p 636 -f DNfile \
-D "uid=bjensen,dc=siroe,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.
$ ldapdelete -h hostname -p 636 -f DNfile -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.