Chapter 5
ldapdelete
The ldapdelete tool is a simple command for deleting entries in an LDAP directory. In its simplest form, it takes distinguished names (DNs) on the command line or from the standard input and deletes the corresponding entries. It can also take input from a file for bulk processing and has options for configuring advanced features such as SSL security.
The ldapdelete 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 ldapdelete 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 ldapdelete command binds to the given directory server and issues a delete command for each entry given by a DN in the input. In order to delete an entry in a directory server, the DN used for binding and authentication must have the permission to delete the given entries.
Only leaf entries, which do not have any children, may be deleted from a directory. For example, when deleting a subtree representing an organization unit, you must first delete all the entries it contains before deleting the entry representing the organizational unit.
When deleting DNs listed in a file, the tool will process each delete operation separately, in the order they are given in the file. Therefore, DNs representing leaf entries must be listed before the DNs for their parent entries.
Syntax
The syntax of the ldapdelete command line has four 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 the next section.
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 as standard input or 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 the first form without any DN
input, 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 EOF marker is platform dependent:
The ldapdelete -H command will display a usage help text that briefly describes all options.
Options
The ldapdelete 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 ldapdelete command.
Table 5-1 Common Options of the ldapdelete 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 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 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
|
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 iPlanet Directory Server Administrator's 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 "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 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 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 ldapdelete processes input files and handles errors.
Table 5-2 Input and Output Options of the ldapdelete Command
|
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. You might want to use this option to perform the conversion from the specified character set to UTF8, thus overriding the LANG setting.
Using this argument, you can input the bind DN and the target DNs in the specified character set. The ldapdelete tool converts the input from these arguments 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 "Searching an Internationalized Directory" in Appendix B of the iPlanet Directory Server Administrator's Guide.
|
|
-c
|
|
Continuous mode: errors are reported but the ldapdelete tool will continue processing input and performing operations. When this option is omitted, the default is to quit after reporting an error.
|
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 delete 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 5-3 SSL Options of the ldapdelete 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 ldapdelete 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() 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 ldapdelete 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 5-4 Return Values of the ldapdelete 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 delete request did not comply with the LDAP protocol. The Directory Server may send 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.
|
|
32 (0x20)
|
LDAP_NO_SUCH_OBJECT: sent by the Directory Server if the entry that you want deleted does not exist and if no referral URLs are available.
|
|
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 if the database is read-only.
|
|
66 (0x42)
|
LDAP_NOT_ALLOWED_ON_NONLEAF: sent by the Directory Server if the entry that you want deleted has entries beneath it in the directory tree (in other words, if this entry is a parent entry to other entries).
|
|
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 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).
Specifying Commas in DNs
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 this example, the user bjensen wishes to delete an entry in the "Siroe Bolivia, S.A." subtree of the directory:
-
$ ldapdelete -h hostname
\
-D "uid=bjensen,dc=siroe,dc=com" -w bindPassword
\
"cn=Lucia Fuentes,ou=People,o=Siroe Bolivia\S.A."
Using the Standard Input
Using the -v and -c options, you can enter DNs interactively through the standard input. In this example, the user bjensen wishes to remove an entry but enters the DN incorrectly at first:
-
$ ldapdelete -h hostname
-v -c \
-D "uid=bjensen,dc=siroe,dc=com" -w bindPassword
-
ldapdelete: started Thu Jun 14 11:34:17 2001
ldap_init( host
, 389 )
-
cn=Pete Mimsky,ou=People,dc=siroe,dc=com
-
deleting entry cn=Pete Mimsky,ou=People,dc=siroe,dc=com
ldap_delete: No such object
-
cn=Pete Minsky,ou=People,dc=siroe,dc=com
-
deleting entry cn=Pete Minsky,ou=People,dc=siroe,dc=com
entry removed
-
^D
Using a DN File
For bulk operations, list all of the DNs to delete in a text file. Specify each DN on a separate line in the file. 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=siroe,dc=com
cn=Sue Jacobs,ou=People,dc=siroe,dc=com
Then specify this DNfile
on the command line with the -f option. 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=siroe,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 and client authentication. In server authentication, the server only accepts 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 ldapdelete tool with server authentication, give only the -P option on the command line, in addition to other options. For example:
-
$ ldapdelete -h hostname
-p 636 -f DNfile
\
-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:
-
$ ldapdelete -h hostname
-p 636 -f DNfile
\
-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.