Messaging Server Administrator's Guide: Mailstone Utility
 


Mailstone Utility

This document describes how to use Mailstone 4.1 for capacity planning and testing on Netscape Messaging Server (versions 3.x and 4.x).

This document contains the following sections:


About the Mailstone Utility
The Mailstone utility is a stress-testing tool that system administrators can use to determine Netscape Messaging Server capacity by testing how the server performs under load. You can use Mailstone on all Unix platforms supported by Netscape Messaging Server and also on Windows NT.

Mailstone can also be used to similarly test and compare other mail servers that support SMTP, POP, and IMAP protocols.

Mailstone simulates tasks that users might perform. It lets you simulate worst-case loads--for example, Monday at 9 a.m., when most users are checking their mail and sending and receiving messages--so you can determine what maximum load your messaging server can take.

Mailstone can be used to test the load-carrying capabilities of a system configuration before it is put into use. Based on how well a mail server handles the loads generated by Mailstone, you can determine whether your current deployment configuration is adequate, or whether you need additional or more powerful server machines.

Mailstone measures both throughput and response time of the mail server being tested. Mailstone reports the number and size of messages sent, the rate at which messages (and bytes) pass through the system, and the average time taken to both transmit a message to the server and receive a message from the server. Mailstone can present its results in both text and graphical format.

Mailstone is run on a client machine (referred to as testmaster in these instructions).

The Mailstone testbed consists of the testmaster machine, any testclient machines, the Messaging Server to be tested, plus the network configuration and Directory Server. (See Figure 0.1.)

Figure 0.1 Mailstone Testbed (Unix environment)

When Mailstone is run on the testmaster machine using the mstone command the following happens:

  1. Command line arguments are combined with configuration files to define the test.
  2. The test processes are executed across the testbed. (In Unix environments rsh is used to run the processes on the other client machines.)
  3. Results are collected and displayed on the HTML results page.

Installing Mailstone
You can install Mailstone at the same time as Messaging Server by choosing Mailstone as one of the Messaging Server components to be installed. See your Messaging Server installation instructions for details on how to do this. The Mailstone software that is installed at the same time as Messaging Server is a version for the same operating system used by Messaging Server.

The instructions in this section describe how to install an all-platforms version of Mailstone separate from a Messaging Server installation. This Mailstone version can be used to test Messaging Server or any other Mailstone-compatible email server. (If you initially install Mailstone as part of Messaging Server installation and later want to install the all-platforms version of Mailstone, see Reinstalling Mailstone.)

To transfer, extract, and install the all-platforms version of the Mailstone archive files follow these steps:

  1. Locate the Mailstone archive file for your platform.
  2. (The contents of both files are identical. Different file types are provided for convenience.)

    For Unix the file is mailstone-4.1.tar.gz.

    For Windows NT the file is mailstone-4.1.zip.

  3. Choose the testmaster machine on which you will run Mailstone and copy the archive file to a temporary installation directory, such as /tmp, on that machine.
  4. The testmaster machine can be the same machine as the server being tested, or a different machine.

  5. Go to the testmaster directory immediately above where you want the Mailstone software to be installed.
  6. For example, if you go to /usr/netscape Mailstone will be installed in
    /usr/netscape/mailstone.

  7. Extract the Mailstone files.
  8. In Unix environments:

    gunzip -c /tmp/mailstone-4.1.tar.gz | tar xf

    In Windows NT environments:

    unzip \tmp\mailstone-4.1.tar.zip

    The extraction process creates the required Mailstone files and places them in a mailstone directory and associated subdirectories.

    The mailstone directory is created as a subdirectory of whatever directory you are in when you extract the files.

    See Table 0.1 for a description of the main Mailstone files.

Once Mailstone is installed, you set up (configure) each test as described in Setting Up Mailstone Tests and then run the mstone program as described in Running Mailstone.

Reinstalling Mailstone

If you initially install Mailstone as part of Messaging Server installation and later want to install the all-platforms version of Mailstone, or you want to reinstall Mailstone for any other reason, you must first perform the following steps before using the installation procedure described above.

  1. Go to the mailstone directory.
  2. For example: cd /usr/netscape/mailstone.

  3. Rename the mailstone/conf directory.
  4. For example: mv conf conf.save.

  5. Rename (or remove) the mailstone/bin directory.
  6. For example: mv bin bin.old.

  7. Rename (or remove) the mailstone/gnuplog directory.
  8. For example: mv gnuplot gnuplot.old.

  9. Rename (or remove) the mailstone/gd directory.
  10. For example: mv bin gd.old.

  11. Rename (or remove) the mailstone/perl directory.
  12. For example: mv bin perl.old.

The Mailstone Files

By default, Mailstone files are stored in a directory named mailstone and in its subdirectories. These directories are created when the Mailstone files are extracted with tar (Unix) or are unzip (NT). File names are the same for both Unix and NT platforms, except that in some cases NT files have filename extensions such as .exe or .bat.

The main Mailstone files are listed in Table 0.1 (ancillary files are not listed). Where no subdirectory is shown, the file is in the mailstone directory.

Table 0.1 Important Mailstone files

