B.2. rsearch (Search Stress Tests)

The rsearch utility opens multiple threads that perform the same operation, quickly and repeatedly, in a loop against the specified Directory Server instance, according to the parameters set in the command.
At its simplest, rsearch emulates multiple client connections for search operations. With additional options, rsearch can be expanded to perform compare, modify, delete, and bind/unbind operations along with search operations.
The tool also tracks the performance of the operations and outputs a running stream of averaged results.

Note

The results of rsearch tests naturally depend on the performance of the Directory Server and its host machine. Optimize the configuration of the Directory Server and machine first through performance tuning (as in the Tuning Red Hat Directory Server Performance).
The rsearch utility is located in the /usr/bin directory.

B.2.1. Syntax

rsearch -D bind_dn -w password -s suffix -f filter [ -h host ] [ -p port ] [ -S scope ] [ -b ] [ -u ] [ -L ] [ -N ] [ -v ] [ -y ] [ -q ] [ -l ] [ -m ] [ -M ] [ -d ] [ -c ] [ -i file_for_filters ] [ -B DN_or_uid_file ] [ -A attributes ] [ -a file_of_attributes ] [ -n ] [ -o search_time_limits ] [ -j sample_interval ] [ -t threads ] [ -T timelimit ] [ -V ] [ -C number_of_samples ] [ -R reconnect_interval ] [ -x ] [ -W password ] [ -U text ] [ -\? or -H ]

B.2.2. Options

Table B.5. rsearch Options

Option Description
-A attributes Contains a list of attributes to be used with the search request. This cannot be used with -a.
-a file_of_attributes Points to a file which contains a list of attributes to be used with the search request. Each attribute must be on a separate line in the file. For example: 
attr1
attr2
...
This cannot be used with -A.
-B DN_or_uid_file Contains a list of either DNs or UIDs which are used to bind to the server. For DNs, each entry has two lines, one for the DN and one for the UID (which is used as the default password): 
DN: dn
UID: uid
...
The UID files simple has one UID per line: 
UID: uid1
UID: uid2
...
-b Tells the utility to bind before every operation.
-C sample_numbers Gives the number of samples to take and then exits the utility.
-c Specifies a compare operation. If this is used, then the -B option must be used.
-D bind_dn Gives the bind DN for the rsearch utility to use to connect to the server; if no other identity is supplied in a DN file (-B -x), this is the identity used to run tests.
-d Specifies a delete operation. If this is used, then the -B option must be used.
-f filter Contains the search filter to be used with search operations.
-h host Gives the host name of the LDAP server to connect to. The default, if not given, is localhost.
-i file Points to a file that contains the names to be appended to the search filter passed with the -f option. The name file is a simple list, with each name on a separate line: 
joe
jane
A filter option that could be used with this file would be “uid=”, which results in filters of both "uid=joe" and "uid=jane" randomly being used.
-j sample_interval Specifies an interval, in seconds, to wait before collecting a sample.
-L Sets the connection to linger. The connection is discarded when the utility closes.
-l Logs the utility output.
-M Specifies a modify operation for an indexed attribute (telephonenumber). This requires the -B option.
-m Specifies a modify operation for an unindexed attribute (description). This requires the -B option.
-N Specifies that the tool will only bind to the server, without running any other operation.
-n Reserved for future use.
-o search_time_limit Gives the time limit, in seconds, to use for search operations.
-p port Gives the port to use to connect to the Directory Server instance. If this is not used, the default is 389.
-q Runs the tool quietly.
-R reconnect_interval Tells the utility to drop the connection to server and reconnect after the specified number of searches (reconnect_interval).
-S scope Sets the search scope. The allowed values are 0, 1, and 2, corresponding to one-level, base, and subtree, respectively. The default is 2.
-s suffix Gives the suffix in the Directory Server against which to run all of the tests.
-T timelimit Sets a total time limit for the rsearch tests. Once the utility hits that limit, the tool closes.
-t threads Sets the number of threads for the utility to open. The default is 1.
-U Passes a filter to use with the bind file. If -x is not used, this option is ignored. The default value is '(uid=%s)'.
-u Tells the utility not to unbind from the server, but simply to close the connection.
-V Shows the running averages of the rsearch results.
-v Runs the command in verbose mode.
-W Gives the password to use to bind with identities in the -B file. If this is not given, the default is the UID value.
-x Tells the utility to use the contents of the -B file for binding. If this is not used, than the -B option is ignored.
-y Runs the command with no delay between tests.
-\? or -H Prints the usage for the tool.

