gecko-dev/mstone/INSTALL

		Mstone 4.15 Quick Installation

This version of Mstone runs on many current UNIX platforms and NT.
Only a web browser and text editor are needed to view the results and
configure tests.


QUICK INSTALL
-------------

IMPORTANT: If you have an existing mstone, save a copy of the
mstone/conf directory to preserve any configuration files you may want
to keep.

Unpack distribution:

	tar xzf /tmp/mstone_OPT.tar.gz
or
	gunzip -c /tmp/mstone_OPT.tar.gz | tar xf -
or
	unzip /tmp/mstone_OPT.zip

	cd mstone

Both the tar.gz file and the zip file are identical.  Use whichever is
more convenient for you.

This will create a sub-directory named "mstone" with files and
directories under that.  

cd mstone

NOTE: all scripts must be run from the mstone directory.


Do initial configuration:

Run "mstone config".  It will ask you about your system configuration.
Fill in the appropriate values and create the optional user accounts
and broadcast account.  When it asks about client machines, enter them
separated by commas, with no spaces (e.g. host1,host2,host3).  If you
need to re-configure, run "mstone config".

The machine starting the test may also be a client.  For accurate
results, clients should not be run on the test mailserver machine (or
its directory server).  If all the client machines are not running
the same operating system version, see "Configuring Client Machines"
below to configure for different OSes.

When the test master is on NT, only the local machine may be a client
and only one process is allowed.  You will not be asked about client
machines.

Setup only configures the most important parameters.  If you have more
advanced needs, edit conf/general.wld appropriately.

Run "mstone setup".  It will now push the necessary files to each
client machine.  If there are problems (i.e. with rsh permissions),
fix them and re-run "mstone setup" until everything works.


Install test accounts:

Setup will create a file called conf/MAILHOST.ldif (where MAILHOST is the
name of your mail server).  If you are not using Netscape Messaging
and Directory Servers, then you may have to edit the ldif file or use
alternate means to create the user accounts.

To import these users into Netscape Messaging Server, use "add
entries" from the directory console or use the ldapmodify command line
utility.

Note: imports will go faster if access logging is disabled.  For large
user counts (more than 10,000 users), it may be much faster to export
the current database, merge the files together manually, and then
import the new database.

Here is how the ldapmodify supplied with Netscape Messaging Server
would be used.

setenv LD_LIBRARY_PATH /usr/netscape/messaging/lib
cd /usr/netscape/messaging
shared/bin/ldapmodify -h mailhost -a -D 'cn=directory manager' -w d_m_password < conf/MAILHOST.ldif


Check time consistency:

IMPORTANT: The system time on each client machine must be synchronized
within one second of each other for accurate results graphs.

Run "checktime" to see the time on each client.  There should not be
more than two seconds difference among the displayed time.

The best way to synchronize clients is use NTP (Network Time Protocol)
or similar protocols (like rdate or timeslave) that have sub second
accuracy.

A simple utility called "timesync" is provide to push the local
system time to all clients.  You must be root and have root rsh
permissions to use timesync.  Timesync only works on OSs that support
setting seconds using "date MMDDhhmmCCYY.ss".  Timesync is only
accurate to a second (at best) and should only be used if better
protocols aren't available.

When running the test master on NT, "checktime" and "timesync" are
never needed (because there is only one client machine).  Timesync
will be ignored for NT clients, another method must be used
(e.g. timeserv or Dimension4).


Run tests:

Try it out.  Use small process and thread counts until everything is
working.

mstone pop -t 30s

The script will tell you how many processes and threads it is running
on each system and where errors are logged.  At the end of the test,
it will print out a URL for the test results and an indication of the
size of the errorlog file (stderr).

The results of the mstone run will display statistics for each
protocol that was tested.  The results are presented in both a HTML
web page and a text file.  The text file is simple and uniform, while
the web page is more user readable.  The web page has links to the
test configuration files, error log, and the text version.

For long tests run (e.g. 8 hours), the results can be updated while
the test is running by using the "process" utility.  Don't run
"process" near the very end of the test.

If a test has to be aborted, then use "process" to generate a report
using the available data.


Customize tests:

Copy and edit the scripts (e.g. "conf/pop.wld") to define new tests.
The CONFIG section specifies all the attributes used in the test.
Other sections specify the protocols to be tested and the parameters
for them.

All switches can be overridden on the command line to facilitate
easier testing.  The exact configuration (include command line
overrides) is stored with the results from each test.


Maintenance:

You can run "mstone setup" at any time (except during a test :-) to
update the files on the client machines.

Use "mstone cleanup" to remove the files created by "mstone setup".

After the test is finished, the directories under "tmp/" can be
compressed or deleted to save space.  All the information about a test
run is stored in the "results/" directories.


Configuring client machines:

Edit conf/general.wld to include CLIENT sections for each machines to
use.

You can also specify the OS type for each client machine.  Set the
"Arch" parameter in each CLIENT section as appropriate (e.g. SunOS5.6,
Linux2.2_x86, AIX4.2, HP-UXB.11.00, IRIX6.5, OSF1V4.0, WINNT4.0). The
directories under "bin" specify the available OS types.

For NT4.0 clients with a UNIX test master, you will need to configure
"command" and "tempDir" for proper operation.  See the "HOSTS=winnt01"
example in conf/sample.wld.

The total number of processes and threads that can be supported on a
client is dependent on the number of commands in the test, the OS, and
available memory.  Check the stderr log for messages about not being
able to create processes or threads.  Check on the client machines
during the test and make sure they aren't running out of CPU.  The
UNIX programs "top" and "vmstat" are good for this.  If the client CPU
is more than 75% busy, use more machines.

Also watch out for network saturation.  You may have to use machines
with separate networks to the server to reach full server load.


Know problems:

There can be extraneous errors or connections after the specified end
of the test.  These are most likely do to stopping the test and should
be ignored.

At the end of the test, all current connections will logout without
any delays.  This can cause very high peak loads.

If one process exits early (due to misconfiguration or resource
exhaustion) and the monitoring command did not specify a count (%c),
then the monitoring tasks will be terminated early as well.

Monitoring commands that specify a count (%c), may take longer than
predicted and delay the processing of test results.  This is because
vmstat actually delays the requested time plus the time needed to
generate the statistics summary.

If you are doing tests with large thread counts, you may have to run
as root to allow mailclient to raise its resource limits.

The telemetry logging for SMTP, POP3, and IMAP4 is incomplete.  Most
commands are captured, but banners and message contents may be missing.

The MaxBlocks parameter gets divided by the total number of processes
before starting each client.  This doesn't account for clients that
don't have commands to run.

The HTTP protocol used by WMAP allows connections to be dropped and
re-connected as needed.  WMAP logs this as an error and an additional
connect.  The error log must be consulted to distinguish another types
of connection errors (timeout or connection refused) from an automatic
re-connect.

The HTTP protocol test is experimental and subject to change.