Chapter 15 The Rate of Authentication Measurement Tool

The 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:

Overview

The 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 Usage

Using 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

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:

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:

Sample Output

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

Command-Line Examples

The 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 100

Adding 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

Previous Contents Index Next
Sun ONE Directory Server Resource Kit 5.2 Tools Reference