Client tools
Normally we have different ways of performing certain activities. We can either use the command-line utilities or we can use a GUI for similar activities. A GUI or a graphical user interface is a handy tool in cases like:
•You have taken up a new product for study/use.
•The command-line utilities fail to give a proper understanding of the system topology.
The GUI provides the user a graphical feel of a product. For example, if a person wants to see the topology of a set of interconnected systems, he can have a much better view of the same through the GUI, rather than on the command line. However, there are situations where the command-line utilities seem to dominate over the GUI. Some of the disadvantages of the GUI can be listed as:
•Very little chances of automation
•Slow response
These drawbacks are overcome using the command line utilities.The command line utilities can be judiciously incorporated in scripts to have the desired tasks/tests automated. The responses from the command line clients are much faster as regards their GUI counterparts.
Let us talk in terms of the IBM Tivoli Directory Server. Suppose you want to continuously monitor the directory server, for the number of operations completed at a given instant of time. It will not be a good idea to manually refresh the Web Administration page every 10–15 seconds, to see what the number of completed operations are at different instants of time. However, it would be a good idea to put the monitor search (ldapsearch -D<admin DN> -w <admin PW> -s base -b cn=monitor objectclass=* | grep -i operations) in a shell script, set a delay of 10–15 seconds, and allow it to run for the duration you want. No more user intervention is required and the results can be stored in a file, which can be analyzed at will. There are a lot more advantages of using the command-line utilities. We will be seeing these advantages in this chapter.
To begin with let us see what clients are shipped with the directory server and what can be done using them.
The client tools for the IBM Tivoli Directory Server come in two flavors. You can have the GUI as well as the command line utilities.
As far as the GUI is considered, the ITDS 5.2 Web Administration tool, which is shipped along with the product, acts as the graphical client for the directory server. However, that will not be explained here in its entirety. The relevant chapters will keep referring to the ways in which a particular activity can be done using the Web Administration tool. This chapter will mainly focus on the command line client utilities.
The LDAP clients that we will be seeing in this chapter are:
•ldapchangepwd
•ldapdelete
•ldapexop
•ldapmodify and ldapadd
•ldapmodrdn
•ldapsearch
10.1 The ldapchangepwd command
ldapchangepwd is the command line tool for modifying a user’s password. Here is the synopsis of the ldapchangepwd command.
10.1.1 Synopsis
ldapchangepwd -D binddn -w passwd | ? -n newpassword | ? [-C charset] [-d debuglevel][-G realm][-h ldaphost] [-K keyfile] [-m mechanism] [-M] [-N certificatename] [-O maxhops] [-p ldapport] [-P keyfilepw] [-R] [-U username] [-v] [-V version] [-y proxydn] [-Y] [-Z] [-?]
10.1.2 Options
The options are:
•-C charset
Specifies that the DNs supplied as input to the ldapchangepwd utility are represented in a local character set, as specified by charset. Use -C charset to override the default, where strings must be supplied in UTF-8. You may refer the ITDS 5.2 Administration Guide to get to know the character sets that we support.
You can download the administration guide from:
 
Note: The supported values for charset are the same values supported for the charset tag that is optionally defined in Version 1 LDIF files.
•-d debuglevel
Set the LDAP debugging level to debuglevel. You may refer Chapter 18, “Debugging IBM Tivoli Directory Server related issues” on page 589, for further information on what debugging levels can be set for the clients. The level is the same as applicable to ibmslapd (the directory server process) while running it in debug mode.
•-D binddn
Use binddn to bind to the LDAP directory. binddn is a string-represented DN. When used with -m DIGEST-MD5, it specifies the authorization ID. It can be either a DN or an authorized string that starts with u: or dn:.
•-G realm
Specify the name of the realm. When used with the -m DIGEST-MD5, the value is passed to the server during the bind.
•-h ldaphost
Specify an alternate host on which the LDAP server is running. This option is useful in the event that your client is installed on a different system than directory server.
•-K keyfile
Specify the name of the SSL or TLS key database file with default extension of kdb. If the key database file is not in the current directory, specify the fully qualified key database filename. If a key database filename is not specified, this utility will first look for the presence of the SSL_KEYRING environment variable with an associated filename. If the SSL_KEYRING environment variable is not defined, the default keyring file will be used, if present.
A default keyring file, ldapkey.kdb, and the associated password stash file, ldapkey.sth, are installed in the /lib directory under LDAPHOME, where LDAPHOME is the directory where the directory server was installed. LDAPHOME varies by operating system platform:
 – AIX operating systems - /usr/ldap
 • HP-UX operating systems - /usr/IBMldap
 – Linux operating systems - /usr/ldap
 – Solaris operating systems - /opt/IBMldapc
 – Windows operating systems - C:Program FilesIBMLDAP
 
Note: This is the default install location. The actual LDAPHOME is determined during installation. Currently it is possible to specify a different installation path only for Solaris and Windows. The other platforms are mandatorily installed at the default location.
See IBM Directory C-Client SDK Programming Reference for more information about default key database files, and default Certificate Authorities. This document can be downloaded from:
If a keyring database file cannot be located, a “hard-coded” set of default trusted certificate authority roots is used. The key database file typically contains one or more certificates of certificate authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots. For more information on managing an SSL or TLS key database, refer to Chapter 15, “Securing the directory” on page 431.
This parameter effectively enables the -Z switch.
•-m mechanism
Use mechanism to specify the SASL mechanism to be used to bind to the server. The ldap_sasl_bind_s() API will be used. The -m parameter is ignored if -V 2 is set. If -m is not specified, simple authentication is used.
•-M
Manage referral objects as regular entries.
•-n newpassword | ?
Specifies the new password. Use the ? to generate a password prompt. Using this prompt prevents your password from being visible through the ps command.
•-N certificatename
Specify the label associated with the client certificate in the key database file. If the LDAP server is configured to perform server authentication only, a client certificate is not required. If the LDAP server is configured to perform client and server authentication, a client certificate might be required. certificatename is not required if a certificate/private key pair has been designated as the default. Similarly, certificatename is not required if there is a single certificate/private key pair in the designated key database file. This parameter is ignored if neither -Z nor -K is specified.
•-O maxhops
Specify maxhops to set the maximum number of hops that the client library takes when chasing referrals. The default hopcount is 10.
•-p ldapport
Specify an alternate TCP port where the LDAP server is listening. The default LDAP port is 389. If -p is not specified and -Z is specified, the default LDAP SSL port 636 is used.
•-P keyfilepw-
Specify the key database password. This password is required to access the encrypted information in the key database file, which may include one or more private keys. If a password stash file is associated with the key database file, the password is obtained from the password stash file, and the -P parameter is not required. This parameter is ignored if neither -Z nor -K is specified.
•-R
Specifies that referrals are not to be automatically followed.
•-U username
Specifies the username. This is required with -m DIGEST-MD5 and ignored when any other mechanism is used. The value username depends on what attribute the server is configured to use. It might be a uid or any other value that is used to locate the entry.
•-v
Use verbose mode, with many diagnostics written to standard output.
•-V version
Specifies the LDAP version to be used by ldapdchangepwd when it binds to the LDAP server. By default, an LDAP V3 connection is established. To explicitly select LDAP V3, specify -V 3. Specify -V 2 to run as an LDAP V2 application. An application, like ldapdchangepwd, selects LDAP V3 as the preferred protocol by using ldap_init instead of ldap_open.
•-w passwd | ?
Use passwd as the password for authentication. Use the ? to generate a password prompt. Using this prompt prevents your password from being visible through the ps command.
•-y proxydn
Specifies the DN to be used for proxied authorization. You can refer the section on ldapsearch for an example of using the -y option.
•-Y
Use a secure TLS connection to communicate with the LDAP server. The -Y option is only supported when IBM’s GSKit, is installed.
•-Z
Use a secure SSL connection to communicate with the LDAP server. The -Z option is only supported when the SSL component entry, as provided by IBM’s GSKit, is installed.
•-?
Displays the syntax help for ldapchangepwd.
10.1.3 Examples
The following examples illustrate the options that we have just discussed.
Example 1
The following command:
C:>ldapchangepwd -D cn=user1,o=ibm,c=us -w user -n user1
Changes the password of the entry with commonName “user1” from user to user1.
Example 2
Here is an example for using a different charset than the default. First, let us verify the codepage of the current database. You can do so with the following instructions on Windows.
On Windows, you need to work in the DB2 shell, invoked by running the db2cmd command. In that shell, here are the commands to use:
C:>set DB2INSTANCE=ldapdb2
C:>db2start
C:>db2 connect to ldapdb2
Database Connection Information
Database server = DB2/NT 8.1.2
SQL authorization ID = ADMINIST...
Local database alias = LDAPDB2
C:>db2 get db cfg for ldapdb2 | grep -i code
Database code page = 1208
Database code set = UTF-8
Database country/region code = 1
The output from these commands show that the current database is UTF-8.
 