File
Description
mstone
The command script that you run to perform a Mailstone test as described in Running Mailstone.
cleanup
A script that removes Mailstone software and files from testclient machines (Unix environments only).
install
A text file giving additional information on installation procedures.
process
A script to reprocess test results with different labels and descriptions. This does not rerun the test.
README
A text file providing additional information about using Mailstone.
setup
A script that prepares your systems for a test series by copying the correct version of Mailstone software and the specified test messages to the /var/tmp directories in Unix environments or the %TEMP directory in NT environments. See Running Mailstone.
checktime

A utility that checks the current system time on all machines that are part of the test. (Unix environments only). See Synchronizing Client Machines.
timesync

A utility the synchronizes the system time on all machines that are part of the test. (Unix environments only). See Synchronizing Client Machines.
conf/all.tbd

The machine configuration file that you use to specify the machines participating in the test and the number of processes and threads on each machine. See Machine Configuration File (all.tbd)
conf/general.doc

The system data file that describes the system configuration. The contents of general.doc are appended to the test result output. See System Data File (general.doc).
conf/general.wld

The general configuration file you use to specify general configuration parameters for the test as a whole. See General Configuration File (general.wld).
conf/impap.pl

A sample primary configuration file (testname script) for IMAP servers. See Primary Configuration File (testname.pl), Running Mailstone.
conf/imap.wld

The workload configuration file you use to specify IMAP configuration parameters including command weighting. See Workload configuration File (testname.wld).
conf/pop.pl

A sample primary configuration file (testname script) for POP servers. See Primary Configuration File (testname.pl) and Running Mailstone.
conf/pop.wld

The workload configuration file you use to specify POP configuration parameters including command weighting. See Workload configuration File (testname.wld).
conf/popimapsmtp.pl

A sample primary configuration file (testname script) for POP, IMAP, and SMTP service. See Primary Configuration File (testname.pl) and Running Mailstone.
conf/popimapsmtp.wld

The workload configuration file you use to specify POP, IMAP, and SMTP configuration parameters including command weighting. See Workload configuration File (testname.wld).
conf/popsmtp.pl

A sample primary configuration file (testname script) for POP and SMTP service. See Primary Configuration File (testname.pl) and Running Mailstone.
conf/popsmtp.wld

The workload configuration file you use to specify POP and SMTP configuration parameters including command weighting. See Workload configuration File (testname.wld).
conf/sample.wld

A text file describing the various configuration files.
conf/smtp.pl
conf/smtp.wld

Message configuration files used to specify delivery rates for different message types. See Message Configuration File.
/data/en-*.msg
The "filler" message bodies that Mailstone uses when it sends messages during testing. See Test Messages.
ldif/create_accounts_ldif
A script to create user accounts for a Mailstone test. See Establishing the Test User Base.
ldif/create_broadcast.ldif
A script to create broadcast accounts for a Mailstone test. See Establishing the Test User Base.
ldif/postmasterldif
Configuration script for creating user accounts. See Establishing the Test User Base.


Setting Up Mailstone Tests
To configure for a Mailstone test run, you typically perform the following steps:

  1. Specify your general test parameters that will apply to all test runs in your General Configuration file.
  2. By default, this file is named general.wld. See General Configuration File (general.wld).

  3. Specify testbed machine parameters in the Machine Configuration file.
  4. These machine parameters can be used for multiple test runs. By default, this file is named all.tbd. See Machine Configuration File (all.tbd).

  5. Edit the contents of your System Data file to specify the system configuration data you want appended to test results.
  6. By default, this file is named general.doc. See System Data File (general.doc).

  7. Customize parameters for a specific test in one or more primary configuration files.
  8. By default, these files use the naming format testname.pl, where testname identifies a file containing test parameters for a single test run. The testname.pl file is used on the command line with the mstone command to run a specific test. See Primary Configuration File (testname.pl).

  9. Customize service and command parameters for a specific test in a workload configuration file.
  10. By default, these files use the naming format testname.wld, where testname matches the name of the corresponding primary configuration file. See Workload configuration File (testname.wld).

  11. Create or modify any additional configuration files that you specify in the primary or workload configuration files.
  12. These might include additional workload or message configuration files. See Workload configuration File (testname.wld) and Message Configuration File.

  13. If you have not already done so, create the test users as described in Establishing the Test User Base.
  14. (Optional.) Create the test messages to be sent as described in Test Messages.
  15. Since Netscape provides test messages in a range of sizes, you only need to create your own if you want to use sizes or contents different from those already provided.

  16. Run setup to copy messages and executables to testclient as described in Client Machine Setup.
  17. (Even though there are no additional testclient machines in Windows environments, this also has to be done because the testmaster machine acts as a testclient machine.)

  18. (Unix only.) If you are using machines other than testmaster as testclients, run checktime as described in Synchronizing Client Machines to verify that the system clocks are within 2 seconds of each other.
Configuring Test Parameters

You specify Mailstone test parameters in configuration files. Configuration files are stored in the mailstone/conf directory.

Configuration Files

There are different kinds of configuration files:

Note: The primary configuration file (testname.pl) specifies test parameters either in the primary file itself, or by including additional configuration files as described in these instructions. Figure 0.2 diagrams a typical relationship of various Mailstone configuration files as described here. But the setup described here is simply a typical example that uses different files for different kinds of parameters. You can set up your configuration file or files as you wish. For example, you could use different files, or include the different kinds of parameter in the same file.

