Sun ONE Directory Server Resource Kit 5.2 Tools Reference |
Chapter 15
The Rate of Authentication Measurement ToolThe authrate tool measures the possible rate of authentication to an LDAP v3 directory. This chapter provides instructions on how to use the modrate tool. It contains the following sections:
OverviewThe authrate tool measures the possible rate of authentication to an LDAP v3 directory. It is similar to the rsearch functionality described in Chapter 12, "The rsearch Search Tool," providing a mechanism for using random bind DN and password credentials. The DSRK and its updates include the latest version of the tool in the DSRK_base/bin/dsrk52 directory.
Note
As with all measures of performance, results depend upon many factors, such as the options and parameter values given, directory configuration, machine load, and network traffic, and should be analyzed accordingly. In order to obtain accurate performance measurements, both client and server machines should be dedicated to the performance test and properly tuned. (See Chapter 10, "The idsktune Optimization Tool" for more information.)
Command UsageUsing multiple threads, the authrate tool repeatedly initializes a connection and binds to a directory server, without performing any other operation. Threads may be configured to keep open connections and perform LDAP binds repeatedly. The command-line options let you specify the bind credentials. The modrate tool has the following built-in defaults:
The tool displays performance results at regular intervals. In general, when the authrate tool encounters an error, it displays a message and continues running. It will attempt to bind again indefinitely, even after encountering an error.
Syntax
The syntax of the authrate tool on the command-line takes the following form:
authrate -D "bindDN" -w password [ options ]
Where:
- bindDN and password are the bind credentials, with the bind DN is usually in double quotes ("") for the shell. The bind DN and password may use %s and %d placeholders to include random strings and numbers. (See Randomly Generated Bind DNs for more information.)
- options are the command-line options and their parameters described in Options.
Options
The authrate options and parameters are described in Table 15-1. The authrate -H command and option when run on the command-line will display brief descriptions of all the command-line options.
Table 15-1 Command-Line Options for authrate
Option
Parameter
Purpose
-h
hostname
Specify the hostname of the directory server. The default is localhost.
-p
port
Specify the port number when accessing the directory server host. The default is 389.
-D
bindDN
Specify a bind DN for accessing the directory, usually in double quotes ("") for the shell. See Randomly Generated Bind DNs for information on how to include %s or %d placeholders for random strings or numbers using the -i or -r option, respectively.
-w
password
Specify the password for the bind DN. The password may also contain %s or %d placeholders that will use the same random strings or numbers as the bind DN substitutions. See Randomly Generated Bind DNs for details.
-i
inputFile
Give the name of the file containing strings that will be randomly substituted into %s placeholders in the bind DN and password. Each line of the input file is treated as a separate string. See Randomly Generated Bind DNs for more information.
-r
maxRand
Give the maximum range for random numbers to be substituted into %d placeholders in the bind DN and password. You may specify this option twice: the first random number will be in the range [0, maxRand1-1], the second will be in the range [1, maxRand2].
-k
Keep connections open when performing binds. With this option, the authrate tool will measure only the execution time of the bind operation. When this option is omitted, the initialization and freeing of the connection is also measured as part of each authentication sequence.
-u
Specify that the tool should not unbind from the server and just close the socket for the connection. This option has no effect when the -k option is specified.
-t
threads
Specify the number of threads that authrate will run in parallel. The output displays the average performance of all threads combined. The default is a single thread.
-j
seconds
Specify the measurement and display interval, in seconds; the default is 5. authrate repeats the authentication sequence as many times as possible during the interval and prints results after each interval elapses.
-m
bindOps
Specify the maximum number of bind operations for each thread to perform. When this option is not specified, all threads will repeat the authentication sequence indefinitely.
-q
Quiet output mode: the measurements for each interval will not be displayed.
-H
Display the usage help text that briefly describes all options.
Randomly Generated Bind DNs
To simulate real usage conditions and reduce any artifacts due to the repetitive nature of the tests, the authrate tool provides a mechanism for generating a random bind DN for authentication.
Syntax
You can include randomly generated numbers by specifying the following placeholders:
- In the bind DN, the first and second occurrences of %d will be replaced by a random number in the ranges [0, maxRand1-1] and [1, maxRand2], respectively, where maxRand1 and maxRand2 are given by the first and second occurrences of the -r option on the command-line. The bind DN parameter may have no more than two %d placeholders.
- In the password parameter, all occurrences of %d will be replaced by the same random number in the range [0, maxRand1-1], where maxRand1 is given by the first occurrence of the -r option on the command-line. The password parameter may have up to 8 placeholders, to generate a password with enough characters when the random substitution is a single digit.
- In both the bind DN and password parameter, the %s placeholder will be replaced by the same random string from an input file given by the -i option. Each line of this file is treated as a complete string to insert.
Substitution Rules
The tool applies the following rules for substitutions. An incorrect command-line will return a usage error:
To use the random authentication, your test directory must contain entries written with these substitution rules in mind. Because the same random number or string will be substituted into both bind DN and password, your entries must have matched DN and password pairs. For example, the following entries have one number in the DN and two in the password:
dn: cn=test0,dc=example,dc=com
password: auth00dn: cn=test1,dc=example,dc=com
password: auth11dn: cn=test2,dc=example,dc=com
password: auth22
...dn: cn=test10,dc=example,dc=com
password: auth1010
...dn: cn=test99,dc=example,dc=com
password: auth9999The following command will test authentication using these entries:
authrate -D "cn=test%d,dc=example,dc=com" -w "auth%d%d" -r 100
Sample OutputCode Example 15-1 is sample output that might be retreived from the authrate tool. When running, the authrate tool displays one line of measurements every interval (5 seconds by default). All data on an output line concerns only the elapsed interval. Use the -j seconds option to specify a different interval length.
Reading an output line backwards, it shows:
- The total number of authentications completed by all threads during the full interval.
- The rate in parentheses is the average number of authentications per second for all threads (the total divided by the number of seconds in the interval).
- The given Avg is the average number of authentications per thread during the interval (the total divided by the number of threads).
Command-Line ExamplesThe examples in this section will measure authentication performance in your directory server in various scenarios. Results will be meaningful only if factors such as machine load and network traffic remain constant during and between tests. These examples suppose the contents of your test directory are configured as detailed in Randomly Generated Bind DNs. You will need to adapt other parameters to your environment:
Open and Bind Rate
This command will launch 3 threads (-t 3), each of which will repeatedly open a connection, bind with randomly generated credentials (-D "cn=test%d,dc=example,dc=com" -w "auth%d%d" -r 100), unbind, and close the connection (no -u -k options). The tool will display combined results for all threads at one minute intervals (-j 60).
$ authrate -h hostname -p port -t 3 -j 60 \
-D "cn=test%d,dc=example,dc=com" -w "auth%d%d" -r 100Adding the -u option to this command-line will test whether the directory server handles clients that don’t unbind before disconnecting.
Bind Rate Alone
This command will use a single thread to keep a connection open (-k) in order to repeatedly bind with randomly generated credentials (-D "cn=test%d,dc=example,dc=com" -w "auth%d%d" -r 100). The LDAP protocol allows clients to bind multiple times without unbinding, and this test measures performance in this situation.
$ authrate -h hostname -p port -k \
-D "cn=test%d,dc=example,dc=com" -w "auth%d%d" -r 100