Note: We have used a UNIX utility here called grep, which is not available on Windows by default. You can take the entire output in a file and search for the relevant lines.
The next command:
C:>ldapchangepwd -D cn=user1,o=ibm,c=us -w user1 -C ISO-8859-1 -n user2
changing password for entry cn=user1,o=ibm,c=us
Changes the password of the entry with the commonName “user1” from user1 to user2. Note that ldapchangepwd tells the server that the dn that is passed to it was specified in the ISO-8859-1 character set.
Example 3
Let us run the ldapchangepwd command with the minimum debuglevel of 1, just to see the kind of debug output it shows up. Here is what you get when you try to use invalid credentials to change the password:
C:>ldapchangepwd -D cn=user1,o=ibm,c=us -w user2 -d 1 -n user3
065:19:42:30 T2652 ldap_sasl_bind
065:19:42:30 T2652 ldap_sasl_bind_direct
065:19:42:30 T2652 put_ctrls_into_ber: ctrls=00304F88
065:19:42:30 T2652 put_ctrls_into_ber: return(rc=0)
065:19:42:30 T2652 send_initial_request
065:19:42:30 T2652 open_default_connection
065:19:42:30 T2652 new_connection: connect=1
065:19:42:30 T2652 open_ldap_connection
065:19:42:30 T2652 connect_to_host: rainbow:389
065:19:42:30 T2652 sd 716 connected to: 127.0.0.1
065:19:42:30 T2652 new_connection: successful - return(lc=00306520)
065:19:42:30 T2652 send_server_request: msgid=1, bind=NONE
065:19:42:30 T2652 use_connection: lc=00306520, new refcount=2
065:19:42:30 T2652 flush_request: msgid=1
065:19:42:30 T2652 do_ldap_select
065:19:42:30 T2652 ldap_result
065:19:42:30 T2652 wait4msg (infinite timeout)
065:19:42:30 T2652 do_ldap_select
065:19:42:30 T2652 read1msg
065:19:42:30 T2652 got result msgid 1, original id 1
065:19:42:30 T2652 free_request (origid 1, msgid 1)
065:19:42:30 T2652 free_connection: lc=00306520, force=0, unbind=1
065:19:42:30 T2652 free_connection: lc=00306520, not freed, refcnt 1
065:19:42:30 T2652 get_ctrls_from_ber: ctrls_p=0012FE78
065:19:42:30 T2652 get_ctrls_from_ber: Control OID = 1.3.6.1.4.1.42.2.27.8.5.1, critical = No, value follows
065:19:42:30 T2652 get_ctrls_from_ber: control value is NULL.
065:19:42:30 T2652 get_ctrls_from_ber: return(0), ctrls=00306060, 1 controls returned
065:19:42:30 T2652 ldap_msgfree
065:19:42:30 T2652 ldap_controls_free: ctrls=00304F88
065:19:42:30 T2652 ldap_control_free: ctrl=00304F48
065:19:42:30 T2652 ldap_controls_free: ctrls=00000000
065:19:42:30 T2652 ldap_err2string
ldap_simple_bind: Invalid credentials
Example 4
Here is an example where you use the -h hostname argument to indicate the host where the password change is expected:
C:>ldapchangepwd -h localhost -D cn=user1,o=ibm,c=us -w user5 -n user6
changing password for entry cn=user1,o=ibm,c=us
Since the default host is localhost, this command is the same as the one shown in “Example 1” on page 242.
Example 5
This example shows the way password changes are done over SSL:
C:>ldapchangepwd -D cn=user1,o=ibm,c=us -K F:KEYSclientCMS.kdb -P client -Z -w user6 -n user7
changing password for entry cn=user1,o=ibm,c=us
Here the path of the key file is passed using the -K option, the keyfile password is passed using the -P option and the SSL flag is turned on using the -Z option (this is optional in the example shown above, as -K is supposed to enable the -Z switch by default).
Example 6
This example shows the use of the -N option.
C:>ldapchangepwd -D cn=user1,o=ibm,c=us -K f:RamakrishnaKEYSclientCMS.kdb -P client -Z -N client -w user7 -n user8
ldap_simple_bind: Operations error
changing password for entry cn=user1,o=ibm,c=us
Can't contact LDAP server
 
C:>ldapchangepwd -D cn=user1,o=ibm,c=us -K f:RamakrishnaKEYSclientCMS.kdb -P client -Z -N clientCMS -w user7 -n user8
changing password for entry cn=user1,o=ibm,c=us
This example shows that you are not allowed to change the password in case you pass the wrong certificate name. In “Example 5” on page 244, the client was picking up the correct certificate to talk to the server, as that was the only one available and which acted as the default one.
Example 7
This example shows the use of the -p option:
C:>ldapchangepwd -D cn=user1,o=ibm,c=us -p 389 -w user8 -n user9
changing password for entry cn=user1,o=ibm,c=us
As seen above the port, over which ldapchangepwd is talking to the server, is 389. This happens to be the default port. This is configurable, and in the cases where the default port was changed, the -p option is needed.
Example 8
This example shows the use of flags/options pertaining to referrals. We will get to know the details on using the -O option, here. You may refer the ldapsearch section for illustrations on the -M and -R options.
Assuming we have a set of referrals pointing to an entry, as follows:
cn=ref1,o=ibm,c=us -> o=ref,o=ibm,c=us -> cn=user1,o=ibm,c=us
ref1 is a referral to ref, which in turn is a link to cn=user1.
If the ldapchangepwd is run on the entry cn=ref1,o=ibm,c=us with number of hops =1:
C:>ldapchangepwd -D cn=ref1,o=ibm,c=us -p 389 -w user9 -O 1 -n user1
ldap_simple_bind: Referral limit exceeded
The example shows that cn=ref1,o=ibm,c=us could not reach the actual target cn=user1,o=ibm,c=us in the specified number of hops (1).
Now let us remove the restrictions on the referrals:
C:>ldapchangepwd -D cn=ref1,o=ibm,c=us -p 389 -w user9 -n user1
changing password for entry cn=ref1,o=ibm,c=us
Now the password change takes place successfully.
Example 9
The next example shows the ldapchangepwd command driven in verbose (-v ) mode:
C:>ldapchangepwd -D cn=ref1,o=ibm,c=us -p 389 -v -w user1 -n user2
ldap_init(NULL, 389)
changing password for entry cn=ref1,o=ibm,c=us
delete userpassword:
user1
add userpassword:
user2
ldapchangepwd complete
The example shows a more detailed way as to how ldapchangepwd goes about changing the password of a specific user.
Example 10
This example shows the usage of the -V option:
C:>ldapchangepwd -D cn=ref1,o=ibm,c=us -V 2 -w user1 -n user2
ldap_bind_s: Inappropriate authentication
 
C:>ldapchangepwd -D cn=ref1,o=ibm,c=us -V 3 -w user2 -n user3
changing password for entry cn=ref1,o=ibm,c=us
As shown above the server refuses the client any service, saying Inappropriate Authentication, as it is expecting a version 3 call from ldapchangepwd.
Example 11
This example shows the usage of the -w password | ? and -n newpassword | ? options in place of the password to avoid entering them on the command line:
C:>ldapchangepwd -D cn=ref1,o=ibm,c=us -w ? -n ? -v
Enter Old password ==>
Enter New password ==>
ldap_init(NULL, 389)
changing password for entry cn=ref1,o=ibm,c=us
delete userpassword:
user3
add userpassword:
user4
ldapchangepwd complete
The verbose mode is deliberately turned on here to show how the change in the password is taking place. In case the passwords are entered along with the command (without the ? option), the passwords remain in the history of the shell and it is possible for other users to go through the history and get the passwords. Also the ps command would be showing the password. To overcome such issues option of ? is used.
Example 12
The next example shows how the user’s password may be changed over TLS:
C:>ldapchangepwd -D cn=user1,o=ibm,c=us -Y -w user6 -n user7 -K F:RamakrishnaKEYSclientCMS.kdb -P client
changing password for entry cn=user1,o=ibm,c=us
The server should be capable of accepting TLS connections in this case.
The root DSE search can be used to verify this:
C:>ldapsearch -s base objectclass=* | grep security
security=tls
You may refer Chapter 15, “Securing the directory” on page 431, for further information on TLS.
The -G realm option is effective only when you have set up SASL communications. That is, it goes hand-in-hand with the -m mechanism option. Same is the case with the -U username option. The -U options is ignored if -m option is not specified in the command line. More information on Realms can be had from the ITDS 5.2 Administration Guide. This document can be found at:
As far as the SASL mechanisms considered, you can have more information on the same by reading Chapter 15, “Securing the directory” on page 431.
10.1.4 SSL, TLS notes
To use the SSL or TLS - related functions associated with this utility, the SSL or TLS libraries and tools must be installed. The SSL or TLS libraries and tools are provided with IBM’s Global Security Kit (GSKit), which includes security software developed by RSA Security Inc.
 
