ldap performance tools user’s guide · 4 using the ldap performance tools the ldap performance...

36
LDAP Performance Tools User’s Guide Release 2.0 July 2014

Upload: vandat

Post on 07-Nov-2018

266 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

LDAP Performance Tools User’s Guide

Release 2.0

July 2014

Page 2: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

LDAP Performance Tools User's Guide Release 2.0

Copyright © 2014, Oracle and/or its affiliates. All rights reserved.This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

LDAP Performance Tools User’s Guide 1.0 Page 2

Page 3: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

IntroductionThe LDAP Performance Tools package provides utilities to help you evaluate the performance of an LDAP server.

This User's Guide includes installation, requirements and a description of the different utilities contained in the package. The guide contains the following sections:

“ 1 Before You Install ”

“2 Installing the LDAP Performance Tools ”

“ 3 Removing the LDAP Performance Tools Software ”

“ 4 Using the LDAP Performance Tools ”

1 Before You Install• The LDAP Performance Tools is provided as a ZIP compressed archive file. You must have a

utility to unzip the file.

• Java SE 6 (or a later version) must already be installed on the machine where you want to run the tools. If you do not have Java installed in your system, you can download it at the following location: http://www.oracle.com/technetwork/java/javase/downloads/index.htmlFollow the installation procedure described in the link above to install Java.

2 Installing the LDAP Performance ToolsTo install the LDAP Performance Tools, download the ZIP file with the tools and uncompress it by running an unzip utility in the directory where you want the tools to be installed. After uncompressing the file, the directory LDAPPerfTools will be created.

3 Removing the LDAP Performance Tools SoftwareTo remove the LDAP Performance Tools software from your system, you must delete the directory LDAPPerfTools from the directory where the tools were installed.

LDAP Performance Tools User’s Guide 1.0 Page 3

Page 4: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

4 Using the LDAP Performance ToolsThe LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate. Each of these utilities enables you to test the performance of your LDAP server for a given LDAP operation.

You can launch the tools separately to see how your LDAP server behaves for each operation. Since in real-life scenarios the servers must handle different type of operations simultaneously, you can also launch the tools in parallel. This can help you to determine whether the LDAP server behaves as expected when it must handle multiple operations in a mixed load.

This section contains the following subsections:

“ 4.1 Locating the Tools ”

“ 4.2 Executing the Tools ”

“ 4.3 addrate ”

“ 4.4 authrate ”

“ 4.5 delrate ”

“ 4.6 modrate ”

“ 4.7 searchrate ”

“ 4.8 Mixed Operation Load Examples ”

“ 4.9 The LDIF Template File ”

“ 4.10 The Format String and --argument Options ”

4.1 Locating the ToolsThe following directories are contained in the LDAPPerfTools directory where you installed the tools:

• The bat directory contains the Windows batch files that must be used on Windows systems. Each batch file launches one of the utilities in the package.

• The bin directory contains the UNIX script files that must be used on UNIX systems. Each script file launches one of the utilities in the package.

4.2 Executing the ToolsThe utilities in the LDAP Performance Package utilities are command-line tools. The tools will look for the default Java installed on your system. Alternatively, you can specify the Java installation to be used by setting the environment variable JAVA_HOME.

LDAP Performance Tools User’s Guide 1.0 Page 4

Page 5: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

For example in a UNIX system with JDK7 installed:$ export JAVA_HOME=/usr/lib/jvm/jdk7$ cd <Directory where zip file was uncompressed>$ LDAPPerfTools/bin/modrate –help[ Usage of the utility modrate is displayed in the terminal]

4.3 addrateUse the addrate utility when you want to measure the add throughput and the response time of a directory service.

You must specify the host name, port number, and credentials to be used to connect to the server you want to test. You must also provide a template LDIF file which describes the entries to be added. The template LDIF must contain a value that specifies how the template file parameter values will be generated.

For a more detailed explanation of the format and syntax of the contents of the template file and how to use it with the –-argument option, see sections “4.9 The LDIF Template File “ and “ 4.10 The Format String and --argument Options .”

4.3.1 addrate ExampleThe following example uses the addrate utility to return performance information for the add operation:bin/addrate --hostName "localhost:1389" --bindDN "cn=directory manager" --bindPasswordFile /tmp/password.txt --templateFile /tmp/templateLDIF.ldif --argument "inc(/tmp/cns.txt)" --argument "randstr(30,[A-Z][a-z][0-9]();-)" --numConnections 1 –-noRebind --percentile 99.5

In this example:

• The server is in the local machine and its port is 1389 (--hostName "localhost:1389").

• The tool will use one connection that will be kept opened and will not rebind (--numConnections 1 --noRebind).

• The tool will display the response time for a percentile of 99.5% (--percentile 99.5). This means that 99.5 % of the operations have a response time below the displayed value.

• The tool will generate entries of type person with a random password of 30 characters, and the cn values that are included in a file. To achieve this, the files /tmp/templateLDIF.ldif and /tmp/cns.txt must exist.

Contents of example /tmp/templateLDIF.ldif:dn: cn=name - %1$s,ou=People,dc=example,dc=comobjectClass: personobjectClass: topcn: name - %1$ssn: surname - %1$suserPassword: %2$s

LDAP Performance Tools User’s Guide 1.0 Page 5

Page 6: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

Contents of example /tmp/cns.txt:Aaccf AmarAarika AtpcoAaron Atrc[Contents of the file with more cn values...]

For a more detailed explanation of the format and syntax of the contents of the template file and how to use it with the --argument option, see sections “ 4.9 The LDIF Template File ” and “4.10 TheFormat String and --argument Options.”

In this example, addrate will generate entries using the contents of the template file. The two parameters defined in the template file are provided using the --argument option. The first parameter is used in three different attributes of the entry.

To retrieve the value of the first parameter, the tool will use the consecutive, incremental line of the file /tmp/cns.txt (--argument "inc({/tmp/cns.txt)").

To retrieve the value of the second parameter, the tool will generate a random string of 30 alphanumerical characters with some special characters also allowed (--argument randstr "(30,[A-Z][a-z][0-9]+;-)")

Calling addrate with the options specified in Example 4.2.1-1, the directory server will try to add entries like the following ones:dn: cn=name - Aaccf Amar,ou=People,dc=example,dc=comobjectClass: personobjectClass: topcn: name - Aaccf Amarsn: surname - Aaccf AmaruserPassword: RB02vsnr62hnsfvGPcbsHogSnf6y9x

dn: cn=name - Aarika Atpco,ou=People,dc=example,dc=comobjectClass: personobjectClass: topcn: name - Aarika Atpcosn: surname - Aarika AtpcouserPassword: sgIsSgJsPAsyCstrM5tckjbEzwwvQB

The command output is displayed in a table. The Throughput section indicates the last number of operations per second, and the average number of operations per second since the tool was launched. The Response Time section indicates the most recent response time, the average response time, and the maximum response times for 99.5% of the requests. You can also see the number of errors per second.------------------------------------------------ Throughput Response Time (ops/second) (milliseconds) recent average recent average 99.5% err/sec------------------------------------------------ 577.3 500.5 0.836 0.981 6.851 0.0 668.3 556.5 0.764 0.894 6.682 0.0 588.9 564.6 0.738 0.853 6.535 0.0 797.9 611.3 0.675 0.807 6.461 0.0

LDAP Performance Tools User’s Guide 1.0 Page 6

Page 7: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

Note - In this example /tmp/cnx.txt must have enough values to be able to run the command-line as long as it is intended to, without starting to generate duplicate entries. When the processing is finished, addrate --argument "inc(/tmp/cns.txt)" will start from the beginning of the file again.

4.3.2 addrate UsageThis utility can be used to measure add throughput and response time of adirectory service using template-defined entry data

Usage: addrate {options}

Where {options} include:

