Language:
Format:

Appendix A. Testing Scripts Available with Directory Server

Red Hat Directory Server provides two scripts which can be used to test Directory Server performance in different stress or load conditions. The test scripts simulate different environments which allow administrators to assess configuration or machine changes before putting them in production.

Both ldclt and rsearch are located in the /usr/bin directory.

A.1. ldclt (Load Stress Tests)

The LDAP client script (ldclt) establishes multiple client connections to a server, under user-defined scenarios, to load-test the Directory Server. Client operations include directory adds, searches, modifies, modRDNs, and deletes, as well setup operations like generating LDIF files. Operations can be randomized — binding and unbinding as random users, performing random tasks — to simulate more realistic usage environments for the directory.

The ldclt tool measures the completion time of continuously-repeated operations to measure Directory Server performance. Using multiple threads makes it possible to test performance under high loads. Each test performs the same type of LDAP operation, but with different settings (like different user credentials, different attribute types or sizes, and different target subtrees).

Along with defining the LDAP operation variables, administrators can control the thread performance in order to set a specific load on the server.

The ldclt tool is specifically intended to be used for automated tests, so its options are extensive, flexible, and easily scripted, even for complex test operations.

Note

Remember that ldclt is a load test, and therefore uses a significant amount of system resources. The tool uses a minimum of 8 MB of memory. Depending on the numbers of threads, types of operations, and other configuration settings, it can use much more memory.

Depending on the type of operations and the directory data used for those operations, ldclt may set its own resource limits. For information on managing system resource limits, see the man pages for ulimit and getrlimit.

The ldclt utility is located in the /usr/bin directory.

A.1.1. Syntax

ldlt-q-Q-v-V-Emax_errors-bbase_DN-hhost-pport-ttimeout-Dbind_DN-wpassword-oSASL_options-eexecution_params-amax_pending-nnumber_of_threads-iinactivity_times-Nnumber_of_samples-Ierror_code-Ttotal_number_of_operations-rlow_range-Rhigh_range-ffilter-sscope-Sconsumer-Psupplier_port-Wwait_time-Zcertificate_file

A.1.2. ldclt Options

Table A.1. ldclt Options

Option	Description
-a max_pending_ops	Runs the tool in asynchronous mode with a defined maximum number of pending operations.
-b base_dn	Gives the base DN to use for running the LDAP operation tests. If not given, the default value is `dc=example,dc=com`.
-D bind_dn	Gives the bind DN for the `ldclt` utility to use to connect to the server.
-E max_errors	Sets the maximum number of errors that are allowed to occur in test LDAP operations before the tool exits. The default is 1000.
-e execution_params	Specifies the type of operation and other test environment parameters to use for the tests. The possible values for `-e` are listed in Table A.2, “Execution Parameters”. This option can accept multiple values, in a comma-separated list.
-f filter	Gives an LDAP search filter to use for search testing.
-h	Specifies the host name or IP address of the Directory Server to run tests against. If a host is not specified, `ldclt` uses the local host.
-I error_code	Tells `ldclt` to ignore any errors encountered that match a certain response code. For example, `-I 89` tells the server to ignore error code 89.
-i inactivity_times	Sets a number of intervals that the tool can be inactive before exiting. By default, this setting is 3, which translates into 30 seconds (each operations interval being 10 seconds long).
-N number_of_samples	Sets the number of iterations to run, meaning how many ten-second test periods to run. By default, this is infinite and the tool only exits when it is manually stopped.
-n number_of_threads	Sets the number of threads to run simultaneously for operations. The default value is 10.
-o SASL_option	Tells the tool to connect to the server using SASL and gives the SASL mechanism to use. The format is `-o` saslOption=value. saslOption can have one of six values: * mech, the SASL authentication mechanism * authid, the user who is binding to the server (Kerberos principal) * authzid, a proxy authorization (ignored by the server since proxy authorization is not supported) * secProp, the security properties * realm, the Kerberos realm * flags The expected values depend on the supported mechanism. The `-o` can be used multiple times to pass all of the required SASL information for the mechanism. For example: [literal,subs="+quotes,verbatim"] …. -o "mech=DIGEST-MD5" -o "authzid=test_user" -o "authid=test_user" ….
-P supplier_port	Gives the port to use to connect to a supplier server for replication testing. The default, if one is not given, is 16000.
-p port	Gives the server port number of the Directory Server instance that is being tested.
-Q	Runs the tool in "super" quiet mode. This ignores any errors that are encountered in operations run by `ldclt`.
-q	Runs the tool in quiet mode.
-R number	Sets the high number for a range.
-r number	Sets the low number of a range.
-S consumer_name	Gives the host name of a consumer server to connect to run replication tests.
-s scope	Gives the search scope. As with `ldapsearch`, the values can be subtree, one, or base.
-T ops_per_thread	Sets a maximum number of operations allowed per thread.
-t timeout	Sets a timeout period for LDAP operations. The default is 30 seconds.
-V	Runs the tool in very verbose mode.
-v	Runs the tool in verbose mode.
-W wait_time	Sets a time, in seconds, for the `ldclt` tool to wait after one operation finishes to start the next operation. The default is 0, which means there is no wait time.
-w password	Gives the password to use, with the `-D` identity, to bind to the Directory Server for testing.
-Z /path/to/cert.db	Enables TLS for the test connections and points to the file to use as the certificate database.