Note: For information regarding the use of 128-bit and triple DES encryption by LDAP applications, including the LDAP sample programs, see “LDAP_SSL” in the IBM Directory C-Client SDK Programming Reference. This section describes the steps required to build the sample programs and your applications so that they can use SSL with the strongest encryption algorithms available. This document can be downloaded from:
See the makefile associated with the sample programs for more information on linking an LDAP application so that it has access to 128-bit and triple-DES encryption algorithms.
The content of a client’s key database file is managed with the gsk7ikm utility. For more information on this Java utility, please refer Chapter 15, “Securing the directory” on page 431. The gsk7ikm utility is used to define the set of trusted certification authorities (CAs) that are to be trusted by the client. By obtaining certificates from trusted CAs, storing them in the key database file, and marking them as “trusted”, you can establish a trust relationship with LDAP servers that use “trusted” certificates issued by one of the trusted CAs. The gsk7ikm utility can also be used to obtain a client certificate, so that client and server authentication can be performed.
If the LDAP servers accessed by the client use server authentication only, it is sufficient to define one or more trusted root certificates in the key database file. With server authentication, the client can be assured that the target LDAP server has been issued a certificate by one of the trusted CAs. In addition, all LDAP transactions that flow over the SSL or TLS connection with the server are encrypted including the LDAP credentials that are supplied on the ldap_bind or ldap_simple_bind_s. For example, if the LDAP server is using a high-assurance VeriSign certificate, you should obtain a CA certificate from VeriSign, import it into your key database file, and mark it as trusted. If the LDAP server is using a self-signed server certificate, the administrator of the LDAP server can supply you with a copy of the server’s certificate request file. Import the certificate request file into your key database file and mark it as trusted.
If the LDAP servers accessed by the client use client and server authentication, it is necessary to:
•Define one or more trusted root certificates in the key database file. This allows the client to be assured that the target LDAP server has been issued a certificate by one of the trusted CAs. In addition, all LDAP transactions that flow over the SSL or TLS connection with the server are encrypted, including the LDAP credentials that are supplied on the ldap_bind or ldap_simple_bind_s.
•Create a key pair using gsk7ikm and request a client certificate from a CA. After receiving the signed certificate from the CA, store the certificate in the client key database file.
10.1.5 Diagnostics
The exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error.
10.2 The ldapdelete command
ldapdelete is the command-line tool for deleting a single or a group of users/entries. The entries to be deleted can be passed through the command line or through file redirection. Let us go further and see the detailed synopsis of the ldapdelete command.
10.2.1 Synopsis
ldapdelete [-c] [-C charset] [-d debuglevel][-D binddn] [-f file] [-G realm] [-h ldaphost] [-i file] [-k] [-K keyfile] [-m mechanism] [-M] [-n] [-N certificatename] [-O maxops] [-p ldapport] [-P keyfilepw] [-R] [-s][-U username} [-v] [-V version] [-w passwd | ?] [-y proxydn][-Y] [-Z] [dn]...
10.2.2 Description
ldapdelete is a command-line interface to the ldap_delete library call.
ldapdelete opens a connection to an LDAP server, binds, and deletes one or more entries. If one or more Distinguished Name (DN) arguments are provided, entries with those DNs are deleted. Each DN is a string-represented DN. If no DN arguments are provided, a list of DNs is read from standard input, or from a file, if the -i flag is used.
To display syntax help for ldapdelete, type:
ldapdelete -?.
10.2.3 Options
ldapdelete has options/arguments like -C charset, -d debuglevel, -D binddn, -G realm, -h ldaphost, -K keyfile, -m mechanism, -M, -N certificatename, -O maxhops, -p ldapport, -P keyfilepw, -R, -U username, -v, -V, -w passwd | ?, -y proxydn, -Y, -Z, which are the same as the ldapchgpwd command and have been explained in “Options” on page 239. Therefore they are not explained any further here. The command line arguments for ldapdelete that We will be seeing, in this section, are as follows:
•-c
Continuous operation mode. Errors are reported, but ldapdelete continues with modifications. Otherwise the default action is to exit after reporting an error.
•-f file
Read a series of lines from a file, performing one LDAP delete for each line in the file. Each line in the file should contain a single distinguished name.
•-i file
Read a series of lines from a file, performing one LDAP delete for each line in the file. Each line in the file should contain a single distinguished name.
•-k
Specifies to use server administration control.
•-n
Show what would be done, but do not actually modify entries. Useful for debugging in conjunction with -v.
•-s
Use this option to delete the subtree rooted at the specified entry.
•-dn
Specifies one or more DN arguments. Each DN should be a string-represented DN.
10.2.4 Examples
Lets see a set of examples illustrating the options/arguments that we have just discussed above.
Example 1
The following command:
ldapdelete "cn=Delete Me, o=University of Life, c=US"
Attempts to delete the entry with commonName “Delete Me” directly below the “University of Life” organizational entry. It might be necessary to supply a binddn and passwd, for deletion to be allowed (see the -D and -w options).
Example 2
Here is an example of using the -c argument.
Assuming the fact that there exists an LDIF file test.ldif, with the contents:
cn=user10,o=ibm,c=us
cn=user4,o=ibm,c=us
And with the directory users as shown below:
C:>ldapsearch -D cn=root -w secret -b o=ibm,c=us cn=user* dn
cn=user1,o=ibm,c=us
cn=user2,o=ibm,c=us
cn=user3,o=ibm,c=us
cn=user4,o=ibm,c=us
Now if the ldapdelete command is used without the -c option:
C:>ldapdelete -D cn=root -w secret -f test.ldif
Deleting entry cn=user10,o=ibm,c=us
ldap_delete: No such object
 
C:>ldapdelete -D cn=root -w secret -c -f test.ldif
Deleting entry cn=user10,o=ibm,c=us
ldap_delete: No such object
Deleting entry cn=user4,o=ibm,c=us
As seen and expected, -c did not break ldapdelete and it went ahead with the deletion of the rest of the entries specified in the file.
There are other ways of doing the same operation:
ldapdelete -D cn=root -w secret -c -i test.ldif
ldapdelete -D cn=root -w secret -c < test.ldif
Example 3
This example is an illustration of the Admin Control (-k). Assuming the fact that there exists a replication topology and attempts to delete some entries on the replica:
C:>ldapdelete -D cn=root -w secret cn=user3,o=ibm,c=us
Deleting entry cn=user3,o=ibm,c=us
ldap_delete: DSA is unwilling to perform
ldap_delete: additional info: Data not encrypted
Referral:
ldap://localhost:636
That is, with the normal set of options, we are not able to delete the entry. Now we can delete the same using the Admin Control as follows:
C:>ldapdelete -D cn=root -w secret -k cn=user3,o=ibm,c=us
Deleting entry cn=user3,o=ibm,c=us
Example 4
This example shows the use of the -n option:
C:>ldapdelete -D cn=root -w secret -n -dn cn=user1,o=ibm,c=us
!Deleting entry cn=user1,o=ibm,c=us
 
C:>ldapsearch -D cn=root -w secret -b cn=user1,o=ibm,c=us objectclass=* dn
cn=user1,o=ibm,c=us
The example shows that the entry is not physically deleted.
Example 5
This example shows how the dn that is to be deleted can be passed in the same line as the ldapdelete command, without any input redirection from a file.
C:>ldapdelete -D cn=root -w secret -k -dn cn=user3,o=ibm,c=us
Deleting entry cn=user3,o=ibm,c=us
Example 6
This example shows the use of the -s option to delete an entire subtree. Here is how that can be done.
Suppose we want to delete the subtree “cn=sub,o=ibm,c=us” with subentries as shown below:
C:>ldapsearch -D cn=root -w secret -b cn=sub,o=ibm,c=us objectclass=* dn
cn=sub,o=ibm,c=us
 
cn=sub1,cn=sub,o=ibm,c=us
Now here is the command to delete the subtree in a single shot:
C:>ldapdelete -D cn=root -w secret -s cn=sub,o=ibm,c=us
Deleting entry cn=sub,o=ibm,c=us
 
C:>ldapsearch -D cn=root -w secret -b cn=sub,o=ibm,c=us objectclass=* dn
ldap_search: No such object
ldap_search: matched: O=IBM,C=US
 
Note: If no DN arguments are provided, the ldapdelete command waits to read a list of DNs from standard input. To break out of the wait, use Ctrl+C or Ctrl+D.
10.2.5 SSL, TLS notes
The SSL- or TLS-related functions associated with this utility are as like the ones described with ldapchangepwd.
10.2.6 Diagnostics
Exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error.
10.3 The ldapexop command
ldapexop is the tool for performing the extended operations pertaining to the IBM Tivoli Directory Server.
10.3.1 Synopsis
ldapexop [-C charset] [-d debuglevel][-D binddn][-e] [-G realm] [-h ldaphost] [-help][-K keyfile] [-m mechanism] [-N certificatename] [-p ldapport]
[-P keyfilepw] [-?] [-U username] [-v] [-w passwd | ?] [-Y] [-Z]
 
-op {cascrepl | clearlog | controlqueue | controlrepl | getAttributes | getlogsize | getusertype | quiesce | readconfig | readlog | stopserver | unbind | uniqueattr }
10.3.2 Description
The ldapexop utility is a command-line interface that provides the capability to bind to a directory and issue a single extended operation along with any data that makes up the extended operation value.
The ldapexop utility supports the standard host, port, SSL, TLS, and authentication options used by all of the LDAP client utilities. In addition, a set of options is defined to specify the operation to be performed, and the arguments for each extended operation
To display syntax help for ldapexop, type:
ldapexop -?
Or:
ldapexop -help
10.3.3 Options
The options for the ldapexop command are divided into two categories:
•General options that specify how to connect to the directory server. These options must be specified before operation specific options.
•Extended operation option that identifies the extended operation to be performed.
General options
These options specify the methods of connecting to the server and must be specified before the -op option.
ldapexop expects general options such as -C charset,-d debuglevel, -D binddn, -G realm, -h ldaphost, -help, -K keyfile, -m mechanism, -p ldapport,-P keyfilepw, -?, -U username, -v, -w passwd | ?, -Y, -Z which are the same as the ldapchangepwd command and have been explained in “Options” on page 239.
There is one general option that needs explanation here.
•-e
This option displays the LDAP library version information and quits. Here is an example of the output:
C:>ldapexop -e
SDK Version: 510
Protocol Version: 300
SDK Build Level: Oct 1 2003
Extended operations option
The -op extended-op option identifies the extended operation to be performed. The extended operation can be one of the following values:
•cascrepl -action <actionvalue> -rc <contextDN> [options]
This extended operation is for controlling the cascading replication. The requested action is applied to the specified server and also passed along to all replicas of the given subtree. If any of these are forwarding replicas, they forward the extended operation to their replicas.
The operation cascades over the entire replication topology.
-action {quiesce | unquiesce | replnow | wait}
This is a required attribute that specifies the action to be performed.
 – quiesce
This operation indicates the server to take no further updates till the relevant subtree is unquiesced. While setting up the topology, it is desired that the changes should not go through the servers participating in the topology, so that a data consistency is maintained across all the servers. Hence there is the option of quiescing the servers. The only way to make any updates to a quiesced server is through an Admin Control. The obvious reason for having the option of the Admin Control is that you need to write to the servers the replication related information and you need a channel to write to the servers even when they are quiesced. Hence the necessity and implementation of the Admin Control.
 – unquiesce
Resume normal operation, client updates are accepted. Once a topology is completed the subtree (replication context) can be unquiesced. that is, It is ready to accept changes again.
 – replnow
Replicate all queued changes to all replica servers as soon as possible, regardless of schedule. In other words this option triggers forceful replication.
 – wait
Wait for all updates to be replicated to all replicas. In other words the topology will be in a sort of dormant stage or a sort of sleep mode, till the entire topology has come to a balanced or synchronized state. That is all the updates in the queues of the relevant Masters/Forwarders have gone in place.
 – -rc contextDn