-A, --asynchronous Use asynchronous mode and don't wait for results before sending the next request-c, --numConnections {numConnections} Number of connections per target host Default value: 1-e, --percentile {percentile} Calculate max response time for a percentile of operations Default value: 0-f, --keepConnectionsOpen Keep connections open-F, --noRebind Keep connections open and don't rebind-g, --argument {generator function or static string} Argument used to evaluate the Java style format strings in the file provided with the --templateFile option. The set of all arguments provided form the argument list in order. Besides static string arguments, they can be generated per iteration with the following functions: "inc({filename})" Consecutive, incremental line from file "inc({min},{max})" Consecutive, incremental number "rand({filename})" Random line from file "rand({min},{max})" Random number "randstr({length},<charSet>)" Random string of specified length and optionally from characters in the charSet string. A range of character can be specified with [start-end] charSet notation. If no charSet is specified, the default charSet of [A-Z][a-z][0-9] will be used-i, --statInterval {statInterval} Display results each specified number of seconds Default value: 5-l, --templateFile {file} The path to the template file containing LDIF entry template along with Java style format string syntax specifying generated data formatting as in 'dn: uid=user.%d,ou=people,dc=example,dc=com'-m, --maxIterations {maxIterations} Max iterations, 0 for unlimited Default value: 0-M, --targetThroughput {targetThroughput} Target average throughput to achieve Default value: 0

LDAP Performance Tools User’s Guide 1.0 Page 7

Page 8: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

-S, --scriptFriendly Use script-friendly mode-t, --numThreads {numThreads} Number of worker threads per connection Default value: 1

LDAP Connection Options

-D, --bindDN {bindDN} DN to use to bind to the server Default value: cn=Directory Manager-E, --reportAuthzID Use the authorization identity control-h, --hostname {host} Directory server hostname:port. Multiple servers may be specified Default value: Borrero.local-j, --bindPasswordFile {bindPasswordFile} Bind password file-K, --keyStorePath {keyStorePath} Certificate key store path-N, --certNickname {nickname} Nickname of certificate for SSL client authentication-o, --saslOption {name=value} SASL bind options-P, --trustStorePath {trustStorePath} Certificate trust store path-q, --useStartTLS Use StartTLS to secure communication with the server-T, --trustStorePassword {trustStorePassword} Certificate trust store PIN-u, --keyStorePasswordFile {keyStorePasswordFile} Certificate key store PIN file-U, --trustStorePasswordFile {path} Certificate trust store PIN file--usePasswordPolicyControl Use the password policy request control-w, --bindPassword {bindPassword} Password to use to bind to the server-W, --keyStorePassword {keyStorePassword} Certificate key store PIN-X, --trustAll Trust all server SSL certificates-Z, --useSSL Use SSL for secure communication with the server

Utility Input/Output Options

--noPropertiesFile No properties file will be used to get default command line argument values--propertiesFilePath {propertiesFilePath} Path to the file containing default property values used for command line arguments-v, --verbose Use verbose mode

LDAP Performance Tools User’s Guide 1.0 Page 8

Page 9: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

General Options

-V, --version Display version information-?, -H, --help Display this usage information

4.4 authrateUse the authrate utility when you want to measure the bind throughput and the response time of a directory service using user-defined bind or search-then-bind operations.

You must specify the host name, port number, and credentials to be used to connect to the server you want to test. The value of --bindDN can be parametrized using the Java format String to be able to bind using different DNs.

The authrate utility also enables you to do performance testing in a particular use case that might not be of interest for most users. It enables you to execute a search that returns an entry whose DN will be used to perform a bind through a search-then-bind operation. To execute this search-then-bind operation you can specify the base DN to be used to do the search, the scope of the search, and its filter. Both the filter and the base DN can use parameters using the Java format String syntax. The values of these parameters are specified using the --argument option. To pass the DN returned by the search, and to do the bind, use --bindDN '%2$s'.

Note – The search request must only retrieve one entry. If any entries are retrieved, the search will fail.

For a more detailed explanation of the Java format syntax for the filter, --bindDN and --baseDN options about how to use them with the --argument option, see section 4.9 The LDIF Template File .

For more information about the syntax of the LDAP filter, see section 4.10 The Format String and --argument Options .

4.4.1 authrate Example 1In this example, the authrate utility is used to return bind performance information:bin/authrate --hostName localhost:1389 --bindDN '%s' --bindPassword password --argument "rand(/tmp/binddns.txt)" --numConnections 2 --targetThroughput 500 --invalidPassword 20

In this example:

• The server is in the local machine and its port is 1389 (--hostName "localhost:1389").

• The tool will use two connections (--numConnections 2).

• The tool will have a target throughput of 500 binds/second (--targetThroughput 500). If the tool determines that the directory server is performing above this number, the tool will restrict the number of binds per second. This is particularly useful when you want to see how the server performs under a certain operation load with a mix of operations.

LDAP Performance Tools User’s Guide 1.0 Page 9

Page 10: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

• The tool will bind using random bind DN values from a file. In this example, the tool uses --bindDN '%s', whose parameter value is provided by --argument "rand(/tmp/binddns.txt)". Assume that a file /tmp/binddns.txt exists and contains the DNs of the entries that you can use to bind to the server.

The following are DN examples:cn=directory managercn=myuser,ou=People,dc=example,dc=comcn=myuser2,ou=People,dc=example,dc=com[…]

Note - In this example, if the last line of the /tmp/binddns.txt is empty, the file will be used to bind as anonymous. If you do not want to bind as anonymous, do not add an empty line to the end of the /tmp/binddns.txt file.

The authrate tool will simulate 20 percent of invalid credential errors (--invalidPassword 20). For the percentage of invalid bindings to be exactly 20, all the DNs in /tmp/binddns.txt must have as associated password “password”.

The tool will try to bind using the password “password” with all the bind DNs (--bindPassword password).

The command output is displayed in a table. The Throughput section indicates the last number of operations per second, and the average number of operations per second since the tool was launched. The Response Time section indicates the most recent response time, the average response time, and the maximum response times for three different percentiles ( 99.9, 99.99 and 99.999 % of the requests). You can also see the number of errors per second.----------------------------------------------------------------- Throughput Response Time (ops/second) (milliseconds) recent average recent average 99.9% 99.99% 99.999% err/sec----------------------------------------------------------------- 505.3 508.8 0.820 0.820 11.365 83.416 83.416 102.8 500.8 504.8 0.817 0.818 8.305 83.416 83.416 102.6 499.2 502.9 0.736 0.791 12.399 83.416 83.416 104.0 499.0 501.9 0.703 0.769 11.365 18.568 83.416 101.7 500.3 501.6 0.679 0.751 12.399 54.889 83.416 100.5 499.1 501.2 0.506 0.710 12.390 54.889 83.416 106.4

The results in this table indicate that the errors per second are 20 % of the total throughput. The total throughput is limited to 500 operations per second.

4.4.2 authrate Example 2

In this example, the authrate utility is used to determine the bind performance on an entry by executing a search-then-bind operation:bin/authrate --hostName "localhost:1389" --bindDN '%2$s' --bindPassword password --baseDN 'uid=user.%1$d,ou=People,dc=example,dc=com' --argument "inc(1,100)" --searchScope base "objectclass=*"

LDAP Performance Tools User’s Guide 1.0 Page 10

Page 11: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

In this example:

• Before executing the bind, the LDAP server must provide anonymous access in order to retrieve the DNs that will be used to bind. See section “ 4.4.3 Configuring Anonymous Access “ for more information.

• The server is in the local machine and its port is 1389 (--hostName "localhost:1389")

• The server contains users with DNs of type (in the example we assume that we have 100 of them):

uid=user.0,ou=People,dc=example,dc=comuid=user.1,ou=People,dc=example,dc=comuid=user.2,ou=People,dc=example,dc=com[…]

• All the users above have a password of value “password”.

• The authrate tool will search for the entries where the parameter value is provided by --argument "inc(1,100)"). The parameter value is incremental from 1 to 100, based on the assumption that there are 100 entries that will be used to bind.

