Chapter 10   rsearch


The rsearch (repeated search) tool is a multi-threaded LDAP client program that measures the performance of LDAP search, compare, modify, delete, and authentication operations. It performs operations continuously and computes an average operation rate at regular intervals.

This tool is written in C using the iPlanet LDAP SDK for C and may be used to measure the performance of any LDAP directory. As with all measures of performance, results depend upon many factors, such as machine load, network traffic and directory configuration, and should be analyzed accordingly. In order to obtain accurate performance measurements, both client and server machines should be dedicated to the performance test and properly tuned (see Chapter 8 "idsktune").

This chapter contains the following sections:

• Command Usage

• Sample Output

• Command-Line Examples

Command Usage

---

The rsearch command launches a number of threads that perform synchronous operations on the given directory server. The threads are simple loops that perform the same operation over and over as quickly as possible.

At regular intervals (every 10 seconds by default) the tool displays the statistics collected for operations completed during the elapsed interval. It shows the average number of operations per thread, the total number of operations, the number of operations per second, and the inverse in milliseconds per operation.

The default operation is to perform a search with the filter given on the command line. In order to simulate more realistic directory usage, you may provide a filter file with multiple filter strings that the tool will select from randomly.

The rsearch tool will also measure the performance of compare, modify, delete, and authentication operations. These require you to provide a file containing the DNs or UIDs for entries that will be randomly selected for performing each operation. The output for these operations contains the same information as for searches.

Syntax

The rsearch command has the following syntax:

rsearch -D "bindDN " -w password -s "suffix " -f "filter " [ options ]

Where:

• bindDN and password are the bind credentials with sufficient permissions to search or modify the directory.

• suffix is the base DN for the search or modify operations.