The -e option sets execution parameters for the ldclt test operations. Multiple parameters can be configured, in a comma-separated list. For example:

-e add,bindeach,genldif=/var/lib/dirsrv/slapd-instance/ldif/generated.ldif,inetOrgPerson

Table A.2. Execution Parameters

Parameter	Description
abandon	Initiates abandon operatons for asynchronous search requests.
add	Adds entries to the directory (`ldapadd`).
append	Appends entries to the end of the LDIF file generated with the `genldif` option.
ascii	Generates ASCII 7-bit strings.
attreplace=name:mask	Run modify operations that replace an attribute (name) in an existing entry.
attrlist=name:name:name	Specifies a list of attributes to return in a search operation.
attrsonly=#	Used with search operations, to set whether to read the attribute values. The possible values are 0 (read values) or 1 (do not read values).
bindeach	Tells the `ldclt` tool to bind with each operation it attempts.
bindonly	Tells the `ldclt` tool to only run bind/unbind operations. No other operation is performed.
close	Tells the tool to close the connection rather than perform an unbind operation.
cltcertname=name	Gives the name of the TLS client certificate to use for TLS connections.
commoncounter	Makes all threads opened by the `ldclt` tool to share the same counter.
counteach	Tells the tool to count each operation, not only successful ones.
delete	Initiates delete operations.
deref	Adds the dereference control to search operations (`esearch`). With adds, this tells `ldclt` to add the `secretary` attribute to new entries, to allow dereference searches.
dontsleeponserverdown	Causes the tool to loop very fast if server down.
emailPerson	This adds the `emailPerson` object class to generated entries. This is only valid with the add operation (`-e add`).
esearch	Performs an exact search.
genldif=filename	Generates an LDIF file to use with the operations.
imagesdir=path	Gives a location for images to use with tests.
incr	Enables incremental values.
inetOrgPerson	This adds the `inetOrgPerson` object class to generated entries. This is only valid with the add operation (`-e add`).
keydbfile=file	Contains the path and file name of the key database to use with TLS connections.
keydbpin=password	Contains the token password to access the key database.
noglobalstats	Tells the tool not to print periodical global statistics.
noloop	Does not loop the incremental numbers.
object=filename	Builds entry objects from an input file.
person	This adds the `person` object class to generated entries. This is only valid with the add operation (`-e add`).
random	Tells the `ldclt` utility to use all random elements, such as random filters and random base DNS.
randomattrlist=name:name:name	Tells the `ldclt` utility to select random attributes from the given list.
randombase	Tells the `ldclt` utility to select a random base DN from the directory.
randombaselow=value	Sets the low value for the random generator.
randombasehigh=value	Sets the high value for the random generator.
randombinddn	Tells the `ldclt` utility to use a random bind DN.
randombinddnfromfile=file	Tells the `ldclt` utility to use a random bind DN, selected from a file. Each entry in the file must have the appropriate DN–password pair.
randombinddnlow=value	Sets the low value for the random generator.
randombinddnhigh=value	Sets the high value for the random generator.
rdn=attrname:value	Gives an RDN to use as the search filter. This is used instead of the `-f` filter.
referral=value	Sets the referral behavior for operations. There are three options: on (allow referrals), off (disallow referrals), or rebind (attempt to connect again).
smoothshutdown	Tells the `ldclt` utility not to shut down its main thread until the worker threads exit.
string	Tells the `ldclt` utility to create random strings rather than random numbers.
v2	Tells the `ldclt` utility to use LDAPv2 for test operations.
withnewparent	Performs a modRDN operation, renaming an entry with newparent set as an argument.
randomauthid	Uses a random SASL authentication ID.
randomauthidlow=value	Sets the low value for a random SASL authentication ID.
randomauthidhigh=value	Sets the high value for the random SASL authentication ID.

