|
| |
| Sun ONE Directory Server Resource Kit 5.2 Tools Reference | |
Chapter 12
The rsearch Search ToolThe rsearch tool is a multi-threaded 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 chapter provides instructions on how to use the ldclt tool. It contains the following sections:
OverviewThe rsearch tool (repeated search) is an LDAP client that performs repeated LDAP operations. The DSRK and its updates include the latest version of the tool in the DSRK_base/bin/dsrk52 directory. It is written in C using the Sun™ ONE LDAP SDK for C and may be used to measure performance on any LDAP directory.
Note
As with all measures of performance, results depend upon many factors, such as the options and parameter values given, directory configuration, machine load, and network traffic, 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 10, "The idsktune Optimization Tool" for tuning information.)
Command UsageThe rsearch command launches a number of threads that perform synchronous operations on the given directory server.
Note
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. The default operation is to perform a search from a filter defined 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 distinguished names (DNs) or UIDs for entries that will be randomly selected to perform each operation. The output for these operations is:
Syntax
The syntax of the rsearch tool on the command-line takes the following form:
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 Chapter 4 of the Sun ONE Directory Server Getting Started 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 parameters described in Options.
Options
The rsearch options and parameters are described in Table 12-1. The rsearch -\? command when run on the command-line will display text that briefly describes all of the command-line options.
Table 12-1 Command-Line Options for rsearch
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:
-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. See DN and UID File Formats.
-\?
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.
DN and UID File Formats
The -B option specifies a file containing either DN and UID values or UID values alone, as shown in Table 12-2. DN files are used as input for 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 for more information.
Table 12-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.
Sample OutputCode Example 12-1 is sample output that might be retreived from the rsearch tool. The given Rate is the average number of operations per thread over the elapsed interval (10 seconds by default or 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 ExamplesThe 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 based on the following:
- 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 need to provide DN and UID files that correspond to the contents of your directory. (See DN and UID File Formats for more information.)
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.
Note
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
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).
$ rsearch -h hostname -p port -s "" -f "" \
-D "" -w "" -N -b -L -T 100Random DN Authentication Rate
This command will bind repeatedly, each time as a random DN found in the DN file (-B DNfile -x). It uses the DN’s UID from that file as the password, repeats binding with no other operations (-N -b -L), and runs indefinitely (no -T option).
$ rsearch -h hostname -p port -s "" -f "" -D "" -w "" \
-B DNfile -x -N -b -L
Random UID Authentication Rate
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).
$ rsearch -h hostname -p port -s "" -f "" \
-D "" -w "" -B UIDfile -x -N -b -L
Note
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
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).
$ rsearch -h hostname -p port -s "" -f "" \
-D "cn=Directory Manager" -w password -N -b -L -T 100Measuring 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 for more information.) Filter files may also contain the following 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
This command will bind once as the given DN (-D bindDN -w password) and search repeatedly for entries under the "dc=example,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.
$ rsearch -h hostname -p port -s "dc=example,dc=com" \
-D "bindDN" -w password -f "cn=*jones*"Search Rate Using Anonymous Bind
This command will perform a single anonymous bind (-D "" -w "") and search repeatedly for random surnames taken from a filter file (-f "sn=%s" -i filterFile).
$ rsearch -h hostname -p port -s "dc=example,dc=com" \
-D "" -w "" -f "sn=%s" -i filterFileSearch Rate Using DN Bind
This command will bind once as the given DN (-D bindDN -w password) and search repeatedly for entries matching random surnames taken from a filter file (-f "sn=%s" -i filterFile).
$ rsearch -h hostname -p port -s "dc=example,dc=com" \
-D "bindDN" -w password -f "sn=%s" -i filterFileSpecific Attribute Search Rate
This command will retrieve only the givenName and mail attributes of entries matching random surnames taken from a filter file (-f "sn=%s" -i filterFile).
$ rsearch -h hostname -p port -s "dc=example,dc=com" \
-D "" -w "" -f "sn=%s" -i filterFile -A givenName,mailMeasuring 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.
Tip
To further resemble actual search operations, multiple threads can simulate load on the server. Set the thread option to model the expected load on your directory.
Anonymous Bind and Search Rate
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=example,dc=com" suffix.
$ rsearch -h hostname -p port -s "dc=example,dc=com" \
-D "" -w "" -f "sn=%s" -i filterFile -b -L -t 10Random DN Bind and Search Rate
This command will create 10 threads (-t 10), each of which will repeatedly bind, search for entries under the "dc=example,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 uses 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.
$ rsearch -h hostname -p port -s "dc=example,dc=com" -D "" -w "" \
-B DNfile -x -f "sn=%s" -i filterFile -b -L -t 10Random UID Bind and Search Rate
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.
$ rsearch -h hostname -p port -s "dc=example,dc=com" -D "" -w "" \
-B UIDfile -x -f "sn=%s" -i filterFile -b -L -t 10
Note
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
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 a DN file, and display verbose results every 5 seconds (-j 5 -v).
$ rsearch -h hostname -p port -s "" -f "" \
-D "bindDN" -w password -B DNfile -c -t 2 -j 5 -vBind and Compare Rate
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 a 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 as 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.
$ rsearch -h hostname -p port -s "" -f "" -D "" -w "" \
-B DNfile -x -c -b -L -t 2 -j 5 -v
Measuring Modify Operations
The following examples will measure the performance of modify operations. The rsearch tool performs a 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
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, the command does not verify this and will function normally even if it is not.
$ 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 -bThe 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
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, the command does not verify this and will function normally even if it is.
$ 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 -bThe 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
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).
$ rsearch -h hostname -p port -s "" -f "" \
-D "cn=Directory Manager" -w password -B DNfile -d -T 7
Tip
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
This command will repeatedly perform delete operations on entries randomly chosen from a DN file (-B DNfile -d), while rebinding every time (-b -L) as the root DN (-D "cn=Directory Manager" -w password).
$ rsearch -h hostname -p port -s "" -f "" -D "cn=Directory Manager" \
-w password -B DNfile -d -b -L -T 7
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.