• The scope of the search will be base (--searchScope base) and the filter objectclass=*.

• The result of the search will be used finally to bind (--bindDN '%2$s').

The command output is displayed in a table. The Throughput section indicates the last number of operations per second, and the average number of operations per second since the tool was launched. The Response Time section indicates the most recent response time, the average response time, and the maximum response times for three different percentiles ( 99.9, 99.99 and 99.999 % of the requests). The table also indicates the last number of search + bind operations per second. You can also see the number of errors per second, and the percentage of time spent doing the bind compared to the total time.------------------------------------------------------------------------------ Throughput Response Time (ops/second) (milliseconds) recent average recent average 99.9% 99.99% 99.999% err/sec bind time %------------------------------------------------------------------------------ 794.6 799.1 1.213 1.213 32.502 77.596 77.596 0.0 42.61074.4 938.0 0.856 1.006 22.165 77.596 77.596 0.0 44.31331.5 1069.4 0.697 0.878 18.213 61.514 77.596 0.0 43.81599.0 1201.7 0.607 0.788 13.524 61.514 102.622 0.0 42.71589.7 1279.2 0.611 0.744 11.643 50.274 102.622 0.0 43.71669.6 1344.2 0.581 0.710 10.142 34.591 102.622 0.0 43.51664.1 1389.9 0.584 0.689 9.419 34.591 102.622 0.0 42.81687.1 1427.1 0.576 0.672 8.663 32.502 102.622 0.0 43.71649.9 1451.8 0.588 0.661 8.019 31.726 102.622 0.0 44.01596.0 1466.3 0.607 0.655 7.811 31.726 102.622 0.0 44.21708.3 1488.3 0.569 0.646 7.565 30.801 102.622 0.0 43.91678.5 1504.1 0.579 0.640 7.029 28.616 102.622 0.0 43.71673.7 1517.2 0.580 0.635 6.707 28.616 102.622 0.0 44.21563.4 1520.5 0.621 0.634 6.402 26.609 77.596 0.0 43.61641.9 1528.6 0.591 0.631 6.331 24.100 77.596 0.0 43.71627.6 1534.8 0.596 0.629 6.154 22.179 77.596 0.0 43.41701.2 1544.6 0.570 0.625 6.006 22.165 77.596 0.0 43.9

LDAP Performance Tools User’s Guide 1.0 Page 11

Page 12: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

4.4.3 Configuring Anonymous AccessWhen you use the Oracle Unified Directory server, you can configure anonymous access by adding the following global ACI:(targetattr!="userPassword||authPassword")(version 3.0; acl "Anonymous read access"; allow (read,search,compare) userdn="ldap:///anyone";)