A.1.3. Results from ldclt

ldclt continuously runs whatever operation is specified, over the specified number of threads. By default, it prints the performance statistics to the screen every ten (10) seconds.

The results show the average number of operations per thread and per second and then the total number of operations that were run in that ten-second window.

ldclt[process_id] Average rate: number_of_ops/thr (number_of_ops/sec), total: total_number_of_ops

For example:

ldclt[22774]: Average rate: 10298.20/thr  (15447.30/sec), total: 154473

ldclt prints cumulative averages and totals every 15 minutes and when the tool is exited.

ldclt[22774]: Global average rate: 821203.00/thr  (16424.06/sec), total: 12318045
ldclt[22774]: Global number times "no activity" reports: never
ldclt[22774]: Global no error occurs during this session.
Catch SIGINT - exit...
ldclt[22774]: Ending at Wed Feb 24 18:39:38 2010
ldclt[22774]: Exit status 0 - No problem during execution.

Some operations (like adds) and using verbose output options like -v or -V output additional data to the screen. The kind of information depends on the type of operation, but it generally shows the thread performing the operation and the plug-ins called by the operation. For example:

ldclt -b ou=people,dc=example,dc=com -D "cn=Directory Manager" -w secret12 -e add,person,incr,noloop,commoncounter -r90000 -R99999 -f "cn=testXXXXX" -V

...
ldclt[11176]: T002: After ldap_simple_bind_s (cn=Directory Manager, secret12)
ldclt[11176]: T002: incremental mode:filter="cn=test00009"
ldclt[11176]: T002: tttctx->bufFilter="cn=test00009"
ldclt[11176]: T002: attrs[0]=("objectclass" , "person")
ldclt[11176]: T002: attrs[1]=("cn" , "test00009")
ldclt[11176]: T002: attrs[2]=("sn" , "toto sn")
...
ldclt[11176]: Average rate:   195.00/thr  (  195.00/sec), total:    1950
ldclt[10627]: Global average rate:  238.80/thr  (238.80/sec), total:   2388
ldclt[10627]: Global number times "no activity" reports: never
ldclt[10627]: Global no error occurs during this session.
Catch SIGINT - exit...
ldclt[10627]: Ending at Tue Feb 23 11:46:04 2010
ldclt[10627]: Exit status 0 - No problem during execution.

Most errors are handled by ldclt without interrupting the test. Any fatal errors that are encountered are listed with the tool’s exit status and returned in the cumulative total.

Global no error occurs during this session.

Any LDAP operations errors that occur are handled within the thread. A connection error kills the thread without affecting the overall test. The ldclt utility does count the number of times each LDAP error is encountered; if the total number of errors that are logged hits more than 1000 (by default), then the script itself will error out.

The way that ldclt responds to LDAP errors can be configured. Using the -E option sets a different threshold for the script to error out after encountering LDAP errors. Using the -I option tells the script to ignore the specified LDAP error codes in all threads. Changing the error exit limit and ignoring certain error codes can allow you to tweak and improve test scripts or test configuration.

A.1.4. Exiting ldclt and ldclt Exit Codes

The ldclt command runs indefinitely. The script can stop itself in a handful of situations, like encountering a fatal runtime or initialization error, hitting the limit of LDAP errors, having all threads die, or hitting the operation or time limit.

