B.2. rsearch (Search Stress Tests)
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.
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.
Note
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 Red Hat Directory Server Performance Tuning Guide).
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 |
Refers to a file that contains the names to be appended to the search filter passed with the
-f option. The name file is a list, with each name on a separate line. For example:
joe jane
A filter option that can be used with this file is, for example,
-f "uid=%s" , 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
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
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
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 ascn=%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 is 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
rsearch
returns the current running average for the operations run by the script.
date timestamp - Rate: num_ops/thr (ops/sec = num ms/op), total: ops (number thr)
# rsearch -D "cn=Directory Manager" -w password -s "ou=people,dc=example,dc=com" -f "objectclass=%s" -i /home/filter.txt 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
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
-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*"
-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
-A
option.
-i filter_file
option is required if you use the %s
variable in the -f filter
option.
B.2.3.4. Authentication Testing
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
-D
and -w
arguments have emtpy values, so the tool does not 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
-D
and -w
arguments, 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.
-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
DN: dn1 UID: uid1 DN: dn2 UID: uid2 ...
-b
option measures the rate of each set of bind-modify operations. If the -b
option is not 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
-m
option. The command performs modify operations on the description
attribute for each entry selected from the DN file.
description
attribute is indexed, so make sure that the attribute is not 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
-M
option. The command performs modify operations on the telephoneNumber
attribute for each entry selected from the DN file.
telephoneNumber
attribute is not indexed, so make sure that the attribute is indexed before running the test.
B.2.3.6. Compare Operation Testing
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
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
-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 runsrsearch
in verbose mode and prints the results of each bind attempt and compare operation.
B.2.3.7. Delete Operation 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
-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
-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
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)
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
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.
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
-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
-R
, sets a time interval for the tool to reconnect to the Directory Server.
B.2.3.9. Bind Testing with Any Operation
rsearch
. This requires one option, -b
, which tells the tool to bind to the server with every operation.
-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
rsearch
:
-b
(required)-L
(recommended)
-i filter_file
option is required if you use the %s
variable in the -f filter
option.
Example B.30. Testing Anonymous Bind Operations
# rsearch -D "" -w "" -s "" -f "" -N -b -L
-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
-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
"(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
rsearch
opens one thread for operations. The -t
option allows a multiple threads to be opened.