You can add the global ACI by running the following command:bin/dsconfig set-access-control-handler-prop \--add global-aci:\(targetattr!=\"userPassword\|\|authPassword\"\)\(version\3.0\;\ acl\ \"Anonymous\ read\ access\"\;\ allow\ \(read,search,compare\)\userdn=\"ldap:///anyone\"\;\) \ --hostname Borrero.localhost \ --port 4444 \ --trustAll \ --bindDN cn=Directory\ Manager \ --bindPasswordFile ****** \ --no-prompt

Note – If you are not fully aware of the consequences of adding the global ACI, do it only in the context of performance testing.

For more information, see “Defining Anonymous Access” in the Oracle® Fusion Middleware Administrator's Guide for Oracle Unified Directory

4.4.4 authrate UsageThis utility can be used to measure bind throughput and response time of adirectory service using user-defined bind or search-then-bind operations.Format strings may be used in the bind DN option as well as the authid andauthzid SASL bind options. A search operation may be used to retrieve the bindDN by specifying the base DN and a filter. The retrieved entry DN will beappended as the last argument in the argument list when evaluating formatstrings. For example, to measure simple bind performance using the retrieveduser DN as the bind DN: authrate -D '%2$s' -p password -b "dc=example,dc=com"-g 'rand(0,10000)' '(user=user.%1$d)'

Usage: authrate {options} [filter format string] [attributes ...]

Where {options} include:

-a, --dereferencePolicy {dereferencePolicy} Alias dereference policy ('never', 'always', 'search', or 'find') Default value: never-b, --baseDN {baseDN} Base DN format string.-c, --numConnections {numConnections} Number of connections per target host Default value: 1-e, --percentile {percentile} Calculate max response time for a percentile of operations Default value: 0

LDAP Performance Tools User’s Guide 1.0 Page 12

Page 13: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

-f, --keepConnectionsOpen Keep connections open-g, --argument {generator function or static string} Argument used to evaluate the Java style format strings (ie. the values for --baseDN, --bindDN and the Search Filter). The set of all arguments provided form the argument list in order. Besides static string arguments, they can be generated per iteration with the following functions: "inc({filename})" Consecutive, incremental line from file "inc({min},{max})" Consecutive, incremental number "rand({filename})" Random line from file "rand({min},{max})" Random number "randstr({length},<charSet>)" Random string of specified length and optionally from characters in the charSet string. A range of character can be specified with [start-end] charSet notation. If no charSet is specified, the default charSet of [A-Z][a-z][0-9] will be used-i, --statInterval {statInterval} Display results each specified number of seconds Default value: 5-I, --invalidPassword {invalidPassword} Percent of bind operations with simulated invalid password Default value: 0-m, --maxIterations {maxIterations} Max iterations, 0 for unlimited Default value: 0-M, --targetThroughput {targetThroughput} Target average throughput to achieve Default value: 0-s, --searchScope {searchScope} Search scope ('base', 'one', 'sub', or 'subordinate') Default value: sub-S, --scriptFriendly Use script-friendly mode

LDAP Connection Options

-D, --bindDN {bindDN} DN to use to bind to the server Default value: cn=Directory Manager-E, --reportAuthzID Use the authorization identity control-h, --hostname {host} Directory server hostname:port. Multiple servers may be specified Default value: Borrero.local-j, --bindPasswordFile {bindPasswordFile} Bind password file-K, --keyStorePath {keyStorePath} Certificate key store path-N, --certNickname {nickname} Nickname of certificate for SSL client authentication-o, --saslOption {name=value} SASL bind options-P, --trustStorePath {trustStorePath} Certificate trust store path-q, --useStartTLS

LDAP Performance Tools User’s Guide 1.0 Page 13

Page 14: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

Use StartTLS to secure communication with the server-T, --trustStorePassword {trustStorePassword} Certificate trust store PIN-u, --keyStorePasswordFile {keyStorePasswordFile} Certificate key store PIN file-U, --trustStorePasswordFile {path} Certificate trust store PIN file--usePasswordPolicyControl Use the password policy request control-w, --bindPassword {bindPassword} Password to use to bind to the server-W, --keyStorePassword {keyStorePassword} Certificate key store PIN-X, --trustAll Trust all server SSL certificates-Z, --useSSL Use SSL for secure communication with the server

Utility Input/Output Options

--noPropertiesFile No properties file will be used to get default command line argument values--propertiesFilePath {propertiesFilePath} Path to the file containing default property values used for command line arguments-v, --verbose Use verbose mode

General Options

-V, --version Display version information-?, -H, --help Display this usage information

4.5 delrateUse the delrate utility when you want to measure the delete operation throughput and the response time of a directory service.

You must specify the host name, port number, and credentials to be used to connect to the server you want to test. To specify the entries to be deleted, use the --targetDN option. The --targetDN option can be parametrized using the Java format String to be able to bind using different DNs.

For a more detailed explanation of the Java format syntax for the --targetDN option and about how to use them with the --argument option, see section “ 4.10 The Format String and --argument Options .”

LDAP Performance Tools User’s Guide 1.0 Page 14

Page 15: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

4.5.1 delrate ExampleIn this example, the delrate utility returns delete performance information: bin/delrate --hostName "localhost:1389" --bindDN "cn=directory manager" --bindPassword password --asynchronous --noRebind --numConnections 4 --numThreads 5 --scriptFriendly --percentile 99 --targetDN 'uid=user.%1$d,ou=People,dc=example,dc=com' --argument "inc(1,1000000)"

In this example:

• The server is in the local machine and its port is 1389 (--hostName "localhost:1389").

• The delete operation is executed asynchronously, without waiting for the previous operation to complete ( --asynchronous).

• The connections are kept open (--noRebind).

• Four connections and five threads per connection are used (--numConnections 4 --numThreads 5).

• The script-friendly mode displays the results (--scriptFriendly).

• The maximum response-time is displayed in milliseconds for 99 % of the operations (--percentile 99).

• The entries to be deleted have a similar DN, and you can generate its DN by incrementing an integer. (--targetDN 'uid=user.%1$d,ou=People,dc=example,dc=com' --argument "inc(1,1000000)").

The command output is displayed in a table. The Throughput section indicates the last number of operations per second, and the average number of operations per second since the tool was launched. The Response Time section indicates the most recent response time, the average response time, and the maximum response times for three different percentiles ( 99.9, 99.99 and 99.999 % of the requests). You can also see the number of errors per second.------------------------------------------------------------------------------ Throughput Response Time (ops/second) (milliseconds) recent average recent average 99.9% 99.99% 99.999% err/sec ------------------------------------------------------------------------------ 4.674 520.4 547.5 29337.140 29337.140 44678.042 448.9 23.1 9.699 107.3 319.4 36241.147 30538.322 49542.340 100.5 1.914.7 55.6 229.7 39076.178 31241.380 54450.929 49.2 1.219.702 32.2 179.5 41195.570 31694.483 56929.337 26.4 0.024.794 12.4 145.2 47853.490 31977.265 62027.241 9.4 0.029.794 2.4 121.2 36480.910 31992.227 62027.326 0.2 0.034.796 19.4 106.6 58436.692 32683.819 73087.025 15.8 0.039.797 23.0 96.1 62083.373 33567.958 76759.294 20.2 2.944.798 13.4 86.9 59918.592 34021.696 78779.626 6.8 0.049.72 228.4 100.9 69442.135 41960.394 86418.573 223.5 0.954.721 101.6 100.9 70820.392 44614.908 92342.119 96.0 0.759.722 19.0 94.1 80780.197 45226.461 94650.346 13.0 3.5

LDAP Performance Tools User’s Guide 1.0 Page 15

Page 16: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

Note – In this example, there are number of errors per second which are non-zero. This is because several connections are open, and each thread of each connection has its own incremental counter. This means that all the threads will try to delete the same DNs, which results in only one thread of one connection being able to delete successfully the entries. To prevent this from happening, you can launch the following command which uses just one connection and five threads:bin/delrate --hostName "localhost:1389" --bindDN "cn=directory manager" --bindPassword password --asynchronous --noRebind --numConnections 1 --numThreads 1 --percentile 99 --targetDN 'uid=user.%1$d,ou=People,dc=example,dc=com' --argument "inc(1,1000000)"

The command output is displayed in a table. The Throughput section indicates the last number of operations per second, and the average number of operations per second since the tool was launched. The Response Time section indicates the most recent response time, the average response time, and the maximum response times 99.0 % of the requests. The number of errors per second and number of requests per response are also displayed.

------------------------------------------------------------------- Throughput Response Time (ops/second) (milliseconds) recent average recent average 99.0% err/sec req/res------------------------------------------------------------------- 12.6 46.6 7339.066 1344.388 9441.857 0.0 0.0 14.8 36.0 12339.707 2862.398 14445.807 0.0 0.0 15.5 30.8 17408.386 4710.260 19321.755 0.0 0.0 14.8 27.6 22363.101 6608.967 24222.852 0.0 0.0 13.8 25.3 27058.777 8472.952 29274.415 0.0 0.0 11.4 23.3 32199.378 10134.385 33868.163 0.0 0.0 11.8 21.9 37189.320 11962.840 38907.944 0.0 0.0 12.0 20.8 42174.075 13905.684 43821.941 0.0 0.0 12.6 19.9 47176.591 16010.169 48839.347 0.0 0.0 11.4 19.2 52357.887 17977.710 53921.002 0.0 0.0 12.8 18.6 57038.351 20215.741 58888.600 0.0 0.0

4.5.2 delrate UsageThis utility can be used to measure delete throughput and response time of adirectory service.

Usage: delrate {options}

Where {options} include:

-A, --asynchronous Use asynchronous mode and don't wait for results before sending the next request-b, --targetDN {targetDN} Target entry DN format string-c, --numConnections {numConnections} Number of connections per target host Default value: 1-e, --percentile {percentile}

LDAP Performance Tools User’s Guide 1.0 Page 16

Page 17: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

Calculate max response time for a percentile of operations Default value: 0-f, --keepConnectionsOpen Keep connections open-F, --noRebind Keep connections open and don't rebind-g, --argument {generator function or static string} Argument used to evaluate the Java style format string of the value for --targetDN. The set of all arguments provided form the argument list in order. Besides static string arguments, they can be generated per iteration with the following functions: "inc({filename})" Consecutive, incremental line from file "inc({min},{max})" Consecutive, incremental number "rand({filename})" Random line from file "rand({min},{max})" Random number "randstr({length},<charSet>)" Random string of specified length and optionally from characters in the charSet string. A range of character can be specified with [start-end] charSet notation. If no charSet is specified, the default charSet of [A-Z][a-z][0-9] will be used-i, --statInterval {statInterval} Display results each specified number of seconds Default value: 5-m, --maxIterations {maxIterations} Max iterations, 0 for unlimitedDefault value: 0-M, --targetThroughput {targetThroughput} Target average throughput to achieve Default value: 0-S, --scriptFriendly Use script-friendly mode-t, --numThreads {numThreads} Number of worker threads per connection Default value: 1

LDAP Connection Options

-D, --bindDN {bindDN} DN to use to bind to the server Default value: cn=Directory Manager-E, --reportAuthzID Use the authorization identity control-h, --hostname {host} Directory server hostname:port. Multiple servers may be specified Default value: Borrero.local-j, --bindPasswordFile {bindPasswordFile} Bind password file-K, --keyStorePath {keyStorePath} Certificate key store path-N, --certNickname {nickname} Nickname of certificate for SSL client authentication-o, --saslOption {name=value} SASL bind options-P, --trustStorePath {trustStorePath} Certificate trust store path

LDAP Performance Tools User’s Guide 1.0 Page 17

Page 18: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

-q, --useStartTLS Use StartTLS to secure communication with the server-T, --trustStorePassword {trustStorePassword} Certificate trust store PIN-u, --keyStorePasswordFile {keyStorePasswordFile} Certificate key store PIN file-U, --trustStorePasswordFile {path} Certificate trust store PIN file--usePasswordPolicyControl Use the password policy request control-w, --bindPassword {bindPassword} Password to use to bind to the serverW, --keyStorePassword {keyStorePassword} Certificate key store PIN-X, --trustAll Trust all server SSL certificates-Z, --useSSL Use SSL for secure communication with the server

Utility Input/Output Options

--noPropertiesFile No properties file will be used to get default command line argument values--propertiesFilePath {propertiesFilePath} Path to the file containing default property values used for command line arguments-v, --verbose Use verbose mode

General Options

-V, --version Display version information-?, -H, --help Display this usage information

4.6 modrateUse the modrate utility when you want to measure the modify throughput and the response time of a directory service.

You must specify the host name, port number, and credentials to be used to connect to the server you want to test. You must also describe the modification to be done. This is done by providing the DN to be modified, and the attribute and new value to be used . Both the DN and the <value>:<attribute> pairing can be parametrized using the Java format String. The parameter values are specified using the --attribute option.

For a more detailed explanation of how to use the --argument option with Java format String, see section “ 4.10 The Format String and --argument Options .”

LDAP Performance Tools User’s Guide 1.0 Page 18

Page 19: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

4.6.1 modrate ExampleThis modrate example modifies performance information. bin/modrate --hostName "localhost:1389" --bindDN "cn=directory manager" --bindPassword password --noRebind --numConnections 4 --numThreads 5 --percentile 99 --targetDN 'uid=user.%1$d,ou=People,dc=example,dc=com' --argument "inc(1,1000000)" --argument "randstr(10)" --argument "rand(1000,10000)" 'description:%2$s' 'postalCode:%3$d'

In this example:

• The server is in the local machine and its port is 1389 (--hostName "localhost:1389").

• The connections are kept open (––noRebind).

• Four connections and 5 threads per connection are used (––numConnections 4 ––numThreads 5).

• The maximum response-time is displayed in milliseconds for 99 % of the operations (––percentile 99).

• The entries to be modified have a similar DN. You can generate its DN by incrementing an integer. (––targetDN 'uid=user.%1$d,ou=People,dc=example,dc=com' ––argument "inc(1,1000000)").

• The description is modified by replacing its value with a random string of 10 characters). The postal code is modified by replacing its value with a random number between 1000 and 10000. The corresponding arguments and trailing values are --argument "randstr(10)" --argument "rand(1000,10000)" 'description:%2$s' 'postalCode:%3$d'.

