Chapter 12   modrate


The modrate tool measures the performance of modify operations in an LDAP v3 directory. It is similar to the rsearch functionality described previously, except that it performs modifications on random user-defined attributes.

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 modrate tool repeatedly performs modify operations on a directory server. Threads may be configured to open connections and perform LDAP bind operations with every modification. The command-line options let you specify the target entries and attributes to be modified. 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.

• Referrals are never followed.

• The time limit for operations is not modifiable. The default time limit is that defined by the directory server.

The tool displays performance results at regular intervals. In general, when the modrate tool encounters an error, it displays a message and continues running. It will attempt to bind again or modify again indefinitely, even after encountering an error.

Syntax

The modrate command has the following syntax:

modrate -D "bindDN " -w password -b "baseDN " [ options ] \
        -M "attribute :length :charSet " ...

Where:

• bindDN and password are bind credentials with write permission to the target entry or entries. The bind DN is usually in double quotes ("") for the shell.

• baseDN is the DN of the entry to be modified, usually in double quotes ("") for the shell. The target entry should support the attributes given by the -M option, either for modification or for addition when not already present. The base DN may use either of the following placeholders (see "Random Modifications"):
  • %d to include random numbers up to the value given by the -r option.

  • %s to include a random string from the file given with the -i option.

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

• The -M parameter gives the information needed to generate random attribute values. There can be any number of -M parameters on the command line.
  • attribute is the name of an existing attribute of the target entry or entries given by the base DN. If this attribute does not exist on the target entry, it will be added and be subject to schema checking if it is enabled in the directory.

  • length is an integer giving the desired number of characters in random attribute string values.

  • charSet specifies a set of individual ASCII characters (c ) and ranges of characters, according to the following syntax:

    (c *([c -c ])*)* for example: [A-Z][a-z][0-9]

  For each modify operation, a modrate thread will randomly choose one of the attribute names and generate a new string value of the given length by choosing each character randomly from the given charSet .

Running the modrate command without any options or parameters will display the usage help text that briefly describes all options.

Options

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

Table 12-1    Command-Line Options for the modrate 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. Depending on its write permissions, the bind DN may influence authentication and modify performance.
-w	password	Specify the password for the bind DN.
-b	baseDN	Specify the base DN of the target entry, usually in double quotes ("") for the shell. See "Random Modifications" on how to include %s or %d placeholders for random strings or numbers with the -i or -r options, respectively.
-M	modString	Specify the name of an attribute to modify and how to randomly generate a new value for it. The modString format (attribute :length :charSet ) is described in "Syntax".
-i	inputFile	Give the name of the file containing strings that will be randomly substituted into %s placeholders in the base DN. Each line of the input file will be treated as a separate string. See "Random Modifications" for more information. This option is incompatible with the -r option.
-r	maxRand	Give the maximum range for random numbers to be substituted into %d placeholders in the base DN. 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 ]. This option is incompatible with the -i option.
-k		Keep connections open between modify operations. With this option, the modrate tool will measure only the execution time of bind and modify operations. When this option is omitted, the initialization and freeing of the connection is also measured as part of each modification sequence.
-K		Keep connections and binds open between modify operations. With this option, the modrate tool will measure only the execution time of modify operations. When this option is omitted, the initialization, binding, unbinding, and freeing of the connection is also measured as part of each 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 either -k or -K options are specified.
-O	hopLimit	(Capital letter O) Specify the maximum number of referral hops to follow while finding an entry to modify. By default, there is no limit.
-R		Specify that referrals should not be followed. By default, referrals are followed automatically.
-a		Specify asynchronous modification mode. This option is currently not working.
-t	threads	Specify the number of threads that modrate 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. modrate repeats the modify operation sequence as many times as possible during the interval and prints results after each interval elapses.
-m	modifyops	Specify the maximum, cumulated number of modify operations for each thread to perform. When this option is not specified, all threads will repeat the modify sequence indefinitely.
-q		Quiet output mode: the measurements for each interval will not be displayed.

Random Modifications