This is a required attribute that specifies the root of the subtree. rc stands for replication context. In case you have set up replication, you can edit the relevant subtree to find that the object class ibm-replicationContext is added to the subtree, say, for example, o=ibm,c=us, to make it eligible for replication. The term rc is picked up from this (r)eplication (c)ontext.
options
 – -timeout secs
This is an optional attribute that if present, specifies the timeout period in seconds. If not present, or 0, the operation waits indefinitely. For better performance of your replication topology it is advisable to set a timeout period. Some of the servers in the topology may be down. Consequently the updates to these down servers may not be sent till the servers are up. Hence there is no point in waiting indefinitely for the changes to pass to all the servers. Keeping a timeout would mean that you are allocating the necessary resources for the necessary amount of time and not more. If there are any anomalies in the topology at a given instant of time, they can be detected using the other options of the ldapexop command.
For example:
ldapexop -op cascrepl -action -quiesce -rc "o=acme,c=us" -timeout 60
This command is meant to quiesce the subtree o=acme,c=us that is, prevent it from taking any further updates, other than from the administration control. The operation is supposed to quit if it does not complete in 60 seconds.
•clearlog -log <logname>
This extended operation is used to clear the log files from the command line. The log files which can be cleared by the ldapexop command are listed below, as an argument to the -log option to ldapexop.
-log {audit | bulkload | cli | slapd | ibmdiradm | adminDaemon | debug}
This is a required attribute that specifies which log file to be cleared. The parameters to the -log, as shown above, are mostly self-explanatory as to what it’ll clear. The only log that needs a mention is the debug log. When you use ldapexop to clear the debug log then the file pointed to by LDAP_DEBUG_FILE is cleared. This environment variable is supposed to store the file name so that when you are collecting the server debug trace the same can be redirected to it. For example:
ldapexop -op clearlog -log debug
•controlqueue -skip <skipvalue> -ra <agreementDN>
This extended operation, as its name indicates, is used for controlling the replication queue, as identified by the replication agreement.
 – -skip {all | change-id}:
This is a required attribute.
 • all
This option indicates to skip all pending changes for this agreement.
 • change-id
This option identifies the single change to be skipped. If the server is not currently replicating this change, the request fails. In other words, if there are 100 entries in the replication queue, you are allowed to skip just the 100th. entry in the queue. There is no direct option, whereby you can skip any nth. entry in the replication queue. The entry to be skipped always has to be the front of the queue.
 – -ra agreementDN
This is a required attribute that specifies the DN of the (r)eplication (a)greement. The objectclass pertaining to the replication agreement is ibm-replicationAgreement. ra is derived from this objectclass.
For example:
ldapexop -op controlqueue -skip all -ra "cn=server3, ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,o=acme,c=us"
 
ldapexop -op controlqueue -skip 2185 -ra "cn=server3,ibm-replicaSubentry=master1-id,ibm-replicaGroup=default, o=acme,c=us"
•controlrepl -action <actionvalue> {-rc <contextDN> | -ra <agreementDN>}
This extended operation is useful for controlling the replication activities associated with a specific subtree or associated with a specific recipient of replication.
 – -action {suspend | resume | replnow}
This is a required attribute that specifies the action to be performed. This option is used either to suspend, resume or forcefully replicate changes over a specific queue as identified by the other options passed.
 – -rc contextDn | -ra agreementDn
The -rc contextDn is the DN of the replication context. The action is performed for all agreements for this context. The -ra agreementDn is the DN of the replication agreement. The action is performed for the specified replication agreement. that is, to say if the -rc option is specified then that will affect all the queues associated with this subtree. And if -ra is specified then only that queue which corresponds to this agreementDN, will be affected.
For example:
ldapexop -op controlrepl -action suspend -ra "cn=server3, ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,o=acme,c=us"
This is an example to suspend the replication activities associated with the queue, where the supplier is the one pointed to by master1-id and the recipient is the one pointed to be server3.
•getattributes -attrType <type> -matches bool <value>
This is an extended operation whereby we can fetch the attributes of a specific type as understood by the rest of the options that go along. Let us see the detailed specifics on the same:
-attrType {operational | language_tag | attribute_cache | unique | configuration}
This is a required parameter for the getattributes extended operation. It specifies type of attribute being requested.
 – operational
These are the set of attributes tracking the operations of the directory server. The clients are not supposed to play around with these attributes, as doing so may force the server to give incorrect information. The examples of the operational attributes are the attributes pertaining to ACLs, the attributes storing the timestamps of different events, some attributes of password policy, etc. For more information refer to Chapter 11, “Schema management” on page 287.
 – language_tags
The term, language tags, defines a mechanism that enables the directory to associate natural language codes with values held in a directory and enables clients to query the directory for values that meet certain natural language requirements.
Here is an example:
ldapsearch -b "o=ibm,c=us" (objectclass=organization) description;lang-en
The server returns values of an attribute description;lang-en, but does not return values of an attribute description or description;lang-fr.
If a request is made specifying an attribute without providing a language code, then all attribute values regardless of their language code are returned. Further information on this, refer to ITDS v5.2 Administration Guide, which can be found at:
 – attribute_cache
In ITDS 5.2, there is a new concept of an attribute cache. This is designed for enhanced performance of the directory server. The attribute cache will store information pertaining to attributes. There is a setting by means of which you can select/deselect the set of attributes that can be cached. Like if you wish that the uid attribute should be cached, whenever there is a search on uid, just make the necessary settings and information pertaining to uid would be cached. Hence next time you need to get a specific set of results the attribute cache will also be screened, thus enhancing performance.
 – unique
Each attribute in the LDAP schema maps to a single table. By adding any attribute to the list of unique attributes, the relevant column in the table corresponding to the attribute is made unique. Consequently if you make postaladdress as unique, it will not be possible for more than one object, in this directory server, to have the same postaladdress.
 – configuration
These are basically attributes pertaining to the configuration of the server.
•-matches bool {true | false}
Specifies whether the list of attributes returned matches the attribute type specified by the -attrType option.
For example:
ldapexop -op getattributes -attrType unique -matches bool true
Returns a list of all attributes that have been designated as unique attributes.
ldapexop -op getattributes -attrType unique -matches bool false
Returns a list of all attributes that have been not been designated as unique attributes.
•getlogsize -log <logname>
This extended operation is used to request log file size, precisely in terms of the number of lines in the log file. This is very much like the ‘wc -l’ command on UNIX. However, ldapexop is more sophisticated way of doing such things though as you need not specify the name of the log file, just the type of the log is sufficient.
-log {audit | bulkload | cli | slapd | ibmdiradm | adminDaemon | debug}
This is a required attribute that specifies the log file to be queried The size of the log file, in lines, is written to standard output.
For example:
ldapexop -op getlogsize -log slapd
2000 lines
•getusertype
This extended operation is used to get to know the profile/privileges of a given user. This extended operation returns the user type based on the bound DN. For example:
ldapexop - D <AdminDN> -w <Adminpw> -op getusertype
Returns:
User : root_administrator
Role(s) : server_config_administrator directory_administrator
The description on the “User type and user roles” for extended operations is coming up shortly in the same section.
•quiesce -rc <contextDN> [options]
quiesce or unquiesce subtree extended operation. This extended operation is used to quiesce or unquiesce the servers associated with a specific subtree. The subtree is indicated by the -rc parameter.
-rc contextDN: This is a required attribute that specifies the DN of the replication context (subtree) to be quiesced or unquiesced.
The option is -end. This is an optional attribute that if present, specifies to end the quiesce state, or in other words unquiesce the subtree. If not specified the default is to quiesce the subtree. For example:
ldapexop -op quiesce -rc "o=acme,c=us"
ldapexop -op quiesce -end -rc "o=ibm,c=us"
•readconfig -scope <scopevalue>
This extended operation helps the server to dynamically read updates to the configuration file. Let us go into the specifics of the same:
-scope { entire | single <entry DN> <attribute> | entry <entry DN> | subtree <entry DN> }
This is a required attribute. This specifies the scope of the configuration file that needs to be re-read by the server, which is currently up.
 – entire
This option specifies to reread the entire configuration file.
 – single <entry DN><attribute>
This option specifies to read the single entry and attribute as specified.
 – entry <entry DN>
This option specifies that the server is supposed to read the specified entry.
 – subtree <entry DN>
This option specifies that the server is supposed to read the entry and the entire subtree under it.
For example:
ldapexop -op readconfig -scope entire
ldapexop -op readconfig -scope single "cn=configuration" ibm-slapdAdminPW
By means of the above example you are asking the server to dynamically take note of the new admin password.
There is a set of attributes which can be dynamically re-read by the directory server. If you change any other attributes and even if you ask the server to re-read the entire configuration file, changes will not take effect dynamically. The following is a list of attributes that can be changed dynamically. You do not have to restart the server for these changes to take effect:
 – cn=Configuration
 • ibm-slapdadmindn
 • ibm-slapdadminpw
 • ibm-slapderrorlog
 • ibm-slapdpwencryption
 • ibm-slapdsizelimit
 • ibm-slapdsysloglevel
 • ibm-slapdtimelimit
 – cn=Front End, cn=Configuration
 • ibm-slapdaclcache
 • ibm-slapdaclcachesize
 • ibm-slapdentrycachesize
 • ibm-slapdfiltercachebypasslimit
 • ibm-slapdfiltercachesize
 • ibm-slapdidletimeout
 – cn=Event Notification, cn=Configuration
 • ibm-slapdmaxeventsperconnection
 • ibm-slapdmaxeventstotal
 – cn=Transaction, cn=Configuration
 • ibm-slapdmaxnumoftransactions
 • ibm-slapdmaxoppertransaction
 • ibm-slapdmaxtimelimitoftransactions
 – cn=ConfigDB, cn=Config Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
 • ibm-slapdreadonly
 – cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
 • ibm-slapdbulkloaderrors
 • ibm-slapdclierrors
 • ibm-slapdpagedresallownonadmin
 • ibm-slapdpagedreslmt
 • ibm-slapdpagesizelmt
 • ibm-slapdreadonly
 • ibm-slapdsortkeylimit
 • ibm-slapdsortsrchallownonadmin
 • ibm-slapdsuffix