Figure 0.2 Mailstone test files

Configuration File Command Elements

Table 0.2 describes the various command elements you can use in a configuration file.

Table 0.2 Workload configuration file command elements

Command
Description
<command> </command>
Beginning and ending tags for a command block. Where command can be one of these: SMTP, POP3, IMAP4, default, or graph.
HOSTS=name
Command block attribute specifying that the commands are to be run on a particular testclient. For example,
<IMAP4 HOSTS=client3> specifies that the IMAP4 commands are to be run on the client3 machine.


Note the following:
<default> </default>
Beginning and ending tags for defaults that apply to the entire test run.
<include filename>
Invokes (loads) another configuration file. For example, <include conf/general.wld> specifies that the general.wld file is to be included as a test parameter. You can use multiple <include> statements.
addressFormat format
Specifies the mail address convention for the test users you create.

For format, the user ID is specified as a text string that is the same for all user IDs plus the location of the user ID number which is shown as %ld. For example: test%ld@server1.airius.com specifies test users with names like test0, test1, test2, and so forth. The starting number is specified with the firstAddress command.

See Setting Up Test User-Accounts for a more complete description of address formatting.
checkMailInterval time
Specifies how often to check for mail. For example, checkMailInterval 5s means check for mail every five seconds. The default is every 10 minutes (10m).
file filename
Specifies a file containing a test message. For example: file en-17k.msg. Test message files are stored in the mailstone/data directory. You can create your own test message files as described in Test Messages.
firstAddress
The first (lowest) number for test user accounts. For example firstAddress 0 starts test user ID numbers with zero.

See Setting Up Test User-Accounts for a more complete description of address formatting.
firstLogin
The first (lowest) number for test login formats. For example, firstLogin 0 starts login ID numbers with zero.

See Setting Up Test User-Accounts for a more complete description of address formatting.
idleTime time
Specifies the number of seconds to delay after connecting before starting the test. For example, idleTime 2m means delay two minutes after connecting. The minimum is five seconds.
leaveMailOnServer N
Can only be used within a POP3 or IMAP4 command block. Specifies whether or not messages are to be marked as read on the server but not deleted.
loginFormat format
Specifies the how test users login to get their email. In most cases, this will be similar to the addressFormat without the @domain component. For example: loginFormat test%ld or
loginFormat server-test%ld.

loopDelay time
Specifies seconds between download checks.
For example: loopDelay 10s creates a delay of 10 seconds between checks.
numAccounts NNN
Specifies the number of accounts (users) to be included in the test. For example, numAccounts 5000 means that 5000 accounts will be included in the test.
numAddresses NNN
Specifies the number of test users for this testbed. To properly stress test your server configurations, you should create as many users as that server is expected to handle when it is in full operation at maximum expected capacity.
numlogins NNN
Specifies the number of logins for this testbed. Normally, this would be the same number as for numAddresses.
numLoops NNN
Specifies the number of checks to perform before closing the connection.

For example: numLoops 200 specifies that 200 checks will be performed before the connection is closed.
numRecips N
Can only be used within an SMTP command block. Specifies the number of users to whom the message is sent.

For example, numRecips 7 causes that message to be sent to seven test users chosen at random.
passwdFormat password
Specifies the password used by the test users you create. If your users were created with the ldif scripts as described in Establishing the Test User Base, this is the password specified at that time. The password is encoded in base64 format.

You can create a single password used by all users. For example, to specify that all have netscape as their password, you would enter:
passwdFormat netscape


Or you can specify that each user have a unique password based on a pattern. For example, to specify that all have passwords in the format of netscapeN, with N a number, you would enter:
passwdFormat netscape%ld

portNum NN
Specifies a non-default port number for a service. If no port number is specified, the default port for that service is used.
server name
The name of the mail server being tested. For example:
server server-2.airius.com.

smtpMailFrom address
Can only be used within an SMTP command block. Specifies the email address of the user from whom test messages are sent. All test messages are sent by the single user specified here.

For example,
server1-test0@server1.airius.com

useEHLO N
By default, HELO protocol is used. You can specify a protocol with useEHLO as follows. This command can only be used within an SMTP command block.
useAUTHLOGIN N
By default SMTP does not require AUTHLOGIN. You can require AUTHLOGIN with useAUTHLOGIN. This can only be used within an SMTP command block. If you require AUTHLOGIN, you must also specify the EHLO protocol with useEHLO 1.
weight NN
Specifies the relative frequency of Mailstone running that command. See Weights in Configuration Files for details.

Weights in Configuration Files

Commands in workload files are assigned a weight factor that determines the relative frequency of the command's occurrence. For example, if the numeric weights you have assigned to all commands called by the test add up to 25, and a particular command has a weight of 15, then that command has a 60 percent chance of being chosen every time a command is executed, while a command with a weight of 5 has only a 20 percent chance of being chosen. By adjusting the weight factors for the different commands, you can balance them according to your needs.

Some workload files contain a single command and the weight specification applies to that command. Other workload files contain multiple command blocks, each of which has its own weight specification