• filter is an RFC 2254-compliant LDAP search filter (see "LDAP Search Filters" in Appendix B of the iPlanet Directory Server Administrator's Guide). The filter may use the %s syntax to include strings from a file given with the -i option.

• options are the command-line options and their parameters described in the next section.

Command-line parameters such as DNs and filters should be enclosed in double quotes ("...") if they contain special characters for the shell. When the required options (-D, -w, -s, and -f) are not needed for a given operation, they may be given as an empty string ("").

The rsearch -\? command will display a usage help text that briefly describes all options.

Options

The rsearch options and parameters are described in the following table.

Table 10-1    Command-Line Options for the rsearch Tool 

Option	Parameter	Purpose
-h	hostname	Specify the hostname of the directory server. The default is localhost.
-p	port	Specify the port number when accessing the directory server host. The default is 389.
-D	bindDN	Specify a bind DN for all operations, usually in double quotes ("") for the shell. Depending on its access permissions, the given bind DN may affect authentication and search performance.
-w	password	Specify the password for the bind DN.
-s	suffix	Specify the suffix to use as the base DN for all operations, usually in double quotes ("") for the shell.
-f	filter	Specify a filter for search operations, usually in double quotes ("") for the shell. This option can be used with an input file, for example, the filter cn=%s will use a random string from a file specified by the -i option.
-i	filterFile	Give the name of the file containing filter strings. The filter will be selected randomly from this file. See "Filter File Format" for more information.
-S	scope	Specify the scope of a search. The scope parameter may have one of the following values: 0 - For searching only the base entry. 1 - For searching one level below the base entry. 2 - For searching all levels below the entry. This is the default.
-A	attributes	A comma separated list of attribute names to specify which attribute values will be returned by searches.
-N		No operation: using this flag, the tool will only bind to the server, instead of binding and performing a search, which is the default. The -c, -d, and -m options will be ignored when this flag is used.
-b		Perform a bind before every operation (and unbind afterwards).
-u		Do not unbind from the server, just close the connection.
-L		Set the linger mode on the TCP socket to avoid too many leftover closed connections.
-y		Set the TCP_NODELAY mode on the TCP socket.
-t	threads	Specify the number of threads that rsearch will use. Use the -v option for verbose output including measurements from each thread. The default is a single thread.
-j	seconds	Specify the sampling interval, in seconds; the default is 10. rsearch repeats the given operation as many times as possible during the interval and prints results after each interval elapses.
-T	seconds	Specify the time limit, in seconds, after which rsearch will display the cumulated average and stop. When this option is not specified, rsearch will run until its process is terminated.
-V		Alternate output at every interval: display only the rate and cumulated average rate of operations per thread.
-v		Verbose output at every interval: gives the measurements from each thread, including the minimum and maximum operation times observed, as well as the average for all threads.
-q		Quiet output mode: the measurements for each interval will not be displayed. If -T is specified, only the final average will be shown.
-B	UIDfile or DNfile	Specify the file needed for input to the compare, delete, modify, and authentication operations. Must be used in conjunction with the -c, -d, -m or -x flags, respectively, to specify the operation. See "DN and UID File Formats" for more information.
-c		Perform compare operations on the uid attribute of entries chosen randomly from a DN file specified by the -B option. Comparisons are set up to be randomly true or false and verified accordingly.
-d		Perform delete operations on entries chosen randomly from a DN file specified by the -B option. Note that rsearch does not replace these entries, meaning that delete operations will cause an error when a DN is randomly selected the second time. This will not affect rsearch, but the statistics will be skewed unless the entries are otherwise restored or replaced.
-m		Perform modify operations on the description attribute, assuming it is not indexed. The entries to be modified are chosen randomly from a DN file specified by the -B option.
-M		Perform modify operations on the telephonenumber attribute, assuming that it is indexed. The entries to be modified are chosen randomly from a DN file specified by the -B option.
-x		Perform bind operations using a DN and its UID as a password for authentication. The DN is selected randomly from a UID or DN file specified by the -B option.
-\?		Display the usage help text that briefly describes all options.

Filter File Format

The -i option is followed by the name of a text file containing filter strings. Each line of the file is taken to be a filter string and may contain spaces, as follows:

Filter string 1
Filter string 2
...

When using a filter file, you must use the -f option with a filter containing the %s placeholder. When performing each search, the placeholder will be textually replaced by a filter string randomly selected from the filter file.

The filter may contain only one placeholder, for example, -f "cn=%s". Alternatively, you may specify -f "%s" on the command line and give complete filters in the filter file. This will allow you to perform more complex searches.

When using a filter file, it should contain the appropriate strings for searching in your directory. For example, you may want to measure exact string matching searches, searches that fail, or compound search expressions. Also the number of filter strings will determine how often the same search is repeated: few strings imply that search results are more likely to be retrieved from the directory server's cache.

DN and UID File Formats

The -B option specifies a file containing either DN and UID values or UID values alone, as shown in the following table.

Table 10-2    DN or UID File Formats

DN File Format	UID File Format
DN: dn_string UID: uid_string DN: dn_string2 UID: uid_string2 ...	UID: uid_string UID: uid_string2 ...

In these formats, the DN: and UID: keywords must be followed by at least one space. Everything after that space is taken literally; do not use quotes unless you want them to appear in the string.

DN files are used as input to the compare, modify, and delete operations. Both DN and UID files may be used as input for binding when performing authentication and search operations (see "Measuring Bind and Authentication Operations", and "Random DN Bind and Search Rate").

When used for binding by specifying the -x option, the two file formats are treated differently. If you use the DN file format, authentication for the bind will use the DN as the bind DN and the UID as the password. If you have a file containing only UIDs, rsearch will use its -D bindDN and -w password parameters to bind and search for an entry with the given UID. It will find the DN of that entry, and then bind again with this DN, using the UID as the password.

Sample Output

---

Rate: 648.00/thr (129.60/sec = 7.7160msec/op ), total: 1296 (2 thr)
Rate: 645.00/thr (129.00/sec = 7.7519msec/op ), total: 1290 (2 thr)
Rate: 642.50/thr (128.50/sec = 7.7821msec/op ), total: 1285 (2 thr)
...
Final Average rate: 130.74/sec = 7.6488msec/op, total: 1285

The given Rate is the average number of operation per thread over the elapsed interval (10 seconds by default). Use the -j seconds option to specify a different interval. All data on an output line concerns only the elapsed interval. Use the -V option to display a running average of operations per thread per interval.

If you specify a time limit with the -T seconds option, the final average rate is computed and displayed; otherwise, the command runs until you terminate it. This average is totaled over all threads, giving the absolute operation rate and its inverse, the average time to complete each operation.

Command-Line Examples

---

The following sections give examples of rsearch command usage for measuring the performance of various scenarios. You will need to adapt these examples to your environment:

• The hostname and port placeholders should be replaced with the hostname and port number of your directory. When significant, the suffix should represent the contents of the directory tree or subtree you wish to test.

• For meaningful results, thread numbers and time limit options should be scaled according to your directory's expected load.

• You will also need to provide DN and UID files that correspond to the contents of your directory (see "DN and UID File Formats").

Measuring Bind and Authentication Operations

The following examples will measure bind and authentication performance in your LDAP directory. These commands perform only bind and unbind operations. They do not perform any searches, except when part of the binding procedure.

In all of the bind and authentication examples, the -s suffix and -f filter options have no effect because no search is performed. They are given as empty strings ("") because they are required on the command line.

Anonymous Bind Rate

$ rsearch -h hostname -p port -s "" -f "" \
          -D "" -w "" -N -b -L -T 100

This command will bind anonymously (-D "" -w ""), repeat binding with no other operations (-N -b), avoid opening too many connections (-L), use a single thread (no -t option), display statistics every 10 seconds (no -j option), and finish in about 100 seconds (-T 100).

Random DN Authentication Rate

$ rsearch -h hostname -p port -s "" -f "" -D "" -w "" \
          -B DNfile -x -N -b -L

This command will bind repeatedly, each time as a random DN found in the DN file (-B DNfile  -x), use the DN's UID from that file as the password, repeat binding with no other operations (-N -b -L), and run indefinitely (no -T option).

The -D "" and -w "" options are required on the command line but have no effect.

Random UID Authentication Rate

$ rsearch -h hostname -p port -s "" -f "" \
          -D "" -w "" -B UIDfile -x -N -b -L

This command is a typical authentication scenario where the client must first find the DN corresponding to a UID before binding. In each bind sequence, this command will select a random UID from the given UID file (-B UIDfile -x), bind anonymously (-D "" -w "") to find the DN of the corresponding entry, and then bind as this DN using the UID for authentication. It will repeat the binding sequence without performing searches until the process is killed (-N -b -L).

You may need to set the -D and -w options for valid authentication if your directory does not allow anonymous binding.

Root DN Bind Rate

$ rsearch -h hostname -p port -s "" -f "" \
          -D "cn=Directory Manager" -w password -N -b -L -T 100

This command will bind as root DN (-D "cn=Directory Manager" -w password ), and repeat binding with no other operations (-N -b -L) for about 100 seconds (-T 100).

Measuring Search Operations

The following examples will measure search performance in your directory server. All of the searches are performed within a single bind, so the results are those of the search operation alone, assuming factors such as machine load and network traffic remain constant.

In these examples, you will need to provide the suffix and filter strings for valid entries in your test directory (see "Filter File Format"). Filter files may also contain different kinds of filter strings that may give different performance results:

• Strings containing wildcards will give measurements that reflect substring search rate.

• Strings without wildcards will give measurements that reflect the search rate for exact matches.

• Filter strings may also include operators other than equality, such as ranges that are greater than (>=) or less than (<=) a given value, or approximate spelling searches (~=).

Simple Search

$ rsearch -h hostname -p port -s "dc=Siroe,dc=com" \
          -D "bindDN " -w password -f "cn=*jones*"

This command will bind once as the given DN (-D bindDN -w password ) and search repeatedly for entries under the "dc=Siroe,dc=com" suffix that contain the "cn=*jones*" substring. Because every search uses the same filter and returns the same entries, entry caching in the directory server will influence results. In all of the following examples, the use of a filter file helps provide more realistic measurements.

Search Rate Using Anonymous Bind

$ rsearch -h hostname -p port -s "dc=Siroe,dc=com" \
          -D "" -w "" -f "sn=%s" -i filterFile

This command will perform a single anonymous bind (-D "" -w "") and search repeatedly for random surnames taken from the filter file (-f "sn=%s" -i filterFile ).

Search Rate Using DN Bind

$ rsearch -h hostname -p port -s "dc=Siroe,dc=com" \
          -D "bindDN " -w password -f "sn=%s" -i filterFile

This command will bind once as the given DN (-D bindDN -w password ) and search repeatedly for entries matching random surnames taken from the filter file (-f "sn=%s" -i filterFile ).

Specific Attribute Search Rate

$ rsearch -h hostname -p port -s "dc=Siroe,dc=com" \
          -D "" -w "" -f "sn=%s" -i filterFile -A ginenName,mail

This command will retrieve only the givenName and mail attributes of entries matching random surnames taken from the filter file (-f "sn=%s" -i filterFile ).

Measuring Bind and Search Operations

The following commands are similar to the search examples, except that rsearch will bind before every search operation and unbind afterward. These examples mimic the usual behavior of directory clients and thus measure the average time taken to serve a directory client. Again, if filter files contain strings with wildcards, performance will reflect substring search rates, otherwise it will reflect exact search rates.

To further resemble actual search operations, multiple threads simulate load on the server. Set the thread option to model the expected load on your directory.

Anonymous Bind and Search Rate

$ rsearch -h hostname -p port -s "dc=Siroe,dc=com" \
          -D "" -w "" -f "sn=%s" -i filterFile -b -L -t 10

This command will create 10 threads (-t 10), each of which will repeatedly bind, search, and unbind (-b), while avoiding too many open connections (-L). It always uses anonymous binding (-D "" -w "") and searches for random surnames (-f "sn=%s" -i filterFile ) in entries under the "dc=Siroe,dc=com" suffix.

Random DN Bind and Search Rate

$ rsearch -h hostname -p port -s "dc=Siroe,dc=com" -D "" -w "" \
          -B DNfile -x -f "sn=%s" -i filterFile -b -L -t 10

This command will create 10 threads (-t 10), each of which will repeatedly bind, search for entries under the "dc=Siroe,dc=com" suffix, and unbind (-b), while avoiding too many open connections (-L). It always binds with a DN randomly selected from the DN file (-B DNfile -x) and use the DN's UID from that file as the password (see "DN and UID File Formats"). The -D "" and -w "" options are required on the command line but have no effect.

Random UID Bind and Search Rate

$ rsearch -h hostname -p port -s "dc=Siroe,dc=com" -D "" -w "" \
          -B UIDfile -x -f "sn=%s" -i filterFile -b -L -t 10

This command is identical to the previous one for measuring random DN bind and search rate, except it uses a UID file (see "DN and UID File Formats"). Here, in each repeated search sequence, the command will first select a random UID from the UID file (-B UIDfile -x), bind anonymously (-D "" -w "") to find the DN of the corresponding entry, and then bind as this DN using the UID for authentication before performing the search.

You may need to set the -D and -w options for valid authentication if your directory does not allow anonymous binding.

Measuring Compare Operations

The following examples will measure the performance of compare operations. The -s "" and -f "" options have no effect but are required on the command line.

Compare Rate

$ rsearch -h hostname -p port -s "" -f "" \
          -D "bindDN " -w password -B DNfile -c -t 2 -j 5 -v

This command will create two threads (-t 2), each of which will bind once using the given bindDN and password (use -D "" -w "" for anonymous binding), repeatedly perform a compare operation (-c) on the uid attribute of random DNs from the DN file, and display verbose results every 5 seconds (-j 5 -v).

Bind and Compare Rate

$ rsearch -h hostname -p port -s "" -f "" -D "" -w "" \
          -B DNfile -x -c -b -L -t 2 -j 5 -v

In this form, the -D "" and -w "" options have no effect but are required on the command line.

This command will create two threads (-t 2), each of which will bind before every compare operation (-c -b -L) and unbind afterwards, while displaying verbose results every 5 seconds (-j 5 -v). Binding will use a random DN from the DN file (-B DNfile  -x) with the DN's corresponding UID as the password. Another DN will be randomly selected from the same file and used the target of the compare operation based again on its UID. This implies that directory entries for DNs appearing in the DNfile must have the same UID and password.

Measuring Modify Operations

The following examples will measure the performance of modify operations. The rsearch tool performs modify operation on the telephonenumber and description attributes. These examples assume that the telephonenumber attribute is indexed in your test directory and that the description attribute is not.

In these examples, the -s "" and -f "" options have no effect but are required on the command line. Also, adding the -x option will use the same DN file for both binding and modification. In this case however, all DNs in your DN file must have modification rights to all entries corresponding to those DNs.

Indexed Attribute Modify Rate

$ rsearch -h hostname -p port -s "" -f "" \
          -D "cn=Directory Manager" -w password -B DNfile -M

$ rsearch -h hostname -p port -s "" -f "" \
          -D "cn=Directory Manager" -w password -B DNfile -M -b

These commands will bind as the root DN (-D "cn=Directory Manager" -w password) and repeatedly perform a modify operation on the telephonenumber attribute of randomly chosen entries from the DN file (-B DNfile  -M). While this example scenario assumes that the telephonenumber attribute is indexed, this command does not verify this and will function normally even if it is not.

The first form of this command will bind only once and measure the average rate of modify operations. The second form with the -b option will rebind at every modify operation to measure the average time for the bind and modify operation sequence.

Non-Indexed Attribute Modify Rate

$ rsearch -h hostname -p port -s "" -f "" \
          -D "cn=Directory Manager" -w password -B DNfile -m

$ rsearch -h hostname -p port -s "" -f "" \
          -D "cn=Directory Manager" -w password -B DNfile -m -b

These commands will bind as the root DN (-D "cn=Directory Manager" -w password) and repeatedly perform a modify operation on the description attribute of randomly chosen entries from the DN file (-B DNfile  -m). While this example scenario assumes that the description attribute is not indexed, this command does not verify this and will function normally even if it is.

The first form of this command will bind only once and measure the average rate of modify operations. The second form with the -b option will rebind at every modify operation to measure the average time for the bind and modify operation sequence.

Measuring Delete Operations

The following examples will measure the performance of delete operations in your directory. The -s "" and -f "" options have no effect but are required on the command line.

Delete Rate

$ rsearch -h hostname -p port -s "" -f ""
          -D "cn=Directory Manager" -w password -B DNfile -d -T 7

This command will bind once as the root DN (-D "cn=Directory Manager" -w password ) and repeatedly delete entries whose DN was randomly chosen from the DN file (-B DNfile -d).

Because DNs are randomly chosen from the DN file, errors will occur when the tool tries to delete entries that have already been chosen and deleted. To minimize these errors, set the time limit option (-T 7) and use a DN file with a large number of DNs.

Bind and Delete Rate

$ rsearch -h hostname -p port -s "" -f "" -D "cn=Directory Manager"
          -w password -B DNfile -d -b -L -T 7

This command will repeatedly perform delete operations on entries randomly chosen from the DN file (-B DNfile -d), while rebinding every time (-b -L) as the root DN (-D "cn=Directory Manager" -w password ).

---

Note	Do not use the -x option when performing bind and delete operations: this will cause rsearch to attempt to bind with DNs that may have already been deleted.

---