The command output is displayed in a table. The Throughput section indicates the last number of operations per second, and the average number of operations per second since the tool was launched. The Response Time section indicates the most recent response time, the average response time, and the maximum response times for 99.0 % of the requests. The number of errors per second and number of requests per response are also displayed.------------------------------------------------ Throughput Response Time (ops/second) (milliseconds) recent average recent average 99.0% err/sec------------------------------------------------2063.8 2078.3 9.661 9.661 98.895 0.03024.0 2671.8 6.240 7.231 79.460 0.03640.8 2938.0 5.197 6.538 65.456 0.04559.0 3284.9 4.074 5.806 54.851 0.04540.7 3509.4 4.019 5.393 48.724 0.04319.1 3632.2 4.287 5.194 45.357 0.0

4.6.2 modrate UsageThis utility can be used to measure modify throughput and response time of adirectory service using user-defined modifications

LDAP Performance Tools User’s Guide 1.0 Page 19

Page 20: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

Usage: modrate {options} [(attribute:value format string) ...]

Where {options} include:

-A, --asynchronous Use asynchronous mode and don't wait for results before sending the next request-b, --targetDN {targetDN} Target entry DN format string-c, --numConnections {numConnections} Number of connections per target host Default value: 1-e, --percentile {percentile} Calculate max response time for a percentile of operations Default value: 0-f, --keepConnectionsOpen Keep connections open-F, --noRebind Keep connections open and don't rebind-g, --argument {generator function or static string} Argument used to evaluate the Java style format strings (ie. the values for --targetDN and the [attribute:value] pairs). The set of all arguments provided form the argument list in order. Besides static string arguments, they can be generated per iteration with the following functions: "inc({filename})" Consecutive, incremental line from file "inc({min},{max})" Consecutive, incremental number "rand({filename})" Random line from file "rand({min},{max})" Random number "randstr({length},<charSet>)" Random string of specified length and optionally from characters in the charSet string. A range of character can be specified with [start-end] charSet notation. If no charSet is specified, the default charSet of [A-Z][a-z][0-9] will be used-i, --statInterval {statInterval} Display results each specified number of seconds Default value: 5-m, --maxIterations {maxIterations} Max iterations, 0 for unlimited Default value: 0-M, --targetThroughput {targetThroughput} Target average throughput to achieve Default value: 0-S, --scriptFriendly Use script-friendly mode-t, --numThreads {numThreads} Number of worker threads per connection Default value: 1

LDAP Connection Options

-D, --bindDN {bindDN} DN to use to bind to the server Default value: cn=Directory Manager-E, --reportAuthzID

LDAP Performance Tools User’s Guide 1.0 Page 20

Page 21: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

Use the authorization identity control-h, --hostname {host} Directory server hostname:port. Multiple servers may be specified Default value: Borrero.local-j, --bindPasswordFile {bindPasswordFile} Bind password file-K, --keyStorePath {keyStorePath} Certificate key store path-N, --certNickname {nickname} Nickname of certificate for SSL client authentication-o, --saslOption {name=value} SASL bind options-P, --trustStorePath {trustStorePath} Certificate trust store path-q, --useStartTLS Use StartTLS to secure communication with the server-T, --trustStorePassword {trustStorePassword} Certificate trust store PIN-u, --keyStorePasswordFile {keyStorePasswordFile} Certificate key store PIN file-U, --trustStorePasswordFile {path} Certificate trust store PIN file--usePasswordPolicyControl Use the password policy request control-w, --bindPassword {bindPassword} Password to use to bind to the server-W, --keyStorePassword {keyStorePassword} Certificate key store PIN-X, --trustAll Trust all server SSL certificates-Z, --useSSL Use SSL for secure communication with the server

Utility Input/Output Options

--noPropertiesFile No properties file will be used to get default command line argument values--propertiesFilePath {propertiesFilePath} Path to the file containing default property values used for command line arguments-v, --verbose Use verbose mode

General Options

-V, --version Display version information-?, -H, --help Display this usage information

LDAP Performance Tools User’s Guide 1.0 Page 21

Page 22: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

4.7 searchrateUse the searchrate utility to measure the search throughput and the response time of a directory service using user-defined searches.

You must specify the host name, port number, and credentials to be used to connect to the server you want to test. You must also describe the search to be done. This is done by providing the base DN of the search , the scope of the search , the filter of the search, and the arguments to be retrieved by the search (with the trailing arguments) . The base DN and the filter of the search can be parametrized using the Java format String. The parameter values are specified using the –-attribute option.

Important: The -F (--noRebind) option is required if -t (--numThreads) is greater than one. For example, if the –numThreads value is not the default, then the value is probably greater than one.

For a more detailed explanation of how to use the –-argument option with Java format String, see section “ 4.9 The LDIF Template File .”

For reference about the syntax of the search filter, see section “ 4.10 The Format String and --argument Options .”

4.7.1 searchrate ExampleIn this example, the searchrate utilitiy is used to return search performance information:bin/searchrate --hostName "localhost:1636" --useSSL --trustAll --bindDN "cn=directory manager" --bindPassword password --baseDN '%1$s' --argument "dc=example,dc=com" --searchScope sub --argument 'inc(1,10000)' '&(objectclass=person)(uid=user.%2$d)' cn

In this example:

The server is in the local machine and its port is 1636 (--hostName "localhost:1636").• The port is configured to use SSL (--useSSL --trustAll).

• The search will look under the whole subtree of a given base DN (--baseDN '%1$s' --argument "dc=example,dc=com" --searchScope sub).

• The search will look for the person entries with a given UID and will retrieve their common name (--argument 'inc(1,10000)' '&(objectclass=person)(uid=user.%2$d)') cn

LDAP Performance Tools User’s Guide 1.0 Page 22

Page 23: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

The command output is displayed in a table. The Throughput section indicates the last number of operations per second, and the average number of operations per second since the tool was launched. The Response Time section indicates the most recent response time, the average response time, and the maximum response times for three different percentiles ( 99.9, 99.99 and 99.999 % of the requests). The number of errors per second and entries per search are also displayed.