Weight commands use the syntax:

weight nn

where nn is a number representing the weight factor of that command, or command block. For example:

weight 9

assigns the numeric weight of nine to that command.

Specifying Times in Configuration Files

Times are specified in configuration commands by a number followed by one of these time unit designations:

For example, 4m specifies a time of four minutes.

General Configuration File (general.wld)

The general configuration file specifies general configuration parameters that apply to all Mailstone tests across this testbed. By default, the general configuration file is named general.wld.

The default general.wld file contains the following lines:

<Default>
server servername
smtpMailFrom from-address
addressFormat addressformat
loginFormat loginformat
passwdFormat password
numAddresses NNN
numLogins NNN
</Default>

See Table 0.2 for a description of command elements. You can modify this file as needed.

Primary Configuration File (testname.pl)

The primary configuration file specifies configuration parameters for an individual test run. The primary configuration file also identifies the other configuration files used by the test. By default, primary configuration files use the naming format: testname.pl, where testname identifies a particular set of test parameters.

When you run a test, the primary configuration file is specified on the command line using this syntax:

mstone testname.pl [options]

Note: Parameters specified in a primary file can be over-ridden by specifying alternate parameters as command-line options when mstone is run. See Table 0.4 for a description of the valid command-line options.

Primary files are PERL scripts that have the filename extension of .pl. Examples in these instruction use testname.pl as the primary configuration file.

Five sample primary files are provided for your use:

You can create and use additional primary files as necessary. You can name your primary files whatever you want so long as you always include the .pl file type extension at the end of the name. (Note that if you store the file in some directory other than mailstone/conf, you must specify a full path on the command line to identify the file.)

These are the operative commands in typical primary configuration files:

The sample.wld file provides additional descriptions of commands you can use in a testname file and how they are structured.

Note: When creating or editing a primary file, all operative commands must come before the #=== Do not edit below this line === marker.

See Table 0.2 for a description of command elements. You can modify these files as needed.

System Data File (general.doc)

The system data file specifies additional data to be added to the test report. That is, at the end of each test run the information in the system data file is appended to the HTML-formatted test results report. By default, this file is named general.doc. Typically, the system data file describes the Messaging Server being tested. However, you can use this file to add any information you wish to the test report.

The system data file is a block of HTML-formatted text that can be inserted into an HTML file.

A typical system data file looks like this:

<PRE>
<B> Mailhost.domain.com </B>
Netscape Messaging Server 4.1 (2/18/99)
E6000
26x250MHz UltraSPARC-II
6.5GB RAM
A3500 w/ 60x9GB 7200 RPM
store: 5 x (10x9 RAID-0)
queue: 1 x (10x9 RAID-0)
</PRE>

Machine Configuration File (all.tbd)

The machine configuration file specifies the machines that make up your testbed. By default, this file is named all.tbd.

The Machine File in Unix Environments

A typical machine configuration file for a Unix environment looks like:

# machine numprocs threads
# can include files the same way the workload files do
# <include conf/moreclients.tbd>

testclient1 procs threads
testclient2 procs threads

where:

testclient1 and other testclient machines are the client machines participating in the test. The testmaster machine can also serve as a test client if you wish, in which case the testmaster machine would be listed. Note however that the Messaging Server machine should not be a testclient machine.

procs is the number of processes on that machine. For example, 4

threads is the number of threads running on that machine. For example, 10.

For example, if your testmaster machine is named antares, and you want it to also be a testclient, and you are using the sirius and polaris machines as additional testclients, your entries might look like this:

antares 4 10
sirius 4 10
polaris 1 1

As a general rule, it is best to first create a small-scale test with few machines and processes to make sure that your configurations are properly interacting. Then build up to a full-scale test that includes multiple client machines to reach or exceed the capacity of the server.

The Machine File in NT Environments

In Windows NT environments, Mailstone can only be run on a single machine. Therefore, the all.tbd file should only contain a single entry for that machine. For example:

localhost 1 50

Workload configuration File (testname.wld)

The workload configuration file specifies the services and commands to be tested, their weights, and the test message files to be used. Typically, there is a corresponding workload file for each different primary file By default, workload configuration files use the filename extension testname.wld, where testname matches the name of the corresponding primary configuration file.

Netscape provides sample workload files for different kinds of tests: imap.wld, pop.wld, smtp.wld, popimapsmtp.wld, and popsmtp.wld. You can create additional workload files as necessary.

Within the file, each command element is placed on its own line.

Command elements for a particular service (SMTP, POP3 or IMAP4) are grouped together as a block between <command> and </command> tags. For example, the command elements that apply to POP3 are placed between <POP3> and </POP3> tags. Attributes such as HOSTS can be added to <command> tags.

Command elements that apply to the entire test run (all services) are grouped together as a block between <Default> and </Default> tags. Note that command elements in a <command> block or <Default> block override any multi-test defaults specified in the general configuration file (general.wld). And a value specified for a command in a <command> block overrides a value specified for that command in a <Default> block.

For example, the operative portions of the sample popsmtp.wld file look like this:

<include conf/general.wld>

<SMTP HOSTS=client1>
file en-1k.msg
weight 10
#numAddresses 200
</SMTP>