The statistics for the run are not displayed until the command completes, either through the script exiting or by a user terminating the script. There are two ways to interrupt the ldclt script.

Hitting control—backslash (kbd:[^\]) or kill -3 prints the current statistics without exiting the script.
Hitting control—C (^C) or kill -2 exits the script and prints the global statistics.

When the ldclt script exits or is interrupted, it returns an exit code along with the statistics and error information.

Table A.3. ldclt Exit Codes

Exit Code	Description
0	Success (no errors).
1	An operation encountered a serious fatal error.
2	There was an error in the parameters passed with the tool.
3	The tool hit the maximum number of LDAP errors.
4	The tool could not bind to the Directory Server instance.
5	The tool could not load the TLS libraries to connect over TLS.
6	There was a multithreading (mutex) error.
7	There was an initialization problem.
8	The tool hit a resource limit, such as a memory allocation error.
99	The script encountered an unknown error.

A.1.5. Usage Scenarios

These provide general examples of using ldclt to test Directory Server. Test scripts with more complex examples are available in the ldclt source files. You can download this file from the 389 Directory Server project: https://github.com/389ds/389-ds-base/tree/master/ldap/servers/slapd/tools/ldclt/examples

Every ldclt command requires a set of execution parameters (which varies depending on the type of test) and connection parameters (which are the same for every type of operation). For example:

# ldclt -e execution_parameters -h localhost -p 389 -D "cn=Directory Manager" -w secret -b "ou=people,dc=example,dc=com"

When ldclt runs, it first prints all of the configured parameters for that test.

Process ID         = 1464
Host to connect    = localhost
Port number        = 389
Bind DN            = cn=Directory Manager
Passwd             = secret
Referral           = on
Base DN            = ou=people,dc=example,dc=com
Filter             = "cn=MrXXX"
Max times inactive = 3
Max allowed errors = 1000
Number of samples  = -1
Number of threads  = 10
Total op. req.     = -1
Running mode       = 0xa0000009
Running mode       = quiet verbose random exact_search
LDAP oper. timeout = 30 sec
Sampling interval  = 10 sec
Scope              = subtree
Attrsonly          = 0
Values range       = [0 , 1000000]
Filter's head      = "cn=Mr"
Filter's tail      = ""

A.1.5.1. Generating LDIFs

The ldclt tool itself can be used to generate LDIF files that can be used for testing.

Note

When generating an LDIF file, the ldclt tool does not attempt to connect to a server or run any operations.

Generating an LDIF file requires a basic template file that the tool uses to create entries (-e object), and then a specified output file (-e genldif).

The template file can give explicit values for entry attributes or can use variables. If you want a simple way to supply unique values for entry attributes, the /usr/share/dirsrv/data directory contains three data files to generate surnames, first names, and organizational units. These lists of values can be used to create test users and directory trees (dbgen-FamilyNames, dbgen-GivenNames, and dbgen-OrgUnits, respectively). These files can be used with the rndfromfile, incrfromfile, or incrfromfilenoloop options.

The basic format of the template file is:

# comment

attribute: string | variable=keyword(value)

The variable can be any letter from A to H. The possible keywords are listed in Table A.4, “ldclt Template LDIF File Keywords”

Some variables and keywords can be passed with the -e object option and other available parameters (like rdn).

-e object=inet.txt,rdn='uid:[A=INCRNNOLOOP(0;99999;5)]'

Table A.4. ldclt Template LDIF File Keywords

Keyword	Description	Format
RNDN	Generates a random value within the specified range (low - high) and of the given length.	RNDN(low;high;length)
RNDFROMFILE	Pulls a random value from any of the ones available in the specified file.	RNDFROMFILE(filename)
INCRN	Creates sequential values within the specified range (low - high) and of the given length.	INCRN(low;high;length)
INCRNOLOOP	Creates sequential values within the specified range (low - high) and of the given length — without looping through the incremental range.	INCRNOLOOP(low;high;length)
INCRFROMFILE	Creates values by incrementing through the values in the specified file.	INCRFROMFILE(filename)
INCRFROMFILENOLOOP	Creates values by incrementing through the values in the file, without looping back through the values.	INCRFROMFILENOLOOP(filename)
RNDS	Generates random values of a given length.	RNDS(length)