------------------------------------------------------------------------------- Throughput Response Time (ops/second) (milliseconds) recent average recent average 99.9% 99.99% 99.999% err/sec Entries/Srch-------------------------------------------------------------------------------49.3 49.7 1.501 1.501 15.164 15.164 15.164 0.0 1.063.4 56.6 1.263 1.367 15.164 15.164 15.164 0.0 1.066.5 59.9 1.166 1.292 15.164 15.164 15.164 0.0 1.066.6 61.6 1.077 1.234 13.681 15.164 15.164 0.0 1.066.3 62.5 1.068 1.199 15.164 16.376 16.376 0.0 1.071.1 64.0 0.938 1.150 15.164 16.376 16.376 0.0 1.071.1 65.0 0.932 1.116 13.681 16.376 16.376 0.0 1.072.6 65.9 0.890 1.085 13.681 16.376 16.376 0.0 1.072.5 66.7 0.884 1.061 13.681 16.376 16.376 0.0 1.073.0 67.3 0.908 1.044 13.681 23.489 23.489 0.0 1.0

The throughput is significantly low. You can try to see what happens if you do not rebind (--noRebind), and increase the number of connections and threads (--numConnections 4 --numThreads 5) as in this example:bin/searchrate --hostName "localhost:1636" --useSSL --trustAll --bindDN "cn=directory manager" --bindPassword password --noRebind --numConnections 4 --numThreads 5 --baseDN '%1$s' --argument "dc=example,dc=com" --searchScope sub --argument 'inc(1,100)' '&(objectclass=person)(uid=user.%2$d)' cn

LDAP Performance Tools User’s Guide 1.0 Page 23

Page 24: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

The command output is displayed in a table. The Throughput section indicates the last number of operations per second, and the average number of operations per second since the tool was launched. The Response Time section indicates the most recent response time, the average response time, and the maximum response times for three different percentiles ( 99.9, 99.99 and 99.999 % of the requests). The number of errors per second and number of entries per search are also displayed.------------------------------------------------------------------------------- Throughput Response Time (ops/second) (milliseconds) recent average recent average 99.9% 99.99% 99.999% err/sec Entries/Srch-------------------------------------------------------------------------------2012.1 2030.1 9.846 9.846 124.528 163.310 163.310 0.0 1.02632.8 2343.6 7.502 8.476 110.874 152.468 163.310 0.0 1.03362.3 2676.5 5.864 7.404 103.116 146.322 163.310 0.0 1.03613.4 2907.1 5.460 6.809 96.943 145.872 163.310 0.0 1.03538.4 3031.9 5.546 6.518 93.956 137.010 163.310 0.0 1.03493.6 3108.2 5.620 6.351 90.132 136.871 163.310 0.0 1.03572.8 3174.4 5.519 6.217 86.258 136.413 162.370 0.0 1.03380.2 3200.0 5.775 6.159 81.576 126.872 162.370 0.0 1.03346.6 3216.2 5.855 6.124 80.595 125.353 162.370 0.0 1.03369.1 3231.5 5.790 6.089 79.162 124.528 162.370 0.0 1.03312.6 3238.8 5.866 6.069 77.640 124.207 162.370 0.0 1.03477.2 3258.8 5.641 6.030 72.233 119.811 162.370 0.0 1.03638.2 3288.1 5.405 5.977 69.114 119.294 152.468 0.0 1.0

Keeping connections opened and increasing the number of threads can have a huge impact on the throughput performance. This is why the use of connection pools is recommended when possible for LDAP client applications.

4.7.2 searchrate UsageThis utility can be used to measure search throughput and response time of adirectory service using user-defined searches

Usage: searchrate {options} [filter format string] [attributes ...]

Where {options} include:

-a, --dereferencePolicy {dereferencePolicy} Alias dereference policy ('never', 'always', 'search', or 'find') Default value: never-A, --asynchronous Use asynchronous mode and don't wait for results before sending the next request-b, --baseDN {baseDN} Base DN format string.-c, --numConnections {numConnections} Number of connections per target host Default value: 1-e, --percentile {percentile} Calculate max response time for a percentile of operations Default value: 0

LDAP Performance Tools User’s Guide 1.0 Page 24

Page 25: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

-f, --keepConnectionsOpen Keep connections open-F, --noRebind Keep connections open and don't rebind-g, --argument {generator function or static string} Argument used to evaluate the Java style format strings in program parameters (ie. the values for --baseDN and the Search Filter). The set of all arguments provided form the argument list in order. Besides static string arguments, they can be generated per iteration with the following functions: "inc({filename})" Consecutive, incremental line from file "inc({min},{max})" Consecutive, incremental number "rand({filename})" Random line from file "rand({min},{max})" Random number "randstr({length},<charSet>)" Random string of specified length and optionally from characters in the charSet string. A range of character can be specified with [start-end] charSet notation. If no charSet is specified, the default charSet of [A-Z][a-z][0-9] will be used-i, --statInterval {statInterval} Display results each specified number of seconds Default value: 5-m, --maxIterations {maxIterations} Max iterations, 0 for unlimited Default value: 0-M, --targetThroughput {targetThroughput} Target average throughput to achieve Default value: 0-s, --searchScope {searchScope} Search scope ('base', 'one', 'sub', or 'subordinate') Default value: sub-S, --scriptFriendly Use script-friendly mode-t, --numThreads {numThreads} Number of worker threads per connection Default value: 1

LDAP Connection Options

-D, --bindDN {bindDN} DN to use to bind to the server Default value: cn=Directory Manager-E, --reportAuthzID Use the authorization identity control-h, --hostname {host} Directory server hostname:port. Multiple servers may be specified Default value: Borrero.local-j, --bindPasswordFile {bindPasswordFile} Bind password file-K, --keyStorePath {keyStorePath} Certificate key store path-N, --certNickname {nickname} Nickname of certificate for SSL client authentication-o, --saslOption {name=value} SASL bind options

LDAP Performance Tools User’s Guide 1.0 Page 25

Page 26: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

-P, --trustStorePath {trustStorePath} Certificate trust store path-q, --useStartTLS Use StartTLS to secure communication with the server-T, --trustStorePassword {trustStorePassword} Certificate trust store PIN-u, --keyStorePasswordFile {keyStorePasswordFile} Certificate key store PIN file-U, --trustStorePasswordFile {path} Certificate trust store PIN file--usePasswordPolicyControl Use the password policy request control-w, --bindPassword {bindPassword} Password to use to bind to the server-W, --keyStorePassword {keyStorePassword} Certificate key store PIN-X, --trustAll Trust all server SSL certificates-Z, --useSSL Use SSL for secure communication with the server

Utility Input/Output Options

--noPropertiesFile No properties file will be used to get default command line argument values--propertiesFilePath {propertiesFilePath} Path to the file containing default property values used for command line arguments-v, --verbose Use verbose mode

General Options

-V, --version Display version information-?, -H, --help Display this usage information

4.8 Mixed Operation Load ExamplesThe examples in this section illustrate what happens in a server where search, modify, add, and delete operations are executed concurrently. In the Mixed Operation Load examples:

• The argument --targetThroughput is used to limit the throughput for each operation.

• The example is based on the assumption that the server receives requests for 1500 search, 500 modify, 200 add, and 100 delete operations per second.

• The tools will connect to server localhost:1389 (--hostName "localhost:1389").

• The tools have target DN entries with the following type of DN: dn: uid=user.%1$d,ou=%1$s,dc=example,dc=com.

• The tools use a random number between 1 and 100000 to retrieve the target DN.

LDAP Performance Tools User’s Guide 1.0 Page 26

Page 27: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

• Each tool will use one connection and five threads.

4.8.1 Mixed Operation Load Example 1bin/addrate --hostName "localhost:1389" --bindDN "cn=directory manager" --bindPasswordFile /tmp/password.txt --templateFile /tmp/templateLDIF.ldif --argument "rand(1,100000)" --numThreads 5 --targetThroughput 200 –noRebind

In this example, The contents of the example /tmp/templateLDIF.ldif are:dn: uid=user.%1$d,ou=People,dc=example,dc=comobjectClass: personobjectClass: inetorgpersonobjectClass: organizationalpersonobjectClass: topuid: user.%1$dcn: namesn: surname