<POP3 HOSTS=client2>
weight 10
#leaveMailOnServer 1
</POP3>

<IMAP4 HOSTS=client3>
weight 10
idleTime 5
checkMailInterval 10
numLoops 1000
</IMAP4>

See Table 0.2 for a description of command elements. You can modify these files as needed.

While it is possible to specify all of a test's configuration parameters in the workload file, you may find it more convenient to use separate configuration files for different parameters. These additional configuration files can be called by <include> statements in the primary or workload configuration files. The sample configuration files supplied by Netscape are modeled on this practice of separating different kinds of parameters into separate files, and calling those files with <include> statements in the initial workload configuration file.

Message Configuration File

The message configuration file specifies the message configuration files that identify the names of the files containing messages to be used in the test and the weight (usage ratio) of each message file. In the sample files supplied by Netscape, the message configuration files to be used are specified in the workload configuration file with <include> statements.

By default, message configuration files use the filename convention smtpNNk.wld where NN is a number giving the size (in kilobytes) of the message being specified. Netscape provides sample message configuration files named smtp1k.wld, smtp5k.wld, smtp17k.wld, smtp20k.wld, and smtp32k.wld.

You can create additional workload files as necessary. The operative portion of a sample message configuration file is shown below:

<SMTP>
file en-name.msg
numRecips N
weight N
</smtp>

(As an alternative to using message configuration files, you could simply insert these message-related commands in the workload configuration file itself.)

If you want to use multiple messages of different sizes in a test, you list multiple message configuration files, each specifying a message file of a different size. For example, to use 1K, 17K, and 20K messages in a test, you would enter the following in the workload configuration file:

<include conf/smtp1k-a.wld>
<include conf/smtp17k-a.wld>
<include conf/smtp20k-a.wld>

See Table 0.2 for a description of command elements. You can modify these files as needed.

Establishing the Test User Base

In order to test a messaging server, you need to create a set of test users and their mailboxes.

Caution: This set of test users should not include the user IDs of any actual system users.

To properly test your server configurations, you should create as many test users as the server is expected to handle when it is in full operation at maximum capacity.

To establish your user base you do the following:

Setting Up Test User-Accounts

Note: The scripts and instructions described in this section only work with Netscape Messaging Serves and Directory Server. To set up the user base to test some other mail or directory server, you will have to create your user base by hand or use whatever tools those servers provide.

Your test users must be created in your LDAP directory. (Netscape Messaging requires an LDAP directory.)

All test users must have user IDs in the format textNN, or NNtext, where text is a text string that is identical for all user IDs, and NN is a sequence number that is unique for each user ID. For example, if you had 100 users, they might have user IDs of test0 through test99.

If multiple mail servers share a single LDAP directory, all the Mailstone user IDs must be unique across all servers. For this reason, in multiple server environments test users are specified using the format: servername-textNN.

Keep in mind that the naming format you use for your test users has to be noted in your configuration file with the addressFormat configuration parameter, the starting number has to be noted with the firstAddress configuration parameter, and the total number of test users has to be specified with the numAddresses configuration parameter. For example, if you create a thousand test users with IDs like server1-test0, server1-test1, server1-test2, your corresponding configuration parameters would look like this:

addressFormat server1-test%ld@server1.airius.com
loginFormat server1-test%ld
firstAddress 0
numAddresses 1000
numLogins 1000

Mailstone includes two PERL scripts named create_accounts_ldif and create_broadcast_ldif. These scripts are stored in mailstone/ldif. You can use these scripts to facilitate the creation of the user accounts needed to test a Netscape Messaging Server working with a Netscape Directory Server.

Before running the create_accounts_ldif and create_broadcast_ldif scripts you need to modify the following lines:

Table 0.3 Required modifications to LDIF scripts

Script's default value
Modification needed
$domain "servername";
The fully qualified domain name (FQDN) of the mail server being tested, as listed in your LDAP directory. For example:
$domain = "server1.airius.com";

$mailhost "mailhost";
The fully qualified domain name (FQDN) of the machine that will act as the user's mail host. For example,
$mailhost = "mailserver.airius.com";

$basedn "o=netscape, c=US";
The base distinguished name (DN) for directory searches on your directory.
$userbase "format";
The base text string from which to construct user account names for the test. The text string specified here must match the text string specified for the addressFormat parameter in your configuration file (without the %ld). For example, test or server1-test.
$userpassword "passwd";
The password for all user accounts. This must match the passwdFormat attribute in the configuration file.

NOTE: If you use unique passwords with a replaceable-number format, such as pwd%d, you'll need to bypass or modify this script to accommodate that format.

$firstaccount 0;
The number of the first account to use. This number must match the number specified for the firstAddress parameter in your configuration file.
$num_accounts 2000;
The number of test accounts to create. This should be at least as large as the maximum number of users you expect to use in subsequent tests. This number must match the number specified for the numAddresses parameter in your configuration file
$storebase "p"
On large systems where users are stored in multiple partitions, such as p0, p1, p2, and so on, this identifies partition base name.
$maxstores "4";
This specifies the number of partitions you are using.
$bcastacct "spam";
(For the create_broadcast_ldif script only.) Name of the broadcast account.

