modrate

modrate — measure modification throughput and response time

Synopsis

modrate {options} [(attribute:value template string) …]

Description

This utility can be used to measure modify throughput and response time of a directory service using user-defined modifications.

Example:

modrate -p 1636 -Z -X -D uid=admin -w password \

-F -c 4 -t 4 -b 'uid=user.{1},ou=people,dc=example,dc=com' \

-g 'rand(0,2000)' -g 'randstr(16)' 'description:{2}'

Before trying the example, import 2000 randomly generated users.

When you do not use the -f option to keep connections open and rebind on the connections, the tool can exhaust its available ports, causing the tool to crash. You can work around this problem on test systems by changing TCP settings on the system.

For example, on Linux systems, set the following parameters in the /etc/sysctl.conf file:

net.ipv4.tcp_fin_timeout = 30
net.ipv4.tcp_tw_recycle = 1
net.ipv4.tcp_tw_reuse = 1

The parameter net.ipv4.tcp_fin_timeout sets the length of time in seconds to wait for a final FIN packet before forcing a close of the socket. The default is 60 (seconds).

The parameter net.ipv4.tcp_tw_recycle enables fast recycling of TIME_WAIT sockets. The default is 0 (false). Enabling this can cause Network Address Translation (NAT) issues.

The parameter net.ipv4.tcp_tw_reuse enables reuse of TIME_WAIT sockets for new connections. The default is 0 (false).

These settings are recommended only for testing, and not for production systems .

After making the changes to /etc/sysctl.conf , reload the configuration with the sysctl command:

# sysctl -p

Options

The modrate command takes the following options:

Command options:

-b | --targetDn {targetDN}: Target entry DN template string.
-B | --warmUpDuration {warmUpDuration}: Warm up duration in seconds. Default: 0
-c | --numConnections {numConnections}: Number of connections. Default: 1
-d | --maxDuration {maxDuration}: Maximum duration in seconds, 0 for unlimited. Default: 0
-e | --percentile {percentile}: Calculate max response time for a percentile of operations.
-f | --keepConnectionsOpen: Keep connections open. Default: false
-F | --noRebind: Keep connections open and do not rebind. Default: false
-g | --argument {generator function or static string}: Argument used to evaluate the template strings in program parameters (ie. Base DN, 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.

These functions do not support formatted integers with comma due to the ambiguity between a comma used to separate function arguments and a comma used to separate digits in a formatted integer.
-i | --statInterval {statInterval}: Display results each specified number of seconds. Default: 5
-m | --maxIterations {maxIterations}: Max iterations, 0 for unlimited. Default: 0
-M | --targetThroughput {targetThroughput}: Target average throughput to achieve. Default: 0
--mvcc {mvcc}: Attribute name used in the assertion filter for multi-version concurrency control. For "read_modify" strategy only, ignored otherwise. Default: eTag
-S | --scriptFriendly: Use script-friendly mode. Default: false
--strategy {strategy}: The strategy for modifying entries, which must be one of "modify" or "read_modify". Default: MODIFY
-t | --numConcurrentRequests {numConcurrentRequests}: Number of concurrent requests per connection. Default: 1
--valueCount {valueCount}: Specifies the number of values an attribute should contain. Default: 1
-Y | --proxyAs {authzID}: Use the proxied authorization control with the given authorization ID.

LDAP connection options:

--connectTimeout {timeout}: Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out. Default: 30000
-D | --bindDn {bindDN}: DN to use to bind to the server. Default:
-E | --reportAuthzId: Use the authorization identity control. Default: false
-h | --hostname {host}: Fully-qualified server host name or IP address. Default: localhost.localdomain
-N | --certNickname {nickname}: Nickname of the certificate that should be sent to the server for SSL client authentication.
-o | --saslOption {name=value}: SASL bind options.
-p | --port {port}: Directory server port number.
-q | --useStartTls: Use StartTLS to secure communication with the server. Default: false
-T | --trustStorePassword[:env|:file] {trustStorePassword}: Truststore password which will be used as the cleartext configuration value.
--useJavaKeyStore {keyStorePath}: JKS keystore containing the certificate which should be used for SSL client authentication.
--useJavaTrustStore {trustStorePath}: Use a JKS truststore file for validating server certificate.
--useJceKeyStore {keyStorePath}: JCEKS keystore containing the certificate which should be used for SSL client authentication.
--useJceTrustStore {trustStorePath}: Use a JCEKS truststore file for validating server certificate.
--useJvmTrustStore: Use the JVM truststore for validating server certificate. Default: false
--usePasswordPolicyControl: Use the password policy request control. Default: false
--usePkcs11KeyStore: PKCS#11 keystore containing the certificate which should be used for SSL client authentication. Default: false
--usePkcs12KeyStore {keyStorePath}: PKCS#12 keystore containing the certificate which should be used for SSL client authentication.
--usePkcs12TrustStore {trustStorePath}: Use a PKCS#12 truststore file for validating server certificate.
-w | --bindPassword[:env|:file] {bindPassword}: Password to use to bind to the server. Omit this option while providing the bind DN to ensure that the command prompts for the password, rather than entering the password as a command argument.
-W | --keyStorePassword[:env|:file] {keyStorePassword}: Keystore password which will be used as the cleartext configuration value.
-X | --trustAll: Trust all server SSL certificates. Default: false
-Z | --useSsl: Use SSL for secure communication with the server. Default: false

Utility input/output options:

-n | --no-prompt: Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail. Default: false
--noPropertiesFile: No properties file will be used to get default command line argument values. Default: false
--propertiesFilePath {propertiesFilePath}: Path to the file containing default property values used for command line arguments.
-v | --verbose: Use verbose mode. Default: false

General options:

-V | --version: Display Directory Server version information. Default: false
-H | --help: Display this usage information. Default: false

Exit codes

0: The command completed successfully.
89: An error occurred while parsing the command-line arguments.

Examples

The following example uses the modrate command to write random 16-character description values to user entries:

$ modrate \
 --hostname localhost \
 --port 1636 \
 --useSsl \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --bindDn uid=admin \
 --bindPassword password \
 --noRebind \
 --numConnections 4 \
 --numConcurrentRequests 4 \
 --maxDuration 30 \
 --argument "rand(0,2000)" --targetDn "uid=user.{1},ou=people,dc=example,dc=com" \
 --argument "randstr(16)" 'description:{2}'
-------------------------------------------------------------------------------
|     Throughput    |                 Response Time                |          |
|    (ops/second)   |                (milliseconds)                |          |
|   recent  average |   recent  average    99.9%   99.99%  99.999% |  err/sec |
-------------------------------------------------------------------------------
|  11086.2  11086.2 |    1.404    1.404    14.88    19.14    23.86 |      0.0 |
|  15351.6  13218.9 |    1.031    1.187    13.89    17.04    23.86 |      0.0 |
|  15252.0  13896.6 |    1.038    1.133    13.24    17.30    23.33 |      0.0 |
|  15383.2  14268.3 |    1.029    1.105    13.37    18.22    51.64 |      0.0 |
|  15204.6  14455.5 |    1.041    1.091    13.83    17.83    51.64 |      0.0 |
|  15356.3  14605.3 |    1.030    1.080    13.63    17.83    51.64 |      0.0 |

This example uses the following options:

--hostname localhost , --port 1636 , --useSsl , --usePkcs12TrustStore /path/to/opendj/config/keystore , --trustStorePassword:file /path/to/opendj/config/keystore.pin: Access the server running on the local system over a secure LDAPS connection to port 1636.
--bindDn uid=admin , --bindPassword password: Authenticate as the directory root user uid=admin with the bind password that is literally password . This user is not subject to access control, so rates may be higher than what you observe with a regular user.
--noRebind: Keep connections open and do not rebind.
--numConnections 4: Open 4 connections to the server.
--numConcurrentRequests 4: Perform up to 4 concurrent requests on each connection.
--maxDuration 30: Run for a maximum of 30 seconds.
--argument "rand(0,2000)" --targetDn "uid=user.{1},ou=people,dc=example,dc=com": Target the entry with DN uid=user.number,ou=people,dc=example,dc=com , where number is a random number between 0 and 2000, inclusive.
--argument "randstr(16)" 'description:{2}': Write a random, 16-character string to the description attribute of the target entry. The randstr(16) argument specifies only the length, which is 16. It does not have an optional second argument to specify a character set. Therefore, use the default character set, which is [A-Z][a-z][0-9] .

Notice the following characteristics of the output:

The first two columns show the throughput in operations completed per second. The recent column shows the average rate for operations reflected in this row of output. The average column shows the average rate since the beginning of the run.
The response time columns indicate characteristics of response latency in milliseconds. The recent column shows the average latency for operations reflected in this row of output. The average column shows the average latency since the beginning of the run. The "99.9%" column shows the latency after which 99.9% of operations have completed. Only 1 operation in 1000 took longer than this. The "99.99%" column shows the latency after which 99.99% of operations have completed. Only 1 operation in 10,000 took longer than this. The "99.999%" column shows the latency after which 99.999% of operations have completed. Only 1 operation in 100,000 took longer than this.
The "err/sec" column show the rate of error results per second for this row of output. Unless you have intentionally set up the command to generate errors, this column should indicate 0.0 . Check that this column matches your expectations before looking at any other columns.

Directory Services 7.3.5