B.2.3. Usage Scenarios

The rsearch utility can be used to measure the performance of any LDAP operation. The following examples show how to use rsearch for a variety of common test scenarios.

Note

Even though rsearch requires arguments for search parameters like filter and scope, these arguments can be left empty to perform tests for other kinds of LDAP operations. For example: 
rsearch -D "cn=directory manager" -w secret -s "" -f ""

B.2.3.1. Allowed Configuration Files

Most of the time, the rsearch tool uses the information passed in the command line to connect to the server. The rsearch tool can accept two different configuration files to use in place of the passed arguments:
  • A DN or UID file, which contains a list of either UIDs or both DNs and UIDs. The DN/UID file allows rsearch to connect using multiple, randomly-selected bind identities. Any operation test can be combined with a bind/unbind test.

    Warning

    Random bind identities should not be used with a delete test because the command may attempt to bind with an identity in the DN/UID file that has already been deleted from the directory.
    DN/UID files are used with the -B option to pass the file and then an operation option (-c, -d, -m, or -x).
  • A name file, which contains a list of names to use as part of the given LDAP filters. The filter in the file can be more complex than the ones specified in the -f option. The filter file can be used to run a number of different search tests. For example, having only a few filters means that the tool will begin retrieving results from cache, while using invalid filter can test search failures. It can also test filter performance, such as exact matches, complex filters, or attribute searches.
    When using a filter file, the -f option must be passed with a placeholder value. The placeholder can be used to replace only an attribute value, such as cn=%s, which tells the command to pull the attribute value variable from the filter file. The placeholder can also replace the filter itself (-f "%s") to supply randomly-selected filters from the file.
    The -i option pass the name file to use for the search filters. Every line in the file is appended to whatever filter is given with the -f option. There are a couple of different ways that these two options can be used together:
    • The simplest scenario leaves the -f option empty, so it's just a placeholder. In this case, the filters are taken directly from the file passed with the -i option.
    • Alternatively, the entries in the file could simply be a list of names, and a partial filter can be given for the -f option. For example, the name file could have a list of UIDs (jsmith, bjensen, amorrow) and the -f filter could be "uid=". rsearch automatically appends the name to complete the search filter.

B.2.3.2. Results from rsearch

Periodically (every ten seconds by default), rsearch returns the current running average for the operations run by the script.
The results first show the number of operations performed within that interval. The two ratios in the parenthesis show the total number of operations per second and then the amount of time, in milliseconds, spent on each operation (1 second divided by the total number of operations, multiplied by 1000). 
date timestamp - Rate: num_ops/thr (ops/sec = num ms/op), total: ops (number thr)
For example: 
[jsmith@server ~]$ rsearch -D "cn=directory manager" -w secret -s "ou=people,dc=example,dc=com" -f "objectclass=%s"
rsearch: 1 threads launched.

20100209 20:20:40 - Rate: 65961.00/thr (6596.10/sec = 0.1516ms/op), total: 65961 (1 thr)

B.2.3.3. Search Testing

The core usage of rsearch is search testing. Measuring search performance can be done using only the required arguments with rsearch, without any optional arguments: 
rsearch -D bind_dn -w password -s suffix -f filter
Options can be used to measure specific performance or use a specific environment.
Search filters (in the command line or through a file with the -i file) can test different kinds of indexed attributes:
  • Filters without wildcards show the performance for exact matches
  • Filters with wildcards give performance for substring indexes
  • Filters with operators (=, >=, <=, ~=) show the performance for approximate indexes

Example B.18. Basic Search