Note: Passwords for your test accounts can be the same for all users. For example, you could use the password netscape for all test users. This would be specified in the general configuration file as passwdFormat netscape. Or you can create unique passwords for all test users by defining a password format that includes a number. For example, netscape0, netscape1, and so on, which would be specified in the general configuration file with passwdFormat netscape%ld.

If you decide to use numbers, you have to bypass or modify this script to accommodate that format.

After editing the scripts as described above, you run the create_accounts_ldif script to create an LDIF file that contains directory entries for all the test user accounts:

# perl/perl ldif/create_accounts_ldif > accounts.ldif 

You then add the test LDIF file's entries to your directory. You can use either of the following to update the LDAP Directory from the accounts.ldif file:

Caution: Do not import the test LDIF file. If you import the file, you will create a completely new LDAP database that overwrites your existing directory.

Adding Test Users with Database Manager

You can use the Database Manager feature to add the test user account information in the accounts.ldif file to the LDAP Directory on your instance of Directory Server.

Note: This process will go faster if you first disable access logging on Directory Server.

Directory Server 4.x. To add test users with Directory Server version 4.x, follow these steps:

  1. Make sure the Directory Server is running.
  2. Start up Netscape Console.
  3. Log in.
  4. Open the Server Group containing the instance of Directory Server you want to use.
  5. Double-click the name of the Directory Server.
  6. Click the Configuration tab.
  7. Right-click Database and select the Import menu option.
  8. Enter the name of the file containing your LDIF modifications in the dialog box.
  9. For example, accounts.ldif.

  10. Select Append Data to Database.
  11. Select Add Only.
  12. Select Continue on Error.
  13. Click OK.
Caution: If you are using the Database Manager to update a Netscape Directory Server be sure to use Directory Server's Append Data and Add Only options so as not to overwrite any other entries.

Directory Server 3.x. To add test users with Directory Server version 3.x, follow these steps:

  1. Make sure the Directory Server is running.
  2. Log in to the Directory Server.
  3. You must have read and execute permission to use Database Manager and read and write permissions for the targeted entries in the LDAP directory. (You can run this remotely using -h host.)

  4. Go to the Database Manager screen as described in your Directory Server documentation.
  5. Select the Add Entries form.
  6. In the Full Path to LDIF File field, enter the full absolute path name to the accounts.ldif file that contains the test user entries you want to add.
  7. For example: /usr/local/mailstone/ldif/accounts.ldif

  8. Change to Bind to Server field if needed.
  9. Enter the Password.
  10. Click Okay. The entries are added to your Directory Server manager.
Caution: If you are using the Database Manager to update a Netscape Directory Server, be sure to use the Directory Server's Add Entries user interface so as not to overwrite any other entries.

See the Directory Server Administrator's Guide and online help for more information on adding entries to Netscape Directory Servers.

Adding Test Users with ldapmodify

You can use the ldapmodify command line utility to add the test user account information in the accounts.ldif file to the LDAP Directory instance on your Directory Server.

Note: This process will go faster if you first disable access logging on the Directory Server.

The ldapmodify utility is located in server-root/userdb/ldap/tools.

To update the LDAP Directory with ldapmodify, follow these steps:

  1. In Unix environments, make sure your LD_LIBRARY_PATH environment variable is correctly set.
  2. For example:

    setenv LD_LIBRARY_PATH /usr/netscape/messaging/lib

  3. Make sure the Directory Server is running.
  4. Log in to the Directory Server system as root.
  5. Go to the directory containing the LDIF files.
  6. For example: ../mailstone/ldif/accounts.ldif

  7. Run ldapmodify to update the LDAP Directory.
  8. For example:

    shared/bin/ldapmodify -h mailhost -a \
    -D 'cn=directory manager' -w d_m_password \
    < accounts.ldif

Caution: If you are using ldapmodify to update a Netscape Directory Server be sure to use the -a option so as not to overwrite any existing entries.

See the Directory Server Administrator's Guide, and online Help for more information on adding entries to Netscape Directory Servers and the ldapmodify utility.

Setting Up Test Mailboxes

One way to create mailboxes for the test users in your LDAP directory is by simply running a Mailstone test. However, since creating mailboxes by running a test is time consuming, Netscape provides the create_broadcast_ldif script that can be used with a Netscape Messaging Server to more efficiently create mailboxes for test users. (This script will not work with other mail servers.)

To create mailboxes for your test users using the script, follow these steps:

  1. Edit the create_broadcast_ldif script as described in Table 0.3
  2. Run the create_broadcast_ldif script as follows:
  3. # ./create_broadcast_ldif >> mailboxes.ldif

    Running this script creates the spam broadcast address that initially constructs the user mailboxes.

  4. Import the mailboxes.ldif file just as you imported the accounts.ldif file.
  5. You can import the file using the Database Manager as described in Adding Test Users with Database Manager, or with ldapmodify as described in Adding Test Users with ldapmodify.

Test Messages

The standard test messages used by Mailstone during a test run are contained in message files which are themselves stored in the mailstone/data directory. Five message files of varying sizes are provided for you: en-1k.msg, en-5k.msg, en-17k.msg, en-20k.msg, and en-32k.msg. The number indicates the size of the message in kilobytes. For example, the en-17k.msg file is about 17K long.