•readlog -log <logname> -lines <value>
This extended operation is used to read log files. This extended operation is used to read a set of lines from the relevant log files or read the entire file. Let us go into the further specifics pertaining to this option.
-log audit | bulkload | cli | slapd | ibmdiradm | debug
This is a required attribute that specifies the log file to be queried.
-lines {<first><last> | all}
This is a required attribute that specifies either the number of the first and the last lines to be read from the file or it specifies that all lines are to be read. Lines are numbered starting at 0. The specified lines are written to standard output. For example:
ldapexop -op readlog -log audit -lines 10 20
ldapexop -op readlog -log slapd -lines all
•stopserver
This extended operation helps in stopping the IBM Tivoli Directory Server. For example:
ldapexop -op stopserver
•unbind {-dn <specificDN> | -ip <sourceIP> | -dn <specificDN> -ip <sourceIP> | all}
This extended operation is useful for disconnecting connections based on DN, IP, DN/IP or all connections, as needed. All the connections without any operations and all connections with operations on the work queue are ended immediately. If a worker is currently working on a connection, it is ended as soon as the worker completes that one operation.
 – -dn <specificDN>
By specifying just the dn, ldapexop will end a connection by DN only. This request results in the purging of all the connections bound on the specified DN.
 – -ip <sourceIP>
By specifying just the IP, ldapexop will end a connection by IP only. This request results in the purging of all the connections from the specified IP source.
 – -dn <specificDN> -ip <sourceIP>
By specifying both the dn and the ip, ldapexop will end a connection determined by a DN/IP pair. This request results in the purging of all the connections bound on the specified DN and from the specified IP source.
 – -all
Issues a request to end all the connections. This request results in the purging of all the connections except the connection from where this request originated. This attribute cannot be used with the -dn and/or -ip. parameters.
The unbind option is mostly useful for disconnecting unwanted connections, that may pose a risk, as like Denial of Service, or which are likely to hamper the directory performance. For example:
ldapexop -op unbind -dn cn=john
ldapexop -op unbind -ip 9.182.173.43
ldapexop -op unbind -dn cn=john -ip 9.182.173.43
ldapexop -op unbind -all
•uniqueattr -a <attributeType>
This extended operation is used to identify all the nonunique values for a particular attribute.
-a <attribute>
Specify the attribute for which all conflicting values are to be listed.
 
Note: Duplicate values for binary, operational, configuration attributes, and the objectclass attribute are not displayed. These attributes are not supported extended operations for unique attributes.
For example:
ldapexop -op uniqueattr -a "uid"
The following line is added to the configuration file under the cn=Directory,cn=RDBM Backends,cn=IBM Directory,cn=Schema,cn=Configuration entry for this extended operation:
ibm-slapdPlugin:extendedop /bin/libback-rdbm.dll initUniqueAttr
 
Note: If no DN arguments are provided, the ldapexop command waits to read a list of DNs from standard input. To break out of the wait, use Ctrl+C or Ctrl+D.
SSL, TLS notes
The SSL or TLS - related functions associated with this utility are as like the ones described with ldapchangepwd above.
Diagnostics
Exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error.
User type and user roles for extended operations
The following are the users and their roles for extended operations.
•User
Root administrator: This user is an administrative user whose “simple and External” with “SSL or TLS” bind credentials are stored under the cn=Configuration entry. This user’s Kerberos bind credentials (optional) are stored under the cn=Kerberos,cn=Configuration entry. This user’s Digest-MD5 bind credentials (optional) are stored under the cn=Digest,cn=Configuration entry. In addition, this type of user can bind to the Admin Daemon.
•Role(s)
 – Server configuration administrator
This user has unrestricted access to all information in the configuration backend and can start/stop the server. The user can issue dynamic configuration updates.
 – Directory administrator
This user has unrestricted access to directory data outside the configuration backend (schema, and RDBM backends). This user can search for one or two attributes in the configuration backend. This user may not have any authority to the operating specific backends (OS/400 system projection backend, z/OS RACF SDBM).
 – Administrative group member
This user is basically an administrative user whose “simple or External” with “SSL or TLS, Kerberos (optional), and Digest-MD5 (optional)” credentials are stored under an entry in the subtree cn=Admingroup,cn=Configuration. In addition, this type of user can bind to the Admin Daemon.
•Role(s)
 – Server configuration group member
This user has access to all configuration information except the administrator and admin group credentials. This user has the ability to start and stop the server. The user does not have the ability to add or remove members from the administrative group. The user is not be able to modify the DN, password, Kerberos ID, or Digest-MD5 ID of any administrative group member entry under cn=AdminGroup,cn=Configuration. If the user is an Administrative Group Member the user is able to modify his own password, but is not able to modify his own DN, Kerberos ID, or Digest-MD5 ID. This user is also not able to see the password of any other administrative group member or the IBM Tivoli Directory Server administrator. In addition, this user is not able to add, delete, or modify the audit log settings (the entire cn=Audit,cn=Configuration entry) or clear the audit log. The user is not able to add or delete the cn=Kerberos,cn=Configuration or cn=Digest,cn=Configuration entries, but is able to search all attributes under these entries. The user is able to modify all attributes under these entries except the Kerberos and Digest-MD5 root administrator bind attributes. These users are not able to search or modify the ibm-slapdAdminDN, ibm-slapdAdminGroupEnabled or ibm-slapdAdminPW attributes under the cn=Configuration entry. The user can issue dynamic configuration updates.
 – Directory administrator
This user has unrestricted access to directory data outside the configuration backend (schema, and RDBM backends). This user can search for one or two attributes in the configuration backend. This user may not have any authority to the operating specific backends (OS/400 system projection backend, z/OS RACF SDBM).
 – LDAP user type
This user is a regular LDAP user whose credentials are stored in the DIT of the LDAP Server. The user’s “simple and external” with “SSL or TLS” bind DN is the DN of an entry in the DIT. The user’s password is stored in the userpassword attribute of this entry.
•Role(s)
LDAP User Role: A user having almost no access to the configuration backend. This user can search for one or two attributes in the configuration backend. The user’s access to directory data (schema, and RDBM backends) is controlled by ACLs.
10.4 The ldapmodify and ldapadd commands
This client tool helps in modifying existing entries in the directory or adding new ones. ldapmodify is not used for modifying the RDN values of entries. There is a separate client tool for this which will be explained in “The ldapmodrdn command” on page 270.
10.4.1 Synopsis
ldapmodify [-a] [-b] [-c] [-C charset] [-d debuglevel][-D binddn][-g] [-G realm] [-h ldaphost] [-i file] [-k] [-K keyfile] [-m mechanism] [-M] [-N certificatename] [-O maxhops] [-p ldapport] [-P keyfilepw] [-r] [-R] [-U username] [-v] [-V] [-w passwd | ?] [-y proxydn] [-Y] [-Z]
 
ldapadd [-a] [-b] [-c] [-C charset] [-d debuglevel][-D binddn][-g] [-G realm] [-h ldaphost] [-i file] [-k] [-K keyfile] [-m mechanism] [-M] [-N certificatename] [-O maxhops] [-p ldapport] [-P keyfilepw] [-r] [-R] [-U username] [-v] [-V] [-w passwd | ?] [-y proxydn] [-Y] [-Z]
10.4.2 Description
ldapmodify is a command-line interface to the ldap_modify and ldap_add library calls. ldapadd is implemented as a renamed version of ldapmodify. When invoked as ldapadd, the -a (add new entry) flag is turned on automatically.
ldapmodify opens a connection to an LDAP server, and binds to the server. You can use ldapmodify to modify or add entries. The entry information is read from standard input or from file through the use of the -i option.
To display syntax help for ldapmodify or ldapadd, type:
ldapmodify -?
Or:
ldapadd -?
10.4.3 Options
Options like -C charset, -c, -d debuglevel, -D binddn, -G realm, -h ldaphost, -K keyfile, -k, -m mechanism, -M, -N certificatename, -O maxhops, -p ldapport, -P keyfilepw, -R, -U username, -v, -V, -w passwd | ?, -y proxydn, -Y and -Z have already been discussed for the ldapchangepwd command in 10.1.2, “Options” on page 239.
Here are the options that are additional:
•-a
Add new entries. The default action for ldapmodify is to modify existing entries. If invoked as ldapadd, this flag is always set.
•-b
Assume that any values that start with a ‘/’ are binary values and that the actual value is in a file whose path is specified in place of the value.
•-g
Specifies not to strip the trailing spaces on attribute values.
•-i file
Read the entry modification information from an LDIF file instead of from standard input. If an LDIF file is not specified, you must use standard input to specify the update records in LDIF format.
•-r
Replace existing values by default.
Input format
The contents of the file (or the standard input if no -i flag is given on the command line) should conform to the LDIF format.
Alternative input format
An alternative input format is supported for compatibility with older versions of ldapmodify. This format consists of one or more entries separated by blank lines, where each entry looks like the following:
Distinguished Name (DN)
attr=attrvalue
[attr=attrvalue ...]
Where attr is the name of the attribute and value is the attrvalue.
By default, values are added. If the -r command line flag is given, the default is to replace existing values with the new one. It is permissible for a given attribute to appear more than once, for example, to add more than one value for an attribute. Also note that you can use a trailing ‘\’ to continue values across lines and preserve new lines in the value itself.
attr should be preceded by a - to remove a value. The = and value should be omitted to remove an entire attribute.
attr should be preceded by a + to add a value in the presence of the -r flag.
10.4.4 Examples
Lets see a set of examples illustrating the options/arguments that we have just discussed above.
Example 1
Assuming that the file /tmp/entrymods exists and has the following contents:
dn: cn=Modify Me, o=University of Higher Learning, c=US
changetype: modify
replace: mail
-
add: title
title: Grand Poobah
-
add: jpegPhoto
jpegPhoto: /tmp/modme.jpeg
-
delete: description
-
The command:
ldapmodify -b -r -i /tmp/entrymods
will replace the contents of the Modify Me entry’s mail attribute with the value [email protected], add a title of Grand Poobah, and the contents of the file /tmp/modme.jpeg as a jpegPhoto, and completely remove the description attribute. These same modifications can be performed using the older ldapmodify input format, by modifying the file /tmp/entrymods as:
cn=Modify Me, o=University of Higher Learning, c=US
+title=Grand Poobah
+jpegPhoto=/tmp/modme.jpeg
-description
And by using the command:
ldapmodify -b -r -i /tmp/entrymods
Example 2
Assuming that the file /tmp/newentry exists and has the following contents:
dn: cn=John Doe, o=University of Higher Learning, c=US
objectClass: person
cn: John Doe
cn: Johnny
sn: Doe
title: the world’s most famous mythical person
uid: jdoe
The command:
ldapadd -i /tmp/entrymods
adds a new entry for John Doe, using the values from the file /tmp/newentry.
Example 3
Assuming that the file /tmp/newentry exists and has the contents:
dn: cn=John Doe, o=University of Higher Learning, c=US
changetype: delete
The command:
ldapmodify -i /tmp/entrymods
removes John Doe’s entry.
Example 4
Assuming that the file /tmp/newentry exists and has the contents:
dn: cn=Modify Me, o=University of Higher Learning, c=US
changetype: modify
replace: description
description:abc
The command:
ldapmodify -g -i /tmp/entrymods
retains the trailing spaces in the description field, that is, abc, as they are entered. It would be difficult to search for the spaces here! You may want to try this example in your environments to see that the trailing spaces are actually maintained.
 