To simulate real usage conditions and reduce any artifacts due to the repetitive nature of the tests, the modrate tool provides a mechanism for choosing a random target entry. You can include either randomly generated numbers or random strings from an input file. To do this, specify the following placeholders in the base DN parameter on the command line:

• The first occurrence of %d will be replaced by a 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 second occurrence of %d will be replaced by a random number in the range [1, maxRand2 ], where maxRand2 is given by the second occurrence of the -r option on the command line.

• The %s placeholder will be replaced by a random string from an inputFile 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.

• Placeholder substitution will occur only in the base DN parameters. To use the literal strings "%d" and "%s" within this parameter, you must use "%%d" and "%%s", respectively.

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

The input file is a plain text file that contains the strings for substitution. Each line, including any whitespace, is taken to be one string. Depending on how the placeholder is used, the file may contain full or partial DNs. For example, the -b "uid=%s,ou=people,dc=Siroe,dc=com" option could be used with the following input file:

bjensen
bjense2
mtalbot
kcarter
svaughan
pshelton

The size and contents of the file should be adapted to the directory that you are testing. Generally, the number of possible target entries should be as large as possible to ensure performance is being measured across the whole directory.

Sample Output

---

$ modrate -h hostname -D "cn=directory manager" -w password \
          -b "uid=bjensen,ou=people,dc=Siroe,dc=com" \
          -M 'telephonenumber:10:[0-9]'

Avg r= 37.00/thr ( 7.40/sec), total= 37
Avg r= 36.00/thr ( 7.20/sec), total= 36
Avg r= 29.00/thr ( 5.80/sec), total= 29
Avg r= 35.00/thr ( 7.00/sec), total= 35
Avg r= 38.00/thr ( 7.60/sec), total= 38
Avg r= 39.00/thr ( 7.80/sec), total= 39
^C

When running, the modrate 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 modify operations completed by all threads during the full interval.

• The rate in parentheses is the average number of modify operations per second for all threads (the total divided by the number of seconds in the interval).

• The given Avg is the average number of operations per thread during the interval (the total divided by the number of threads).

Command-Line Examples

---

The examples in this section measure bind and modify performance in your directory server in various scenarios. Results are meaningful only if factors such as machine load and network traffic remain constant during and between tests.

In these examples, you should provide DNs for modifiable entries in your test directory. You will need to adapt these examples 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.

• You should also specify modifiable attributes in the target entries with character sets that conform to your directory's schema.

Open, Bind and Modify Rate

$ modrate -h hostname -p port -D "bindDN " -w password \
          -b "uid=bjensen,ou=people,dc=Siroe,dc=com" \
          -M 'telephonenumber:10:[0-9]' -t 3 -j 60

This command will launch 3 threads (-t 3), each of which will repeatedly open a connection, bind with the given credentials (-D "bindDN " -w password ), modify the telephonenumber attribute of the bjensen entry, unbind, and close the connection (no -u -k -K options). The new attribute value for each modification is a sequence of 10 random digits (-M telephonenumber:10:[0-9]) that simulate a telephone number. 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.

Because every modify operation applies to the same entry, entry caching in the directory server will influence results. In the following examples, the use of an input file containing UID strings helps provide more realistic measurements (see "Random Modifications").

Bind and Modify Rate

$ modrate -h hostname -p port -D "bindDN " -w password \
          -b "uid=%s,ou=people,dc=Siroe,dc=com" -i inputFile \
          -k -M 'telephonenumber:10:[0-9]'

This command will use a single thread to keep a connection open (-k) to repeatedly bind with the given credentials and perform a modify operation on an entry whose UID is randomly chosen from the inputFile . The LDAP protocol allows clients to bind multiple times without unbinding, and this test measures performance in this situation.

Modify Rate Alone

$ modrate -h hostname -p port -D "bindDN " -w password \
          -b "uid=%s,ou=people,dc=Siroe,dc=com" -i inputFile \
          -K -M 'telephonenumber:10:[0-9]'

This command will use a single thread to keep the connection and the bind open (-K) and repeatedly perform a modify operation on an entry whose UID is randomly chosen from the inputFile at each iteration. This will isolate the performance measurements of the modify operation alone.