(You specify which of message files are to be used in a test with a file en-name.msg statement in the message configuration file as explained in Message Configuration File.)

You can create additional message files as needed. (In Unix environments with testclient machine, if you create new message files you also need to rerun setup to copy the new files to the testclients.)


Setting Up Testclient Machines
Windows NT. In Windows NT environments, the testmaster machine is also the only testclient machine. Therefore, the entire test must be run on a single machine.

Unix. In Unix environments, you can use multiple client machines to put stress on a single server machine.

Note: You should not use the machine hosting Messaging Server as a testclient machine.

Client Machine Setup

To set up clients in both Unix and Windows NT environments, you run the setup utility which is stored in the mailstone directory.

Unix. In Unix environments the setup utility copies the necessary software and configuration information to the testmaster and client machines listed in your machine configuration file (all.tbd).

Windows NT. In NT environments, the setup utility copies the necessary software and configuration information to the client directories of the testmaster machine.

If there is existing test configuration information, the utility replaces the old data with new data.

The setup utility uses the following syntax:

setup -m conf/all.tbd

By default, the setup utility uses testbed data contained in the machine configuration file named all.tbd. If you wish to use a different machine configuration file, you specify that file on the command line with the -m option.

To remove Mailstone files from Unix client machines, run the cleanup utility. The cleanup utility uses the following syntax:

cleanup [-m machine.tbd]

Synchronizing Client Machines

For accurate test results it is important that the testmaster and all of the testclient machines show exactly the same time on their system clocks. If at all possible, the times should be identical to less than a second.

Windows NT Note: Since you only have one machine in a Windows NT environment, synchronization as described in this section is not necessary.

To check for time consistency run the checktime utility. The checktime utility uses the following syntax:

checktime [-m machine.tbd]

By default, the checktime utility uses testbed data contained in the machine configuration file (all.tbd). If you wish to use a different machine configuration file, you specify that file on the command line with the -m option.

The checktime utility reports the time for each system. If there are discrepancies of more than a second you need to adjust the system clocks.

The timesync utility is stored in the mailstone directory. You must run timesync as root, and you must have root rsh permissions. The timesync utility uses the following syntax:

timesync [-m machine.tbd]

By default, the timesync utility uses testbed data contained in the machine configuration file named all.tbd. If you wish to use a different machine configuration file, you specify that file on the command line with the -m option.


Running Mailstone
To run a Mailstone test:

  1. Configure the test as described in Setting Up Mailstone Tests.
  2. If you have not already done so, set up your client machine or machines as described in Client Machine Setup.
  3. If you have additional testclient machines in a Unix environment, synchronize them as described in Synchronizing Client Machines.
  4. Run the mstone command using the syntax:
  5. mstone testname [options]

    where testname is the primary configuration file. For example:

    mstone popsmtp

    If your primary configuration file is not stored in mailstone/conf or it does not have the filename extension .pl, you must specify the full name and path.

You can specify command line options as needed. Options specified on the command line override any corresponding configuration parameters in a configuration file. For example, if the configuration file sets the test run time to two hours, but you only want to make a brief trial run of 10 minutes to make sure that the configuration is correct, you would enter this:

mstone popsmtp -t 10m

Table 0.4 describes the command line options you can use with the mstone command.

Table 0.4 mstone command line options

Option
Description
-b banner
Specifies the banner (title) to be displayed as part of test results, where banner is the actual text you want displayed enclosed by quotation marks. For example:
-b 'POP reads (full store)'

-m machinefile
Specifies a Machine Configuration file, where machinefile is the name of the file including a relative path. For example:
-m conf/all.tbd

-r ramptime
Specifies the ramp time, where ramptime is a number and time unit designation. For example, to set a ramp time of 10 seconds:
-r 10s

-t time
Specifies the length of time the test is to run, where time is a number and time unit designation. For example, to set a test run of 20 minutes:
-t 20m

Mailstone in Unix Environments

When run on Unix servers, Mailstone makes use of the following Unix-specific capabilities:

Note: For tests with large number of threads, you may need to run mstone as root in order adjust file descriptor limit.

Checking Results in Mid Test

During a long test run, you can display the current results by running the process command. For example:

process

The process command does not stop or abort a test run; it simply displays the results of the current test up to the point the command was run. In other words, if you run process after 45 minutes, you will see results based on the first 45 minutes of data.

The process command can be used early in a long test run to make sure that it is functioning properly with the correct configuration parameters.

Note: Do not run process when the test run has less than 15 minutes to go before finishing.

Redisplaying Old Test Results

You can also use the process command to reprocess and display older test runs by specifying the data directory on the command line. For example, to reprocess the results of a test that was run on July 14, 1999 at 14:31 which are stored in the mailstone/results/19990714.1431 directory, you would enter this:

process 19990714.1431

Aborting a Test Run

To stop a test run before it has completed, enter Control-C or use any other standard method of halting an ongoing process.


Reviewing Test Results
All of the results files from each Mailstone test run are placed in a time-stamped subdirectory of the mailstone/results directory. For example, the results of a test run on July 14, 1999 at 14:31 (24 hour clock) are stored in a subdirectory named: mailstone/results/19990714.1431.