For example, this template file pulls names from sample files in the /usr/share/dirsrv/data and builds other attributes dynamically.

Example A.1. Example Template File

objectclass: inetOrgPerson
sn: [B=RNDFROMFILE(/usr/share/dirsrv/data/dbgen-FamilyNames)]
cn: [C=RNDFROMFILE(/usr/share/dirsrv/data/dbgen-GivenNames)] [B]
password: test[A]
description: user id [A]
mail: [C].[B]@example.com
telephonenumber: (555) [RNDN(0;999;3)]-[RNDN(0;9999;4)]

The ldclt command, then, uses that template to build an LDIF file with 100,000 entries:

# ldclt -b "ou=people,dc=csb" -e object=inet.txt,rdn='uid:[A=INCRNNOLOOP(0;99999;5)]' -e genldif=100Kinet.ldif,commoncounter

A.1.5.2. Adding Entries

The ldclt tool can add entries that match either of two templates:

person
inetorgperson

The -f filter sets the format of the naming attribute for the user entries. For example, -f "cn=MrXXXXX" creates a name like -f "cn=Mr01234". Using the person or inetorgperson parameter with -f creates a basic entry.

objectclass: person
sn: ex sn
cn: Mr01234

More complex entries (which are good for search and modify testing) can be created using the rdn parameter and an object file. The full range of options for the entries is covered in Section A.1.5.1, “Generating LDIFs”. The rdn and object parameters provide the format for the entries to add or edit in the directory. The rdn execution parameter takes a keyword pattern (as listed in Table A.4, “ldclt Template LDIF File Keywords”) and draws its entry pool from the entries listed in a text file.

-e rdn='uid:[A=INCRNNOLOOP(0;99999;5)]',object=inet.txt

The ldclt tool creates entries in a numeric sequence. That means that the method of adding those entries and of counting the sequence have to be defined as well. Some possible options for this include:

-r and -R to set the numeric range for entries
incr or random to set the method of assigning numbers (these are only used with -f)
-r and -R to set the numeric range for entries
noloop, to stop the add operations when it hits the end of the range rather than looping back

Example A.2. Adding Entries

# ldclt -b ou=people,dc=example,dc=com -D "cn=Directory Manager" -w secret -e add,person,incr,noloop,commoncounter -r0 -R99999 -f "cn=MrXXXXX" -v -q

The add operation can also be used to build a directory tree for more complex testing. Whenever an entry is added to the directory that belongs to a non-existent branch, the ldclt tool automatically creates that branch entry.

Note

The first time that an entry is added that is the child of non-existent branch, the branch entry is added to the directory. However, the entry itself is not added. Subsequent entries will be added to the new branch.

For a branch entry to be added automatically, its naming attribute must be cn, o, or ou.

Example A.3. Creating the Directory Tree

# ldclt -b ou=DeptXXX,dc=example,dc=com -D "cn=Directory Manager" -w secret -e add,person,incr,noloop,commoncounter -r0 -R99999 -f "cn=MrXXXXX" -v -q

A.1.5.3. Search Operations

The most basic ldclt search test simply looks for all entries within the given base DN. This uses two execution parameters: esearch and random.

Example A.4. Basic Search Operation

# ldclt -h localhost -p 389 -D "cn=Directory Manager" -w secret -b "ou=people,dc=example,dc=com" -f uid=testXXXXX -e esearch,random -r0 -R99999 -I 32

Important

A search that returns all entries can use a large amount of memory per thread, as much as 1 GB. ldclt is designed to perform searches that return one entry.

The search results can be expanded to return attributes contained in the entries. (Section A.1.5.1, “Generating LDIFs” has information on generating entries that contain multiple attributes.) To return a specific list of attributes for entries, use the attrlist execution parameter and a colon-separated list of attributes.

Example A.5. Searching for a List of Attributes

# ldclt -h localhost -p 389 -b "ou=people,dc=example,dc=com" -f uid=XXXXX -e esearch,random -r0 -R99999 -I 32 -e attrlist=cn:mail