Note: If no DN arguments are provided, the ldapmodify command waits to read a list of DNs from standard input. To break out of the wait, use Ctrl+C or Ctrl+D.
10.4.5 SSL, TLS notes
The SSL or TLS - related functions associated with this utility are as like the ones described in “The ldapchangepwd command” on page 239.
10.4.6 Diagnostics
Exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error.
10.5 The ldapmodrdn command
This tool is specifically designed to modify the RDN part of an entry’s dn.
10.5.1 Synopsis
ldapmodrdn [-c] [-C charset] [-d debuglevel][-D binddn] [-G realm] [-h ldaphost] [-i file] [-k] [-K keyfile] [-m mechanism] [-M] [-n] [-N certificatename] [-O hopcount] [-p ldapport] [-P keyfilepw] [-r] [-R] [-U username] [-v] [-V] [-w passwd | ?] [-y proxydn] [-Y] [-Z] [dn newrdn | [-i file]]
10.5.2 Description
ldapmodrdn is a command-line interface to the ldap_modrdn library call.
ldapmodrdn opens a connection to an LDAP server, binds, and modifies the RDN of entries. The entry information is read from standard input, from file through the use of the -f option, or from the command-line pair of dn and RDN.
Refer to “LDAP distinguished name syntax (DNs)” on page 43 for information about RDNs and DNs.
To display syntax help for ldapmodrdn, type:
ldapmodrdn -?
10.5.3 Options
The options like -c, -C charset, -d debuglevel, -D binddn, -G realm, -h ldaphost, -k, -K keyfile, -m mechanism, -M, -n, -N certificatename, -O hopcount, -p ldapport, -P keyfilepw, -R, -U username, -v, -V, -w passwd | ?, -y proxydn, -Y, -Z are already explained or would be explained in one of the other sections. Hence we are not taking them in this section. The illustrations can be applied to ldapmodrdn as was to the earlier client utilities.
•-i file
Read the entry modification information from the file instead of from standard input or the command-line (by specifying ran and newrdn). Standard input can be supplied from a file, as well using redirection (“< file”).
•-r
Remove old RDN values from the entry. Default action is to keep old values.
•dn newrdn
See the following section, “Input format for dn newrdn” for more information.
Input format for dn newrdn
If the command-line arguments dn and newrdn are given, newrdn replaces the RDN of the entry specified by the DN, dn. Otherwise, the contents of file (or standard input if no - i flag is given) consist of one or more entries:
Distinguished Name (DN)
Relative Distinguished Name (RDN)
One or more blank lines may be used to separate each DN and RDN pair.
10.5.4 Examples
Here are a few examples of using the ldapmodrdn command.
Example 1
Assuming that the file /tmp/entrymods exists and has the contents:
cn=user, o=ibm, c=US
cn=NewUser
Note the output of the command:
C:>ldapmodrdn -D cn=root -w secret -i test.ldif
copying cn=user, o=ibm, c=US to cn=NewUser
Example 2
Assuming that the file /tmp/entrymods exists and has the contents:
cn=NewUser, o=ibm, c=US
cn=user
Observe the output of the command:
C:>ldapmodrdn -D cn=root -w secret -r -i test.ldif
moving cn=NewUser, o=ibm, c=US to cn=user
In both examples the RDN is changed. It is changed from user to NewUser in example 1 and NewUser to user in example 2. However the thing to note is that by using -r we are moving the current value to a new one with an RDN change and in case we do not use the -r option we are copying the contents from one dn to another. Thus using -r is supposed to yield better modrdn performance.
 
Note: If no DN arguments are provided, the ldapmodrn command waits to read a list of DNs from standard input. To break out of the wait, use Ctrl+C or Ctrl+D.
10.5.5 SSL, TLS notes
The SSL or TLS - related functions associated with this utility are as like the ones described with ldapchangepwd in “The ldapchangepwd command” on page 239.
10.5.6 Diagnostics
Exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error.
10.6 The ldapsearch command
This is the most widely used client tool. The obvious reason being that the LDAP protocol is a read-optimization protocol and ldapsearch is a tool for reading/fetching data from the LDAP server.
10.6.1 Synopsis
ldapsearch [-a deref] [-A] [-b searchbase] [-B] [-C charset] [-d debuglevel] [-D binddn] [-F sep] [-G realm] [-h ldaphost] [-i file] [-K keyfile] [-l timelimit] [-L] [-m mechanism] [-M] [-n] [-N certificatename] [-o attr_type] [-O maxhops] [-p ldapport] [-P keyfilepw] [-q pagesize] [-R] [-s scope ] [-t] [-T seconds] [-U username] [-v] [-V version] [-w passwd | ?] [-z sizelimit] [-y proxydn] [-Y] [-Z] filter [-9 p] [-9 s] [attrs...]
10.6.2 Description
ldapsearch is a command-line interface to the ldap_search library call.
ldapsearch opens a connection to an LDAP server, binds, and performs a search using the filter. The filter should conform to the string representation for LDAP filters (see ldap_search in the IBM Tivoli Directory Server Version 5.2 C-Client SDK Programming Reference for more information on filters).
You can get this document at:
If ldapsearch finds one or more entries, the attributes specified by attrs are retrieved and the entries and values are printed to standard output. If no attrs are listed, all attributes are returned.
To display syntax help for ldapsearch, type ldapsearch -?.
10.6.3 Options
The options like -C charset, -d debuglevel, -D binddn, -e, -G realm, -h ldaphost, -K keyfile, -m mechanism, -n, -O maxhops, -p ldapport, -P keyfilepw, -U username, -w passwd | ?, -Y, -Z have already been discussed in 10.1, “The ldapchangepwd command” on page 239. The options that are specific to the ldapsearch command are:
•-a deref
Specify how aliases dereferencing is done. deref should be one of:
 – never: Aliases are never dereferenced.
 – always: Aliases are always dereferenced.
 – search: Aliases are deferenced when searching.
 – find: Aliases are dereferenced only when locating the base object.
•-A
Retrieve attributes only (no values). This is useful when you just want to see if an attribute is present in an entry and are not interested in the specific values.
•-b searchbase
Use searchbase as the starting point for the search instead of the default. If -b is not specified, this utility will examine the LDAP_BASEDN environment variable for a searchbase definition. If neither is set, the default base is set to ““, which is a null search. A null search returns all the entries in the entire Directory Information Tree (DIT). This search requires a -s subtree option. Otherwise, an error message is displayed. Be aware that null based search requests consume a lot of resource.
•-B
Do not suppress display of non-ASCII values. This is useful when dealing with values that appear in alternate character sets such as ISO-8859.1. This option is implied by the -L option.
•-F sep
Use sep as the field separator between attribute names and values. The default separator is ‘=’, unless the -L flag has been specified, in which case this option is ignored.
•-i file
Read a series of lines from a file, performing one LDAP search for each line. In this case, the filter given on the command line is treated as a pattern where the first occurrence of %s is replaced with a line from file. If file is a single “-” character, then the lines are read from standard input.
For example, in the command,
ldapsearch -V3 -v -b “o=ibm,c=us” -D “cn=admin” -w ldap -i filter.input %s dn
The file filter.input file might contain the following filter information:
(cn=*Z)
(cn=*Z*)
(cn=Z*)
(cn=*Z*)
(cn~=A)
(cn>=A)
(cn<=B)
 
 
Note: Each filter must be specified on a separate line.
The command performs a search of the subtree o=ibm,c=us for each of the filters beginning with cn=*Z. When that search is completed, the search begins for the next filter cn=*Z* and so forth until the search for the last filter cn<=B is completed.
 
Note: The -i < file> option replaces the -f < file> option. The -f option is still supported, although it is deprecated.
•-l timelimit
Wait at most timelimit seconds for a search to complete.
•-L
Display search results in LDIF format. This option also turns on the -B option, and causes the -F option to be ignored.
•-M
Manage referral objects as regular entries.
•-N certificatename
Specify the label associated with the client certificate in the key database file.
 