The Results Page

Mailstone displays the results of a test run as an HTML page named results.html. There is one results file in each test run subdirectory.

An HTML-formatted index of all test runs is created and maintained in the mailstone/results/index.html file. This file contains live links to the results.html files from every test run.

The top portion of a typical results file is shown in Figure 0.3. (Your results will vary depending on how you configured your test run.)

Figure 0.3 Example Mailstone test result page (top portion)

In this illustration:

Following the test result tables, the results file displays the tests results as a series of graphs. At the end of the results.html file under the heading "Details" is a description of test run parameters. This is the text you specified in the system data file (general.doc). A typical description is shown in Figure 0.4.

Figure 0.4 Example Mailstone test results page (test description)

About the Test Results

Mailstone breaks each client session into timers:

Some stages may be bypasses depending on the protocol and workload.

Each timer tracks variables:

The bytes written and read represent data bytes for the retrieve and submit timers, and protocol bytes for all others.

The number of successful operations is try minus error.

There are also some special timers. The block timer counts the number of workload command blocks that have been executed. This can help indicate problems with the workload files.

The mailstone results tables are split into three sections.

For readability, values may be displayed in K bytes (1024), M bytes (1048576), and G bytes (1073741824) and rounded off.

The steps involved for each protocol are as follows (the timers affected are listed in upper case).

IMAP4 protocol steps:

CONNECT by TCP.

Read the BANNER.

LOGIN with ID and password.  

Get response.

IDLE for idleTime.

Repeat this part numLoops times (or until test ends)

{

   COMMAND: select inbox folder. Get response.

   Read each new messages

   {

      COMMAND: Fetch the message size. Get response.
      RETRIEVE message. Get data.

      COMMAND: Send noop. Get response.

      COMMAND: Mark message as deleted and seen. Get response. 

   }

   COMMAND: Expunge deleted messages. Get response. 

   IDLE for loopDelay

}

LOGOUT

IDLE for blockTime

POP3 protocol steps:

CONNECT by TCP.

Read the BANNER.

LOGIN with ID and password. Get response.

COMMAND: stat how many message are available. Get response.

IDLE for idleTime

Repeat this part numLoops times (or until out of messages or test ends)

{

   RETRIEVE message. Get data.

   Unless leaveMailOnServer is set, COMMAND: delete message. 
Get response.

   IDLE for loopDelay

}

LOGOUT

IDLE for blockTime

SMTP protocol steps:

CONNECT by TCP.

Read the BANNER.

If useEHLO is set 

{

   COMMAND: send EHLO. Get response and capabilities.

}

Else 

{

   COMMAND: send HELO. Get response.

}

If useAUTHLOGIN is set and AUTH=LOGIN capability is available on 
the server

{

   LOGIN with ID and password. Get response.

}

IDLE for idleTime

Repeat this part numLoops times (or until test ends)

{

   COMMAND: send mail from smptMailFrom. Get response.

   Repeat numRecips times.

   {

       COMMAND: send mail recipient. Get response.

   }

   COMMAND: initiate message body. Get response.

   SUBMIT message. Get response.

   IDLE for loopDelay

}

LOGOUT

IDLE for blockTime

Interpreting Test Results

Consider these two points when reviewing the results of a Mailstone performance analysis:

The principal factors that can distort server statistics are byte throughput and message throughput. After running Mailstone a few times, you may notice that the server byte throughput is directly proportional to the average SMTP message (file) size, and you may also notice that message throughput (as well as byte throughput) is distorted by larger than normal mailboxes. Therefore, be sure to configure your Mailstone tests to reflect your actual or projected messaging characteristics. For example, if during your peak activity in the morning you handle up to 2,000 employees sending an average of 5 messages of 20K average size and receiving 25 messages of same size your test should reflect that. The more accurately your input reflects the reality of your messaging system, the more relevant will be the data generated by Mailstone.

Mailstone displays the results of a test run in terms of the statistics for each protocol: SMTP, POP3, and IMAP4. With this information, you can determine:

If the number of SMTP connections is not in the acceptable range--that is, not close to the projected usage for your installation--consider adding more client processes or machines or checking the server performance during the run. You should also check the message/connection ratio for POP3/IMAP4 for consistency with your projections, and make any necessary adjustments to the mailboxes before running the next test.

Monitoring the server performance during test runs is crucial in understanding the results. If you have a sufficient number of clients for the test, and yet the desired number of client connections is not being achieved and the server CPU usage and process run queue is not settling down after the initial load spike, you may need to modify your server architecture to increase capacity. The bottom line is to determine whether the messaging solution can handle the type of load expected in an acceptable manner.

Note: By default both Netscape Messaging Server and Directory Server are shipped with access logging enabled. This may result in reduced performance. When testing a server with Mailstone, be sure that access logging is set the way it will be when the server is in actual production use.


Removing Mailstone
To remove Mailstone files from testclient machines, run the cleanup utility. The cleanup utility uses the following syntax:

cleanup [-m machine.tbd]

To uninstall Mailstone, remove the /mailstone directory and all of its subdirectories.

 

© Copyright 1999 Netscape Communications Corp., a subsidiary of America Online, Inc. All rights reserved.