The command output is displayed in a table. The Throughput section indicates the last number of operations per second, and the average number of operations per second since the tool was launched. The Response Time section indicates the most recent response time, the average response time, and the maximum response times for three different percentiles ( 99.9, 99.99 and 99.999 % of the requests). The number of errors per second is also displayed.----------------------------------------------------------------- Throughput Response Time (ops/second) (milliseconds) recent average recent average 99.9% 99.99% 99.999% err/sec----------------------------------------------------------------- 203.5 204.6 3.432 3.432 99.445 100.489 100.489 29.3 199.7 202.1 1.982 2.712 98.747 100.489 100.489 31.1 200.2 201.5 1.960 2.462 86.862 100.489 100.489 31.7 200.1 201.1 1.753 2.286 71.837 100.489 100.489 32.4 200.2 200.9 1.761 2.181 71.204 100.489 100.489 33.8

LDAP Performance Tools User’s Guide 1.0 Page 27

Page 28: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

4.8.2 Mixed Operation Load Example 2bin/delrate --hostName "localhost:1389" --bindDN "cn=directory manager" --bindPassword password --asynchronous --noRebind --numThreads 5 --targetDN 'uid=user.%1$d,ou=People,dc=example,dc=com' --argument "rand(1,10000)" --targetThroughput 100

The command output is displayed in a table. The Throughput section indicates the last number of operations per second, and the average number of operations per second since the tool was launched. The Response Time section indicates the most recent response time, the average response time, and the maximum response times for three different percentiles ( 99.9, 99.99 and 99.999 % of the requests). The number of errors per second and number of requests per response are also displayed.-------------------------------------------------------------------------- Throughput Response Time (ops/second) (milliseconds) recent average recent average 99.9% 99.99% 99.999% err/sec req/res-------------------------------------------------------------------------- 102.0 102.5 1.489 1.489 17.757 17.757 17.757 92.0 1.0 99.8 101.2 1.343 1.416 12.007 17.757 17.757 86.4 1.0 99.8 100.7 2.373 1.733 83.936 84.607 84.607 81.0 1.0 99.9 100.5 1.956 1.789 66.811 84.607 84.607 39.0 1.0 100.7 100.5 1.992 1.829 66.811 84.607 84.607 40.6 1.0 100.3 100.5 3.205 2.058 83.936 124.248 124.248 40.5 1.0 99.6 100.4 2.463 2.115 83.936 124.248 124.248 37.5 .0

LDAP Performance Tools User’s Guide 1.0 Page 28

Page 29: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

4.8.3 Mixed Load Operation Example 3bin/searchrate --hostName "localhost:1389" --bindDN "cn=directory manager" --bindPassword password --noRebind --numConnections 4 --numThreads 5 --baseDN '%1$s' --argument "dc=example,dc=com" --searchScope sub --argument 'rand(1,100000)' --targetThroughput 1500 '&(objectclass=person)(uid=user.%2$d)' cn

The command output is displayed in a table. The Throughput section indicates the last number of operations per second, and the average number of operations per second since the tool was launched. The Response Time section indicates the most recent response time, the average response time, and the maximum response times for three different percentiles ( 99.9, 99.99 and 99.999 % of the requests). The number of errors per second and number of entries per search are also displayed.------------------------------------------------------------------------------- Throughput Response Time (ops/second) (milliseconds) recent average recent average 99.9% 99.99% 99.999% err/sec Entries/Srch-------------------------------------------------------------------------------1596.2 606.5 3.072 3.072 48.870 57.791 57.791 0.0 1.01501.1 1553.3 1.668 2.387 87.010 108.215 112.051 0.0 1.01501.3 1535.9 0.918 1.907 50.138 108.104 112.051 0.0 0.91500.4 1527.0 0.785 1.632 43.226 108.033 112.051 0.0 0.31498.8 1521.4 0.700 1.448 38.439 108.033 112.051 0.0 0.31502.1 1518.2 0.597 1.308 37.799 106.582 112.051 0.0 0.31500.5 1515.7 0.631 1.212 35.484 105.309 112.051 0.0 0.31499.7 1513.7 0.566 1.132 33.400 100.827 112.051 0.0 0.31499.6 1512.1 0.560 1.069 32.834 100.827 112.051 0.0 0.3

4.8.4 Mixed Operation Load Example 4bin/modrate --hostName "localhost:1389" --biDN "cn=directory manager" --bindPassword password --noRebind --numThreads 5 --percentile 99 --targetDN 'uid=user.%1$d,ou=People,dc=example,dc=com' --argument "rand(1,100000)" --argument "randstr(10)" --argument "rand(1000,10000)" --targetThroughput 500 'description:%2$s' 'postalCode:%3$d'

LDAP Performance Tools User’s Guide 1.0 Page 29

Page 30: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

The command output is displayed in a table. The Throughput section indicates the last number of operations per second, and the average number of operations per second since the tool was launched. The Response Time section indicates the most recent response time, the average response time, and the maximum response times for 99.0 % of the requests. The number of errors per second and number of requests per response are also displayed.

------------------------------------------------ Throughput Response Time (ops/second) (milliseconds) recent average recent average 99.0% err/sec------------------------------------------------ 519.8 523.1 3.012 3.012 20.102 38.1 499.3 511.1 3.266 3.137 26.844 36.4 500.5 507.6 1.958 2.749 21.355 37.7 499.2 505.5 3.929 3.042 27.700 38.7 501.5 504.7 3.193 3.072 32.090 36.0 500.2 503.9 1.425 2.800 27.801 36.0 499.4 503.3 1.550 2.622 27.143 32.5

4.9 The LDIF Template FileThe LDIF Template file contains the LDAP entry that will be used as a base for creating the LDAP entries to be added. The file can contain parameters that can be used to generate the LDAP entries. You can generate the LDAP entries using the addrate tool.

Note - The LDIF Template file can contain only one entry.

The parameters syntax is the same used by the Java String format. See http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax for a detailed description of the formatting.

4.9.1 LDIF Template File ExampleIn this example, the following LDIF template file contains an entry definition with four different parameters:dn: uid=user.%2$d,ou=%1$s,dc=example,dc=comobjectClass: personobjectClass: inetorgpersonobjectClass: organizationalpersonobjectClass: topuid: user.%2$dcn: name - %3$ssn: surname - %4$s

All the parameters are of type String ($s)except the one used to specify the UID. The UID parameter uses an integer: $d.

To be able to generate entries from the template above, you must provide values for all the four parameters using the –-argument option of the tool.

LDAP Performance Tools User’s Guide 1.0 Page 30

Page 31: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

The –-argument option of the tool enables you to specify static (fixed) values, random values, and incremental values. When running addrate, the tool generates entries in a loop, reading the contents of the template file and using the parameter values provided through the –-argument option.

See section “ 4.10 The Format String and --argument Options ” for more details about how to use the –-argument option.

For example, the following is specified in the command-line. The file /tmp/templateLDIF.ldif contains the entry described above:--templateFile /tmp/templateLDIF.ldif --argument Persons --argument "inc(1,100000000)" --argument "randstr(20)" --argument "randstr(10)"

The tool then generates entries in a loop under ou=Person,dc=example,dc=com . The first –argument value is static. Entries are generated with uid values ending in integer values which are generated incrementally, and cn and sn values which end with random strings. The random part of the cn attribute value will have 20 characters. The random part of the sn attribute value will have 10 characters.

The first two loops when running addrate, will generate the following entries which the tool will try to add to the server:

dn: uid=user.1,ou=Persons,dc=example,dc=comobjectClass: personobjectClass: inetorgpersonobjectClass: organizationalpersonobjectClass: topuid: user.1cn: name - 11wEG4264mLjW9uX9uxIsn: surname - 11wEG4264m

dn: uid=user.2,ou=Persons,dc=example,dc=comobjectClass: personobjectClass: inetorgpersonobjectClass: organizationalpersonobjectClass: topuid: user.2cn: name - Z55LyOGIml6LUjIPWc3qsn: surname – LjW9uX9uxI