Note: If the LDAP server is configured to perform server authentication only, a client certificate is not required. If the LDAP server is configured to perform client and server Authentication, a client certificate might be required. certificatename is not required if a default certificate/private key pair has been designated as the default. Similarly, certificatename is not required if there is a single certificate/private key pair in the designated key database file. This parameter is ignored if neither -Z nor -K is specified.
•-o attr_type
To specify an attribute to use for sort criteria of search results, you can use the -o (order) parameter. You can use multiple -o parameters to further define the sort order. In the following example, the search results are sorted first by surname (sn), then by given name, with the given name (givenname) being sorted in reverse (descending) order as specified by the prefixed minus sign (-):
-o sn -o -givenname
Thus, the syntax of the sort parameter is as follows:
[-]<attribute name>[:<matching rule OID>]
Where:
 – attribute name is the name of the attribute you want to sort by.
 – matching rule OID is the optional OID of a matching rule that you want to use for sorting.
 – The minus sign (-) indicates that the results must be sorted in reverse order.
 – The criticality is always critical.
The default ldapsearch operation is not to sort the returned results.
•-q pagesize
To specify paging of search results, two new parameters can be used: -q (query page size), and -T (time between searches in seconds).
In the following example, the search results return a page (25 entries) at a time, every 15 seconds, until all the results for that search are returned. The ldapsearch client handles all connection continuation for each paged results requested for the life of the search operation.
-q 25 -T 15
If the -v (verbose) parameter is specified, ldapsearch lists how many entries have been returned so far, after each page of entries returned from the server, for example, 30 total entries have been returned.
Multiple -q parameters are enabled such that you can specify different page sizes throughout the life of a single search operation. In the following example, the first page is 15 entries, the second page is 20 entries, and the third parameter ends the paged result/search operation:
-q 15 -q 20 -q 0
In the following example, the first page is 15 entries, and all the rest of the pages are 20 entries, continuing with the last specified -q value until the search operation completes:
-q 15 -q 20
The default ldapsearch operation is to return all the entries in a single request.
No paging is done for the default ldapsearch operation.
•-R
Specifies that referrals are not to be automatically followed.
•-s scope
Specify the scope of the search. scope should be one of:
 – base - Search is limited to the base.
 – one - Search is limited to one-level below the base and does not include the base.
 – sub - Search covers the base as well as its descendants.
 
Note: If you specify a null search, either by not specifying a -b option or specifying -b ““, you must the -s option. The default scope is disabled for a null search.
•-t
Write retrieved values to a set of temporary files. This is useful for dealing with non-ASCII values such as jpegPhoto or audio.
•-T seconds
Time between searches (in seconds). The -T option is only supported when the -q option is specified.
•-y proxydn
Specifies the DN to be used for proxied authorization. The earlier sections did not illustrate this feature. We will have an example in the Examples section down below on the use of this option.
•-z sizelimit
Limit the results of the search to at the most sizelimit entries. This makes it possible to place an upper bound on the number of entries that are returned for a search operation.
•-9 p
Sets criticality for paging to false. The search is handled without paging.
Here is an excerpt from the ITDS 52 Administration guide, which guides us for setting/unsetting this option
The LDAP server returns all referrals to the client at the end of a search request, the same as a search without any controls. That means that if the server has 10 pages of results returned, all the referrals are returned on the 10th page, not at the end of each page. When chasing referrals, the client application needs to send in an initial paged results request, with the cookie set to null, to each of the referral servers. It is up to the application using the client services to decide whether or not to set the criticality as to the support of paged results, and to handle a lack of support of this control on referral servers as appropriate based on the application. Additionally, the LDAP server does not ensure that the referral server supports paged results controls. Multiple lists could be returned to the client application, some not paged. It is at the client application’s decision as to how to best present this information to the end user. Possible solutions include: Combine all referral results before presenting to the end user; show multiple lists and the corresponding referral server host name; take no extra steps and show all results to the end user as they are returned from the server. The client application must turn off referrals to get one truly paged list, otherwise when chasing referrals with the paged results search control specified, unpredictable results might occur.
•-9 s
Sets criticality for sorting to false. The search is handled without sorting.
Here is an excerpt from the ITDS 52 Administration guide, which guides on the setting/unsetting of this option:
The LDAP server returns all referrals to the client at the end of a search request. It is up to the application using the client services to decide whether to set the criticality of the sorted search request, and to handle a lack of support of those controls on referral servers as appropriate based on the application. Additionally, the LDAP server does not ensure that the referral server supports the sorted search control. Multiple lists could be returned to the client application, some not sorted. It is the client application’s decision as to how best to present this information to the end user. Possible solutions include: combine all referral results before presenting to the end user; show multiple lists and the corresponding referral server host name; take no extra steps and show all results to the end user as they are returned from the server. The client application must turn off referrals to get one truly sorted list, otherwise when chasing referrals with sorted search controls specified, unpredictable results might occur.
For more information on the paging/sorting criticality issues you may refer the ITDS 5.2 Administration Guide. The link for the same is provided in the earlier sections.
•filter
Specifies a string representation of the filter to apply in the search. Simple filters can be specified as attributetype=attributevalue. More complex filters are specified using a prefix notation according to the following Backus Naur Form (BNF)
<filter> ::=’(‘<filtercomp>’)’
<filtercomp> ::= <and>|<or>|<not>|<simple>
<and> ::= ‘&’ <filterlist>
<or> ::= ‘|’ <filterlist>
<not> ::= ‘!’ <filter>
<filterlist> ::= <filter>|<filter><filtertype>
<simple> ::= <attributetype><filtertype><attributevalue>
<filtertype> ::= ‘=’|’~=’|’<=’|’>=’
The ‘~=’ construct is used to specify approximate matching. The representation for <attributetype> and <attributevalue> are as described in “RFC 2252, LDAP V3 Attribute Syntax Definitions”. In addition, <attributevalue> can be a single * to achieve an attribute existence test, or can contain text and asterisks (*) interspersed to achieve substring matching.
For example, the filter “mail=*”” finds any entries that have a mail attribute.The filter “mail=*@student.of.life.edu” finds any entries that have a mail attribute ending in the specified string. To put parentheses in a filter, escape them with a backslash () character.
‘
Note: A filter like "cn=Bob *", where there is a space between Bob and the asterisk (*), matches “Bob Carter” but not “Bobby Carter” in IBM Directory. The space between “Bob” and the wildcard character (*) affects the outcome of a search using filters.
Please refer RFC 2254, “A String Representation of LDAP Search Filters” for a more complete description of allowable filters.
Output format
If one or more entries are found, each entry is written to standard output in the form:
Distinguished Name (DN)
attributename=value
attributename=value
attributename=value
...
Multiple entries are separated with a single blank line. If the -F option is used to specify a separator character, it will be used instead of the ‘=’ character. If the -t option is used, the name of a temporary file is used in place of the actual value. If the -A option is given, only the “attributename” part is written.
10.6.4 Examples
Here are some examples of the ldapsearch command.
Example 1
The command:
ldapsearch "cn=john doe" cn telephoneNumber
Performs a subtree search (using the default search base) for entries with a commonName of “john doe”. The commonName and telephoneNumber values is retrieved and printed to standard output. The output might look something like this, if two entries are found:
cn=John E Doe, ou="College of Literature, Science, and the Arts", ou=Students, ou=People, o=University of Higher Learning, c=US
cn=John Doe
cn=John Edward Doe
cn=John E Doe 1
cn=John E Doe
telephoneNumber=+1 313 555-5432
 
cn=John B Doe, ou=Information Technology Division,
ou=Faculty and Staff, ou=People, o=University of Higher Learning, c=US
cn=John Doe
cn=John B Doe 1
cn=John B Doe
telephoneNumber=+1 313 555-1111
Example 2
The command:
ldapsearch -t "uid=jed" jpegPhoto audio
This performs a subtree search using the default search base for entries with user id of “jed“. The jpegPhoto and audio values are retrieved and written to temporary files. The output might look like this, if one entry with one value for each of the requested attributes is found:
cn=John E Doe, ou=Information Technology Division,ou=Faculty and Staff,ou=People, o=University of Higher Learning, c=US
audio=/tmp/ldapsearch-audio-a19924
jpegPhoto=/tmp/ldapsearch-jpegPhoto-a19924
Example 3
This command:
ldapsearch -L -s one -b "c=US" "o=university*" o description
This will perform a one-level search at the c=US level for all organizations whose organizationName begins with university. Search results will be displayed in the LDIF format (You may refer the LDAP Data Interchange Format in the ITDS 52 Administration Guide for the detailed specifics on LDIF format. The link is provided in the earlier sections). The organizationName and description attribute values will be retrieved and printed to standard output, resulting in output similar to this:
dn: o=University of Alaska Fairbanks, c=US
o: University of Alaska Fairbanks
description: Preparing Alaska for a brave new tomorrow
description: leaf node only
 
dn: o=University of Colorado at Boulder, c=US
o: University of Colorado at Boulder
description: No personnel information
description: Institution of education and research
 
dn: o=University of Colorado at Denver, c=US
o: University of Colorado at Denver
o: UCD
o: CU/Denver
o: CU-Denver
description: Institute for Higher Learning and Research
 
