
		Mstone 4.9.4 Quick Installation

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

This file is for installing a binary distribution of mstone.  If you
are building from source, read Building.txt and then return here.


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.tar.gz
or
	unzip /tmp/mstone.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

IMPORTANT! all scripts must be run from the mstone directory!  mstone
will save data within this directory, so you have to have your own
(writable) copy.


Do initial configuration:

Run "mstone config".  It will ask you about your system configuration.
Fill in the appropriate values and (if needed) create the optional
user accounts and broadcast account.  When it asks about client
machines, enter them seperated 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.

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 (for e-mail testing):

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 result graphs.

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

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


Run tests:

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

./mstone pop -t 30s -l 1

The script will tell you how many processes and threads it is running
on each system and where errors are logged.  It will print out a URL
for the test results and update it once a minute while the test runs.

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 machine
friendly, while the web page is more human readable.  The web page has
links to the test configuration files, error log, and the text
version.

If you need to abort the run, type Ctrl-C and then wait for it to
shutdown all the clients.  This can take up to three minutes.  If the
reports are lost or corrupt, use "./process" to re-generate the
reports.


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.


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.


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 with gzip or deleted to save space.  All the information
about a test run is stored in the "results/" directories.


Known problems:

There can be extraneous errors or connections after the test end time.
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.  See IMAP_RAMPDOWN
in the documentation for a way to control shutdown in the most common
case.

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 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 very limited and experimental.