rsearch -D "cn=test user,cn=config" -w secret -s "dc=example,dc=com" -f "sn=*smith*"
A basic search (which covers caching, since there's only one filter given and multiple search operations) uses the following arguments:
  • -D, which gives the bind identity
  • -w, which gives the bind password
  • -s, which gives the search target (scope)
  • -f, which gives the search filter

Example B.19. Searches for Specific Attributes

rsearch -D "cn=test user,cn=config" -w secret -s "dc=example,dc=com" -f "sn=%s" -i /home/filter.txt -A givenname,mail,uid
Along with the required arguments, this command searches for three specific attributes in the entries, using the -A option.
The -i option is not required, but it is recommended to supply different search filters so that the results are pulled fresh from the database, not from the cache.

B.2.3.4. Authentication Testing

The rsearch utility uses the user DN and password in the (required) -D and -w arguments to bind to the server. To test authentication performance, these credentials can be left blank, can be passed a list of credentials that are randomly selected, or be set to a special user, like the Directory Manager.

Example B.20. Anonymous Binds

rsearch -D "" -w "" -s "dc=example,dc=com" -f "sn=%s" -i /home/filter.txt
The -D and -w arguments have emtpy values, so the tool doesn't have any bind credentials to use to connect to the server. This initiates an anonymous bind.

Example B.21. Random User Authentication

rsearch -D "" -w "" -s "dc=example,dc=com" -f "sn=%s" -i /home/filter.txt -B /home/uids.txt -x
Rather than using the credentials in the -D and -w arguments, the the rsearch tool can be instructed to pull random bind identities from a list of given UIDs or DNs. This requires two options:
  • -B points to a file with a list of bind identities. For a UID file, this is simply a list of UIDs, one per line: 
    UID: uid1
UID: uid2
...
    For DNs, each entry has two lines, one for the DN and one for the UID (which is used as the default password): 
    DN: dn
UID: uid
...
  • -x forces the tool to use the file from the -B argument.
For DNs, the tool uses the DN line for the DN and the UID line as the password. The -U option tells the tool to use an attribute other than the UID as the entry naming attribute and -W passes a different password (which, by default, is the UID). 
rsearch -D "" -w "" -s "dc=example,dc=com" -f "sn=%s" -i /home/filter.txt -B /home/uids.txt -x -U "(cn=*)" -W newpassword

B.2.3.5. Modify Operation Testing

rsearch can be used to measure the performance of modify operations on two kinds of attributes: indexed and unindexed. The modify operation is signaled by using either the -M or the -m option. A list of entries to run modify operations against is passed using the -B option.

Note

Running a modify operation requires a DN file, which has the format: 
DN: dn1
UID: uid1

DN: dn2
UID: uid2
...
Using the -b option measures the rate of each set of bind-modify operations. If the -b option isn't used, then there is only one bind operation, and the test shows the average of all modify operations that are run.

Example B.22. Modify Operations on Unindexed Attributes

rsearch -D "cn=test user,cn=config" -w secret -s "" -f "" -m -B /home/dns.txt -v
Modify operations against unindexed attributes are done by using the -m option. The command performs modify operations on the description attribute for each entry selected from the DN file.
The test will run successfully even if the description attribute is indexed, so make sure that the attribute isn't indexed before running the test.

Example B.23. Modify Operations on Indexed Attributes

rsearch -D "cn=test user,cn=config" -w secret -s "" -f "" -M -B /home/dns.txt -v
Modify operations against indexed attributes are done by using the -M option. The command performs modify operations on the telephoneNumber attribute for each entry selected from the DN file.
The test will run successfully even if the telephoneNumber attribute isn't indexed, so make sure that the attribute is indexed before running the test.

B.2.3.6. Compare Operation Testing

The ldapcompare operation can be tested using rsearch by passing the -c option. The tool runs compare operations against the UID attribute, based on the list of UIDs passed in the -B option.

Note

Running a compare operation requires a DN file, which has the format: 
DN: dn1
UID: uid1

DN: dn2
UID: uid2
...

Example B.24. Compare Operations

rsearch -D "cn=test user,cn=config" -w secret -s "" -f "" -c -B /home/dns.txt -v
The -c argument tells the command to perform compare operations. This is required. Two other arguments are useful for measuring the performance of compare operations:
  • -B (without the -x), which provides a list of entries that the server can run compare operations for.
  • -v, which runs rsearch in verbose mode and prints the results of each bind attempt and compare operation.

B.2.3.7. Delete Operation Testing

Only one option is required with the delete performance testing: -d, which tells the command to run delete operations. As with other operations, the -B argument can be used to pass a file which contains a list of entries to be randomly selected and deleted.

Note

Do not use the -B -x option pair with delete operations, because the command may attempt to bind to the server with an identity which has already been deleted.

Example B.25. Delete Operations

rsearch -D "cn=test user,cn=config" -w secret -s "" -f "" -d -B /home/dns.txt
If the -B argument is used to supply a list of entries available to delete, then it must be a DN file, which has the format: 
DN: dn1
UID: uid1

DN: dn2
UID: uid2
...

B.2.3.8. Changing Time Limits

As with many performance tests, rsearch has several time-based metrics:
  • The period that operations are run for gathering one round of statistics (by default, ten seconds)
  • How long the tool runs (by default, indefinitely)
  • How long the tool maintains a connection to the server (by default, indefinitely)
All three time limits can be reset.

Example B.26. Setting the Operations Interval

rsearch -D "cn=test user,cn=config" -w secret -s "dc=example,dc=com" -f "cn=%s" -i /home/filter.txt -b -j 20
The rsearch tool prints the results for the operations performed in the immediate interval. The default interval is ten (10) seconds, so every line in the output represents the statistics for the operations run in the preceding ten second. This interval can be changed using the -j option.
This resets the test interval to 20 seconds.

Example B.27. Setting the Test Time Limit

rsearch -D "cn=test user,cn=config" -w secret -s "dc=example,dc=com" -f "cn=%s" -i /home/filter.txt -b -T 600

...

20100210 18:36:21 - Rate: 68561.00/thr (6856.10/sec = 0.1459ms/op), total: 68561 (1 thr)
20100210 18:36:31 - Rate: 78016.00/thr (7801.60/sec = 0.1282ms/op), total: 78016 (1 thr)
Final Average rate: 7328.85/sec = 0.1364msec/op, total: 78016
Normally, the command runs indefinitely, until the command is interrupted. The -T option sets a time limit (in seconds) for the test to run and then exit cleanly. When the tool exits, it prints a final summary of the averages of all test run intervals.

Example B.28. Setting a Reconnect Interval

rsearch -D "cn=test user,cn=config" -w secret -s "dc=example,dc=com" -f "cn=%s" -i /home/filter.txt -b -R 30
The tool usually opens one connection to the server. The reconnect option, -R, sets a time interval for the tool to reconnect to the Directory Server.

B.2.3.9. Bind Testing with Any Operation

Bind and unbind rates can be checked with any operation (search, modify, delete, compare) which is measured by rsearch. This requires one option, -b, which tells the tool to bind to the server with every operation.
Two other attributes can be used with bind testing: -L (which sets the tool to linger) and -N (which tells the tool to bind and unbind without performing any other operations).

Example B.29. Binding and Unbinding with Every Operation

rsearch -D "cn=test user,cn=config" -w secret -s "dc=example,dc=com" -f "cn=%s" -i /home/filter.txt -b -L
Two options are used to initiate bind and unbind operations for every operation performed by rsearch:
  • -b (required)
  • -L (recommended)
The -i option is not required, but it is recommended to supply different search filters so that the results are pulled fresh from the database, not from the cache.

Example B.30. Testing Anonymous Bind Operations

rsearch -D "" -w "" -s "" -f "" -N -b -L
To test the anonymous bind rate, simply use the -b option and leave the values for the -D and -w options empty. The -N option ensures that the command only attempts bind and unbind operations.

Example B.31. Testing Random Bind Operations

rsearch -D "" -w "" -s "" -f "" -B /home/uids.txt -x -N -b -L
As with anonymous bind operations, the required arguments can be left blank. The -N option ensures that the command only attempts bind and unbind operations, while the -B and -x options supply a list of random bind credentials for the command to select from.

Example B.32. Testing Using a Filter with Bind Operations

rsearch -D "" -w "" -s "" -f "" -B /home/uids.txt -x -U "(uid=*son)" -N -b -L
Normally, any identity contained in the bind file (UID or DN) can be used for bind testing. The default filter is "(uid=%s)", which every identity entry has. To use only a subset of the identities in the file, the -U option can be used to pass an alternate filter.

B.2.3.10. Performing Multi-Threaded Testing

Example B.33. Multiple Threads

rsearch -D "cn=test user,cn=config" -w secret -s "dc=example,dc=com" -f "sn=%s" -i /home/filter.txt -t 5
By default, rsearch opens one thread for operations. The -t option allows a multiple threads to be opened.