Alternatively, the ldclt search operation can return attribute values for attributes randomly selected from the search list. The list is given in the randomattrlist execution parameter with a colon-separated list of attributes.

Example A.6. Searching for a List of Random Attributes

# ldclt -h localhost -p 389 -b "ou=people,dc=example,dc=com" -f uid=XXXXX -e esearch,random -r0 -R99999 -I 32 -e randomattrlist=cn:sn:ou:uid:mail:mobile:description

The filter used to match entries can target other entry attributes, not just naming attributes. It depends on the attributes in the generated LDIF.

Example A.7. Searches with Alternate Filters

# ldclt -h localhost -p 389 -b "ou=people,dc=example,dc=com" -f mail=XXXXXX@example.com -e esearch,random -r0 -R99999 -I 32 -e randomattrlist=cn:sn:ou:uid:mail:mobile:description

The search operation can also use the RDN-style filter to search for entries. The rdn and object execution parameters provide the format for the entries to add or edit in the directory. The rdn execution parameter takes a keyword pattern (as listed in Table A.4, “ldclt Template LDIF File Keywords”) and draws its entry pool from the entries listed in a text file.

Example A.8. Searches with RDN Filters

# ldclt -h localhost -p 389 -b "ou=people,dc=example,dc=com" -e rdn='mail:[RNDN(0;99999;5)]@example.com',object="inet.txt" -e attrlist=cn:telephonenumber

A.1.5.4. Modify Operations

The attreplace execution parameter replaces specific attributes in the entries.

The modify operation uses the RDN filter to search for the entries to update. The rdn and object parameters provide the format for the entries to add or edit in the directory. The rdn execution parameter takes a keyword pattern (as listed in Table A.4, “ldclt Template LDIF File Keywords”) and draws its entry pool from the entries listed in a text file.

Example A.9. Modify Operation

# ldclt -h localhost  -p 389 -D "cn=Directory Manager" -w secret -b "ou=people,dc=example,dc=com" -e rdn='uid:[RNDN(0;99999;5)]' -I 32 -e attreplace='description: random modify XXXXX'

A.1.5.5. modrdn Operations

The ldclt command supports two kinds of modrdn operations:

Renaming entries
Moving an entry to a new parent

The ldclt utility creates the new entry name or parent from a randomly-selected DN.

The basic rename operation requires three execution parameters:

rename
rdn='pattern'
object=file

The rdn and object parameters provide the format for the entries to add or edit in the directory. The rdn execution parameter takes a keyword pattern (as listed in Table A.4, “ldclt Template LDIF File Keywords”) and draws its entry pool from the entries listed in a text file.

Example A.10. Simple Rename Operation

# ldclt -h localhost -p 389 -D "cn=Directory Manager" -w secret -b "ou=people,dc=example,dc=com" -I 32 -I 68 -e rename,rdn='uid:[RNDN(0;999;5)]',object="inet.txt"

Using the withnewparent execution parameter renames the entry and moves it beneath a new parent entry. If the parent entry does not exist, then the ldclt tool creates it.^[3]

Example A.11. Renaming an Entry and Moving to a New Parent

# ldclt -h localhost -p 389 -D "cn=Directory Manager" -w secret12 -b "ou=DeptXXX,dc=example,dc-com" -I 32 -I 68 -e rename,withnewparent,rdn='uid:Mr[RNDN(0;99999;5)]',object="inet.txt"

A.1.5.6. Delete Operations

The ldclt delete operation is exactly the reverse of the add operation. As with the add, delete operations can remove entries in several different ways:

Randomly (-e delete,random)
RDN-ranges (-e delete,rdn=[pattern])
Sequentially (-e delete,incr)

Random deletes are configured to occur within the specified range of entries. This requires the following options:

-e delete,random
-r and -R for the range bounds
-f for the filter to match the entries

Example A.12. Random Delete Operations

# ldclt -b "ou=people,dc=example,dc=com" -D "cn=Directory Manager" -w secret -e delete,random -r0 -R99999 -f "uid=XXXXXX" -I 32 -v -q