dn: o=University of Florida, c=US
o: University of Florida
o: UFl
description: Shaper of young minds
Example 4
This command:
ldapsearch -b "c=US" -o ibm-slapdDN "objectclass=person" ibm-slapdDN
This performs a subtree level search at the c=US level for all persons. When this special attribute is used for sorted searches, the search results are sorted by the string representation of the Distinguished Name (DN). The output might look something like this:
cn=Al Edwards,ou=Widget Division,ou=Austin,o=IBM,c=US
cn=Al Garcia,ou=Home Entertainment,ou=Austin,o=IBM,c=US
cn=Amy Nguyen,ou=In Flight Systems,ou=Austin,o=IBM,c=US
cn=Arthur Edwards,ou=Widget Division,ou=Austin,o=IBM,c=US
cn=Becky Garcia,ou=In Flight Systems,ou=Austin,o=IBM,c=US
cn=Ben Catu,ou=In Flight Systems,ou=Austin,o=IBM,c=US
cn=Ben Garcia Jr,ou=Home Entertainment,ou=Austin,o=IBM,c=US
cn=Bill Keller Jr.,ou=In Flight Systems,ou=Austin,o=IBM,c=US
cn=Bob Campbell,ou=In Flight Systems,ou=Austin,o=IBM,c=US
Example 5
Here is an example to see the behavior of the -M and -R flags, pertaining to referrals. Assumption is that there exists a custom object class, which inherits from the referral class and also has the userPassword attribute in it. The custom object class is named myreferral and cn=myref,o=ibm,c=us is an object of the same. cn=myref,o=ibm,c=us refers to cn=user1,o=ibm,c=us.
C:>ldapsearch -D cn=myref,o=ibm,c=us -w user1 -s base -b cn=myref,o=ibm,c=us objectclass=*
cn=user1,o=ibm,c=us
objectclass=organizationalPerson
objectclass=person
objectclass=top
sn=1
cn=user1
 
C:>ldapsearch -D cn=myref,o=ibm,c=us -w user1 -M -s base -b cn=myref,o=ibm,c=us objectclass=*
ldap_simple_bind: Invalid credentials
 
C:>ldapsearch -D cn=myref,o=ibm,c=us -w myref -M -s base -b cn=myref,o=ibm,c=us objectclass=*
cn=myref,o=ibm,c=us
objectclass=myreferral
objectclass=referral
objectclass=top
ref=ldap://localhost/cn=user1,o=ibm,c=us
cn=myref
 
C:>ldapsearch -D cn=myref,o=ibm,c=us -w myref -R -s base -b cn=myref,o=ibm,c=us objectclass=*
ldap_simple_bind: Referral returned
C:>ldapsearch -D cn=root -w secret -R -s base -b cn=myref,o=ibm,c=us objectclass=*
ldap_search: Referral returned
Unfollowed referral: ldap://localhost/cn=user1,o=ibm,c=us
As shown above, if you try to chase a referral with the binddn as the dn of the referral and the bind password as that of the target (cn=user1,o=ibm,c=us) you do reach there. However, if you treat cn=myref,o=ibm,c=us as a normal entry (-M) then the bind password of the referral is expected and not of the target object. And lastly if the referrals aren’t chased (-R) then you get back a referral from the server, which is displayed only when bound as an administrator.
Example 5
Assuming the fact that cn=alias2,o=ibm,c=us is an alias of an entry cn=alias1,o=ibm,c=us which in turn is an alias of cn=user1,o=ibm,c=us, here is what We will get on the different options of dereferencing:
•deref: always
C:>ldapsearch -D cn=root -w secret -a always -b cn=alias1,o=ibm,c=us objectclass=* dn
cn=user1,o=ibm,c=us
 
C:>ldapsearch -D cn=root -w secret -a always -b cn=alias2,o=ibm,c=us objectclass=* dn
cn=user1,o=ibm,c=us
•deref: searching with searchbase as a non-alias
C:>ldapsearch -D cn=root -w secret -a searching -b o=ibm,c=us objectclass=* dn | grep -i alias
<No output>
•deref: finding with searchbase as a non-alias
C:>ldapsearch -D cn=root -w secret -a finding -b o=ibm,c=us objectclass=* dn | grep -i alias
cn=alias1,o=ibm,c=us
cn=alias2,o=ibm,c=us
•deref: searching with searchbase as a alias
C:>ldapsearch -D cn=root -w secret -a searching -b cn=alias2,o=ibm,c=us objectclass=* dn
cn=user1,o=ibm,c=us
•deref: finding with searchbase as a alias
C:>ldapsearch -D cn=root -w secret -a finding -b cn=alias2,o=ibm,c=us objectclass=* dn
cn=user1,o=ibm,c=us
•deref: never
C:>ldapsearch -D cn=root -w secret -a never -b cn=alias2,o=ibm,c=us objectclass=* dn
cn=alias2,o=ibm,c=us
The above examples clearly demonstrate the different ways the aliases can be treated by ldapsearch. Also, it is noteworthy that the difference in the output from -deref : searching and -deref : finding is based on the fact whether the searchbase is an alias or not.
Example 6
The following command shows the use of the -A option:
C:>ldapsearch -D cn=root -w secret -a never -b cn=alias2,o=ibm,c=us -A objectclass=*
cn=alias2,o=ibm,c=us
aliasedobjectname
objectclass
cn
Example 7
Here we bring out the difference between using the -B switch and not using it:
C:>ldapsearch -D cn=root -w secret -a never -b cn=user,o=ibm,c=us -B objectclass=* jpegPhoto
cn=user,o=ibm,c=US
jpegPhoto=BMµ?
 
C:>ldapsearch -D cn=root -w secret -a never -b cn=user,o=ibm,c=us objectclass=* jpegPhoto
cn=user,o=ibm,c=US
jpegPhoto=NOT ASCII
As shown above, if -B switch is used, the binary data will also appear in the ldapsearch output, though it is not apparently meaningful.
Example 8
This example brings out the difference between using the -F sep option and not using it:
C:>ldapsearch -D cn=root -w secret -b cn=user,o=ibm,c=us objectclass=* sn
cn=user,o=ibm,c=US
sn=j
C:>ldapsearch -D cn=root -w secret -b cn=user,o=ibm,c=us -F :
objectclass=* sncn=user,o=ibm,c=US
sn:j
Example 9
This example shows the use of the -l option.
Consider the following search:
ldapsearch -D cn=root -w secret -l 1 -b o=ibm,c=us objectclass=*
Currently o=ibm,c=us has 10,000 entries below it. However, the ldapsearch is given a total time limit of 1second for returning all the results. After that time exceeds and if ldapsearch has not finished with all the desired entries, the following message is flashed and the search stops:
ldap_search: Timelimit exceeded
Example 10
With the assumption that there exists an entry cn=user1,o=ibm,c=us with two children as cn=h1,cn=user1,o=ibm,c=us and cn=h2,cn=user1,o=ibm,c=us, this example shows the use of the -o option:
C:>ldapsearch -D cn=root -w secret -o cn -s sub -b cn=user1,o=ibm,c=us objectclass=* dn
cn=h1,cn=user1,o=ibm,c=us
cn=h2,cn=user1,o=ibm,c=us
cn=user1,o=ibm,c=us
 
C:>ldapsearch -D cn=root -w secret -o -cn -s sub -b cn=user1,o=ibm,c=us objectclass=* dn
cn=user1,o=ibm,c=us
cn=h2,cn=user1,o=ibm,c=us
cn=h1,cn=user1,o=ibm,c=us
Example 11
This example shows the differences between the various options associated with the parameter scope, specified using -s:
C:>ldapsearch -D cn=root -w secret -s base -b cn=user1,o=ibm,c=us objectclass=* dn
cn=user1,o=ibm,c=us
 
C:>ldapsearch -D cn=root -w secret -s sub -b cn=user1,o=ibm,c=us objectclass=* dn
cn=user1,o=ibm,c=us
cn=h1,cn=user1,o=ibm,c=us
cn=h2,cn=user1,o=ibm,c=us
 
C:>ldapsearch -D cn=root -w secret -s one -b cn=user1,o=ibm,c=us objectclass=* dn
cn=h1,cn=user1,o=ibm,c=us
cn=h2,cn=user1,o=ibm,c=us
Example 12
This example illustrates the use of the -z flag:
C:>ldapsearch -D cn=root -w secret -b cn=user1,o=ibm,c=us objectclass=* dn
cn=user1,o=ibm,c=us
cn=h1,cn=user1,o=ibm,c=us
cn=h2,cn=user1,o=ibm,c=us
 
C:>ldapsearch -D cn=root -w secret -b cn=user1,o=ibm,c=us -z 1 objectclass=* dn
 
cn=user1,o=ibm,c=us
ldap_search: Sizelimit exceeded
Example 13
This example illustrates the use of the proxy dn, through the -y flag.
Assuming that there exist 2 users cn=user1,o=ibm,c=us. user2 is not allowed to see the password of user1, however user2 is in the Proxy group.
C:>ldapsearch -D cn=user2,o=ibm,c=us -w user2 -s base -b cn=user1,o=ibm,c=us objectclass=*
cn=user1,o=ibm,c=us
objectclass=organizationalPerson
objectclass=person
objectclass=top
sn=1
cn=user1
 
C:>ldapsearch -D cn=user2,o=ibm,c=us -w user2 -y cn=user1,o=ibm,c=us -s base -b cn=user1,o=ibm,c=us objectclass=*
cn=user1,o=ibm,c=us
objectclass=organizationalPerson
objectclass=person
objectclass=top
sn=1
cn=user1
userpassword={SHA}s9qne0wEqVUbh4HQMZH+CY8yXmc=
Note the difference between the two searches that are fired on the LDAP server and also the difference in the output that are we seeing.
In the first case user2 is trying to fetch the entire entry of user1, by binding as user2. The result is that user1 does not reveal the userPassword to user2.
Now in the second case, as user2 is in the Proxy Group, it is able to fire a query on the entry of user1, as a proxy of user1 (using the -y option) and get the userPassword.
For information on the Proxy Group, you may refer the ITDS v 52 Administration Guide. The link for the same is put up in one of the sections above.
10.6.5 SSL, TLS notes
The SSL or TLS - related functions associated with this utility are as like the ones described with ldapchangepwd in “The ldapchangepwd command” on page 239.
10.6.6 Diagnostics
Exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error.
10.7 Summary
After seeing these utilities let us have a summary of what was done in this chapter. This chapter was mainly focussed on learning the following client utilities:
•ldapchangepwd
•ldapdelete
•ldapexop
•ldapmodify and ldapadd
•ldapmodrdn
•ldapsearch
We also saw the detailed explanations on the options that the above utilities would take.
 
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset