The searchrate Command-Line Tool

Perform repeated searches against an LDAP directory server.

Usage

searchrate {arguments}

LDAP Connection and Authentication Arguments

• -h {host} / --hostname {host} — The IP address or resolvable name to use to connect to the directory server. If this is not provided, then a default value of 'localhost' will be used.
  
  
• -p {port} / --port {port} — The port to use to connect to the directory server. If this is not provided, then a default value of 389 will be used.
  The specified value must not be less than 1 or greater than 65,535.
  
  
• -D {dn} / --bindDN {dn} — The DN to use to bind to the directory server when performing simple authentication.
  A provided value must be able to be parsed as an LDAP distinguished name as described in RFC 4514.
  
  
• -w {password} / --bindPassword {password} — The password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
  
  
• -j {path} / --bindPasswordFile {path} — The path to the file containing the password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
  The specified path must refer to a file that exists.
  
  
• --promptForBindPassword — Indicates that the tool should interactively prompt the user for the bind password.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -Z / --useSSL — Use SSL when communicating with the directory server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -q / --useStartTLS — Use StartTLS when communicating with the directory server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --defaultTrust — Use the JVM's default trust store, and optionally an additional trust store specified using the --trustStorePath argument, to non-interactively determine whether to trust any certificate chain presented during TLS negotiation. If the chain cannot be trusted based on any of those sources, then negotiation will fail without prompting about whether to trust it.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -X / --trustAll — Trust any certificate presented by the directory server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -K {path} / --keyStorePath {path} — The path to the file to use as the key store for obtaining client certificates when communicating securely with the directory server.
  
  
• -W {password} / --keyStorePassword {password} — The password to use to access the key store contents.
  
  
• -u {path} / --keyStorePasswordFile {path} — The path to the file containing the password to use to access the key store contents.
  The specified path must refer to a file that may or may not exist.
  
  
• --promptForKeyStorePassword — Indicates that the tool should interactively prompt the user for the password to use to access the key store contents.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --keyStoreFormat {format} — The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the key store file.
  
  
• -P {path} / --trustStorePath {path} — The path to the file to use as trust store when determining whether to trust a certificate presented by the directory server.
  
  
• -T {password} / --trustStorePassword {password} — The password to use to access the trust store contents.
  
  
• -U {path} / --trustStorePasswordFile {path} — The path to the file containing the password to use to access the trust store contents.
  The specified path must refer to a file that may or may not exist.
  
  
• --promptForTrustStorePassword — Indicates that the tool should interactively prompt the user for the password to use to access the trust store contents.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --trustStoreFormat {format} — The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the trust store file.
  
  
• --verifyCertificateHostnames — Indicates that the tool should verify that the hostname or IP addressed used to establish connections ot the LDAP server matches an address for which the server's TLS certificate was issued.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -N {nickname} / --certNickname {nickname} — The nickname (alias) of the client certificate in the key store to present to the directory server for SSL client authentication.
  
  
• -o {name=value} / --saslOption {name=value} — A name-value pair providing information to use when performing SASL authentication.
  
  
• --useSASLExternal — Use the SASL EXTERNAL mechanism to authenticate.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --helpSASL — Provide information about the supported SASL mechanisms, including the properties available for use with each.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Search Arguments

• -b {dn} / --baseDN {dn} — The base DN to use for the searches. It may be a simple DN or a value pattern to specify a range of DNs (e.g., "uid=user.[1-1000],ou=People,dc=example,dc=com"). See https://docs.ldap.com/ldap-sdk/docs/javadoc/index.html?com/unboundid/util/ValuePattern.html for complete details about the value pattern syntax. This argument must not be used in conjunction with the --ldapURL argument.
  
  
• -s {scope} / --scope {scope} — The scope to use for the searches. It should be 'base', 'one', 'sub', or 'subord'. If this is not provided, then a default scope of 'sub' will be used. This argument must not be used in conjunction with the --ldapURL argument.
  The provided value should be one of 'base', 'one', 'sub', or 'subordinate'.
  
  
• -f {filter} / --filter {filter} — The filter to use for the searches. It may be a simple filter or a value pattern to specify a range of filters (e.g., "(uid=user.[1-1000])"). See https://docs.ldap.com/ldap-sdk/docs/javadoc/index.html?com/unboundid/util/ValuePattern.html for complete details about the value pattern syntax. Exactly one of this argument and the --ldapURL arguments must be provided.
  
  
• -A {name} / --attribute {name} — The name of an attribute to include in entries returned from the searches. Multiple attributes may be requested by providing this argument multiple times. If no request attributes are provided, then the entries returned will include all user attributes. This argument must not be used in conjunction with the --ldapURL argument.
  
  
• --ldapURL {url} — An LDAP URL that provides the base DN, scope, filter, and requested attributes to use for the search requests (the address and port components of the URL, if present, will be ignored). It may be a simple LDAP URL or a value pattern to specify a range of URLs. See https://docs.ldap.com/ldap-sdk/docs/javadoc/index.html?com/unboundid/util/ValuePattern.html for complete details about the value pattern syntax. If this argument is provided, then none of the --baseDN, --scope, --filter, or --attribute arguments may be used.
  
  
• -z {num} / --sizeLimit {num} — The maximum number of entries that the server should return in response to each search request. A value of zero indicates that the client does not wish to impose any limit on the number of entries that are returned (although the server may impose its own limit). If this is not provided, then a default value of zero will be used.
  The specified value must not be less than 0 or greater than 2,147,483,647.
  
  
• -l {seconds} / --timeLimitSeconds {seconds} — The maximum length of time, in seconds, that the server should spend processing each search request. A value of zero indicates that the client does not wish to impose any limit on the server's processing time (although the server may impose its own limit). If this is not provided, then a default value of zero will be used.
  The specified value must not be less than 0 or greater than 2,147,483,647.
  
  
• --dereferencePolicy {never|always|search|find} — The alias dereferencing policy to use for search requests. The value should be one of 'never', 'always', 'search', or 'find'. If this is not provided, then a default value of 'never' will be used.
  A provided value should be one of the following: 'always', 'never', 'search', 'find'.
  
  
• --typesOnly — Indicates that server should only include the names of the attributes contained in matching entries rather than both names and values.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Request Control Arguments

• --assertionFilter {filter} — Indicates that search requests should include the assertion request control with the specified filter.
  A provided value must be able to be parsed as an LDAP search filter as described in RFC 4515.
  
  
• --simplePageSize {size} — Indicates that search requests should include the simple paged results control with the specified page size.
  The specified value must not be less than 1 or greater than 2,147,483,647.
  
  
• --sortOrder {sortOrder} — Indicates that search requests should include the server-side sort request control with the specified sort order. This should be a comma-delimited list in which each item is an attribute name, optionally preceded by a plus or minus sign (to indicate ascending or descending order; where ascending order is the default), and optionally followed by a colon and the name or OID of the desired ordering matching rule (if this is not provided, the the attribute type's default ordering rule will be used).
  
  
• -Y {authzID} / --proxyAs {authzID} — Indicates that the proxied authorization control (as defined in RFC 4370) should be used to request that operations be processed using an alternate authorization identity. This may be a simple authorization ID or it may be a value pattern to specify a range of identities. See https://docs.ldap.com/ldap-sdk/docs/javadoc/index.html?com/unboundid/util/ValuePattern.html for complete details about the value pattern syntax.
  
  
• -J {oid}[:{criticality}[:{stringValue}|::{base64Value}]] / --control {oid}[:{criticality}[:{stringValue}|::{base64Value}]] — Indicates that search requests should include the specified request control. This may be provided multiple times to include multiple request controls.
  A provided value must be a string representation of a valid LDAP control in the form {oid}[:{criticality}[:{stringValue}|::{base64Value}]].
  
  

Rate Management Arguments

• -t {num} / --numThreads {num} — The number of threads to use to perform the searches. If this is not provided, then a default of one thread will be used.
  The specified value must not be less than 1 or greater than 2,147,483,647.
  
  
• -i {num} / --intervalDuration {num} — The length of time in seconds between output lines. If this is not provided, then a default interval of five seconds will be used.
  The specified value must not be less than 1 or greater than 2,147,483,647.
  
  
• -I {num} / --numIntervals {num} — The maximum number of intervals for which to run. If this is not provided, then the tool will run until it is interrupted.
  The specified value must not be less than 1 or greater than 2,147,483,647.
  
  
• --iterationsBeforeReconnect {num} — The number of search iterations that should be processed on a connection before that connection is closed and replaced with a newly-established (and authenticated, if appropriate) connection. If this is not provided, then connections will not be periodically closed and re-established.
  The specified value must not be less than -2,147,483,648 or greater than 2,147,483,647.
  
  
• -r {searches-per-second} / --ratePerSecond {searches-per-second} — The target number of searches to perform per second. It is still necessary to specify a sufficient number of threads for achieving this rate. If neither this option nor --variableRateData is provided, then the tool will run at the maximum rate for the specified number of threads.
  The specified value must not be less than 1 or greater than 2,147,483,647.
  
  
• --variableRateData {path} — The path to a file containing information that can be used to cause the tool to vary the target rate over time. Use the generateSampleRateFile argument to generate a sample rate definition file with comments that describe the required format for this file.
  The specified path must refer to a file that exists.
  
  
• --generateSampleRateFile {path} — The path to a sample variable data rate file that should be generated. This file will contain comments that describe the expected format for the file to use with the variableRateData argument.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• --warmUpIntervals {num} — The number of intervals to complete before beginning overall statistics collection. Specifying a nonzero number of warm-up intervals gives the client and server a chance to warm up without skewing performance results.
  The specified value must not be less than 0 or greater than 2,147,483,647.
  
  

Additional Arguments

• --timestampFormat {format} — Indicates the format to use for timestamps included in the output. A value of 'none' indicates that no timestamps should be included. A value of 'with-date' indicates that both the date and the time should be included. A value of 'without-date' indicates that only the time should be included.
  A provided value should be one of the following: 'none', 'with-date', 'without-date'.
  
  
• -a / --asynchronous — Indicates that the client should operate in asynchronous mode, in which it will not be necessary to wait for a response to a previous request before sending the next request. Either the '--ratePerSecond' or the '--maxOutstandingRequests' argument must be provided to limit the number of outstanding requests.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -O {num} / --maxOutstandingRequests {num} — Specifies the maximum number of outstanding requests that should be allowed when operating in asynchronous mode.
  The specified value must not be less than 1 or greater than 2,147,483,647.
  
  
• --suppressErrorResultCodes — Indicates that information about the result codes for failed operations should not be displayed.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -c / --csv — Generate output in CSV format rather than a display-friendly format
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -R {value} / --randomSeed {value} — Specifies the seed to use for the random number generator.
  The specified value must not be less than -2,147,483,648 or greater than 2,147,483,647.
  
  
• --interactive — Launch the tool in interactive mode.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --outputFile {path} — Write all standard output and standard error messages to the specified file instead of to the console.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• --appendToOutputFile — Indicates that the tool should append to the file specified by the --outputFile argument if it already exists. If this argument is not provided and the output file already exists, it will be overwritten.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --teeOutput — Write all standard output and standard error messages to the console as well as to the specified output file. The --outputFile argument must also be provided.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -H / --help — Display usage information for this program.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --help-debug — Display usage information for debug logging.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --enable-debug-logging — Enables debug logging for the tool.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --debug-log-level {level} — The debug log level to use for the tool. Allowed values include 'off', 'severe', 'warning', 'info', 'fine', 'finer', and 'finest'. If this is not specified, a default level of 'severe' will be used.
  
  
• --debug-log-category {category} — The message categories to include in the debug log output. Allowed values include 'asn1', 'connect', 'exception', 'ldap', 'connectionpool', 'ldif', 'monitor', 'codingerror', and 'other'. This argument may be provided multiple times to indicate that multiple categories should be included. If this is not specified, then all categories will be included.
  
  
• --include-debug-stack-traces — Indicates that debug log messages should include a stack trace with the code location from which each debug message originated.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --use-multi-line-debug-messages — Indicates that debug log messages (which will be JSON objects) should be written as multi-line strings rather than single-line strings.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --debug-log-file {path} — The path to the debug log file to be written. If this is not specified, a default path of 'searchrate.debug' will be used.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• -V / --version — Display version information for this program.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --propertiesFilePath {path} — The path to a properties file used to specify default values for arguments not supplied on the command line.
  The specified path must refer to a file that exists.
  
  
• --generatePropertiesFile {path} — Write an empty properties file that may be used to specify default values for arguments.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• --noPropertiesFile — Do not obtain any argument values from a properties file.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --suppressPropertiesFileComment — Suppress output listing the arguments obtained from a properties file.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Required Argument Sets

• At least one of the following arguments must be provided: --filter, --ldapURL

Dependent Argument Sets

• If the --keyStorePassword argument is provided, then the --keyStorePath argument must also be provided.
• If the --keyStorePasswordFile argument is provided, then the --keyStorePath argument must also be provided.
• If the --promptForKeyStorePassword argument is provided, then the --keyStorePath argument must also be provided.
• If the --trustStorePassword argument is provided, then the --trustStorePath argument must also be provided.
• If the --trustStorePasswordFile argument is provided, then the --trustStorePath argument must also be provided.
• If the --promptForTrustStorePassword argument is provided, then the --trustStorePath argument must also be provided.
• If the --keyStorePath argument is provided, then at least one of the following arguments must also be provided: --useSSL, --useStartTLS
• If the --trustStorePath argument is provided, then at least one of the following arguments must also be provided: --useSSL, --useStartTLS
• If the --defaultTrust argument is provided, then at least one of the following arguments must also be provided: --useSSL, --useStartTLS
• If the --trustAll argument is provided, then at least one of the following arguments must also be provided: --useSSL, --useStartTLS
• If the --bindPassword argument is provided, then at least one of the following arguments must also be provided: --bindDN, --saslOption
• If the --bindPasswordFile argument is provided, then at least one of the following arguments must also be provided: --bindDN, --saslOption
• If the --promptForBindPassword argument is provided, then at least one of the following arguments must also be provided: --bindDN, --saslOption
• If the --asynchronous argument is provided, then at least one of the following arguments must also be provided: --ratePerSecond, --maxOutstandingRequests
• If the --maxOutstandingRequests argument is provided, then the --asynchronous argument must also be provided.
• If the --appendToOutputFile argument is provided, then the --outputFile argument must also be provided.
• If the --teeOutput argument is provided, then the --outputFile argument must also be provided.

Exclusive Argument Sets

• The following arguments cannot be used together: --useSSL, --useStartTLS
• The following arguments cannot be used together: --keyStorePassword, --keyStorePasswordFile, --promptForKeyStorePassword
• The following arguments cannot be used together: --trustStorePassword, --trustStorePasswordFile, --promptForTrustStorePassword
• The following arguments cannot be used together: --defaultTrust, --trustAll
• The following arguments cannot be used together: --trustAll, --trustStorePath
• The following arguments cannot be used together: --bindDN, --saslOption, --useSASLExternal
• The following arguments cannot be used together: --bindPassword, --bindPasswordFile, --promptForBindPassword
• The following arguments cannot be used together: --variableRateData, --generateSampleRateFile
• The following arguments cannot be used together: --baseDN, --ldapURL
• The following arguments cannot be used together: --scope, --ldapURL
• The following arguments cannot be used together: --filter, --ldapURL
• The following arguments cannot be used together: --attribute, --ldapURL
• The following arguments cannot be used together: --asynchronous, --simplePageSize
• The following arguments cannot be used together: --propertiesFilePath, --noPropertiesFile

Examples

• Test search performance by searching randomly across a set of one million users located below 'dc=example,dc=com' with ten concurrent threads. The entries returned to the client will include the givenName, sn, and mail attributes.

    searchrate --hostname server.example.com --port 389 \
         --bindDN uid=admin,dc=example,dc=com --bindPassword password \
         --baseDN dc=example,dc=com --scope sub \
         --filter "(uid=user.[1-1000000])" --attribute givenName \
         --attribute sn --attribute mail --numThreads 10

• Generate a sample variable rate definition file that may be used in conjunction with the --variableRateData argument. The sample file will include comments that describe the format for data to be included in this file.

    searchrate --generateSampleRateFile variable-rate-data.txt