RDN-based deletes use the rdn execution parameter with a keyword (as listed in Table A.4, “ldclt Template LDIF File Keywords”) and draws its entry pool from the entries listed in a text file. This format requires three execution parameters:

-e delete
-e rdn='pattern'
-e object='file'

Example A.13. RDN-Based Delete Operations

# ldclt -b "ou=people,dc=example,dc=com" -D "cn=Directory Manager" -w secret -e delete,rdn='uid:[INCRNNOLOOP(0;99999;5)]',object="inet.txt" -I 32 -v -q

The last delete operation format is much like the random delete format, only it moves sequentially through the given range, rather than randomly:

-e delete,incr
-r and -R for the range bounds
-f for the filter to match the entries

Example A.14. Sequential Delete Operations

# ldclt -b "ou=people,dc=example,dc=com" -D "cn=Directory Manager" -w secret -e delete,incr -r0 -R99999 -f "uid=XXXXXX" -I 32 -v -q

A.1.5.7. Bind Operations

By default, each ldclt thread binds once to the server and then runs all of its operations in a single session. The -e bindeach can be used with any other operation to instruct the ldclt tool to bind for each operation and then unbind before initiating the next operation.

-e add,bindeach ...

To test only bind and unbind operations, use the -e bindeach,bindonly execution parameters and no other operation information. For example:

# ldclt -h localhost -p 389 -b "ou=people,dc=example,dc=com" -e bindeach,bindonly -e bind_info

The bind operation can specify a single user to use for testing by using the -D and -w user name-password pair in the connection parameters.

Note

Use the -e close option with the bind parameters to test the affect that dropping connections has on the Directory Server, instead of unbinding cleanly.

Example A.15. Bind Only and Close Tests

# ldclt -h localhost -p 389 -D "cn=Directory Manager" -w secret -e bindeach,bindonly,close

There are also execution parameters which can be used to select a random bind identity from a given file (randombinddnfromfile) or using a DN selected randomly from within a range (-e randombinddn,randombinddnlow=X,randombinddnhigh=Y).

Example A.16. Random Binds from Identities in a File

# ldclt -h localhost -p 389 -e bindeach,bindonly -e randombinddnfromfile=/tmp/testbind.txt

Binding with a random identity is useful if identities have been added from a generated LDIF or using -e add, where the accounts were added in a range. The ldclt tool can autogenerate values using X as a variable and incrementing through the specified range.

Example A.17. Random Binds from Random Base DN

# ldclt -h localhost -p 389 -e bindeach,bindonly -D "uid=XXXXX,dc=example,dc=com" -w testXXXXX -e randombinddn,randombinddnlow=0,randombinddnhigh=99999

A.1.5.8. Running Operations on Random Base DNs

Any operation can be run against randomly-selected base DNs. The trio of randombase parameters set the range of organizational units to select from. A variable in the -b base entry sets the format of the base DN.

-b "ou=DeptXXX,dc=example,dc=com" -e randombase,randombaselow=0,randombasehigh=999 ...

A.1.5.9. TLS Authentication

Every operation can be run over TLS to test secure authentication and performance for secure connections. There are two parameters required for TLS authentication.

The connection parameters, -Z, which gives the path to the security databases for the Directory Server
The execution parameters, cltcertname, keydbfile, and keydbpin, which contains the information that the server will prompt to access the TLS databases

For example, this runs bind tests over TLS:

# ldclt -h host -p port -e bindeach,bindonly -Z certPath -e cltcertname=certName,keydbfile=filename,keydbpin=password

A.1.5.10. Abandon Operations

The -e abandon parameter opens and then cancels operations on the server. This can be run by itself or with other types of operations (like -e add or -e esearch).

# ldclt -e abandon -h localhost -p 389 -D "cn=Directory Manager" -w secret -v -q -b "ou=people,dc=example,dc=com"

A.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 Red Hat Directory Server Performance Tuning Guide).

The rsearch utility is located in the /usr/bin directory.

A.2.1. Syntax

rsearch-Dbind_dn-wpassword-ssuffix-ffilter-hhost-pport-Sscope-b-u-L-N-v-y-q-l-m-M-d-c-ifile_for_filters-BDN_or_uid_file-Aattributes-afile_of_attributes-n-osearch_time_limits-jsample_interval-tthreads-Ttimelimit-V-Cnumber_of_samples-Rreconnect_interval-x-Wpassword-Utext-\? or -H

A.2.2. Options

Table A.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: [literal,subs="+quotes,verbatim"] …. 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): [literal,subs="+quotes,verbatim"] …. DN: dn UID: uid … …. The UID files simple has one UID per line: [literal,subs="+quotes,verbatim"] …. 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: [literal,subs="+quotes,verbatim"] …. 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.

A.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 ""

A.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 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.

A.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:

# 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)

A.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 A.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 is 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 A.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 filter_file option is required if you use the %s variable in the -f filter option.

A.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 A.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 does not have any bind credentials to use to connect to the server. This initiates an anonymous bind.

Example A.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 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

A.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 is not used, then there is only one bind operation, and the test shows the average of all modify operations that are run.

Example A.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 is not indexed before running the test.

Example A.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 is not indexed, so make sure that the attribute is indexed before running the test.

A.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 A.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.

A.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 A.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
...

A.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 A.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 A.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 A.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.

A.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 A.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 filter_file option is required if you use the %s variable in the -f filter option.

Example A.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 A.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 A.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.

A.2.3.10. Performing Multi-Threaded Testing

Example A.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.

^[3] As with the add operation, the first time that the parent is referenced by the tool, the parent entry is created, but the entry which prompted the add operation is not created.

Select Your Language

Infrastructure and Management

Cloud Computing

Storage

Runtimes

Integration and Automation

Appendix A. Testing Scripts Available with Directory Server

A.1. ldclt (Load Stress Tests)

A.1.1. Syntax

A.1.2. ldclt Options

A.1.3. Results from ldclt

A.1.4. Exiting ldclt and ldclt Exit Codes

A.1.5. Usage Scenarios

A.1.5.1. Generating LDIFs

A.1.5.2. Adding Entries

A.1.5.3. Search Operations

A.1.5.4. Modify Operations

A.1.5.5. modrdn Operations

A.1.5.6. Delete Operations

A.1.5.7. Bind Operations

A.1.5.8. Running Operations on Random Base DNs

A.1.5.9. TLS Authentication

A.1.5.10. Abandon Operations

A.2. rsearch (Search Stress Tests)

A.2.1. Syntax

A.2.2. Options

A.2.3. Usage Scenarios

A.2.3.1. Allowed Configuration Files

A.2.3.2. Results from rsearch

A.2.3.3. Search Testing

A.2.3.4. Authentication Testing

A.2.3.5. Modify Operation Testing

A.2.3.6. Compare Operation Testing

A.2.3.7. Delete Operation Testing

A.2.3.8. Changing Time Limits

A.2.3.9. Bind Testing with Any Operation

A.2.3.10. Performing Multi-Threaded Testing

Language and Page Formatting Options

Appendix A. Testing Scripts Available with Directory Server

A.1. ldclt (Load Stress Tests)

A.1.1. Syntax

A.1.2. ldclt Options

A.1.3. Results from ldclt

A.1.4. Exiting ldclt and ldclt Exit Codes

A.1.5. Usage Scenarios

A.1.5.1. Generating LDIFs

A.1.5.2. Adding Entries

A.1.5.3. Search Operations

A.1.5.4. Modify Operations

A.1.5.5. modrdn Operations

A.1.5.6. Delete Operations

A.1.5.7. Bind Operations

A.1.5.8. Running Operations on Random Base DNs

A.1.5.9. TLS Authentication

A.1.5.10. Abandon Operations

A.2. rsearch (Search Stress Tests)

A.2.1. Syntax

A.2.2. Options

A.2.3. Usage Scenarios

A.2.3.1. Allowed Configuration Files

A.2.3.2. Results from rsearch

A.2.3.3. Search Testing

A.2.3.4. Authentication Testing

A.2.3.5. Modify Operation Testing

A.2.3.6. Compare Operation Testing

A.2.3.7. Delete Operation Testing

A.2.3.8. Changing Time Limits

A.2.3.9. Bind Testing with Any Operation

A.2.3.10. Performing Multi-Threaded Testing