4.10The Format String and --argument OptionsUse argument option to generate the values for the parameters defined in any of the following:

• The contents of the file of the --templateFile option in the addrate tool.

• The value of --bindDN and the LDAP filter in the authtrate tool.

• The value of --targetDN in the delrate tool.

• The value of --targetDN and the attribute:value pair to be modified in the modrate tool.

• The value of --baseDN and the filter in the searchrate tool.

LDAP Performance Tools User’s Guide 1.0 Page 31

Page 32: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

The options --bindDN, --targetDN, and –-baseDN options and the filters described above can take as values Java format strings. For a detailed description of the formatting here see: http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax .

For example, the following filter contains two different parameters. Both are of type String:(&(objectclass=%1$s)(cn=%2$s))The values of the parameters in the filter above are specified using the ––argument option.

The types of parameter values you can use with the ––argument option are described in the following section:

“ 4.10.1 Static Value ”

“ 4.10.2 Incremental Value from a File ”

“ 4.10.3 Incremental Integer Value ”

“ 4.10.4 Random Line from File Value ”

“ 4.10.5 Random Integer Value ”

“ 4.10.6 Random String Value ”

4.10.1 Static ValueSpecify directly the value you want to be used. If the value can be parsed to an integer, the value of the --argument option will be handled as an integer. Otherwise it will considered a String.

Examples using the ––targetDN option with a format String:• --targetDN 'cn=%s' --argument myuid

The value of --targetDN will be cn=uid myuid every time.• --targetDN 'cn=%d' --argument 4

The value of --targetDN will be every time cn=4--targetDN 'cn=%s' --argument 4An error will be generated . The format String expects a String, but an integer value is generated by the --argument option.

4.10.2 Incremental Value from a FileUse inc({filename}). Each time the corresponding parameter value must be evaluated, the next line of the file will be read. The returned values will have String format.

LDAP Performance Tools User’s Guide 1.0 Page 32

Page 33: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

Example using the --targetDN option with a format String and the following file (/tmp/strings.txt):One1Two

--targetDN 'cn=%s' –argument "inc(/tmp/strings.txt)"

The value of --targetDN will be:cn=Onecn=1cn=Twocn=One

[...]

4.10.3 Incremental Integer ValueSpecify inc({min},{max}) with the minimum and maximum inclusive values that must be returned. The parameter value is an integer.Examples using the –targetDN option with a format String:--targetDN 'employeeNumber=%s' –argument "inc(1,3)"Returns an error. The format String expects a String but an integer value is generated by the –argument option)

• --targetDN 'employeeNumber=%d' –argument "inc(1,3)"The value of --targetDN will be:

employeeNumber=1employeeNumber=2employeeNumber=3employeeNumber=1[...]

Note - When you launch more than one connection (using ––numConnection 2, for instance), you should not rely on incremental values (––argument inc({min},{max}) or ––argument inc({filename})) to generate unique values. The connections will use separate counters to do the increment, which leads to generating entries with duplicate values. An example would be to launch the following command-line using the files described in the first example of section “ 4.3 addrate .” bin/addrate --hostname "localhost:1389" --bindDN "cn=directory manager" --bindPasswordFile /tmp/password.txt --templateFile /tmp/templateLDIF.ldif --argument "inc(/tmp/cns.txt)" --argument "randstr(30,[A-Z][a-z][0-9]();-)" --numConnections 2

LDAP Performance Tools User’s Guide 1.0 Page 33

Page 34: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

This will generate entries with the same DN, which leads to errors (only the entry generated for one connection will be added):dn: cn=name - Aaccf Amar,ou=People,dc=example,dc=comobjectClass: personobjectClass: topcn: name - Aaccf Amarsn: surname - Aaccf AmaruserPassword: sgIsSgJsPAsyCstrM5tckjbEzwwvQB

dn: cn=name - Aaccf Amar,ou=People,dc=example,dc=comobjectClass: personobjectClass: topcn: name - Aaccf Amarsn: surname - Aaccf AmaruserPassword: RB02vsnr62hnsfvGPcbsHogSnf6y9x

4.10.4 Random Line from File ValueUse rand({filename}). A random line from the file will be picked and passed as parameter. The parameter type will be String.

Example using the --targetDN option with a format String and the following file (/tmp/strings.txt):One1Two

--targetDN 'uid=%s' –-argument "rand(/tmp/strings.txt)"

The value of --targetDN will be generated using a random line of the file. For instance:uid=1uid=1uid=Oneuid=Two[...]

LDAP Performance Tools User’s Guide 1.0 Page 34

Page 35: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

4.10.5 Random Integer ValueUse rand({min},{max}). A random number between the minimum and maximum values will be generated. The parameter value is an integer.Examples using the --targetDN option with a format String:--targetDN 'employeeNumber=%s' --argument "rand(10,300)" Returns an error. The format String expects a String, but an integer value is generated by the --argument option.

--targetDN 'employeeNumber=%d' --argument "rand(10,300)"The value of --targetDN will be random. For example:

employeeNumber=129employeeNumber=53employeeNumber=278employeeNumber=201[…]

4.10.6 Random String ValueUse randstr({length},<charSet>). A random string of specified length with the provided charset will be generated. If no charset is specified, [A-Z][a-z][0-9] (alphanumeric charset) will be used. You can specify both character intervals or characters. The resulting parameter will be a String.

Examples using the --targetDN option with a format String:--targetDN 'employeeNumber=%d' –argument "randstr(2,[0-9])"Returns an error. The format String expects an integer, but a String value is generated by the --argument option.

• --targetDN 'uid=%s' –argument "randstr(30,[A-Z][0-9]{}<>-)"The value of ––targetDN will be random. The value of the uid will be a random String of 30 characters with alphanumerical characters and some special characters. For example:

uid=7XSGZE-MBV01AE2NI<IDKDVZ4Q}-OCuid=-YW0M7K7R3DTNOO2OYS1S{}EFXZH1Luid=G>WRAWXE9S47X5KMQWQH<}YB39QN}7

4.11 LDAP ReferencesSee a description of the LDAP filter syntax: http://tools.ietf.org/html/rfc4515

LDAP Performance Tools User’s Guide 1.0 Page 35

Page 36: LDAP Performance Tools User’s Guide · 4 Using the LDAP Performance Tools The LDAP Performance Tools contains the following utilities: addrate, authrate, delrate, modrate, and searchrate

4.12 Using a Properties File with the LDAP Performance ToolsThe following mutually exclusive options are used with the LDAP Performance tools to indicate whether a properties file is used:

• --noPropertiesFileNo properties file will be used to get default command-line argument values.

• --propertiesFilePath {propertiesFilePath}Path to the file containing default property values used for command-line arguments

4.12.1 Locating the Properties FileUtilities that use the common properties file have the following default behavior:

• If the --noPropertiesFile option is specified, the command-line interface does not try to locate a properties file. Only options specified on the command line are evaluated.

• If the --propertiesFilePath option is specified, property values are read from this file.

• If no properties file is found in either of these locations, the default behavior is applied. Only arguments specified on the command line are evaluated.

4.12.2 Order of Precedence of Options and PropertiesOptions and their corresponding values specified on the command line take precedence over the properties defined in the properties file.

The properties file has the standard JAVA properties file format (property-name=value).The file supports variations on property names to enable them to be overridden according to the command that uses them. For example, the properties file might contain the following:hostname=localhostport=1389bindDN=cn=Directory ManagerbindPasswordFile=/tmp/password.txtNumThreads=5

If a command-line interface uses the port property, the command first tries to locate a toolname.port definition. If this is not defined, the command tries to locate a port definition. For example, the properties file might have several port options defined for different utilities:port=389modrate.port=2389authrate.port=2389searchrate.port=1389

Note - Do not use quotation marks around the values in the properties file . For example, to specify a port number use port=389.

LDAP Performance Tools User’s Guide 1.0 Page 36