Chapter 13   authrate


The authrate tool measures the possible rate of authentication to an LDAP v3 directory. It is similar to the rsearch functionality described previously, providing a mechanism for using random bind DN and password credentials.

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 8 "idsktune").

This chapter contains the following sections:

• Command Usage

• Sample Output

• Command-Line Examples

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:

• All operations use the LDAP v3 protocol. The tool cannot be used to test directories that only support LDAP v2.

• The tool uses simple or anonymous binding. No secure binding is possible.

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 authrate command has the following syntax:

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 "Random Authentication").

• options are the command-line options and their parameters described in the next section.

The authrate -H command will display the usage help text that briefly describes all options.

Options

The authrate options and parameters are described in the following table.

Table 13-1    Command-Line Options for the authrate Tool 

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 "Random Authentication" 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 "Random Authentication" 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 "Random Authentication" 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.

Random Authentication

To simulate real usage conditions and reduce any artifacts due to the repetitive nature of the tests, the authrate tool provides a mechanism for using a random bind DN. 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.

The tool applies the following rules for substitutions. An incorrect command line will return a usage error:

• You must specify at least as many -r options as %d placeholders you use in the bind DN.

• To use the literal strings "%d" and "%s" within the bind DN or password, you must use "%%d" and "%%s", respectively.

• You may use only one type of placeholder, either decimal number or string.

To use the random authentication, your test directory must contain entries written with these substitutions 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=siroe,dc=com
password: auth00

dn: cn=test1,dc=siroe,dc=com
password: auth11

dn: cn=test2,dc=siroe,dc=com
password: auth22
...

dn: cn=test10,dc=siroe,dc=com
password: auth1010
...

dn: cn=test99,dc=siroe,dc=com
password: auth9999

The following command will test authentication using these entries:

authrate -D "cn=test%d,dc=siroe,dc=com" -w "auth%d%d" -r 100

Sample Output

---

$ authrate -h hostname -p port \
           -D "cn=test%d,dc=siroe,dc=com" -w "auth%d%d" -r 100

Avg r= 754.00/thr (150.80/sec), total= 754
Avg r= 774.00/thr (154.80/sec), total= 774
Avg r= 829.00/thr (165.80/sec), total= 829
Avg r= 825.00/thr (165.00/sec), total= 825
Avg r= 836.00/thr (167.20/sec), total= 836
Avg r= 837.00/thr (167.40/sec), total= 837
^C

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 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 explained in "Random Authentication". You will need to adapt other parameters to your environment:

• The hostname and port placeholders should be replaced with the hostname and port number of your directory.

• For realistic results, thread numbers should be scaled according to your directory's expected load.

Open and Bind Rate

$ authrate -h hostname -p port -t 3 -j 60 \
           -D "cn=test%d,dc=siroe,dc=com" -w "auth%d%d" -r 100

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=siroe,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).

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

$ authrate -h hostname -p port -k \
           -D "cn=test%d,dc=siroe,dc=com" -w "auth%d%d" -r 100

This command will use a single thread to keep a connection open (-k) to repeatedly bind with randomly generated credentials (-D "cn=test%d,dc=siroe,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.