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.