Slamd Admin Guide

Administration and Usage Guide
SLAMD Distributed Load Generation Engine
Version 1.8.1
December 2004
Contents
1. Introduction...............................................................................................................5
2. Installation Prerequisites.........................................................................................6
3. Installing the SLAMD Server....................................................................................8
4. Using SLAMD Clients.............................................................................................12

Using the Client Manager.......................................................................................................15
Using the Swing-Based GUI Client........................................................................................16
Using the Resource Monitor Client........................................................................................17
5. Using the Administration Interface.......................................................................29
6. Scheduling Jobs for Execution.............................................................................31

Using the Command-Line Job Scheduler..............................................................................35
7. Managing Scheduled Jobs.....................................................................................40

Pending Jobs..........................................................................................................................40
Running Jobs..........................................................................................................................43
Completed Jobs......................................................................................................................44
8. Viewing Job Execution Results.............................................................................48
9. Optimizing Jobs......................................................................................................52
Pausing an Optimizing Job.....................................................................................................56
Scheduling Optimizing Jobs from the Command Line..........................................................57
10.Organizing Job Information..................................................................................60

Real Job Folders.....................................................................................................................60
Virtual Job Folders..................................................................................................................61
2 SLAMD Administrator's Guide

Searching for Job Information................................................................................................62
Uploading Files into Job Folders............................................................................................63
11.Adding New Job Classes......................................................................................65

Installing Job Packs................................................................................................................66
12.Using the Standalone Client.................................................................................67
13.Configuring the SLAMD Server............................................................................69

Configuration Directory Settings............................................................................................69
Core SLAMD Server Configuration........................................................................................70
Mailer Configuration...............................................................................................................72
Logger Configuration..............................................................................................................73
Logger Thread Configuration.................................................................................................74
Client Manager Listener Configuration..................................................................................74
Client Listener Configuration..................................................................................................75
Resource Monitor Client Listener Configuration....................................................................77
Real-Time Stat Listener Configuration...................................................................................77
Scheduler Configuration.........................................................................................................78
User Interface Configuration..................................................................................................79
Exporting and Importing Job Data.........................................................................................84
Generating Reports................................................................................................................85
14.Starting and Stopping SLAMD..............................................................................86

Starting the Tomcat Servlet Engine.......................................................................................86
Starting SLAMD......................................................................................................................86
Restarting SLAMD..................................................................................................................87
Stopping SLAMD....................................................................................................................87
Stopping the Tomcat Servlet Engine.....................................................................................88
15.Tuning the Configuration Directory.....................................................................89
16.Configuring Tomcat...............................................................................................91
17.Configuring Access Control.................................................................................95

Configuring Tomcat to Require Authentication for HTTP Clients.........................................95
Configuring SLAMD to Use Access Control..........................................................................97
Restricting Access to Features in SLAMD.............................................................................98
Configuring the SLAMD Server to Operate in Read-Only Mode........................................101
Enabling Restricted Read-Only Mode.................................................................................101
3
Configuring the Client Listener to Require Client Authentication........................................103
18.Using SSL with SLAMD.......................................................................................105

Configuring the JSSE Certificate Database.........................................................................105
Enabling SSL for Communication with Web Browsers.......................................................108
Enabling SSL for Communication with SLAMD Clients......................................................109
Enabling SSL between SLAMD and the Config and User Directories................................109
Enabling SSL Between Tomcat and the User Directory.....................................................111
Copying an NSS-Based Certificate to a JSSE Keystore.....................................................112
19.Interacting with SLAMD from the Command Line............................................114

Specifying the SLAMD Configuration Directory Settings....................................................115
Adding SLAMD Schema Information to the Configuration Directory..................................116
Adding SLAMD Configuration to the Configuration Directory.............................................116
Starting the SLAMD Server..................................................................................................116
Stopping the SLAMD Server................................................................................................117
Restarting the SLAMD Server..............................................................................................117
Reloading Job Class Definitions..........................................................................................117
Retrieving SLAMD Status Information.................................................................................118
Retrieving Log File Information............................................................................................118
Retrieving Job Data..............................................................................................................119
Saving Job Data to Tab-Delimited Text...............................................................................120
Cancelling a Scheduled Job.................................................................................................121
Enabling and Disabling Scheduled Jobs.............................................................................121
Adding Job Classes..............................................................................................................122
Installing Job Packs..............................................................................................................122
Creating and Deleting Job Folders......................................................................................123
Exporting Job Data...............................................................................................................123
Importing Job Data...............................................................................................................124
Uploading Files.....................................................................................................................124
Listing Job Folders...............................................................................................................125
20.Troubleshooting SLAMD Problems...................................................................126

General Server Troubleshooting..........................................................................................126
General Client Troubleshooting...........................................................................................128
Jobs Won't Start...................................................................................................................129
Running Out of Memory.......................................................................................................130
Administrative Interface Problems.......................................................................................131
21.SLAMD License....................................................................................................133

Introduction
The SLAMD Distributed Load Generation Engine is a Java-based application

designed for stress testing and performance analysis of network-based
applications. Unlike many other load generation utilities, SLAMD provides an
easy way to schedule a job for execution, either immediately or at some point in
the future, have that job information distributed to a number of client systems,
and then executed concurrently on those clients to generate higher levels of load
and more realistic usage patterns than a standalone application operating on a
single system. Upon completing the assigned task, the clients report the results of
their execution back to the server where the data is combined and summarized.
Using an HTML-based administrative interface, users can then view those results
either in summary form or in varying levels of detail. Users may also view
graphs of the statistics collected and may even export that data into a format that
may be imported into spreadsheets or other external applications for further
analysis.
The SLAMD environment is also highly extensible. Custom jobs that interact
with network applications and collect statistics may be developed either by
writing Java class files or executed using the embedded scripting engine. The
kinds of statistics that are collected while jobs are being executed may also be
customized, as well as the kinds of information that may be provided to a job to
control the way in which it operates. Although it was originally designed for
assessing the performance of LDAP directory servers, SLAMD is quite well
suited for interacting with any network-based application that uses either TCP- or
UDP-based transport protocols.
This document provides information about installing and running the components
of the SLAMD environment. Additional topics, like developing custom jobs for
execution in the SLAMD environment, are not discussed here but are detailed in
other documents.
Introduction 5
Installation Prerequisites
Before SLAMD may be installed and used, there are a number of preliminary
requirements that must be satisfied:
All components of the SLAMD environment have been written in Java and
therefore a Java runtime is required to use them. All components have been
developed using the Java 1.4.0 specification, and version 1.4.0 or higher of the
runtime should be installed on the system that will host the SLAMD server as
well as all systems that will be used to run the SLAMD client. Any system
that will be used to develop custom jobs for execution in the SLAMD
environment should have the Java 1.4.0 or higher SDK installed.
NOTE Both the Java runtime and the Java SDK may be obtained online at
http://java.sun.com/.
Some aspects of job execution are time sensitive, and differences in system
clocks can cause inaccuracies in the results that they can obtain. Therefore,
time synchronization should be used on all systems in the SLAMD
environment to ensure that such clock differences do not occur.
The communication that occurs between clients and the SLAMD server
requires that the hostname of those systems be available. The addresses of all
client systems must be resolvable by both the client and server systems through
DNS or some other mechanism like the /etc/hosts file.
Much of the configuration and all of the job data for the SLAMD environment
is stored in an LDAP directory server, and therefore a directory server must be
accessible by the system that will act as the SLAMD server. SLAMD has been
designed and tested with the iPlanet Directory Server 5.1 and the Sun ONE
Directory Server 5.2.
NOTE The entries that store information about scheduled jobs may be quite
large, and therefore it is necessary to ensure that the configuration
directory is properly tuned to ensure that it will be able to properly
handle these entries.

The HTML that comprises the SLAMD administrative interface is dynamically
generated using Java servlet 1.2 technology. A servlet engine required to
provide this capability. By default, SLAMD is provided with the Apache
Tomcat servlet engine and this engine is quite capable of providing the
administrative interface. However, it should be possible to use any compliant
servlet engine to host that interface. In addition to Tomcat, SLAMD has been
tested with the Sun ONE Web Server 6.0 SP3.
Nearly all interaction with the SLAMD server is performed through an HTML
interface. A Web browser must be installed on all systems that will access the
administration interface. SLAMD has been tested with Netscape and Mozilla,
but the administrative interface has been designed in accordance with the
HTML 4.01 specification and therefore any browser capable of rending such
content may be used. Even text-based browsers are quite capable of
performing all administrative tasks.
NOTE If SLAMD is to be used in a purely text-based environment, then it is

recommended that the links browser be installed on systems that need to
access the administration interface. Links is a text-based browser that is
similar to the better-known "lynx" (available at
http://lynx.browser.org/), but provides better support for rendering
tables, which are used throughout the SLAMD administrative interface.
See http://links.sourceforge.net/ for more information.
Installation Prerequisites 7
Installing the SLAMD Server
Once all the prerequisites have been filled, it is possible to install the SLAMD
server. That may be done as follows:
1. Copy the installation archive "slamd-1.8.0.tar.gz" onto the server system

and into the location in which you wish to install SLAMD and extract the files
contained in that archive. All files will be placed in a subdirectory named
"slamd".
NOTE If you wish to use a name other than "slamd" for the base directory, then
you may simply rename that directory immediately after extracting the
installation archive. However, once the SLAMD server has been
started, the path in which it is installed should not be changed.
2. Go into the newly-created slamd directory.
3. Edit the bin/startup.sh shell script. This shell script will be used to start the
SLAMD server and the administrative interface, but it must first be edited so
that the settings are correct for your system. Set the value of the JAVA_HOME
variable to the location in which the Java 1.4.0 or higher runtime environment
has been installed. You may also edit the INITIAL_MEMORY and MAX_MEMORY
variables to specify the amount of memory in megabytes that the SLAMD
server and the administrative interface will be allowed to consume. Comment
out or remove the two lines at the top of the file that provide the warning
message indicating that the startup file has not been configured.
4. Edit the bin/shutdown.sh shell script. This shell script will be used to stop the
SLAMD server and the administrative interface. Set the value of the
JAVA_HOME variable to the location in which the Java 1.4.0 or higher runtime
has been installed and comment out or remove the two lines at the top of the
file that provide the warning message indicating that the shutdown file has not
been configured.
5. Execute the bin/startup.sh shell script to start the Tomcat servlet engine and
make the SLAMD administrative interface available.

6. Start a Web browser and access the SLAMD administrative interface. It will
be available at the URL "http://{address}:8080/slamd", where "{address}" is
the IP address or DNS hostname of the SLAMD server machine. A page
should be displayed indicating that the SLAMD server is unavailable because
it has not yet been configured.
7. Follow the "Initialization Parameters" link to a page on which it is possible to

specify the configuration directory settings. The configuration directory is the
LDAP directory server that will be used to store much of the configuration and
all of the job data for jobs that have been scheduled.
8. Follow the "Config Directory Address" link to be presented with a form that
allows you to specify the address to use for the configuration directory server.
The address must be entered as either an IP address or a hostname, as long as
the SLAMD server machine can contact the configuration directory machine
using the provided address. Repeat this process for the remaining
configuration directory settings. The following table describes the kind of
value that should be used by each:
Config Directory Address Specifies the address that should be used to contact the
configuration directory server.
Config Directory Port Specifies the port number that should be used to contact
the configuration directory server.
Config Directory Bind DN The DN of the user that should be used to bind to the
configuration directory server. This DN must have full
read and write permissions (including the ability to add
and remove entries) for the portion of the directory that is
to hold the SLAMD configuration data.
Config Directory Bind Password The password for the configuration bind DN.
Configuration Base DN The location in the configuration directory under which
all SLAMD information will be stored. If this entry does
not exist, then the SLAMD server can create it provided
that the DN specified is under an existing suffix in the
configuration directory.
Use SSL for Config Directory Settings that control whether the communication between
SSL Key Store Location the SLAMD server and the configuration directory is
encrypted with SSL. It is recommended that the initial
SSL Key Store Password
configuration be completed without SSL. See a later
SSL Trust Store Location section for information on configuring SLAMD for use
SSL Trust Store Password with SSL.
Installing the SLAMD Server 9

9. Click the "Add SLAMD Schema" button at the bottom of the Initialization
Settings page. This will communicate with the configuration directory server,
find the schema subentry, and add the custom SLAMD schema definitions over
LDAP while the server is online. This schema information must be added to
the configuration directory before SLAMD can use it to store configuration and
job information.
NOTE If you prefer, you can add the schema information to the directory
manually rather than over LDAP. A file containing the SLAMD
schema definitions is included in the installation archive as
conf/98slamd.ldif.
10.Click the "Add SLAMD Config" button at the bottom of the Initialization
Settings page. This will automatically add all of the required entries to allow
that directory instance to be used as the configuration directory for SLAMD.
All information added to the directory will be at or below the configuration
base DN.
NOTE At least one entry in the hierarchy of the configuration base DN must
already exist in the directory server before the configuration may be
added to it. For example, if the directory is configured with a suffix of
"dc=example,dc=com" and the configuration base DN is specified as
"ou=SLAMD,ou=Applications,dc=example,dc=com", then at least the
"dc=example,dc=com" entry must already be present in the directory
server before attempting to add the SLAMD configuration data. Any
entries between the directory suffix and the SLAMD configuration base
DN that are not present in the directory will be automatically added
when the "Add SLAMD Config" button is pressed.
11.Click the "Test Connection" button at the bottom of the Initialization Settings
page. This will establish a connection to the configuration directory server,
verify that the bind DN and password provided are correct, verify that the
SLAMD schema and configuration entries have been added to that directory.
If all tests succeed, a message will be displayed indicating that it is suitable for
use as the SLAMD configuration directory. If any failure occurs, details about
that failure will be displayed so that the problem may be corrected.
12.Follow the "SLAMD Server Status" link on the left side of the page. This
page will normally display a significant amount of information about the
SLAMD server, including the number and types of jobs defined, the number of
clients connected, and statistics about the Java environment in which SLAMD
is running. However, when the SLAMD server is offline, much of this
information will not be available.

13.Click the "Start SLAMD" button in the Server Status section and when
prompted, click the "Yes" button to provide confirmation for the startup. If all
goes well, the SLAMD server will be started properly and the full set of
SLAMD functions will be made available.
Installing the SLAMD Server 11

Using SLAMD Clients
Because SLAMD is a distributed load generation engine, the SLAMD server

itself does not execute any of the jobs. Rather, the actual execution is performed
by SLAMD clients, and the server merely coordinates the activity of those clients.
Therefore, before any jobs can be executed, it is necessary to have clients
connected to the server to run those jobs.
The client application communicates with the SLAMD server using a TCP-based
protocol. Therefore, it is possible to install clients on different machines than the
SLAMD server is installed. In fact, this is recommended so that the client and
server do not compete for the same system resources, which could interfere with
the ability of the client to obtain accurate results. Further, is is possible to
connect to the SLAMD server with a large number of clients to process multiple
jobs concurrently, and in such cases it is best to have those clients distributed
across as many machines as possible to avoid problems in which the clients are
competing with each other for system resources.
The package containing the SLAMD client is contained in the server installation
in the file "slamd_client-1.8.0.tar.gz". To install the client on a system, do
the following:
1. Copy the "slamd-client-1.8.0.tar.gz" archive onto the client system and

extract the files contained in that archive. All files will be placed in a
"slamd_client" subdirectory.
NOTE Like the server installation, the directory in which the client files are
placed may be modified. However, unlike the server the client does not
store any path information and therefore it is possible to move or
rename the directory containing the SLAMD client files even after the
client has been used.
2. Edit the "slamd_client.conf" script to provide the appropriate settings for the
client. This script contains a number of configurable options that specify
information used to run the various client applications. Those options include:

JAVA_HOME Specifies the location in which a Java runtime version
1.4.0 or higher is installed.
INITIAL_MEMORY Specifies the amount of memory in megabytes that the
client should allocate when it is started.
MAX_MEMORY Specifies the maximum amount of memory in megabytes
that the client should be allowed to use while it is running.
SLAMD_ADDRESS Specifies the address of the SLAMD server. It may be
either an IP address or DNS-resolvable hostname.
SLAMD_LISTEN_PORT Specifies the port number on which the SLAMD server
accepts connections from clients. In most cases, the
default value of 3000 should be correct.
SLAMD_MANAGER_PORT Specifies the port number on which the SLAMD server
accepts connections from client managers. In most cases,
the default value of 3001 should be correct.
SLAMD_STAT_PORT Specifies the port number on which the SLAMD server
accepts connections from clients reporting in-progress job
statistics. In most cases, the default value of 3003 should
be correct.
ENABLE_REAL_TIME_STATS Indicates whether this client should be allowed to report
results that it obtains for certain kinds of statistics back to
the SLAMD server while the job is running. By default,
this is disabled in order to prevent it from impacting the
performance of the client in cases where it is not required.
REAL_TIME_REPORT_INTERVAL Indicates how frequently in-progress results collected by
the client will be sent to the SLAMD server. By default,
this will be done every 5 seconds.
ENABLE_STAT_PERSISTENCE Indicates whether the client should periodically save the
statistical data it has collected so that they can be
recovered in the event of a problem with the client or the
server that prevents the data from being sent to the server.
By default, this is disabled.
STAT_PERSISTENCE_DIRECTORY Specifies the directory on the client into which the
persistent statistical data will be written. By default, this
will be a directory named "statpersistence" below the
client install root.
STAT_PERSISTENCE_INTERVAL Specifies the interval in seconds with which the statistical
data will be saved on the client while a job is running if
stat persistence is enabled. By default, the data will be
saved every 300 seconds (5 minutes).
Using SLAMD Clients 13

AUTH_ID Specifies the authentication ID that the client should use
to identify itself to the SLAMD server. If no value is
provided, then no authentication will be performed.
AUTH_PASS Specifies the password that the client should use when
authenticating to the SLAMD server. If no value is
provided, then no authentication will be performed.
USE_SSL Indicates whether the client should use SSL to
communicate with the SLAMD server.
BLIND_TRUST Indicates whether the client should blindly trust any SSL
certificate presented by the SLAMD server. This is only
applicable if the client is configured to communicate over
SSL.
SSL_KEY_STORE Specifies the location of the JSSE key store that will be
used by the client if it is to communicate with the
SLAMD server over SSL.
SSL_KEY_PASS Specifies the password required to access the JSSE key
store.
SSL_TRUST_STORE Specifies the location of the JSSE trust store that will be
used by the client if it is to communicate with the
SLAMD server over SSL.
SSL_TRUST_PASS Specifies the password required to access the JSSE trust
store.
AGGREGATE_CLIENT_THREADS Indicates whether the client should aggregate the data
from all the client threads before providing that data to the
SLAMD server. Enabling aggregation will significantly
reduce the size of the data collected, but will remove the
ability to obtain thread-level statistics from that client.
RESTRICTED_MODE Indicates whether the client should operate in restricted
mode. A client operating in restricted mode will only be
used to process jobs for which that client has been
explicitly requested.
MAX_CLIENTS Specifies the maximum number of client instances that
may be created by the client manager running on the
system. A value of zero indicates that there is no limit.
DISABLE_CUSTOM_CLASS_LOADER Indicates whether the custom job class loader should be
disabled. If enabled, updates to job classes on the client
will be recognized without the need to restart the client.
However, some users have reported problems when using
the custom class loader so this option may be used to
disable that functionality if such problems arise.

VERBOSE_MODE Indicates whether the client should operate in verbose
mode, in which case detailed information about the
operations performed by the client will be displayed.
QUIET_MODE Indicates whether the client should operate in quiet mode,
in which case the client will reduce the amount of output
that it generates.
LOG_FILE Specifies the path to a file to which any output from this
client should be sent. If no value is provided, then
information will be sent to standard output.
Once the SLAMD client is installed and configured, it may be started by

executing the command:
./start_client.sh
This will start the client application, connect to the SLAMD server, and indicate
that it is ready to accept new job requests. If a problem occurs, then an error
message will be printed that indicates the cause of the problem so that it may be
corrected.
Note that as of SLAMD version 1.7.2, a new feature has been added that can
attempt to deal with differences in system clocks between the SLAMD server and
client systems. This time synchronization capability will be used by default, and
there is no configuration necessary required to enable it. However, if for some
reason it is decided that it should not be used, then it may be disabled using the
"-Y" argument. For example, the command:
./start_client.sh -Y
will cause the client to start in a manner such that it will not attempt to detect or
adjust for differences in system clocks between the SLAMD server and the client
system. Note that if this argument is used, it is vital that some other means of
ensuring time synchronization between the systems be used (e.g., the network
time protocol).
Using the Client Manager
When using SLAMD in conjunction with a large number of clients, it can become
rather inconvenient to manage all the clients. If the SLAMD server needs to be
restarted for any reason, then all the client connections will be lost and it will be

necessary to restart them. To help ease the process of working with multiple
clients, and especially for cases in which there are systems running multiple
instances of the client application, the SLAMD server contains a system that
allows client connections to be easily re-established in the event of a server
shutdown. This is done through the use of a client manager.
NOTE The SLAMD client manager does not run on Windows platforms. This
is because Windows does not provide a batch file equivalent to the exec
command that can be used in UNIX and Linux shell scripts, in which
the command being executed actually runs under the same process ID as
the shell script that executed it. This functionality is required by the
client manager so that it can properly handle requests to disconnect
clients.
The client manager is an application that runs on the client system and handles
the process of starting and stopping individual clients. Unlike the clients
themselves, however, the client manager is able to remain running even if the
SLAMD server is shut down. If that occurs, then the client manager will
periodically check for the server to come back online and should re-establish the
connection within 30 seconds of the server coming back online. This does not
automatically re-establish the individual client connections, but does provide a
simple means of creating those client connections through the administration
interface.
The client manager is included in the SLAMD client distribution, and therefore
using it does not require the installation of any additional software. It may be
started using the start_client_manager.sh shell script. This script uses the same
slamd_client.conf configuration file that is used by the client, so no further
configuration changes should be necessary.
When the client manager is started, it will attempt to connect to the client
manager listener in the SLAMD server. If the attempt fails, then it will sleep for
30 seconds before trying again. This process will continue until the connection is
successful. At that time, client manager connection will appear on the SLAMD
server status page and may be used to create client connections.
Using the Swing-Based GUI Client
The standard SLAMD client uses a command-line interface, which makes it

useful for starting on remote systems and for automating its use with mechanisms

like the client manager. However, if the client is to be run on a desktop system
(e.g., for testing purposes), then a GUI version may be more desirable. The
Swing-based GUI client can meet that need.
To launch the Swing client, execute the "swing_client.sh" script on UNIX and
Linux systems, or the "swing_client.bat" batch file on Windows systems. A
window will be displayed with a row of buttons along the top and a large text area
filling the rest of the frame. Clicking on the "Connect" button will display a
dialog allowing the user to provide the information necessary to connect to the
SLAMD server. The same options available with the standard SLAMD client
will be available for the Swing-based version.
Once the connection to the SLAMD server is established, information about the
communication between the client and the server will be displayed in the text area
(more information will be displayed if the client is configured to operate in
verbose mode). The text contained in this text area may be copied to the system
clipboard by clicking the "Copy All to Clipboard" button, and the "Copy
Selection to Clipboard" button may be used to copy only a selected portion of the
text to the clipboard.
Using the Resource Monitor Client
The resource monitor client is a special type of client that may be used to collect
statistical data beyond what may be collected by the job. In particular, the
resource monitor client is intended to measure system metrics like CPU
utilization, network traffic, or I/O load. Resource monitor clients may be run on
any system that can communicate with the SLAMD server, although they will
typically be run on a server against which load is being generated. It may also be
beneficial to run monitor clients on the same system as SLAMD clients to ensure
that the load generation process is not overloading the client system.
To install the resource monitor client, copy the slamd_monitor_client-

1.8.0.tar.gz archive to the system to be monitored and extract the files in that
archive. All files will be placed in a slamd_monitor_client directory. Go into
that directory and edit the slamd_monitor_client.conf configuration file. It will
first be necessary to remove or comment out the two lines near the top of the file
that indicate the file must be edited before the monitor client may be run. Then
the other parameters in that file should be provided with appropriate values.
Those parameters include:

JAVA_HOME Specifies the location in which a Java runtime is installed.
A JRE of version 1.4.0 or higher is required.
INITIAL_MEMORY Specifies the amount of memory in megabytes that the
client should allocate when it is started.
MAX_MEMORY Specifies the maximum amount of memory in megabytes
that the client should be allowed to use while it is running.
SLAMD_ADDRESS Specifies the address of the SLAMD server system.
SLAMD_MONITOR_PORT Specifies the port number on which the SLAMD server is
listening for connections from resource monitor clients.
By default, this is port 3002.
SLAMD_STAT_PORT Specifies the port number on which the SLAMD server
accepts connections from clients reporting in-progress job
statistics. In most cases, the default value of 3003 should
be correct.
ENABLE_REAL_TIME_STATS Indicates whether this client should be allowed to report
results that it obtains for certain kinds of statistics back to
the SLAMD server while the job is running. By default,
this is disabled in order to prevent it from impacting the
performance of the client in cases where it is not required.
REAL_TIME_REPORT_INTERVAL Indicates how frequently in-progress results collected by
the client will be sent to the SLAMD server. By default,
this will be done every 5 seconds.
AUTO_RECONNECT Indicates whether the resource monitor client should
automatically attempt to re-establish a connection to the
SLAMD server if it becomes disconnected for some
reason.
AUTH_ID Specifies the user ID that the resource monitor client
should use to authenticate to the SLAMD server. If no
value is provided, no authentication will be performed.
AUTH_PASS Specifies the password that the resource monitor client
should use to authenticate to the SLAMD server. If no
value is provided, no authentication will be performed.
USE_SSL Indicates whether SSL should be used to communicate
with the SLAMD server.
BLIND_TRUST Indicates whether the resource monitor client should
blindly trust any SSL certificate presented by the SLAMD
server. If this option is used, then there should not be any
need to provide SSL key or trust store information.
SSL_KEY_STORE Specifies the location of the JSSE key store that should be
used when establishing an SSL-based connection to the
SLAMD server. This should rarely if ever be necessary.

SSL_KEY_PASS Specifies the password needed to access information in
the JSSE key store. If no key store will be used, no
password is necessary.
SSL_TRUST_STORE Specifies the location of the JSSE trust store that should
be used when establishing an SSL-based connection to the
SLAMD server. If the client is not configured to blindly
trust any certificate, then this may be necessary.
SSL_TRUST_PASS Specifies the password needed to access information in
the SSL trust store. This should not be required unless the
JSSE trust store is in a format that requires a password.
VERBOSE_MODE Indicates whether the resource monitor client should
operate in verbose mode.
Note that as of SLAMD version 1.7.2, the resource monitor client will
automatically try to detect and adjust for differences between the system clocks
on the SLAMD server and on the resource monitor client systems. This time
synchronization capability will be used by default, and there is no configuration
necessary required to enable it. However, if for some reason it is decided that it
should not be used, then it may be disabled using the "-Y" argument. For
example, the command:
./start_monitor_client.sh -Y
will cause the client to start in a manner such that it will not attempt to detect or
adjust for differences in system clocks between the SLAMD server and the client
system. Note that if this argument is used, it is vital that some other means of
ensuring time synchronization between the systems be used (e.g., the network
time protocol).
Once the resource monitor client has been configured, it may be started by
executing the command "./start_monitor_client.sh". This will establish a
connection to the SLAMD server and indicate that the client is available to
process requests for resource monitoring. Note that unlike the standard SLAMD
client, the resource monitor client may process requests for multiple jobs
concurrently, so it is not necessary to start multiple instances of a resource
monitor client on the same system.
When the resource monitor client starts, it will look in the config subdirectory for
configuration files that specify which resource monitors to use. Each of these
configuration files should have at least two properties:
monitor_class -- Specifies the fully-qualified name of the Java class that

provides the resource monitor capabilities.

monitor_enabled -- Indicates whether that resource monitor should be enabled.
If this is set to "false", then that resource monitor will not be used.
The configuration file may also have additional properties, specific to that
monitor class.
SLAMD is provided with several resource monitors. The remainder of this

section will provide details for those monitor classes.
The VMStat Resource Monitor

The VMStat resource monitor can be used to monitor CPU utilization and
memory consumption on any system on which it is used. In particular, it can
capture the following statistics:
CPU User Time -- A measure of the percentage of time that the CPU(s) spend
executing user-space instructions.
CPU System Time -- A measure of the percentage of time that the CPU(s)
spend executing kernel-space instructions.
CPU Idle Time -- A measure of the percentage of time that the CPU(s) are
idle (i.e., not executing user-space or kernel-space instructions).
CPU Busy Time -- A combination of the time that the CPU(s) spend executing
either user-space or kernel-space instructions.
CPU Utilization -- A stacked value tracker that combines the CPU user,
system, and idle times.
Free Memory -- A measure of the amount of free memory on the system.

Depending on the operating system, this may or may not take into account
memory held by the filesystem cache or other items that may consume
memory but may be made available for use if the need arises.
The VMStat resource monitor may be used on Solaris, Linux, HP-UX, and AIX
systems. It supports the following configuration parameters:
capture_cpu_utilization -- Indicates whether the CPU utilization statistic

should be included in the results returned by the resource monitor.
capture_cpu_busy -- Indicates whether the CPU busy time statistic should be

included in the results returned by the resource monitor.

capture_cpu_user -- Indicates whether the CPU user time statistic should be
capture_cpu_system -- Indicates whether the CPU system time statistic should

be included in the results returned by the resource monitor.
capture_cpu_idle -- Indicates whether the CPU idle time statistic should be

capture_free_memory -- Indicates whether the free memory statistic should be

peak_utilization_log_threshold -- Specifies the threshold at which the

resource monitor will generate a log message if the CPU busy time (user time
plus system time) exceeds this value at any point during job execution.
average_utilization_log_threshold -- Specifies the threshold at which the

resource monitor will generate a log message if the average CPU busy time
(user time plus system time) exceeds this value over the duration of the job.
The IOStat Resource Monitor

The IOStat resource monitor can be used to monitor I/O activity on any system on
which it is used. It uses the iostat command to capture the data and reports the
amount of data read and amount of data written (in kilobytes) for each disk. This
resource monitor is supported on Solaris systems, as well as Linux systems using
the iostat command provided in a 4.1.x version of the sysstat package. Other
operating systems, or Linux systems with earlier versions of iostat are currently
not supported.
By default, it will report this data for all disks on the system, although it is
possible to capture information for only a subset of the disks using the
monitor_disks configuration property. If it is present in the configuration file,
this property should contain a comma-delimited list of the disks on the system
you wish to monitor, using the names reported by iostat ("iostat -x -I" on
Solaris and "iostat -d -k" on Linux). It is also possible to specify alternate
names for the disks by following the disk name with an equal sign and the
alternate name. For example:
monitor_disks=ssd1=Database,ssd2=Logs,ssd3=Backups
indicates that three disks should be monitored with names of "ssd1", "ssd2", and
"ssd3". The "ssd1" disk will be named "Database" in the returned statistics,
"ssd2" will be named "Logs", and "ssd3" will be named "Backups".

The IOStat resource monitor does not support any additional configuration
properties.
The NetStat Resource Monitor

The NetStat resource monitor can be used to collect information about network
utilization on the system. Specifically, it captures information about the number
of bytes received and number of bytes transferred by network interfaces on the
system. It is supported on the following operating systems:
Solaris, using the command "kstat -c net :::*bytes" to capture information

about the number of bytes received and transmitted.
Linux, by reading the "/proc/net/dev" file providing information about kernel

data structures. Note that information about all interfaces will be combined,
and that this may include traffic for all protocols, not just those based on TCP.
HP-UX, using the command "netstat -s -p tcp" to capture information

about the number of bytes of TCP traffic transferred.
AIX, using the command "netstat -ss -p tcp" to capture information about
the number of bytes of TCP traffic transferred.
There are no configuration parameters associated with this resource monitor.
NOTE Previous releases of SLAMD used the netstat command on Solaris

systems to obtain information about the amount of network traffic
transferred and received, which could interfere with the operation of the
VMStat resource monitor due to a bug in the Solaris 9 operating system.
The change to use kstat instead of netstat has resolved this issue so that
both the VMStat and NetStat resource monitors can again be enabled
concurrently. Note, however, that performing certain operations (like
using the netstat command or performing a ping) while the VMStat
resource monitor is active (or while using the vmstat command) can
cause inaccuracies to appear in the vmstat results.
The Process Size Resource Monitor

This resource monitor can be used to keep track of the virtual size of a Solaris
process, measured in kilobytes. It is currently only available on Solaris systems
(both SPARC and x86 platforms), as well as Linux systems using the NPTL
threading model.

The only statistic collected by this resource monitor is the virtual process size of a
particular process running on the system. It is possible to specify the process to
be monitored either by process ID (PID), the path to a file containing the process
ID, or the name of the process. It is recommended that a PID file or process name
be used, since that will be more flexible and can handle issues like the process
being killed and restarted with a different process ID.
There are two configuration parameters that may be specified when configuring
this resource monitor, and they are mutually exclusive (i.e., only one should be
given a value, but not both). Those configuration parameters are:
process_id -- This specifies the process ID of the process to monitor. Note

that if the PID is used to identify the process to track and the process is killed
or otherwise stops running and is restarted with a different process ID, then the
monitor will need to be reconfigured with the new process ID.
process_id_file -- This specifies the path to a file containing the process ID

of the process to monitor.
process_name -- This specifies the name of the process to monitor. The

corresponding process ID will be determined by issuing the command:
ps -e -o comm,pid
and finding the first command that contains the provided process name. If the
process ID being monitored is found to be no longer running, then the monitor
will automatically begin looking for a new process to appear with the specified
name in order to find the new process ID.
The Sun ONE Directory Server Resource Monitor

This resource monitor can be used to collect information about the state of the
Sun ONE Directory Server. It does this by periodically querying the cn=monitor
entry for general server information, and the cn=monitor,cn={dbName},cn=ldbm
database,cn=plugins,cn=config entries for statistics on each backend database.
The statistics it collects for the entire server are listed below. Note that these
values are measured at the time the monitor entry is retrieved and therefore may
not accurately reflect all activity in the server over the interval between queries.
Current Connections -- The number of connections established to the

directory server.

Requests in Progress -- The number of requests that have been received by
the server but have not yet been completed. Note that the query issued by the
resource monitor itself will be counted as a request in progress.
Requests Completed -- The number of requests that have been completely

processed by the server since startup.
Other statistics are collected on a per-database level. These statistics will be

reported separately for each database monitored.
Total Database Records -- The total number of keys in the id2entry file of
the backend Berkeley DB database. Note that this counts entries used
internally by the server (e.g., tombstones) that are not considered LDAP
entries.
Total LDAP Entries -- The total number of LDAP entries in the backend
database.
Entry Cache Count -- The total number of entries currently contained in the
entry cache.
Percent of Entries Cached -- The percentage of the LDAP entries in the

backend database that are currently held in the entry cache.
Entry Cache Size -- The estimated size of the entry cache, measured in
megabytes.
Entry Cache Percent Full -- The percentage of the maximum allowed

database cache size that is currently in use.
Entry Cache Hit Ratio -- The percentage of the time that an an entry stored in
the database is found in the entry cache when it is requested.
There are a number of configuration parameters that may be provided to

customize the behavior of the monitor. Those parameters include:
ds_address -- Specifies the address of the directory server to monitor.
ds_port -- Specifies the port of the directory server to monitor. It is not

currently possible to use this resource monitor over SSL.
ds_bind_dn -- Specifies the DN to use to bind to the directory server to retrieve

the monitor entries. If no value is provided, the searches will be performed
anonymously.

ds_bind_pw -- Specifies the password to use to bind to the directory server to
retrieve the monitor entries. If no value is provided, the searches will be
performed anonymously.
capture_current_connections -- Indicates whether the resource monitor

should report information about the number of connections established.
capture_requests_in_progress -- Indicates whether the resource monitor

should report information about the number of requests currently in progress.
capture_requests_completed -- Indicates whether the resource monitor should

report information about the total number of requests processed by the server.
capture_db_entry_count -- Indicates whether the resource monitor should

report information about the number of keys in the backend database.
capture_ldap_entry_count -- Indicates whether the resource monitor should

report information about the number of LDAP entries in the backend database.
capture_entry_cache_count -- Indicates whether the resource monitor should

report information about the number of entries currently in the entry cache.
capture_entry_cache_percent_entries_cached -- Indicates whether the

resource monitor should report information about the percentage of the entries
that are currently in the entry cache.
capture_entry_cache_size -- Indicates whether the resource monitor should

report information about the current size of the entry cache.
capture_entry_cache_percent_full -- Indicates whether the resource monitor

should report information about the percentage of the total allowable size that
the entry cache is currently consuming.
capture_entry_cache_hit_ratio -- Indicates whether the resource monitor

should report the entry cache hit ratio.
monitor_dbs -- Allows the user to specify which database(s) should be

monitored. By default, all backend databases will be monitored, but if this
parameter is provided with a comma-delimited list of database names, only
those databases will be targeted by the monitor.

The Replication Latency Resource Monitor
This resource monitor can be used to measure the length of time required changes
to be propagated by replication from one directory server to another. It has been
designed to work with and tested against the Sun ONE Directory Server, although
it should work with any directory server that supports the LDAP persistent search
control and has the ability to notify any clients performing persistent searches of
changes made through replication. It operates by periodically making changes in
one directory instance (termed the master server) and using a persistent search to
detect those changes in another directory (the replica server). It provides only
one statistic, which is the length of time in milliseconds between the time the
change was made in the master server to the time that it was detected using the
persistent search on the replica.
There are a number of configuration parameters that should be specified when

using the replication latency resource monitor:
master_host -- Specifies the address of the directory server that will serve as
the master for the purpose of latency checking (i.e., the system in which
periodic changes will be made).
master_port -- Specifies the port of the directory server that will serve as the
master for the purpose of latency checking.
master_bind_dn -- Specifies the DN to use when binding to the master

directory server. This user must have permission to modify the specified
attribute of the latency check entry.
master_bind_pw -- Specifies the password to use when binding to the master

directory server.
replica_host -- Specifies the address of the directory server that will serve as
the replica for the purpose of latency checking (i.e., the system against which a
persistent search will be registered to detect changes made in the master
server).
replica_port -- Specifies the port of the directory server that will serve as the
replica for the purpose of latency checking.
replica_bind_dn -- Specifies the DN to use when binding to the replica

directory server. This user must have permission to register a persistent search
against the latency check entry.
replica_bind_pw -- Specifies the password to use when binding to the replica

directory server.

latency_check_entry_dn -- Specifies the DN of the entry that should be
periodically modified in the master server, and against which the persistent
search should be registered in the replica server. This entry must not be
modified by anything except this resource monitor, and if there are multiple
instances of the replication latency resource monitor in use, they must all be
configured to modify different entries.
attr_to_modify -- Specifies the name of the attribute that should be modified

to trigger the change to replicate. This attribute must be allowed for use in the
latency check entry, and the user specified as the master bind DN must have
permission to modify this attribute in the latency check entry.
latency_check_delay -- Specifies the minimum length of time in milliseconds

that should be allowed to elapse between modifications to the latency check
entry in the master server. Before making a latency check modification in the
master server, this monitor will record the current time, and will compare it to
the current time when the change is detected in the replica server using the
persistent search. If less time has elapsed than specified by the latency check
delay configuration parameter, then the monitor will sleep for the remaining
time before performing the next modification. If at least the specified length of
time has passed between the time the change was made in the master and that
change was detected in the replica, then there will be no delay before making
the next change in the master.
The UDP Ping Resource Monitor

The UDP Ping resource monitor provides a mechanism for measuring
characteristics of the network between two systems, including information about
response time and packet loss. It is very similar to the standard ping utility with
the exception that it uses UDP (the user datagram protocol) for communication
rather than ICMP (the Internet Control Message Protocol), since Java does not
provide a means of communicating via ICMP. This resource monitor can be used
with any system that is running the standard UDP echo service, or with any
system running the UDP Ping Server, provided with SLAMD in the
tools/UDPPing directory.
Note that because Java 1.4 and earlier releases did not provide any access to a
high-resolution timer, the best accuracy that can be obtained using this resource
monitor is to the nearest millisecond. While this is likely sufficient for servers
separated by a WAN or other relatively slow or high-latency link, most LAN
connections provide the ability to transfer data in fractions of a millisecond.
While Java 1.5 does provide a method for obtaining much more precise timing
(through the System.nanoTime() method), SLAMD must maintain compatibility
with Java 1.4 runtimes and therefore only millisecond-accuracy is available for
this resource monitor. A standalone UDP ping client is available in the

tools/UDPPing directory that can make use of this high-resolution timer on
systems using a Java 1.5 runtime environment, but it cannot be used as a resource
monitor.
The configurable parameters for the UDP Ping resource monitor include:
target_address -- Specifies the address of the system to which the UDP ping
packets will be sent. This may be either an IP address or resolvable name.
target_port -- Specifies the UDP port to which the UDP ping packets should
be sent. The standard echo service uses UDP port 7, although the UDP Ping
Server may be run on any port between 1 and 65535.
ping_interval -- Specifies the minimum length of time in milliseconds

between UDP ping requests. Note that this time is measured from the
beginning of one request to the beginning of the text, making it possible to
target a fixed rate.
ping_timeout -- Specifies the maximum length of time in milliseconds that the

monitor should wait for a response. If a response does not arrive in this length
of time then the monitor will assume that either the request or response was
lost.
packet_size -- Specifies the size in bytes of the datagram packets to send to

the target system. This size must be at least 12 bytes.

Using the Administration Interface
All interaction with the SLAMD server is performed through an HTML

administration interface. This interface provides a number of capabilities,
including:
The ability to schedule new jobs for execution

The ability to view the results of jobs that have completed execution
The ability to view status information about the SLAMD server
The ability to make new job classes available for use in the SLAMD
environment
The ability to configure the SLAMD server
The ability to customize the appearance of the HTML interface
Each of these capabilities will be discussed in detail in later sections. However,

this section will provide a brief overview of the administrative interface to
describe how it may be used.
By default, the administrative interface may be accessed through the URL

"http://{address}:8080/slamd", where {address} is the address of the system on
which the SLAMD server is installed. Any browser that supports the HTML 4.01
standard should be able to use this interface, although different browsers may
have differences in the way that the content is rendered.
Provided that the SLAMD server is running, the left side of the page will contain
a navigation bar with links to the various tasks that may be performed in the
administrative interface. This navigation bar is divided into four major sections:
Manage Jobs
Startup Configuration
SLAMD Configuration
SLAMD Server Status
NOTE If access control is enabled in the administration interface, then some

sections or options may not be displayed if the current user does not
have permission to use those features. Configuring the administrative
interface to use access control is documented in a later section.
Using the Administration Interface 29

The "Manage Jobs" section is the one that will be used most frequently by end
users. This section provides options to schedule new jobs for execution, view
results of jobs that have already been completed, view information about jobs that
are currently running or awaiting execution, and viewing the kinds of jobs that
may be executed in the SLAMD environment. Additional information about the
options in this section will be provided later in this document.
The "Startup Configuration" section provides options to edit settings in the

configuration file that contains the information required to start the SLAMD
server (by default, webapps/slamd/WEB-INF/slamd.conf). These settings include
specifying the settings used for communicating with the configuration directory
and the settings used for access control. These topics will be discussed later in
this document.
The "SLAMD Configuration" section provides options to edit the SLAMD server
settings that are stored in the configuration directory. These settings include
options to configure the various components of the SLAMD server, as well as to
customize the appearance of the administrative interface.
The "SLAMD Server Status" option provides the ability to view information
about the current state of the SLAMD environment including the number of jobs
currently running and/or awaiting execution, the number of clients that are
connected and what each of them is doing, and information about the JVM in
which the SLAMD server is running. This section also provides administrators
with the ability to start and stop the SLAMD server, as well as the ability to
interact with the cache used for storing access control information, and to
manually disconnect clients or establish new client connections if the need arises.

Scheduling Jobs for Execution
One of the most important capabilities of the SLAMD server is the ability to
schedule jobs for execution. It is possible to schedule them to execute
immediately or at some point in the future, on one or more client systems, using
one or more threads per client system, and with a number of other options.
In order for a job to be available for processing, it must first be defined in the
SLAMD server. It is possible for users to develop their own job classes and add
them to the SLAMD server so that they may be executed by clients. The process
for defining new job classes is documented in a later section, but the SLAMD
server is provided with a number of default job classes that can be used to interact
with an LDAP directory server.
To schedule a job for execution, it is first necessary to follow the "Schedule a

Job" link in the "Manage Jobs" section of the navigation sidebar. This will
display a page containing a list of all job classes that have been defined to the
server. To choose the type of job to execute, follow the link for that job class,
and a new page will be displayed containing a form in which the user may specify
how the job is to be executed. Some of the parameters that may be specified are
specific to the type of job that was chosen, and the parameters specific to the
default job classes will be documented in a later section. However, some of those
options are the same for every type of job and will be discussed in this section.
The common configuration parameters that are displayed by default are as

follows:
Place in Folder -- This drop-down list box allows the user to specify the job
folder in which the job information should be placed. Note that this option will
only be visible if one or more job folders have been created.
Description -- This field allows the user to provide a brief description of the
job that can allow it to be distinguished in a list of completed jobs. This is an
optional field, and if no description is desired then none needs to be provided.
Start Time -- This field allows the user to specify the time at which the job
should start running. If no value is provided, then the job will start running as
Scheduling Jobs for Execution 31

soon as possible. If a value is provided, then it must be in the form
"YYYYMMDDhhmmss".
Stop Time -- This field allows the user to specify the time at which the job
should stop running, provided that it has not already stopped for some other
reason. If no value is provided, then the job will not be stopped because of the
stop time. If a value is provided, then it must be in the form
"YYYYMMDDhhmmss".
Duration -- This field allows the user to specify the maximum length of time
in seconds that the job should be allowed to run. This is different from the stop
time because it is calculated from the time that the job actually starts running,
regardless of the scheduled start time. If no value is provided, then there will
be no maximum duration.
Number of Clients -- This field allows the user to specify the number of
clients on which the job will run. When the time comes for the job to run, it
will be sent to the specified number of clients to do the processing. This is a
required parameter, and it must be a positive integer.
Wait for Available Clients -- This checkbox allows the user to specify what
should happen if the time comes for the job to start but there is not an
appropriate set of clients available to perform that processing. If this box is not
checked, then the job will be cancelled. If this box is checked, then the job
will be delayed until an appropriate set of clients is available.
Threads per Client -- This field allows the user to specify the number of
threads that should be created on each client to run the job. Each thread will
execute the instructions associated with the job at the same time, which allows
a single client to perform more work and generate a higher load against the
target server. However, specifying too many threads may cause a scenario in
which the client system or the target server are overloaded which could
produce inaccurate results.
Statistics Collection Interval -- This field allows the user to specify the
minimum interval over which statistics will be collected while a job is being
executed. Statistics will be collected for the entire duration of the job, but they
will also be collected for each interval of the specified duration while that job
is active. This is helpful for graphing or otherwise analyzing the results of the
job over time.
Job Comments -- This text area allows the user to add free-form text that
describes additional aspects of the job that cannot be reflected through the
other parameters associated with the job. Unlike the other parameters common
to all jobs, the job comments field appears at the bottom of the schedule job
form. In addition, these comments may be edited after the job has started

running or even after the job has completed. This makes it possible to provide
comments on the job based on observations gathered during job execution.
In addition to the above parameters, there are a number of other options that are
available by clicking on the "Show Advanced Scheduling Options" button. These
options are more specialized than the above parameters and therefore may not
need to be used in most cases. However, they are available for use if necessary.
These advanced options include:
Job Is Disabled -- This checkbox allows the user to specify whether the job
should be disabled when it is scheduled. When a job is disabled, it will not be
considered eligible for execution until it is enabled. This may be beneficial for
cases in which it is necessary to make changes to the job after it has been
scheduled (e.g., if a number of jobs are scheduled at the same time and then
individual changes need to be made to each of them).
Display In Read-Only Mode -- This checkbox allows the user to specify

whether the job should be displayed if the SLAMD server is running in
restricted read-only mode. More information about restricted read-only mode
will be provided in the section on access control.
Number of Copies -- This field allows the user to specify the number of
copies that will be made of the current job when it is scheduled. By default,
only a single copy is made, but it is possible to specify any number of copies.
This is useful for cases in which a number of jobs of the same type are to be
executed with only minor differences between them, since each job can be
edited after it is scheduled to make those minor changes.
Make Copies Interdependent -- This field allows the user to indicate that if
multiple copies are to be made, those copies should be interdependent such that
each copy will be dependent upon the previous copy.
Time Between Copy Startups -- This field allows the user to specify the
length of time in seconds that should be left between each job's start time when
multiple jobs are scheduled. Note that this is the interval between start times
for the jobs and not the time between the end of one job and the beginning of
the next. If this is not specified, then all copies will be scheduled with the
same start time.
Use Specific Clients -- This text area allows the user to request that the job be
executed on a specific set of clients. By default, the clients that will be used to
run a job cannot be guaranteed. However, if a specific set of addresses are
specified then those systems will be used to run the job. It is possible to
specify either the IP address or DNS hostname (as long as those names can be
resolved to IP addresses), and a separate address should be specified per line.

Resource Monitor Clients -- This text area allows the user to request that
resource monitoring be conducted on the specified systems. It is possible to
resolved to IP addresses). If multiple systems are to be monitored, then the
addresses of those systems should be placed on separate lines.
Monitor Clients if Available -- This checkbox allows the user to specify

whether the SLAMD server should automatically perform resource monitoring
on any client systems that also have active resource monitor clients.
Thread Startup Delay -- This field allows the user to specify the length of
time in milliseconds that each client should wait between starting each thread.
This is useful for cases in which there are a number of threads on the client that
may be attempting the same operations at the same time in a manner that could
lead to resource contention. By introducing a small delay between each thread,
that contention may be at least somewhat reduced for more accurate results.
Job Dependencies -- This field allows the user to specify one or more jobs on
which the current job will be dependent. That is, any job on which the current
job is dependent must complete its execution before the current job will be
considered eligible for execution. When a job is initially scheduled, only a
single dependency may be specified. However, by editing the job after it is
scheduled it is possible to add additional dependencies. Only jobs that are
currently in the pending or running job queues will be possible to specify as
dependencies when scheduling or editing a job.
Notify on Completion This field allows the user to specify the e-mail
addresses of one or more users that should be notified when the job has
completed. If multiple addresses are to be included, then they should be
separated by commas and/or spaces. Note that this option will only appear if
the SLAMD mailer has been enabled.
The remaining parameters that appear on the form when scheduling a new job
will be specific to that job type. If the current job is one of the default jobs, then
those parameters are described later in this document. However regardless of the
job type, Following the link at the top of the page in the sentence "Click here for
help regarding these parameters" will display a page with information on each of
those parameters.
Once all of the appropriate parameters have been specified for the job, clicking
the "Schedule Job" button will cause those parameters to be validated and,
provided that all the values provided were acceptable, the job will be scheduled
for execution. If any of the provided parameters was not acceptable, then an error
message will be displayed indicating the reason that the provided value was

inappropriate and the form will be displayed allowing the user to correct the
problem.
Some jobs may also provide the ability to test the job parameters before
scheduling the job to verify whether they are suitable for use (e.g., to specify
whether the server is reachable using the specified address, whether the username
and password are valid, etc.). In this case, clicking the "Test Job Parameters"
button will cause the SLAMD server to execute a set of tests defined for that job
class to determine whether the provided set of parameters are acceptable. Note
that some jobs may not offer this capability, and in that case the "Test Job
Parameters" button will not be displayed. Further, for those that do allow for this
kind of testing even if one or more of the tests fail it does not necessarily indicate
that the parameters are invalid since the test is performed by the SLAMD server
system rather than any of the clients, and therefore any failures should be
investigated to determine whether it actually does present a problem.
Using the Command-Line Job Scheduler
Although the primary interface to SLAMD is accessed through a Web browser, it

is also possible to schedule jobs for execution from the command line. This can
be useful if a number of jobs are to be scheduled at once, or if jobs are to be
scheduled by an automated process (e.g., a cron job that runs tests against a daily
build). This can be done using the command-line job scheduler. The command-
line job scheduler communicates with the SLAMD server over HTTP through the
administrative interface, which means that it will honor any access controls that
are configured in the server so that unauthorized users will not be allowed to use
this mechanism to schedule jobs.
The command-line job scheduler is provided with the SLAMD server and is
included in the slamd_server.jar archive contained in the webapps/slamd/WEB-
INF/lib directory. It is similar to the standalone client in that it reads much of the
information to use when scheduling the job from a configuration file. A base
configuration file can be generated by the command-line scheduler itself using the
command:
java -cp {classpath} CommandLineJobScheduler -g {className} -f {configFile}
where
is the Java classpath that specifies where all the class files needed to
{classpath}
schedule the job reside. It should contain at least the path to the
slamd_server.jar file, as well as the webapps/slamd/WEB-INF/classes

directory where the job class files reside. If a job class references any
additional third-party classes, then those appropriate classes should be included
in the classpath as well.
is the fully-qualified name of the job class for which to generate the
{className}
configuration file. This class must reside in the specified classpath.
{configFile} is the path to the configuration file to be generated.
For example, to generate a configuration file for the

com.sun.slamd.example.SearchRateJobClass job class from within the
webapps/slamd/WEB-INF directory, the command line could look like:
java -cp lib/slamd_server.jar:classes:lib/ldapjdk.jar \

CommandLineJobScheduler \
-g com.sun.slamd.example.SearchRateJobClass \
-f /tmp/searchrate.conf
Note the addition of the ldapjdk.jar file into the classpath, as it contains the
necessary libraries for the SearchRate job to communicate over LDAP. If this is
not included in the classpath, then a java.lang.NoClassDefFoundError error will
be thrown, indicating that a required class could not be found.
When this command is executed, the file /tmp/searchrate.conf will be

generated containing a basic configuration that may be used to schedule the job.
This file should be edited before it is used to schedule the job. As when
scheduling a job using the Web interface, there are a number of parameters that
will always appear in this configuration file. They include:
job_class -- This specifies the fully-qualified name of the job class to be

scheduled. This should not be changed, as the configuration file was generated
specifically for this class and will likely not work properly for other kinds of
jobs.
job_folder -- This specifies the name of the folder in which this job should be
placed. This is an optional parameter, and if it is not specified the the job will
be placed in the default "Unclassified" folder.
create_disabled -- This indicates whether the job should be disabled when it

is scheduled. If so, then it will be necessary to manually enable the job before
it can be executed. This must have a value of either "true" or "false".
description -- This specifies the description to use for the job. This is an
optional parameter.

start_time -- This specifies the time at which the job should start running, in
the format YYYYMMDDhhmmss. By default, it will contain the time that the
configuration file was generated. This is required, but if the current time or a
time in the past is specified then the job will be considered immediately
eligible for execution.
stop_time -- This specifies the time at which the job should stop running. This
is optional, but if specified it should be in the format YYYYMMDDhhmmss.
duration -- This specifies the maximum length of time in seconds that the job
should be allowed to run. This is an optional parameter.
num_clients -- This specifies the number of clients that should be used to

execute the job. This is a required parameter and its value must be a positive
integer.
wait_for_clients -- This indicates how the SLAMD server should operate if

there is not a sufficient set of clients available when the job is determined
eligible for execution. If set to "true", then the SLAMD server will wait for an
appropriate set of clients to become available in order to start the job. If set to
"false", then the job will be cancelled if no clients are available.
requested_clients -- This may be used to request that a specific set of clients

be used to run the job. This is optional, but if it is specified then it should be a
comma-delimited list of the addresses of the client systems to use.
monitor_clients -- This may be used to request that one or more resource

monitor clients be used to collect system resource information while the job is
active.
num_threads -- This specifies the number of threads that should be created to

run the job on each client. This is a required parameter and its value must be a
positive integer.
collection_interval -- This specifies the statistics collection interval (in

seconds) to use when running the job. This is a required parameter.
notify_addresses -- This specifies the e-mail address(es) of the individual(s)

to notify when the job has completed. This is an optional argument, but if it is
specified then it should contain a comma-delimited list of the e-mail addresses
to use.
The remainder of the parameters contained in the configuration file will vary
based on the type of job being scheduled. The configuration file will contain

comments indicating what values may be appropriate for them and whether they
are required or optional.
Once the configuration file has been edited, it may be used to schedule the job for
execution. This can be done using the command:
java -cp {classpath} CommandLineJobScheduler -f {configFile} -h {host} -p {port}
where
is the Java classpath that specifies where all the class files needed to
{classpath}
schedule the job reside. It should be the same classpath as was used to
generate the configuration file.
{configFile}is the path to the configuration file containing the information to use
to schedule the job. When scheduling jobs using the command line scheduler,
it is possible to use multiple "-f" options to specify multiple configuration
files. If multiple configuration files are specified, then the jobs will be
scheduled in the order they are provided in the argument list.
is the address of the SLAMD server system. By default, an address of

{host}
"127.0.0.1" will be used.
is the port number on which the SLAMD server is listening for

{port}
connections to the Web-based administrative interface. By default, this is port
8080.
There may also be a number of additional parameters specified if necessary.

Those arguments include:
-A {authID}-- Specifies the user ID to use when authenticating to the SLAMD

server. This should be used if the SLAMD server is configured to require
authentication.
-P {authPW} -- Specifies the password to use when authenticating to the

SLAMD server. This should be used if the SLAMD server is configured to
require authentication.
-S-- Indicates that the communication with the SLAMD server should be over
SSL. The client will blindly trust any SSL certificate presented by the server.
-- Specifies the job ID of the job on which this job should be

-D {jobID}
dependent.

-d -- Indicates that the jobs scheduled should be interdependent. That is, if
multiple jobs are to be scheduled (by using multiple -f options to provide the
separate configuration files), each job scheduled will be dependent upon the
previous.
-- Specifies the URI that should be used to post the job information.
-u {uri}
By default, this will be "/slamd", and it will likely not need to be changed.
-v-- Indicates that the command-line job scheduler should operate in verbose
mode.
If all goes well, the job will be scheduled and the command-line scheduler will
report the job ID used for the job.

Managing Scheduled Jobs
Once a job has been scheduled for execution, it will be added into the pending
jobs queue to await execution. Once all of the criteria required to start the job
have been met (e.g., the start time has arrived, the job is not disabled, all
dependencies have been satisfied, and an appropriate set of clients is available),
then that job will be moved from the pending jobs queue into the running jobs
queue and the job will be sent out to the clients for processing. When that job has
completed execution, the job will be removed from the running jobs queue and
the job information will be updated in the configuration directory.
As described above, a job can really be in one of three stages:
Pending -- the job is awaiting execution and has the potential to be executed
once all the appropriate conditions are met. This also includes jobs that are
disabled.
Running -- The job information has been sent to at least one client, and the
server is currently waiting for results from at least one client.
Completed -- The job has completed all the execution that it is going to do.
This could mean any of a range of values, from an indication that the job
completed successfully to an indication that a problem occurred that prevented
the job from being started.
The SLAMD administrative interface provides links that group the jobs into these
three categories. These are the first three links under in"Manage Jobs" section.
Pending Jobs
The "View Pending Jobs" link provides a way to manage the jobs that have not
yet been given a chance to run. If there are any jobs in this state, then the job ID,

description, job type, scheduled start time, and the current state (pending or
disabled) will be displayed for each job. Following the hyperlink on the job ID
will display more detailed information about the job, including the values of all
the parameters used to schedule it. The page displaying that detailed information
also provides buttons that provide a number of capabilities:
Refresh -- Reloads the information about this job. Note that if the job has
changed states (e.g., it has started running since the page was initially
displayed), then the updated job information will still be displayed even though
the job is no longer in the pending jobs queue.
Edit -- Provides a mechanism through which the job information may be

edited. As long as the job has not yet started, all configuration parameters
associated with the job may be edited. Note that to ensure that the job does not
start running before the editing has been completed, it may be helpful to first
disable the job before making changes to it.
Disable/Enable -- Provides a way of disabling or enabling the job. Only one

of these buttons will be displayed based on the current state of the job.
Clone -- Provides a way of scheduling a new job for execution using the same
parameters as the current job. Upon clicking this button, a form will be
displayed allowing the user to make any desired changes before scheduling the
job. Note that these changes will only impact the new job and will not be
applied to the job from which the new job was cloned.
Cancel -- Provides a means to cancel the job so that it will no longer be

considered eligible for execution. The job will be removed from the pending
jobs queue and will be visible in the completed jobs section with a description
that indicates it was cancelled before it could be started.
Cancel and Delete -- Provides a means to cancel the job so that it will no
longer be considered eligible for execution. Not only will the job be removed
from the pending jobs queue, but all information about the job will be removed
from the configuration directory so it will not be visible in any part of the
administrative interface.
In addition to the above operations that may be performed on a single job, the
"View Pending Jobs" page also provides the ability to perform operations on a
number of jobs at the same time. These operations are made available through
buttons at the bottom of the list of pending jobs, and the jobs on which to perform
that operation may be selected by clicking the checkboxes in front of the
appropriate jobs. The operations that may be performed on pending jobs in this
manner include:
Managing Scheduled Jobs 41

Poll for New Jobs -- This option will cause the SLAMD server to poll the
configuration directory to look for jobs that have been added to it through
some means other than the administrative interface (e.g., adding the job
information directly to the configuration directory using ldapmodify or a
similar utility). This option is provided as an alternative to using the "Job
Refresh Interval" that can be specified in the scheduler configuration.
NOTE The "Poll for New Jobs" feature has now been deprecated and will
likely be removed in a future SLAMD release. Please use the
command-line job scheduler to automate the process of scheduling new
jobs.
Cancel -- This option will cancel all selected jobs so that they will no longer
be allowed to run. The information about those jobs will be accessible in the
"View Completed Jobs" section.
Cancel and Delete -- This option will cancel all selected jobs so that they will
no longer be allowed to run. All information about those jobs will be removed
from the SLAMD server and the configuration directory.
Clone -- This option will create a new copy of each selected job and place it in
the pending jobs queue. The new jobs that are scheduled will be placed in a
disabled state so that they may be edited before they will be considered eligible
for execution.
Disable -- This option allows the user to temporarily disable all selected jobs
so that they will not be allowed to run until they are enabled again. If any of
the selected jobs are already disabled, this will have no effect on those jobs.
Enable -- This option allows the user to enable all selected jobs so that they
will again be considered eligible for execution. If any of the selected jobs are
already enabled, this will have no effect on those jobs.
Add to Virtual Folder -- This option allows the user to add the specified jobs
into a virtual folder. The job information can either be added to an existing
virtual job folder, or a new virtual folder may be created.

Running Jobs
The "View Running Jobs" link provides a way to manage the jobs that are
currently running on at least one client system. Once the job request has been
sent to at least one client system, then that job will be transferred from the
pending jobs queue to the running jobs queue, and it will stay there until there are
no more clients executing that job.
Like pending jobs, the running jobs section will display a list of all jobs that are
currently running. Clicking on the link associated with that job will display
information about that job and will provide buttons that allow the user to perform
the following operations on that job:
Refresh -- Reloads the information about this job. Note that if the job has
changed states (e.g., it has finished running since the page was initially
displayed), then the updated job information will still be displayed even though
the job is no longer in the running jobs queue.
Edit Comments -- Provides the ability for the user to edit the comments
associated with the job. Unlike the other parameters, the job comments may be
edited while the job is in any state.
In-Progress Results -- Provides a way of obtaining results for a job while it is

still running. Note that this button will only be displayed if in-progress results
are currently available for the job, which requires that the clients running the
job be configured to support real-time statistics reporting and also the job
being executed has enabled such reporting for at least one of the statistics it
maintains.
Cancel -- Provides a means to cancel the job so that it will stop its execution.
This will cause the SLAMD server to send a cancel request message to each of
the clients that are currently running the job. As soon as each client sees the
cancel request, it should stop its execution and send back all results that it has
collected up to the time that the cancel request was received. Note that
because of this additional communication between the client and the server, it
may take a few seconds for the cancel to be completed, and jobs that may not
look for the cancel request frequently enough may take even longer to be
cancelled.

If an unexpected problem arises while a job is running, it is possible that
an unexpected error may cause a client to enter a state in which it is not
responsive to a cancel request. If such a situation arises, then it may be
possible to force the cancellation by re-issuing the cancel request. If a client
receives a second request to cancel a job, then it will first attempt to manually
interrupt any threads that may be blocked for some reason, and if that fails the
client may take even more aggressive action to try to force the job to end (e.g.,
by closing a socket that the job was using to communicate with a remote
system).
If all else fails, then an unresponsive client may be manually killed (e.g.,
by terminating any processes associated with it). If that occurs, then the
SLAMD server should recognize that the client is no longer available and will
stop expecting to receive data from the client. The client will not send any
results to the server for that job, but it may allow the server to process the job
data returned from other clients so that at least partial results are available.
The running jobs section also provides the ability to perform operations on
multiple jobs at the same time, just as in the pending jobs section. However, the
only operations that may be performed on running jobs are:
Cancel -- This option will send a cancel request to each client running one of
the selected jobs. As with canceling a single running job, it may take some
time for each job to recognize and respond to the cancel request.
for execution.
Completed Jobs
The "View Completed Jobs" page provides the capability to manage all jobs that
have either completed execution or were unable to run for some reason. This
information is retrieved from the configuration directory, and a field exists at the
top of the completed jobs page that allows the user to specify how far back (in
number of days) the server should look when retrieving the completed job
information.

As with the pending and running jobs, each completed job may be viewed in
detail by following the link associated with the job ID. Further, if the job has
completed execution and results are available, then that information will be
accessible from this page, although that will be discussed in a later section. Also
on that page are buttons that allow operations to be performed on that job,
including:
Refresh -- Reloads the information about this job. Note that if the job is
already in the completed jobs section, then the information displayed for that
job will not change, with the possible exception of changes made to the job
comments.
Edit Comments -- Provides the ability for the user to edit the comments
associated with the job. Unlike the other parameters, the job comments may be
edited while the job is in any state.
Graph -- Provides a way of graphing the statistical information collected while

the job was active. This is an alternative to following the "Graph Job
Statistics" link further down the page, as it is often necessary to scroll down the
page to be able to access that link.
Import Persistent Stats -- Provides a way of importing statistical data saved

on the client using the stat persistence capability. This can be used to import
data from a single client into the server so that at least some of the data can be
recovered in the event of a problem with the communication between the client
and the server. If data needs to be imported from multiple clients (even
multiple clients running on the same system), then this will need to be repeated
once for each client.
Delete -- Provides a way of removing the information about the current job
from the configuration directory. Note that if this is done, information about
the specified job will no longer be available and therefore this option should
only be used when it is certain that the job information will not be needed.
Move -- Provides a way of moving the job information from its current
location into a specified real job folder. Note that a job may not concurrently
exist in two different folders, so moving a job will remove it from its current
folder and place it in the specified destination folder.

Add to Virtual Folder -- Provides a way to include this job in a specified
virtual folder. The job information can either be added to an existing virtual
job folder, or a new virtual folder may be created.
Optimize Results -- Provides a way to schedule an optimizing job, which

attempts to automatically determine the best performance for a given job.
Additional information about optimizing jobs may be found in a later section
of this document.
Generate Report -- Provides a way to generate a report of the job data. The
generated report will contain a representation of the job information in a form
that can be distributed to users that do not have access to the SLAMD server.
It is also possible to perform some operations on multiple completed jobs at the

same time. Those operations are:
for execution.
Compare -- This option will allow the user to generate graphs comparing the
results of the selected jobs. All jobs selected for comparison must be of the
same type and must have statistical information available, although it is not
necessary for them to have the same duration or statistics collection interval. If
any jobs are selected that are either of a different type than the first job chosen,
or if any selected jobs do not have statistics available, then those jobs will not
be included in the comparison. At least two valid jobs must be selected in
order to perform the comparison.
Delete -- This option provides a way of removing the information about the
selected jobs from the configuration directory. Note that if this is done,
information about the specified jobs will no longer be available and therefore
this option should only be used when it is certain that the job information will
not be needed.
Export -- This option provides a way of exporting the summary data for the
selected jobs to a tab-delimited text file for use in an external application. If
all the jobs selected are of the same type, then it will be possible to specify
which specific parameters or statistics should be included in the export. If jobs
of multiple types are selected, only a limited set of options will be available.
Create Folder -- This option provides a way of creating a new job folder that
can be used to group related jobs together. This can be very useful for
archiving job information over time, since the "View Completed Jobs" page

can become rather inefficient to load if there are a large number of jobs for
which information is to be retrieved and displayed. It is currently not possible
to make use of nested folders.
Delete Folder -- This option provides a way of removing an existing job

folder. Note that a job folder must be empty before it can be removed, so any
jobs contained in the folder to be deleted must either be moved out of that
folder or deleted.
Move -- This option provides a way of moving the selected jobs to another
folder. Note that a job may not concurrently exist in two different folders, so
moving a job will remove it from its current folder and place it in the specified
destination folder.
Publish -- This option allows the user to mark the specified jobs for
publication in restricted read-only mode. Note that this option will only be
displayed if management of read-only options has been enabled.
De-Publish -- This option allows the user to unmark the specified jobs for
publication in restricted read-only mode. Note that this option will only be
displayed if management of read-only options has been enabled.
Generate Report -- This option allows the user to generate a report containing
information about the selected jobs. If no jobs are selected, then all jobs and
optimizing jobs contained in the current folder will be included in the report.

Viewing Job Execution Results
Once a job has been executed and all clients have sent the results back to the
SLAMD server, those results will be made available through the administration
interface. Those results will be made available in a variety of forms, and the data
collected can even be exported for use with external programs like spreadsheets
or databases.
When the job summary page is displayed for a particular job, all of the parameters
used to schedule that job will be displayed. If that job has completed execution,
then additional information will be available about the results of that execution.
That additional information falls into three categories:
Job Execution Data -- This section provides an overview of the execution

results and links to obtain more detailed information. This section will be
described below in more detail.
Clients Used -- This section provides the client IDs of all the clients used to
run the job. The client ID contains the address of that client, so this makes it
possible to determine which systems were used in the job execution.
Messages Logged -- This section provides a list of all messages that were
logged while the job was in progress. These messages may provide additional
information about problems that occurred while the job was active, or any
other significant information that should be known about the job execution. If
there were no such messages, then this section will not be displayed.
Of these three sections, the one of most interest is that containing the job
execution data, because it provides the actual results of the execution. Therefore,
the remainder of the discussion of job execution results will focus on this section.
Jobs that run in the SLAMD environment have the ability to use components
called "stat trackers" to collect statistics as they are running. These stat trackers
handle most of the work of dealing with this statistical information, which allows
a developer writing a custom job for the SLAMD environment to ignore most of

the details that would otherwise be required to gather this kind of data. By
default, there are four kinds of stat trackers available for use by SLAMD jobs:
Incremental Trackers -- These are used for cases in which it is simply

necessary to count the number of times that a particular event occurred during
the time that the job was active. For example, this may be used to keep track
of the number of search operations completed in a job that queries an LDAP
directory server.
Integer Value Trackers -- These are used for cases in which it is necessary to
keep track of integer values collected during job execution. For example, this
may be used to keep track of the number of entries returned from each search
performed in an LDAP directory server.
Float Value Trackers -- These are used for cases in which it is necessary to
keep track of floating-point values collected during job execution.
Time Trackers -- These are used for cases in which it is necessary to keep
track of the length of time required to perform a particular task. For example,
this may be used to keep track of the length of time required to perform each
search operation in an LDAP directory server.
Categorical Trackers -- These are used for cases in which it is necessary to

keep track of the number of times that each of multiple types of events
occurred. For example, when performing multiple operations in an LDAP
directory server, this may be used to keep track of the number of each kind of
operation performed.
When a job has completed running, the information gathered by all of the stat
trackers that were used by that job will be reported back to the SLAMD server.
When the summary job information is viewed in the administrative interface, all
of the statistics gathered using each thread of each client will be aggregated
together to provide an overall summary of the information gathered. The
summary information for each statistic depends on the type of stat tracker used to
gather that information.
Just below the summary information is a link allowing the user to view in detail
the statistical information gathered while the job was active. Following this link
will open a new window that provides the user with the ability to view
information gathered over the entire duration of the job all the way down to the
information collected by each thread running on each client used to process the
job. A form at the top of the page allows the user to customize the level of detail
and types of statistics that are displayed.
Viewing Job Execution Results 49

Below the "View Detailed Statistics" link is another link that allows the user to
graphically view the statistical information gathered while the job was active.
Following this link will open a new window containing a form allowing the user
to customize the information to be depicted in the graph, as well as the graph
itself generated from the selected options. The set of options that are available
are dependent upon the type of statistic being graphed, but it will always be able
to specify the width and height of the graph (in pixels) that should be used to
draw that graph.
NOTE The administration interface uses functions in the Java AWT library to
generate the graphs. Historically on UNIX systems, this has required
access to an X server to render the graphics. Java 1.4.0 introduced
support for headless systems, which can provide the ability to render
these graphics without an X server. By default, the SLAMD server is
configured to use this headless support. However, if this does not work
for some reason, then you should configure SLAMD to have access to
an X server. To do this, edit the bin/startup.sh script to comment the
line that defines the USE_HEADLESS environment variable and
uncomment the line that defines the DISPLAY environment variable and
use it to specify the address of an X server that may be used to render
the graphics.
An alternative to using an X server on a different machine is to use the

Xvfb (X virtual framebuffer) utility. This utility provides full X server
without the need for any graphics hardware on the system. The Xvfb
utility is included in the X11R6 distribution available at ftp://ftp.x.org/.
If no X server will be available to the system in any form, then it is

possible to disable all graphing capabilities in the administrative
interface. This option is available under the "User Interface" link of the
"SLAMD Configuration" section of the navigation bar.
Below the "Graph Job Statistics" link is a "Graph Overlaid Job Statistics" link.
This feature is very similar to the "Graph Job Statistics" feature, but allows the
user to overlay two different statistics on the same graph. This makes it possible
to help determine if there is a relationship between two statistics, or to make
comparisons about the values of two similar statistics. Note that this option will
only be available for certain kinds of statistics, and only if there are two
"overlayable" statistics available for the job.
Under the "Graph Overlaid Job Statistics" link is another link that makes it
possible to export the statistical data collected during job execution to a file for
use in an external program like a spreadsheet. If this option is used, then the data
will be exported to a tab-delimited text file that should be readable by virtually
any kind of application in which you would wish to use this data. A form will be

displayed that is similar to the "View Detailed Statistics" form to make it possible
to select the information to be exported. Further, it is possible to specify whether
to include row and column labels in the text file to help clarify the values written
to the file.
Viewing Job Execution Results 51

Optimizing Jobs
When using SLAMD to run benchmarks against a network application, it is often

desirable to find the configuration that yields the best performance. In many
cases, this also involves trying different numbers of clients or threads per client to
determine the optimal amount of load that can be placed on the server to yield the
best results. To help automate this process, SLAMD offers optimizing jobs.
An optimizing job is actually a collection of smaller jobs. It will run the same job
repeatedly with increasing numbers of threads per client until it finds the number
that yields the best performance for a particular statistic. At the present time,
optimizing jobs do not alter the number of clients used to execute the job,
although that option may be available in the future.
There are two ways in which an optimizing job may be scheduled:
View information about a particular completed job that contains the settings
you wish to use for the optimizing job. On this page, click the "Optimize
Results" button at the top of the page.
Follow the "View Optimizing Jobs" link in the navigation sidebar. Choose the
job type from the drop-down list box at the top of that page and click the
"Submit" button.
When the form is displayed that makes it possible to schedule an optimizing job,
there are a number of parameters that may be customized:
Description -- This field allows the user to provide a brief description of the
job. This is a base description, and it will be used for the description of each of
the iterations associated with this optimizing job. This is an optional field, and
if no description is desired then none needs to be provided.
Include Thread Count in Description -- This checkbox allows the user to

specify whether the number of threads should be included in the description for
each iteration of that job. If a base description was specified, then the number
of threads will be included in parentheses after that base description, like "My

Job (2 Threads)". If no base description was specified, then the description for
each job iteration will simply be the number of threads, like "2 Threads".
Display In Read-Only Mode -- This checkbox allows the user to indicate

whether information about this optimizing job and its associated job iterations
should be published in restricted read-only mode
Place In Folder -- This drop-down list allows the user to specify the job folder
in which the optimizing job and all its iterations should be placed when they
are scheduled.
Start Time -- This field allows the user to specify the time at which the first
iteration of the optimizing job should begin execution. If a value is provided,
then it should be a 14-digit number in the form "YYYYMMDDhhmmss". If
no value is provided, then the first iteration will be eligible for execution
immediately.
Duration -- This field allows the user to specify the maximum length of time
in seconds that any particular iteration should be allowed to run. If this is
omitted, then each iteration will run until it completes normally or is manually
cancelled by an administrator.
Delay Between Iterations -- This field allows the user to specify a delay in
seconds that should be allowed between individual iterations of the optimizing
job. This delay will be the length of time between the end of one iteration and
the beginning of the next.
Number of Clients -- This field allows the user to specify the number of
clients that should be used for each iteration of the optimizing job. At the
present time, the number of clients must be the same for each iteration.
Use Specific Clients -- This field allows the user to provide a list of addresses
of client systems that should be used to run the job. By default, the clients that
will be used to run a job cannot be guaranteed. However, if a specific set of
addresses are specified then those systems will be used to run the job. It is
possible to specify either the IP address or DNS hostname (as long as those
names can be resolved to IP addresses), and a separate address should be
specified per line.
Resource Monitor Clients -- This text area allows the user to request that
resource monitoring be conducted on the specified systems. It is possible to
resolved to IP addresses). If multiple systems are to be monitored, then the
addresses of those systems should be placed on separate lines.
Optimizing Jobs 53
Monitor Clients if Available -- This checkbox allows the user to specify
whether the SLAMD server should automatically perform resource monitoring
on any client systems that also have active resource monitor clients.
Minimum Number of Threads -- This field allows the user to specify the
minimum number of threads per client that should be used to run the job. The
first iteration will use this number of threads, and remaining iterations will use
increasingly larger numbers of threads as necessary.
Maximum Number of Threads -- This field allows the user to specify the
maximum number of threads per client that should be used to run the job. This
is not required by the optimization process, and care should be taken if it is
used because it can cause the optimization process to stop prematurely before
the best performance has been identified.
Thread Increment Between Iterations -- This field allows the user to specify
the increase in the number of threads per client that should be used between
iterations.
Statistics Collection Interval -- This field allows the user to specify the
minimum interval over which statistics will be collected while a job is being
executed. Statistics will be collected for the entire duration of the job, but they
will also be collected for each interval of the specified duration while that job
is active. This is helpful for graphing or otherwise analyzing the results of the
job over time.
Statistic To Optimize -- This field allows the user to specify the particular
statistic for which the optimal value should be found. Note that this list may
not include all kinds of statistics collected by a job because some kinds of stat
trackers are not suited to being described by a single value (e.g., categorical
trackers deal with data in multiple categories and "finding the best value" does
not have a concrete meaning in that context).
Optimization Type -- This field allows the user to specify the type of
optimization that should be performed. At the present time, this optimization
type may be either "maximize" to try to find the largest possible value for the
statistic to optimize, or "minimize" to try to find the smallest possible value for
the statistic to optimize.
Maximum Consecutive Non-Improving Iterations -- This field allows the

user to specify the maximum number of consecutive iterations that will be
allowed whose value was not better than a previous iteration. That is, it is
expected that up to a certain number of threads per client, each successive
iteration will exhibit better performance than the previous. Any iteration that
does not yield a better value than all previous iterations is termed a "non-
improving iteration", and the optimization process will stop once the maximum

number of non-improving iterations have been observed in a row. Note that if
a maximum number of threads per client is specified, then the optimization
process may stop before this maximum number of consecutive non-improving
iterations has been reached.
Re-Run Best Iteration -- Indicates whether the best iteration of the optimizing
job should be re-run, optionally with a longer duration. This option can serve
two purposes. First, it can help confirm that the best iteration you found was in
fact the best iteration. Second, it can allow for a relatively short duration to be
used for most iterations of the optimizing job, but still make it possible to use a
longer duration for the iteration found to yield the best results.
Re-Run Duration -- Specifies the duration that should be used when the
server is re-running the best iteration of the optimizing job. This applies only
if the job is configured to re-run the best iteration. A positive value specifies
the maximum time in seconds that iteration should be allowed to run. If no
value is provided, or if a negative or zero value is provided, then the job will
not be stopped because of a maximum duration and will therefore run until it
stops for some other reason (e.g., it completes successfully or it is cancelled by
administrative request).
Notify on Completion -- This field allows the user to specify the e-mail
address of the users that should be notified when the optimization process has
completed. Multiple e-mail addresses may be provided if they are separated by
spaces and/or commas. Note that in order for this option to be visible, the
SLAMD mailer must be properly configured.
When this form is submitted and the optimizing job has been scheduled, it will
immediately schedule a job iteration using the minimum number of threads.
When the scheduled start time arrives and the appropriate clients are available,
this job will start running. When it is complete, the optimizing job will examine
the results and determine whether it is appropriate to schedule another iteration.
If none of the following conditions are met, then another iteration will be
scheduled:
If the job execution ended for any reason other than completing successfully or
reaching the maximum duration, then the optimization process will be declared
complete and will indicate that it stopped because of an error.
If the job did not return any values for the statistic to be optimized, then the
optimization process will be declared complete and will indicate that it stopped
because of an error.
Optimizing Jobs 55
If the iteration ran with the scheduled maximum number of threads per client,
then the optimization process will be declared complete and will indicate that it
completed successfully.
If the iteration provided a value for the specified statistic that was not better
than all previous values and the number of consecutive non-improving
iterations has reached the maximum allowed value, then the optimization
process will be declared complete and will indicate that it completed
successfully.
Pausing an Optimizing Job
Once an optimizing job has been scheduled and starts running, it will only
schedule one iteration at a time. Once that iteration has completed, it the
SLAMD server will examine the results associated with that iteration and
determine if another iteration should be scheduled, or if not if a re-run iteration
should be processed. This process is handled automatically by the SLAMD
server and there is no need for administrative interaction when an optimizing job
is in progress. This is desirable in most cases, but if for some reason an
administrator wants to temporarily pause the optimizing job it can be difficult
because in most cases there is a very narrow window of time between the end of
one iteration and the time the next starts running. If an administrator is watching
carefully and acts quickly, then it may be possible to disable the next iteration
before it starts running, but doing so can be tricky.
To address this problem, SLAMD provides an option to pause an optimizing job

when it is running. If this feature is used, then as soon as the current iteration of
the optimizing job completes, the next iteration will be automatically disabled so
that it will not be eligible to run until an administrator manually enables it.
In order to pause an optimizing job that is currently running, navigate to the page
providing information about that job and click the "Pause" button. This will
indicate to the optimizing job that the next iteration should be disabled when it is
scheduled, and it will also change the text on the button to "Unpause" to indicate
that the optimizing job does not actually need to be paused and that the next
iteration should not be disabled when it is scheduled.

Scheduling Optimizing Jobs from the Command Line
The command-line job scheduler can be used to schedule optimizing jobs as well
as normal jobs. This can be done by providing the "-O" argument to the
command line used to generate the configuration file, for example:
java -cp lib/slamd_server.jar:classes:lib/ldapjdk.jar \

CommandLineJobScheduler \
-g com.sun.slamd.example.SearchRateJobClass \
-f /tmp/searchrate.conf -O
The configuration file generated in this case will be similar to that generated for a
regular job, although there will be some differences. The set of parameters that
will always be present include:
job_class -- This specifies the fully-qualified name of the job class to be

scheduled. This should not be changed, as the configuration file was generated
specifically for this class and will likely not work properly for other kinds of
jobs.
optimize_results -- This indicates that the job scheduled should be an

optimizing job. This should not be changed, as the set of parameters required
for scheduling an optimizing job are slightly different from the parameters
required to schedule a regular job.
job_folder -- This specifies the name of the folder in which this job should be
placed. This is an optional parameter, and if it is not specified the the job will
be placed in the default "Unclassified" folder.
description -- This specifies the description to use for the job. This is an
optional parameter.
start_time -- This specifies the time at which the job should start running, in
the format YYYYMMDDhhmmss. By default, it will contain the time that the
configuration file was generated. This is required, but if the current time or a
time in the past is specified then the job will be considered immediately
eligible for execution.
duration -- This specifies the maximum length of time in seconds that the job
should be allowed to run. This is an optional parameter.
delay_between_iterations -- This specifies the length of time in seconds that

should be allowed between the end of one iteration of an optimizing job and
the beginning of the next. This is a required parameter.
Optimizing Jobs 57
num_clients -- This specifies the number of clients that should be used to
execute the job. This is a required parameter and its value must be a positive
integer.
requested_clients -- This may be used to request that a specific set of clients

be used to run the job. This is optional, but if it is specified then it should be a
comma-delimited list of the addresses of the client systems to use.
min_threads -- This specifies the number of threads that should be created to

run the first iteration of the optimizing job on each client. This is a required
parameter and its value must be a positive integer.
max_threads -- This specifies the maximum number of threads per client that
should be used for an iteration of the optimizing job. This is an optional
parameter, and no value is provided then the optimizing job will continue to
run until it has determined that it has found the best performance.
thread_increment -- This specifies the increment to use for the number of

threads per client between iterations of the optimizing job. This is a required
parameter and its value must be a positive integer.
collection_interval -- This specifies the statistics collection interval (in

seconds) to use when running the job. This is a required parameter.
notify_addresses -- This specifies the e-mail address(es) of the individual(s)

to notify when the job has completed. This is an optional argument, but if it is
specified then it should contain a comma-delimited list of the e-mail addresses
to use.
optimize_statistic -- This specifies the name of the statistic for which the
optimal value should be found. The names of the statistics that may be
optimized will be provided in the comments immediately above the parameter
name.
optimize_type -- The type of optimization to perform on the statistic. This

parameter should have a value of either "Maximize" or "Minimize".
max_nonimproving -- This specifies the maximum number of nonimproving

iterations to use when running the optimizing job. The optimizing job will end
when this number of consecutive jobs have completed that do not yield better
results than the best job run so far. This is a required parameter and its value
must be a positive integer.

rerun -- This indicates whether the best iteration of the optimizing job should
be re-run to determine whether re-running it with the same settings yields the
same results. This must have a value of either "true" or "false".
rerun_duration -- This specifies the length of time in seconds to use as the

maximum duration for the re-run of the best iteration. It may be desirable to
run the re-run iteration for longer than the other iterations to verify that the
results are consistent.
Once the configuration file has been edited, the optimizing job may be scheduled
using the command-line job scheduler in exactly the same way as a regular job.
Refer to the section on scheduling jobs from the command line for details.
Optimizing Jobs 59
Organizing Job Information
After the SLAMD server is used to schedule and run a large number of jobs, the
page that stores completed job information can grow quite large, and the process
of displaying that page can take more time and consume more server resources.
Therefore, for the purposes of both organization and conserving system resources,
the server offers the ability to arrange jobs into folders. It is also possible to
specify a variety of criteria that can be used to search for job information,
regardless of the folder in which it is contained. This section provides
information on using job folders and searching for job information.
Real Job Folders
Real job folders correspond to the location of the job information in the
configuration directory. As such, it is only possible for a job to exist in a single
real folder. Real job folders are used to store information about jobs that have
completed execution so that viewing completed job information does not become
an expensive process.
When the "View Completed Jobs" sidebar link is followed, the SLAMD server
will display the list of completed jobs that have not been placed into any job
folder (i.e., "unclassified" jobs). However, it is possible to display the contents of
other real job folders by selecting the folder name from the drop-down list box at
the top of the page and clicking the "Refresh" button. Note that if no additional
job folders have been created, then this drop-down list box will not be displayed.
To create a new real job folder, click the "Create Folder" button at the bottom of
the page and supplying the name to use for the folder when prompted. Once a
new job folder has been created, it is possible to move jobs into that folder by
clicking the checkboxes in front of the desired job IDs and then clicking the
"Move" button at the bottom of the page.

Clicking the "Delete Folder" button at the bottom of the completed jobs page will
make it possible to delete a real job folder. Note that it is not possible to delete a
real job folder if there are any jobs contained in that folder. Therefore, before
deleting a real job folder, it is necessary to first either delete all jobs that it
contains or move those jobs into another folder.
Virtual Job Folders
Although real job folders can be very beneficial for a number of reasons, they
also have some drawbacks that prevent them from being useful in all
circumstances. For that reason, the SLAMD server offers the ability to classify
jobs in virtual folders in addition to real folders.
Virtual job folders offer a number of advantages over real job folders:
A virtual job folder is completely independent of real job folders. That is, a
virtual job folder can contain jobs from a number of different real job folders.
A virtual job folder is not dependent upon the location of the job information
in the configuration directory. Therefore, a single job can exist in multiple
virtual job folders while it can only exist in a single real job folder.
A virtual job folder can contain jobs in any state. Real job folders will not
display jobs in the pending, running, or disabled states.
In addition to having a specific list of jobs to include, a virtual job folder can
also have a set of search criteria that can be used to dynamically include jobs.
This allows newly-created jobs to be automatically included in the virtual job
folder without requiring any administrative action.
It is possible to add one or more jobs to a virtual job folder when viewing the list
of pending, running, or completed jobs (regardless of the real job folder being
displayed). This is also possible when viewing a list of jobs matching a given
search criteria. When adding jobs to a virtual job folder, an existing virtual folder
may be specified or a new one may be created. A new virtual job folder may also
be created by following the "Virtual Job Folders" link on the navigation sidebar
and clicking the "Create Virtual Job Folder" button on the resulting page. In
order to delete a virtual job folder, simply display that folder and click the "Delete
Virtual Job Folder" button at the top of the page. Note that because a virtual job
folder only contains references to jobs and not the job entries themselves, it is not
necessary to remove all jobs from a virtual job folder before it can be removed.
Organizing Job Information 61

Searching for Job Information
Although job folders provide a powerful means of organizing job data, it may
sometimes be necessary to work with jobs that are not contained in the same
folder, for example to make graphical comparisons between them. In such cases,
it would be possible to create a new virtual folder to hold those jobs temporarily
while performing the comparison, and then remove that folder immediately
thereafter. However, that may be an inconvenience, and if access controls are
enabled it may not be possible for all users. For this reason, the SLAMD server
provides a way to search for jobs based on a provided set of criteria.
The search criteria that may be used by the SLAMD server falls into two
categories. The first category consists of criteria that are applicable to any job
type. These criteria make it possible to search for jobs within a given time frame
(either scheduled or actual run times), with a given duration, or with a given
number of clients or threads per client. The second set of criteria consists of data
specific to one particular type of job. Any parameter that can be used in
scheduling the job may be used as search criteria, but the search will be restricted
only to jobs of the specified type. In the latter case, it is also possible to search
for jobs with statistical values within specified ranges, although this capability is
only available for certain kinds of statistics.
Whenever a search is performed, it is possible to perform a number of operations

on all or some of the matching jobs. Those options include:
for execution.
Compare -- This option will allow the user to generate graphs comparing the
results of the selected jobs. All jobs selected for comparison must be of the
same type and must have statistical information available, although it is not
necessary for them to have the same duration or statistics collection interval. If
any jobs are selected that are either of a different type than the first job chosen,
or if any selected jobs do not have statistics available, then those jobs will not
be included in the comparison. At least two valid jobs must be selected in
order to perform the comparison.
Export -- This option provides a way of exporting the summary data for the
selected jobs to a tab-delimited text file for use in an external application. If
all the jobs selected are of the same type, then it will be possible to specify

which specific parameters or statistics should be included in the export. If jobs
of multiple types are selected, only a limited set of options will be available.
Create Filtered Virtual Job Folder -- This option allows the user to save the
search criteria used to produce this result set in a filtered virtual job folder.
The new virtual job folder will contain a search filter that can be used to
dynamically issue the same query against the configuration directory to
retrieve the matching jobs.
Uploading Files into Job Folders
In many cases, the information displayed about a job when it has completed is not
adequate to obtain a complete understanding of the environment in which the job
was executed. For example, the job parameters may include information about
how to connect to a server, but they would likely not include any details about the
configuration of the server or the system resource utilization while the job was
active. While it may be possible to store at least some of this information in the
job comments, that is not suitable for larger amounts of information. To alleviate
that problem, SLAMD allows users with appropriate permissions to upload files
into job folders so that they may be stored in the configuration directory along
with the job results.
The list of files uploaded into a job folder will be displayed at the bottom of that
folder, either when viewing completed jobs or optimizing jobs. Each uploaded
file will offer up to three options:
View -- Opens a new window and will use it to display the file to the end user.
The content type sent to the browser will be the same as the content type used
to upload the file, so if the browser understands that file type then it will
display it properly.
Save -- Sends the file to the end user using a content type that will not be
recognized by the browser, which should cause the browser to prompt the user
with an option to save the file to disk.
Delete -- Offers the option to remove this file from the configuration directory.
Note that this option will only be displayed to those users that have permission
to manage folders.
Organizing Job Information 63

In addition, below this list of uploaded files, an "Upload File" button will be
displayed to users with permission to manage job folders. This button may be
used to upload files from the browser to the SLAMD server. The user may also
include a one-line description to indicate what the file contains.

Adding New Job Classes
The SLAMD server was designed in such a way that it is very extensible. One of
the ways that this is evident is the ability for an end user to develop a new job
class and add that class to the SLAMD server. Once that class has been added to
the SLAMD server, it will immediately be possible to schedule and run jobs that
make use of that job class. It is not necessary to copy that job class to all client
systems, as that will be done automatically whenever a client is asked to run a job
for which it does not have the appropriate job class.
NOTE Although job classes will be automatically transferred from the SLAMD
server to clients as necessary, if a job class uses a Java library that are
not already available to those client systems, then that library must be
manually copied to each client. Libraries in JAR form should be placed
in the lib directory of the client installation, and libraries provided as
individual class files should be placed under the classes directory (with
all appropriate parent directories created in accordance with the package
in which those classes reside).
It is also important to note that if any new versions of job classes are
installed, it is necessary to manually update each client, as the client
will not have any way of knowing that it would otherwise be using an
outdated version of the job class.
In order to install a new job class into the SLAMD server, it is first necessary to
place the Java class file for that job into a location that can be found by the Java
virtual machine in which the server is running. The best place for these job class
files is under the webapps/slamd/WEB-INF/classes directory, because any file
placed in that directory will be automatically included in the SLAMD server's
classpath. Note that you will need to create any subdirectories that correspond to
the package in which the new job exists. For example, if the new job is defined in
the "com.example.slamd.MyNewJob" class, then you will want to place the class
file in the webapps/slamd/WEB-INF/classes/com/example/slamd directory.
Once the job class has been placed in a location that is visible to the SLAMD
server, it is necessary to inform the server that the new class may be used for jobs.
Adding New Job Classes 65

To do this, follow the "Add a New Job Class" link at the bottom of the "Manage
Jobs" section of the navigation sidebar. This will display a form in which the
fully-qualified name of the Java class may be entered (e.g.,
"com.example.slamd.MyNewJob"). The SLAMD server will first verify that it can
find the indicated job class, and will then verify that it can properly be used as a
SLAMD job. If the new class is acceptable, then a page will be displayed with
information about the new job class. If the new class cannot be found or is not
acceptable, then a message describing the reason for the failure will be displayed.
Once the new job class has been added, it will be immediately available for
execution by clients. Any client that receives a job request for an unknown job
will request that job class from the server and will store that class locally for
future use.
Installing Job Packs
A job pack is a JAR file containing one or more job classes packaged in such a
way to make it easy to install those jobs for use in the SLAMD server. Job packs
may be made available by individuals that have developed custom jobs for use by
other SLAMD users. For information on creating job packs, consult the Job
Developer's Guide.
A job pack may be installed through the administrative interface by following the
"Install a Job Pack" link in the navigation sidebar. If the job pack file is on the
local client system (i.e., the system running the browser), use the upper form to
browse for the file on the local filesystem and click the "Install Job Pack" button
in that form to upload the file to the server and install the job pack. If the job
pack file is on the system running the SLAMD server, use the lower form to
provide the absolute path to that job pack file on the server filesystem and click
the "Install Job Pack" button on that form to install the job pack.
If all goes well, the file will be uploaded to the server, the job classes contained in
it will be unpacked, and the jobs will be registered for use in the SLAMD server.
At this point, the new job classes will be visible by following the "View Job
Classes" or "Schedule a Job" link.

Using the Standalone Client
Even though jobs are designed to be scheduled and coordinated by the SLAMD
server, it is possible to execute a job as a standalone entity. This can be
convenient if you want to run a job in an environment where there is no SLAMD
server available, if you do not need advanced features like graphing results, or if
you are developing a new job for use in the SLAMD environment and wish to test
it without scheduling it through the SLAMD server.
The standalone client is similar to the network-based client in that it is included in

the same installation package as the network client and requires that a Java
environment (1.4.0 or higher) installed on the client system. However, because
there is no communication with the SLAMD server, it is not necessary that the
client address be resolvable or that any SLAMD server be accessible.
The standalone client reads its configuration from the slamd_client.conf file
like the normal SLAMD client. Therefore, it should not be necessary to edit
start_client_manager.sh file before the standalone
Since the standalone client operates independently of the SLAMD server, it is not
possible to use the administrative interface to define the parameters to use for the
job. Instead, the standalone client reads the values of these parameters from a
configuration file. In order to generate an appropriate configuration file, issue the
command:
./standalone_client.sh -g {job_class} -f {config_file}
where {job_class} is the fully-qualified name of the job class file (e.g.,
"com.sun.slamd.example.SearchRateJobClass"), and {config_file} is the path and
name of the configuration file to create. This will create a configuration file may
be read by the standalone client to execute the job. Note that this configuration
file will likely need to be modified before it can actually be used to run a job, but
comments in the configuration file should explain the purpose and acceptable
values for each parameter.
Once an appropriate configuration file is available, then the standalone client may
be used to run the job. In its most basic form, it may be executed using the
command:
Using the Standalone Client 67

./standalone_client.sh -f {config_file}
This will read the configuration file and execute the job defined in that
configuration file using a single thread until the job completes. However, this
default configuration is not sufficient for many jobs, and therefore there are
additional command-line arguments that may be provided to further customize its
behavior. Those configuration parameters are:
-- Specifies the path and name of the configuration file containing

-f {filename}
the information about the job to be executed. See above for information about
generating such a configuration file.
-- Specifies the path and name of the output file to which

-o {filename}
information about job processing will be written. If this is not specified, then
this information will be written to standard output.
-d {value} -- Specifies the job duration,which is the maximum length of time in

seconds that the job should be allowed to run before it is requested to stop. If
this is not specified, then no maximum duration will be enforced.
-- Specifies the statistics collection interval, which is the unit of time

-i {value}
in seconds for which statistical information will be available.
-t {value} -- Specifies the number of threads that will be created to execute the
job. If this is not specified, then a single thread will be used.
-L -- Indicates that the custom job class loader should be disabled and that the
standard class loader should be used for loading job classes.
-h -- Prints usage information for the standalone client and exits.

Configuring the SLAMD Server
Once the SLAMD server has been installed and the settings for the configuration
directory have been specified, the SLAMD server will use a default configuration.
In many cases, the default configuration will be sufficient. However, there are a
number of settings that may be customized to change the way that the various
components of the SLAMD server operate. This section describes the parameters
that are available for the components of the SLAMD server so that it may be
configured most appropriately for the environment in which it will be used.
Configuration Directory Settings
Most of the configuration for the SLAMD server is stored in the configuration
directory. However, when the server is started it must have enough information
available to be able to establish the connection to the configuration directory.
This information is stored in a configuration file (webapps/slamd/WEB-
INF/slamd.conf) that is read when the servlet engine is started. This file also
contains information used for configuring access control in the administrative
interface, but the details of configuring access control are discussed in a later
section.
Note that while it is possible to edit this file by hand, this should not be done
while the SLAMD server or the associated servlet engine are running. Further, it
is recommended that all configuration changes to information in this file be made
through the administration interface.
To edit the settings used to contact the configuration directory, follow the
"Initialization Parameters" link under the "Startup Configuration" section. This
will display a page summarizing the values of all the parameters used to access
the configuration directory. Clicking the link on each parameter name will
display a form in which the value of that option may be changed, in addition to a
detailed description of the purpose of that parameter.
Configuring the SLAMD Server 69

The values of most of these parameters are discussed earlier in this document as
part of the installation process and will not be repeated here. The configuration
parameters not described in that section deal with the use of SSL to communicate
with the configuration directory, which is described in a subsequent section.
Core SLAMD Server Configuration
In general, the SLAMD server is comprised of a number of components that

perform specialized functions. At the very core, the server primarily serves to
coordinate between these components. The client listener, logger, and scheduler
all communicate with each other through the core SLAMD server, and the
administrative interface does the same to expose all the capabilities of the server
to the end user.
Although the primary purpose of the core server is coordination between the other
components, it does have some configuration parameters that may be adjusted:
Job Cache Size -- This parameter specifies the number of jobs that may be
stored in memory within the SLAMD server's job cache. Normally, job
information is stored in the configuration directory, but a small number of jobs
may be stored in the job cache for faster access. Whenever information about
a job is retrieved from the configuration directory, that job will be stored in the
cache so that the next time the information is accessed it will be retrieved from
memory rather than requiring an additional query in the configuration directory
to retrieve the same information. Specifying a larger value allows more jobs to
be stored in memory, but also increases the amount of memory that the
SLAMD server uses. Unless a number of users are expected to access the
administrative interface concurrently, the default job cache size should be
sufficient and increasing this value will not result in a noticeable performance
improvement.
Changes to this parameter will not take effect until the SLAMD server is
restarted.
Log Level -- This parameter specifies the kinds of information that will be
written to the SLAMD server's log file (by default, this log file is created as
webapps/slamd/WEB-INF/slamd.log). Normally, the server logs summary
messages about interaction with clients and job processing, as well as some
significant events and major errors that will always be logged. Unless some
problem is experienced that cannot be debugged some other way, it is
recommended that this default log level be used.
Changes to this parameter will take effect immediately, without the need to

restart the SLAMD server.
The log levels that may be specified include:
- Trace Function Calls -- Provides debugging information about the path
taken to execute code in the various components of the SLAMD server.
This information is of minimal use to the end user but may help in solving
some problems.
- Configuration Handling -- Provides information about changes made to or
values read from the configuration directory server.
- Job Processing -- Provides information about significant events that occur
while a job is being processed.
- Client/Server Interaction -- Provides information about communication that
occurs between clients and the server.
- Admin Interface Events -- Provides debugging information about the
processing associated with interacting with the end user through the
administrative interface.
- SLAMD Server Operation Debugging -- Provides debugging information
about operations that occur within the core SLAMD server.
- Job Processing Debugging -- Provides debugging information about
operations that occur while a job is being processed.
- Client Interaction Debugging -- Provides debugging information about
interaction between clients and the server.
- Scheduler Debugging -- Provides debugging information about operations
that occur within the scheduler.
- Access Manager Debugging -- Provides debugging information about
interaction with the access control manager used to determine the
permissions that a user has in the administrative interface.
Use Custom Class Loader -- This parameter indicates whether the custom job
class loader should be used to load SLAMD job classes. This class loader
provides the ability to dynamically reload modified job classes without the
need to restart the SLAMD server. This is enabled by default, but some users
have reported problems when attempting to load custom jobs (in particular
illegal access exceptions). If such problems arise, this configuration parameter
may be used to disable the custom class loader which should avoid those
problems.
NOTE If the "com.sun.slamd.disableCustomClassLoader" Java system

property is set with a value of "true", then the custom class loader will
not be used, regardless of the setting for the "Use Custom Class Loader"
configuration parameter in the administrative interface. This makes it
possible to use SLAMD in Web application containers that do not allow
custom class loaders to be used.

Mailer Configuration
The mailer component of the SLAMD server may be used to send an e-mail
message to notify one or more users whenever a job has completed. This option
is enabled on a per-job basis (it is among the advanced scheduling options) and
can be specified when the job is scheduled. However, in order to enable this
option, it is first necessary to configure the mailer.
Enable SLAMD Mailer -- Indicates whether the SLAMD server may send e-
mail messages to notify users that a job has completed. If this is disabled, then
the "Notify on Completion" option will not be displayed in the advanced
scheduling options when defining a new job. In addition, if it is disabled, then
the SLAMD server will not send an e-mail notification for any jobs that may
be pending or running, regardless of whether notification addresses have been
provided for those jobs.
Note that the SLAMD server will not allow the mailer to be enabled unless
values have also been provided for the "SMTP Server Address" and the "From
Address" mailer configuration parameters.
SMTP Server Address -- Specifies the DNS hostname or IP address that

should be used to for the SMTP server that will be used to send the notification
e-mail messages. Whenever a notification needs to be performed, the SLAMD
server will attempt to establish an SMTP session with the system specified by
this parameter in order to send the messages. It is not possible to enable the
SLAMD mailer unless a value has been provided for this configuration
parameter.
SMTP Server Port -- Specifies the port number that should be used to
communicate with the SMTP server. The default SMTP port number is 25,
and this should be the correct value in most cases.
From Address -- Specifies the e-mail address that should be used as the
"from" address for the e-mail messages sent by the SLAMD server. It does not
need to be a valid e-mail address, but a value must be specified before the
SLAMD mailer can be enabled.
Servlet Base URI -- Specifies the URL that should be used to access the
SLAMD server's administrative interface. This is an optional parameter, but if
it is specified then e-mail notification messages will include a link to a page in
which the user can view additional information about the job in the
administrative interface. If desired, this can be a URL that points to a read-
only version of the SLAMD server so that users may view information about
the job without being able to clone the job or delete information about it from
the SLAMD server.

Logger Configuration
The logging component of the SLAMD server is used to record information about
things that happen while SLAMD is running. By default, the information written
to this log is relatively limited and includes information about SLAMD startup
and shutdown, job processing, and clients that connect and disconnect. However,
it can be configured (using the log level setting described above) to provide more
verbose output for debugging purposes. In addition, there are a number of other
parameters that can be specified for the logger:
Logger Enabled -- Indicates whether the logger will be used to write data into
the SLAMD log file. By default, the logger will be used but if this checkbox is
disabled, then nothing will be written to the specified log file.
Log File Name -- Specifies the path and name of the file to which log
messages will be written. By default, this file is webapps/slamd/WEB-
INF/slamd.log, but it may be placed in any location that the servlet engine has
permission to write.
restart the SLAMD server. However, if logging is performed asynchronously,
it is possible that some messages logged before the change will still be in the
internal log buffer and will be written to the new file rather than the log file
that was in use at the time the log file was changed.
Always Flush to Disk -- Specifies whether the logger should always perform a
flush after writing anything to disk. Regardless of whether logging is to be
performed synchronously or asynchronously, messages written to the log file
may be buffered internally by the Java I/O implementation rather than
committed to disk immediately. This may provide better performance,
especially when large amounts of information are written to the log, but does
present the possibility that some messages may be lost in the event of a crash
or an abrupt shutdown.
Log Asynchronously -- Specifies whether logging should be performed

synchronously or asynchronously. If logging is performed synchronously, then
each time a message is logged, it will be written out to disk. If logging is
performed asynchronously, then it will be stored in an internal buffer whose

contents will be periodically written to disk. This may provide slightly better
performance, especially when a large number of messages are being logged.
Changes to this parameter are not automatically applied. It is necessary to
restart the SLAMD server in order to change from synchronous to
asynchronous logging, or vice-versa.
Logger Thread Configuration
As described above, whenever logging is performed asynchronously, the log

messages are temporarily stored in an internal queue and periodically written to
disk in bulk to allow better throughput. This is handled through the use of a
separate thread that periodically polls that internal queue, retrieves any messages
contained in it, and writes those messages to disk. If logging is performed
synchronously, then no separate logger thread is used.
The logger thread has a single parameter that may be customized:
Log Poll Delay -- Specifies how frequently (in seconds) the logger thread will
poll the log queue for new messages. If this is set to a smaller value, then the
logger queue will be polled more often and any messages logged will be
written to disk more frequently. In most cases, the default value should be
sufficient.
Changes to this parameter are automatically applied without the need to
restart the SLAMD server. However, it may take some time for the change to
be recognized (up to a time equal to the previous value of the poll delay).
Client Manager Listener Configuration
The client manager listener is the component of the SLAMD server that listens
for and accepts connections from client managers, which may be used to establish
and disconnect client connections.
The client listener has a number of settings that may be customized:
Client Manager Listener Port -- Specifies the port number on which the
SLAMD server will listen for new connections from client managers. By
default, this is port 3001. If it is changed, then all client managers will need to

be updated to use the new port.
Changes to this parameter are not applied automatically and require that
the SLAMD server be restarted.
Maximum Wait Time -- Specifies the maximum length of time in seconds

that the client manager listener will wait for a response to a request that the
server has sent to a client manager. The default value should be sufficient for
most cases unless there is a slow or high-latency connection between the server
and any of the clients, in which case increasing the value may help prevent
missed responses.
Changes to this parameter are applied automatically and without the need
to restart the SLAMD server. However, it will be applied only to new client
manager connections that are established after the change is made. If it is
desirable to use an updated wait time with a client that is already connected,
then that client will need to close and re-establish its connection to the
SLAMD server.
Client Listener Configuration
The client listener is the component of the SLAMD server that listens for and
accepts connections from client systems. The client listener also maintains a list
of the clients that are currently connected to the server and works in conjunction
with the scheduler to allocate an appropriate set of clients to process jobs.
The client listener has a number of settings that may be customized:
Client Listener Port -- Specifies the port number on which the SLAMD
server will listen for new connections from clients. By default, this is port
3000. If it is changed, then all clients will need to be updated to use the new
port.
Keepalive Interval -- Specifies the maximum length of time in seconds that

should be allowed to pass with no communication between the client and the
server. If the client has not communicated with the server within this amount
of time, then the server will send a keepalive message to that client. The
default value of zero disables the use of keepalive messages, and this should be
acceptable in most cases. However in some cases, especially if the clients
connect to the SLAMD server through a firewall, an idle connection may be
closed and keepalive messages are needed to ensure that this does not happen.

to restart the SLAMD server. However, it will be applied only to new
connections that are established after the change is made. If it is desirable to
use an updated keepalive interval with a client that is already connected, then
that client will need to close and re-establish its connection to the SLAMD
server.
Maximum Number of Clients -- Specifies the maximum number of clients

that may be connected to the SLAMD server at any given time. The default
value of zero indicates that there is no limit, and this value should be sufficient
in most cases. However, if a limit is desired, then it may be configured using
this parameter. Once the limit is reached, any client that attempts to establish a
connection will receive a message indicating that all available connections are
in use and the connection will be closed.
to restart the SLAMD server. However, if this value is decreased and there are
already more connections established than the new maximum value, none of
the existing connections will be closed.
Maximum Wait Time -- Specifies the maximum length of time in seconds

that the client listener will wait for a response to a request that the server has
sent to a client. The default value should be sufficient for most cases unless
there is a slow or high-latency connection between the server and any of the
clients, in which case increasing the value may help prevent missed responses.
to restart the SLAMD server. However, it will be applied only to new
connections that are established after the change is made. If it is desirable to
use an updated wait time with a client that is already connected, then that client
will need to close and re-establish its connection to the SLAMD server.
Use SSL -- Indicates whether the client listener should use SSL to accept
connections from clients. If this is enabled, then the correct SSL key and trust
store information must be configured in the Initialization Parameters section.
Note that this applies both to the client listener and the client manager listener,
as they will both either use SSL or both not use SSL.
Require Authentication -- Indicates whether clients will be required to

provide an authentication ID and password when establishing a connection to
the SLAMD server, which can be used to prevent unauthorized clients from
connecting. Note that if this is enabled, then it is also necessary to implement
access control in the administrative interface.

Resource Monitor Client Listener Configuration
The resource monitor client listener is the component of the SLAMD server that
is used to accept connections from resource monitor clients that capture system
resource information. It has only a single configuration parameter:
Client Manager Listener Port -- Specifies the port number on which the
SLAMD server will listen for new connections from resource monitor clients.
By default, this is port 3002. If it is changed, then all client managers will
need to be updated to use the new port.
Real-Time Stat Listener Configuration
The real-time stat listener is the component of the SLAMD server that is used to
accept connections from clients that report job statistics back to the SLAMD
server while the job is in progress. It has the following configuration parameters:
Stat Listener Port -- Specifies the port number on which the SLAMD server
will listen for new connections from clients for the purpose of reporting in-
progress job statistics. By default, this is port 3003. If it is changed, then all
client managers will need to be updated to use the new port.
Max Stat Intervals -- Specifies the maximum number of collection intervals

for which in-progress statistics reported by clients will be retained. Older data
may be discarded in order to make room for new data. By default, the
SLAMD server will store and report data from at most 60 collection intervals
while a job is in progress.

Scheduler Configuration
The scheduler is the component of the SLAMD server that keeps track of the jobs
that have been requested and handles the process of starting them at the
appropriate times and keeping track of them until they have completed running on
all clients.
The following scheduler configuration parameters may be customized:
Scheduler Poll Delay -- Specifies how frequently the scheduler will look
through the pending jobs queue to see if any jobs requests should be sent to
clients for processing. By default, the scheduler will iterate through the
pending jobs queue every five seconds.
Changes to this parameter are applied automatically and without a need to
Job Start Buffer -- Specifies how long before the job's start time the job
request should be sent to client systems. By default, the job information will
be sent to clients approximately 30 seconds before the job is supposed to start
running. This should allow the client time to receive the request, start all
appropriate threads, and perform any necessary initialization that should be
done before the start time actually arrives. However, if clients will be asked to
run jobs that require a significant amount of initialization, then it may be
beneficial to increase the value of this start buffer so that all the initialization
can be complete before the start time arrives.
Note that this option may only be used for jobs that are scheduled with a
start time of some point in the future and only in cases in which all
prerequisites are met for the job to start running when the start time arrives. If
a job is scheduled to run as soon as possible (with either the current time or
sometime in the past set as the start time), then the start buffer will not be used.
Further, if the start time arrives for a job but that job still has unresolved
dependencies or there is not an appropriate set of clients available to run that
job, then the job execution will be delayed, and if it is delayed long enough
then the start buffer will not be used.
Job Refresh Interval -- Specifies the frequency in seconds with which the
scheduler should poll the configuration directory for new job definitions. The
default value of zero indicates that the scheduler will not poll the configuration
directory for jobs, and any new jobs defined in the configuration directory that
were not scheduled through the administrative interface will not be recognized
and scheduled for execution until the SLAMD server is restarted. However, if
the server is configured with a nonzero refresh interval, then new jobs may be

scheduled by adding the job definition into the configuration directory without
the need to use the administrative interface. Note that there is currently no
utility available to schedule jobs in this manner, but such a tool may exist in
the future.
NOTE The "Job Refresh Interval" feature has now been deprecated and will
likely be removed in a future SLAMD release. Please use the
command-line job scheduler to automate the process of scheduling new
jobs.
User Interface Configuration
The HTML pages that comprise the SLAMD administrative interface are
dynamically generated, and much of the HTML that is generated cannot be
altered. However, some aspects of the user interface may be customized by the
end user, and provide a convenient way to specify default values for frequently-
used settings.
The parameters that may be customized within the user interface are listed below.
All of these parameters may be changed on the fly without the need to restart the
SLAMD server or the servlet engine that serves the HTML content.
Supply Default Start Time -- Indicates whether the current time should
automatically be specified as the start time when scheduling a new job for
execution. This is enabled by default, and as a result any form displayed that
allows the user to schedule a new job for execution will automatically have the
start time field populated with the current time. This may make it easier for
the end user to specify a start time because the value provided would already
be in the correct format and it would only be necessary to change a few digits.
If this option is disabled, then forms allowing users to schedule new jobs will
have the start time field blank by default.
Always Show Advanced Scheduling Options -- Indicates whether advanced

scheduling options should be hidden by default when scheduling a job. By
default, this is disabled, which means that certain options will not be displayed
when scheduling a job unless the "Show Advanced Scheduling Options" button
is clicked. If this feature is enabled, then those options will always be
displayed when scheduling a new job.

Show Login ID -- Indicates whether the login ID of the currently authenticated
user should be displayed in the administrative interface. Note that this applies
only when access control is enabled in the administrative interface, and
therefore if access control is not used then no login ID will be displayed. By
default, this feature is enabled and the login ID is displayed at the top of the
navigation sidebar. However, this may be disabled so that the login ID is not
displayed.
Show Time in Sidebar -- Indicates whether the SLAMD server should display
the current time at the top of the navigation sidebar. This is a convenience
feature, intended to be used when scheduling a new job. It allows the user to
determine the current time so that it is easy to select an appropriate start time
for the job.
Disable Graphs -- Indicates whether users will be able to view graphs of the
statistics gathered during job execution. By default, the graphing capability is
enabled, and users will be able to view graphs for a single job or that compare
the results of multiple jobs. However, on some systems a graphics
environment may not be available (on UNIX systems the Java AWT library
used to generate the graphs requires access to an X server to render the
graphics), and if that is the case then the graphing capability may be disabled
so that users will not be presented with options to graph statistics or compare
job results.
Display Graphs in New Window -- Indicates whether a new browser window

will be opened to hold graphs of job statistics. If this is set to "true", then a
new window will be opened and the graph will be displayed there without the
page header or navigation sidebar. If this is set to "false", then the current
window will be used, and the page header and navigation sidebar will remain.
Default Graph Width -- Specifies the width in pixels that will be used when
generating graphs of job results. This value may be customized when viewing
any graph, but the initial graph displayed will always use the default width and
height. Any positive value may be specified, although a value that is too small
may result in graphs that appear "squished", while values that are too large
may not fit on some displays.
Default Graph Height -- Specifies the height in pixels that will be used when
generating graphs of job results. This value may be customized when viewing
any graph, but the initial graph displayed will always use the default width and
height. Any positive value may be specified, although a value that is too small
may result in graphs that appear "squished", while values that are too large
may not fit on some displays.
Default Monitor Graph Height -- Specifies the height in pixels that will be
used when generating graphs of resource monitor statistics. In many cases, it

will be desirable to use a smaller height for resource monitor graphs than for
graphs of job statistics.
Include Server Name in Page Title -- Indicates whether the address of the
SLAMD server should be included in the title of the HTML pages that are
generated. This is disabled by default, but may be useful in cases where a user
is interacting with multiple SLAMD servers concurrently (e.g., performing
benchmarks on multiple private networks that cannot communicate with each
other).
Disable File Uploads -- Indicates whether the SLAMD server should disable
the ability for end users with appropriate permissions to be able to upload files
to be associated with job folders. By default, this users with appropriate
permissions will be allowed to upload files.
Maximum File Upload Size -- Specifies the maximum file size in bytes that
authorized users will be allowed to upload. A value of -1 indicates that no
limit will be imposed.
Enable Management of Read-Only Options -- Indicates whether the

administrative interface should display options that will only be used for the
purpose of publishing jobs in restricted read-only mode. This is disabled by
default, but should be enabled if there are plans to run an instance of the server
in restricted read-only mode.
Hide Optimizing Job Iterations -- Indicates whether the list of completed

jobs should omit any jobs that are associated with an optimizing job. If this is
set to "true", then viewing the list of completed jobs will only display jobs not
associated with an optimizing job.
Report Generator Classes -- This specifies the fully-qualified names of the

Java classes that may be used to generate reports of SLAMD data. The
mechanism that SLAMD uses to generate reports is extensible, but at this time
the API for developing custom report generators has not been made public.
Lines to Add to HTML Header -- This provides the ability for an

administrator to add content into the header of the generated HTML pages (i.e.,
content provided between the "<HEAD>" and "</HEAD>" tags of the generated
pages. The page title, content type, and style sheet data will always be
provided, but if the user wants additional content in the header for some
reason, then it may be specified using this parameter.
HTML Style Sheet -- This provides the ability for an administrator to define
the CSS style sheet that should be used for the generated HTML content. A
default style sheet is provided, but an administrator may change that to alter
many aspects of the appearance of the administrative interface.

Page Header -- This provides the ability for an administrator to define the
HTML content that will be placed at the top of each page in the administrative
interface. The default page header is a table with the Sun logo, the text
"SLAMD Server Administration", and the SLAMD version. If an alternate
header is desired, then it may be specified using this parameter.
Page Footer -- This provides the ability for an administrator to define the
HTML content that should be placed at the bottom of each page in the
administrative interface. This content will be included just below the
copyright message. By default, no additional value is included.
Main Page Contents -- This provides the ability for an administrator to

change the text that appears on the SLAMD intro page, which is shown
whenever the user initially accesses the SLAMD administrative interface
without choosing any operation to perform.
The following custom style types are used in the SLAMD administrative
interface. If an administrator wishes to alter the style sheet used, then these may
be included in the styles that are updated:
blue_background -- This style is used as the background color for the

leftmost cell in the table used as the default page header (i.e., the cell
containing the Sun logo).
yellow_background -- This style is used as the background color for the

center cell in the table used as the default page header (i.e., the cell containing
the text "SLAMD Server Administration").
red_background -- This style is used as the background color for the

rightmost cell in the table used as the default page header (i.e., the cell
containing the SLAMD version).
copyright -- This style is used for the copyright message at the bottom of
generated pages.
nav_bar -- This style is used for the general format of the navigation sidebar
(by default, this defines the gray background used for the sidebar).
nav_header -- This style is used for header elements in the navigation sidebar
(i.e., "Manage Jobs", "Startup Configuration", etc.).
nav_link -- This style is used for the links in the navigation sidebar (i.e.,
"View Pending Jobs", "View Running Jobs", etc.).

warning -- This style is used for warning notices or other noteworthy
information that will appear at the top of the page below the header.
main_form -- This style is used to provide formatting for most forms used in
the administrative interface.
main_header -- This style is used to define the formatting for the title at the
top of each page even with the top of the navigation sidebar.
form_caption -- This style is used to define the formatting used for caption
elements in forms, in particular for the names of parameters on the form
allowing a user to schedule a job.
job_summary_a -- This style is used for defining the formatting used for
even-numbered rows in lists of jobs and optimizing jobs (i.e., the lines with the
gray background in the default style).
job_summary_b -- This style is used for defining the formatting used for odd-
numbered rows in lists of jobs and optimizing jobs (i.e., the lines with the
white background in the default style).
If the page header, page footer, or main page contents are to be updated, then they
can include tags that will dynamically be replaced with appropriate values. The
tags that may be included are:
####SLAMD_VERSION#### -- This will be replaced with the version number for

the SLAMD build in the form major.minor.point (e.g., "1.2.3").
####SLAMD_MAJOR_VERSION#### -- This will be replaced with the major version

number for the SLAMD build. If the SLAMD version is "1.2.3", then the
major version will be "1".
####SLAMD_MINOR_VERSION#### -- This will be replaced with the minor version

number for the SLAMD build. If the SLAMD version is "1.2.3", then the
minor version will be "2".
####SLAMD_POINT_VERSION#### -- This will be replaced with the point version

number for the SLAMD build. If the SLAMD version is "1.2.3", then the point
version will be "3".
####SLAMD_BUILD_DATE#### -- This will be replaced with the SLAMD build

date. It will be in the form "YYYYMMDDhhmmss".
####SLAMD_UNOFFICIAL_BUILD_ID#### -- This is a conditional tag that will be

replaced with the SLAMD build date if the current version of SLAMD is an

unofficial build. If an official build is running, then it will be replaced with an
empty string.
####SUN_LOGO#### -- This will be replaced with an HTML image reference to

the Sun Microsystems logo.
Exporting and Importing Job Data
In many cases, it is desirable to perform benchmarking on a private network so

that the environment can be carefully controlled and to ensure that there are no
external influences on the collected data. In these cases, the SLAMD server
should also be located on that private network so that the clients can communicate
with it without any special network configuration. However, it may also be
desirable to have a more public SLAMD server that allows others to see the
results of jobs that have been completed. To facilitate this, SLAMD offers a way
to easily export the data from one server in a format that can be imported into
another.
To export data from the SLAMD server, follow the "Export Job Data" link in the
"Manage Jobs" section of the navigation sidebar. Upon doing this, a page will be
displayed that allows the user to choose what data to include in the export. By
default, all data stored in the SLAMD server will be included, but it is possible to
only include information from a subset of the folders. After choosing the
appropriate data to include and clicking the "Export" button, the file will be sent
to the user through the browser just like downloading any other kind of file. The
resulting data file will contain all job data, optimizing job data, and any uploaded
files that may have been contained in the selected folders. It will be in an internal
format that is not suitable for use in any application outside of SLAMD.
To import this data into another SLAMD instance, it is first necessary to place the
export file on that SLAMD server's local filesystem, making sure that it is
readable by the user account under which the SLAMD server process operates.
Then, follow the "Import Job Data" link in the navigation sidebar and provide the
absolute path to the data file. SLAMD will parse that file and import its contents
into the underlying configuration directory, making those jobs available for
display in that instance.

Generating Reports
While SLAMD offers access control features and a read-only mode that can be
used to give users access to job data without the ability to perform certain
undesirable operations (e.g., deleting jobs, scheduling new jobs, etc.), this
capability may not be sufficient for all cases. For example, if the SLAMD server
is located on a network that the end user cannot access, then there must be some
other way of providing that information to the user. In order to facilitate this,
SLAMD offers a means of generating self-contained reports that can be viewed
by users with no access to the server.
A report may contain information about a single job or optimizing job, a selected
set of jobs or optimizing jobs within a folder, or information about all jobs and
optimizing jobs contained in a given folder. To generate a report for a single job
or optimizing job, navigate to the page containing information about that job and
click the "Generate Report" button at the top of the page. To generate a report for
a selected set of jobs or optimizing jobs within a folder, view the list of jobs in
that folder, select the jobs to export, and click the "Generate Report" button at the
bottom of the page. To generate a report for all jobs and optimizing jobs in a
folder, click the "Generate Report" button at the bottom of the page without any
jobs selected.
SLAMD provides the ability to generate reports in different formats. At the

present time, the following formats are available:
Plain Text Report Generator -- This report generator will create a plain text
file containing the selected data. Reports generated using this format should be
accessible using any text editor.
HTML Report Generator -- This report generator will create a zip archive
containing a number of HTML documents and optionally images containing
graphs of the job data. Reports generated using this format should be
accessible using any browser capable of rendering HTML 4.01.
SLAMD has been designed so that new report formats can be added in a
relatively easy manner. However, at this time the API required to define a new
report generator has not been made public.

Starting and Stopping SLAMD
The SLAMD server has been designed so that it should not need to be restarted
frequently. Most of the configuration parameters that may be specified within the
SLAMD server can be customized without the need to restart the server itself or
the servlet engine that provides the administrative interface. However, some
changes do require that the server be restarted for that change to take effect, and
this section will describe the preferred ways of starting, stopping, and restarting
the SLAMD server and the Tomcat servlet engine.
Starting the Tomcat Servlet Engine
By default, SLAMD uses the Tomcat servlet engine to generate the HTML pages
used for interacting with the SLAMD server. However, the servlet engine is
responsible for not only generating these HTML pages, but actually for running
the entire SLAMD server. All components of the server run inside the Java
virtual machine used by the servlet engine. Therefore, unless the servlet engine is
running, the SLAMD server will not be available.
As described earlier in this document in the discussion on installing the SLAMD

server, the Tomcat servlet engine may be started by using the bin/startup.sh
shell script provided in the installation archive. This shell script will need to be
edited to specify the path of the Java installation, the amount of memory to use,
and the location of an X server to use when generating graphs. Once that has
been done, this shell script may be used to start the Tomcat servlet engine.
Starting SLAMD
By default, the SLAMD server will be loaded and started automatically when the
servlet engine starts. However, if a problem is encountered when the servlet
engine tries to start the SLAMD server (e.g., if the configuration directory server

is unavailable), then the Tomcat servlet engine will be started but SLAMD will
remain offline. If this occurs, then a message will be displayed indicating that the
SLAMD server is unavailable, and this message should also include information
that can help administrators diagnose and correct the problem.
When the problem has been corrected, the SLAMD server may be started by
following the "SLAMD Server Status" link at the bottom of the navigation bar
and clicking the "Start SLAMD" button (this button will only be visible if the
SLAMD server is not running). This will attempt to start the SLAMD server. If
the attempt is successful, then the full user interface will be available. If the
SLAMD server could not be started for some reason, then it will remain offline
and an informational message describing the problem that occurred will be
displayed.
Restarting SLAMD
As indicated earlier, there are a few configuration parameters that require the
SLAMD server to be restarted in order for changes to take effect. This can be
done easily through the administrative interface without the need to restart the
servlet engine. To do so, follow the "SLAMD Server Status" link at the bottom
of the navigation bar and click the "Restart SLAMD" button on the status page
(this button will only be visible if the SLAMD server is currently running). This
will cause the SLAMD server to be stopped and immediately restarted.
Note that stopping or restarting the SLAMD server (or the servlet engine in which
it is running) will disconnect all clients that are currently connected to the server.
If any of those clients are actively processing jobs, then an attempt will be made
to cancel those jobs and obtain at least partial results, but this cannot be
guaranteed. Any jobs that are in the pending jobs queue are also stored in the
configuration directory and will be properly re-loaded when the SLAMD server is
restarted, although if the SLAMD server is offline for any significant period of
time, then the start times for some of those jobs may have passed which could
cause the pending jobs queue to become backlogged when the server is restarted.
Stopping SLAMD
Restarting the SLAMD server should be sufficient for cases in which it is only
necessary to re-read configuration parameters, but in some cases it may be
necessary to stop the SLAMD server and leave it offline for a period of time (e.g.,
if the configuration directory server is taken offline for maintenance). This can
Starting and Stopping SLAMD 87

be done by following the "SLAMD Server Status" link at the bottom of the
navigation bar and clicking the "Stop SLAMD" button on the status page. This
will cause the SLAMD server to be stopped, and it will remain offline until the
"Start SLAMD" button is clicked or until the servlet engine is restarted.
Note that stopping or restarting the SLAMD server (or the servlet engine in which
it is running) will disconnect all clients that are currently connected to the server.
If any of those clients are actively processing jobs, then an attempt will be made
to cancel those jobs and obtain at least partial results, but this cannot be
guaranteed. Any jobs that are in the pending jobs queue are also stored in the
configuration directory and will be properly re-loaded when the SLAMD server is
restarted, although if the SLAMD server is offline for any significant period of
time, then the start times for some of those jobs may have passed which could
cause the pending jobs queue to become backlogged when the server is restarted.
Stopping the Tomcat Servlet Engine
It should be possible to edit all of the SLAMD server's configuration without

needing to restart the servlet engine in which SLAMD is running. However, if
the configuration of the Tomcat servlet engine itself is to be modified, then it is
necessary to stop and restart Tomcat for those changes to take effect.
Before stopping Tomcat, it is recommended that the SLAMD server be stopped

first. To do this, follow the "SLAMD Server Status" link and click the "Stop
SLAMD" button. Once the SLAMD server has been stopped, it is possible to
stop the Tomcat servlet engine using the bin/shutdown.sh shell script.
If the SLAMD server is not stopped before the attempt to stop the Tomcat servlet
engine, then it is possible (although unlikely) that the Tomcat servlet engine will
not stop properly. If that occurs, then the servlet engine may be stopped by
killing the Java process in which it is running (note that on Linux systems it may
appear as multiple processes). The Tomcat startup scripts have been modified so
that the process ID of the Tomcat process should be written into the logs/pid
file, and if Tomcat does not shut down properly, then this PID may be used to
determine which process or processes should be killed. If it is necessary to
manually kill the Tomcat process, then it should be done using the SIGTERM
signal (the default signal used when the kill command is issued). A SIGKILL
signal should only be used if the Tomcat process or processes do not respond to
the SIGTERM signals.

Tuning the Configuration Directory
In addition to storing the SLAMD configuration, the configuration directory is

used to store information about all jobs that have been scheduled for execution in
the SLAMD environment, including the statistical information gathered from jobs
that have completed. Nearly all of the operations that can be performed in the
administrative interface require some kind of interaction with the configuration
directory, and therefore properly tuning the configuration directory can
dramatically improve the performance of the administrative interface and the
SLAMD server in general. Further, entries that store statistical information may
grow quite large and without proper configuration, it may not be possible to store
this information in the directory. The changes that should be made to the
directory server configuration are described below.
Configuring for Large Entries. All information about scheduled jobs is stored
in the configuration directory. For completed jobs, this includes the statistical
information gathered while those jobs were running. As a result, these entries can
be required to store several megabytes of data, especially for those jobs with a
large number of threads, with a long duration, or that maintain statistics for a
number of items. This can cause a problem because by default the directory
server is configured to allow only approximately two megabytes of information to
be sent to the server in a single LDAP message. This limit is controlled by the
nsslapd-maxbersize configuration attribute, which specifies the maximum
allowed message size in bytes. A value of at least 100 megabytes (104857600
bytes) should be specified to prevent updates with large amounts of statistical
information from being rejected, although it is possible that a job could return
even more than 100 megabytes of data, particularly for jobs that run for a very
long period of time and have a relatively short collection interval.
Cache Tuning. The directory server contains two caches that may be utilized to
improve overall performance: the entry cache and the database cache. The entry
cache holds copies of the most recently used entries in memory so that they may
be retrieved without having to access the database. The database cache holds
pages of the database in memory so that it is not necessary to access the data
stored on the disk. By default, both of these caches are configured to store
Tuning the Configuration Directory 89

approximately ten megabytes of information. Increasing the sizes of these caches
will increase the amount of information that will be stored in memory and
therefore the overall performance when it is necessary to retrieve information
from the directory server. Further, increasing the size of the database cache can
also improve the performance of the server when writing information to the
database.
Proper Indexing. Whenever the SLAMD server needs to retrieve information

from the configuration directory, it will issue an LDAP search request to the
directory. If the directory server is properly indexed, then it will be able to locate
the matching entries more quickly. Adding indexes for the following attributes
will help the directory server to process the queries from SLAMD more
efficiently:
slamdJobActualStopTime -- Presence and equality
slamdJobClassName -- Equality
slamdJobID -- Equality
slamdJobState -- Equality
slamdFileName -- Equality
slamdOptimizingJobID -- Equality
slamdParameterName -- Equality

Configuring Tomcat
The Tomcat 4.0.4 servlet engine provided with SLAMD is configured by default
so that it can adequately serve the administrative interface with no configuration.
However, it may be beneficial to alter the configuration so that it can operate
more effectively. The official documentation is available online at
http://jakarta.apache.org/tomcat/tomcat-4.0-doc/index.html, and has also
been included in the tomcat_info/tomcat-docs directory of the SLAMD
installation archive. Additionally, some common configuration changes are
described in this section. Note that all configuration changes described in this
section require that the Tomcat servlet engine be stopped and restarted for the
changes to take effect. See the documentation in an earlier section for the
appropriate way to stop SLAMD, and to stop and restart Tomcat.
Changing the Port Number. By default, the SLAMD administrative interface is

available on port 8080. This is the default port used by Tomcat, but it may be
easily changed. To do so, edit the conf/server.xml configuration file and locate
the Connector definition with a class name of
"org.apache.catalina.connector.http.HttpConnector". The port attribute in
that definition controls the port number on which the servlet engine listens for
HTTP requests, and changing it will configure Tomcat to listen on the specified
port. Any port number between 1 and 65535 that is not already in use may be
specified.
NOTE If a port number less than or equal to 1024 is specified, then only the
superuser will have permission to bind to that port. Therefore, if such a
port is selected, then only the root user will be able to start or stop the
Tomcat servlet engine.
Configuring the Memory Available to SLAMD. If there are a large number of

clients connected to the SLAMD server, or if jobs are expected to provide a large
amount of information back to the server, then the server may need to consume a
significant amount of memory for some operations. The Java virtual machine in
which Tomcat and the SLAMD server are operating controls the amount of
memory that is available for use. Normally, this is customized through the
Configuring Tomcat 91
CATALINA_OPTS environment variable, but the bin/startup.sh shell script has
been customized so that the memory configuration may be specified there. The
MAX_MEMORY variable specifies the maximum amount of memory in megabytes that
may be used, and the INITIAL_MEMORY variable specifies the amount of memory
that Tomcat will allocate when it starts.
Serving Non-SLAMD Files. Because jobs in the SLAMD environment are

executed on remote client systems, any data used by those jobs must be accessible
by those clients. The file URL parameter type allows those clients to retrieve
information using the HTTP protocol, and therefore if it is to be used, a server
must be available to serve those files. In the provided configuration, Tomcat will
provide only the SLAMD administrative interface. However, it may also be
configured to serve any file over HTTP by editing the configuration as follows:
1. Edit the conf/server.xml file and locate the line
<Context path="" docBase="ROOT" debug="0"/>
2. Remove the "" lines immediately above and below the
definition for the ROOT context (these lines normally comment out the context
definition so that it does not take effect).
3. Edit the conf/web.xml file to remove the "" lines that surround
the "<servlet>" and "<servlet-mapping>" definitions in the "Built In Servlet
Definitions" section.
After Tomcat is restarted, any file placed in the webapps/ROOT directory will be
accessible from the root of the server.
Serving Different Data Files to Different Clients. Some jobs to be executed in

the SLAMD environment allow the user to specify URLs to files containing data
that may be used during job processing. However, specifying a file that is too
large can in some cases have an adverse impact on the performance of the clients.
As a result, it is often beneficial to provide smaller files to clients, but to vary the
contents of those files so that each client is working with a different set of data.
One way to accomplish this task is to use a file URL that directs the client access
a file on its own local filesystem and to place a different file on each client
system. However, this can be very inconvenient in some cases, and it is not
sufficient for cases in which a system is running multiple instances of the
SLAMD client.
To address this problem, the SLAMD server is provided with a servlet that can be
used to serve different files with a single HTTP URL. It works by either
sequentially or randomly choosing one of a set of files to return to the client. All
files to retrieve should be contained in a directory specified in the servlet
configuration and should be given the same base name followed by a period and a
sequentially incrementing number starting with 1. That is, if the base file name is
"data_file", then the individual files to be retrieved should be named "data_file.1",

"data_file.2", "data_file.3", etc. The first time the "data_file" is requested, the
servlet will automatically scan the directory to determine how many files there
are.
To enable this servlet, it is necessary to edit the Tomcat configuration for

SLAMD. The following changes should be made to the webapps/slamd/WEB-
INF/web.xml configuration file:
1. Remove the "" lines around the "<servlet>" tag that define the
GetFile servlet with a class of "com.sun.slamd.misc.GetFile".
2. Edit the value of the "file_directory" initialization parameter to specify the path
to the filesystem directory in which the servlet can find the files to return to the
client.
3. Remove the "" lines around the "<servlet-mapping>" tag for
the GetFile servlet.
Once the GetFile servlet has been enabled, it may be accessed using the URL
"http://{address}:8080/slamd/getfile?file={filename}", where "{address}" is the
address of the SLAMD server and "{filename}" is the base name of the file to
retrieve. On the first access to this URL, the servlet will return the contents of the
file "{filename}.1" to the client. On the second access, the servlet will return the
contents of the file "{filename}.2" to the client. This will continue sequentially
until all files have been exhausted, in which case it will start over with
"{filename}.1". It is also possible to retrieve the files in random order by
appending "&mode=random" to the end of the URL.
The first time a request is issued to the GetFile servlet to retrieve a given file, it
will scan the file directory to determine the total number of files that are
available. This information is then cached so that it is not necessary to make this
determination on each access. While this can help improve the overall
performance of the GetFile servlet, it does not allow the servlet to detect whether
files have been added or removed. If files are added or removed, it is necessary
to clear the cached information so that the servlet will re-scan the directory for the
updated set of files. To do this, retrieve
the URL "http://{address}:8080/slamd/getfile?file={filename}
&mode=remove".
Note that if authentication is enabled in the SLAMD server, then the GetFile
servlet itself will also be considered a protected resource, which means that
clients will need to authenticate to the SLAMD server in order to retrieve files
from the GetFile servlet. Although this is undesirable, there are workarounds
available to deal with this problem. One such workaround would be to start a
second instance of the SLAMD server (perhaps in read-only mode) that does not
require authentication and can be used to serve up the files for the GetFile servlet.
Another workaround that is available in SLAMD version 1.7.1 or later would be
to encode the username and password to use to authenticate to the SLAMD server
in the URL itself, like "http://{username}:{password}@{address}:
Configuring Tomcat 93
8080/slamd/getfile?file={filename}". If this option is used, then it should be
noted that the password will be visible to anyone that can see the job information,
so it is recommended that a generic user ID and password be used for this
purpose. This user does not need permission to do anything in the SLAMD
administrative interface in order to be able to access the files via the GetFile
servlet.

Configuring Access Control
By default, the SLAMD administrative interface will be accessible to all users

without requiring any authentication, and all users will have permission to
perform any operation through that interface. However, Tomcat may be
configured to require that users are required to provide a login ID and password
in order to access the administrative interface. If this is enabled, then the
SLAMD server itself may be configured to limit the operations that individual
users may perform. Both forms of access control perform authentication based on
information in an LDAP directory server. This directory may be the same as or
different from the configuration directory.
Configuring Tomcat to Require Authentication for HTTP Clients
Before any access control may be used in SLAMD, it is necessary to configure

the Tomcat servlet engine to require authentication to any user attempting to
access the administrative interface. To do this, edit the conf/server.xml file and
locate the Context definition starting with the line:
<Context path="/slamd" docBase="slamd" debug="0">
Immediately below this line and before the closing </Context> tag is a Realm
definition with the class "com.sun.slamd.realm.LDAPRealm". This definition is
commented by default, but removing the "" lines above and below
the Realm definition will activate it. However it must first be customized so that
the settings are appropriate for the directory server that will be used to perform
the authentication. The following attributes in the Realm definition should be
given appropriate values for the authentication directory:
ldapHost -- Specifies the address to use to connect to the directory server

containing authentication data. This may be an IP address or a fully-qualified
name (as long as that name may be resolved to an IP address by the SLAMD
server system).
Configuring Access Control 95

ldapPort -- Specifies the port number to use to connect to the directory server
containing the authentication data.
bindDN -- Specifies the DN that will be used to bind to the authentication

directory to locate user accounts. This user must have permission to bind to
the directory server to retrieve user entries. If no value is specified, then the
connection will be bound anonymously.
bindPassword -- Specifies the password that will be used to bind to the

authentication directory to locate user accounts. If no value is specified, then
the connection will be bound anonymously.
loginIDAttribute -- Specifies the LDAP attribute that will be used to store the
login ID attribute. By default, the login ID attribute will be "uid".
userBase -- Specifies the location in the authentication directory under which

user accounts reside.
membershipDN -- Specifies the DN of the static group, dynamic group, or role in

which users must be a member in order to be granted access to the SLAMD
administrative interface. If no value is specified, then any user in the directory
below the specified user base will be granted access.
Note that there are additional attributes that may be specified to configure the
communication between Tomcat and the authentication directory to use SSL.
Those attributes are documented in a later section in the discussion on
configuring SSL in the SLAMD environment.
It is also necessary to edit the webapps/slamd/WEB-INF/web.xml file to complete

configuring Tomcat to require authentication. Remove the "" lines
that surround the "<security-constraint>" and "<login-config>" definitions.
Once this is done, stop the SLAMD server and stop and restart the Tomcat servlet
engine. If everything has been configured properly, authentication will be
required to access the SLAMD administrative interface.
NOTE The configuration changes listed above will authentication only for the
SLAMD administrative interface. No authentication will be required to
access any other content that the Tomcat servlet engine may be
configured to provide. Consult the Tomcat documentation for
configuring access control for information on configuring access control
for other content. Note, however, that the file URL parameter type
cannot access content if authentication is required to retrieve the
specified file.

Configuring SLAMD to Use Access Control
Once LDAP-based authentication has been enabled in the Tomcat servlet engine,
it is possible to further restrict access to the features that users may access in the
SLAMD administrative interface. By default, all features are available to all
users that have access to the SLAMD administrative interface, but it is possible to
restrict the set of features that users may access. Any attempt by a user to access
a feature to which he or she does not have access will be rejected. Further, those
features that the user may not access will not be displayed in the user interface.
NOTE Tomcat must be configured to require authentication before enabling

access control in SLAMD. If this is not done, then the SLAMD server
will reject any attempt to access it and it will be necessary to manually
edit the webapps/slamd/WEB-INF/slamd.conf configuration file to set
the use_access_control configuration parameter to "false" to correct
this problem.
To enable access control within the SLAMD administrative interface, follow the
"Access Control" link in the "Startup Configuration" section of the navigation
sidebar. This will display a page in which it is possible to specify the settings
used for access control in the administrative interface. There are two kinds of
settings on this page: those necessary for connecting to the directory server to
find user entries, and those that specify the sets of users that may access the
various capabilities that may be restricted.
The settings used to access the directory server are similar to those settings
specified in the Realm definition when configuring Tomcat to require access
control. Note that the directory specified in this section must be the same
directory used by Tomcat when authenticating the user. These settings are as
follows:
User Directory Address -- Specifies the address of the directory server that
contains the user information. This should be the same as the value of the
ldapHost attribute in the realm definition.
User Directory Port -- Specifies the port number for the directory server that
contains the user information. This should be the same as the value of the
ldapPort attribute in the realm definition.
User Directory Bind DN -- Specifies the DN to use when binding to the

directory to find user entries. If no DN is specified, then the connection will be
bound anonymously. This should be the same as the value of the bindDN
attribute in the realm definition.

User Directory Bind Password -- Specifies the password to use when binding
to the directory to find user entries. If no password is specified, then the
connection will be bound anonymously. This should be the same as the value
of the bindPassword attribute in the realm definition.
User Base DN -- Specifies the DN under which user entries may be found in
the directory. This should be the same as the userBase attribute in the realm
definition.
Use SSL for User Directory -- Specifies whether the connection to the
directory server should use SSL.
Blindly Trust any SSL Certificate -- Specifies whether the connection to the
user directory should automatically trust any SSL certificate presented by the
directory server.
User ID Attribute -- Specifies the attribute that will be used to find user
entries based on the provided login ID value. This should be the same as the
loginIDAttribute attribute in the realm definition.
Restricting Access to Features in SLAMD
Once SLAMD has been configured to communicate with the user directory, it is
possible to begin restricting access to various components in the SLAMD
administrative interface. Each component may be either accessible to all users or
restricted to only users that are a member of a specified static group, dynamic
group, or role. If no value is specified, then that feature will be available to all
authenticated users. If a value is specified, then it must be the DN of the group or
role containing users that may access the specified feature.
The SLAMD features for which access may be restricted are as follows:
Full Access DN -- Specifies the DN of the group or role whose members have
full access to all components of SLAMD, regardless of the other permissions
assigned to those users. Because users with this permission will not be
restricted in any way, a value must be specified for this access category if any
features are to be restricted in SLAMD.
Start/Stop SLAMD DN -- Specifies the DN of the group or role whose

members will be able to start, stop, and restart the SLAMD server. Note that
these users must also have permission to view the SLAMD status information,
since the buttons to access these features are on the status page.

Start/Stop Access Manager DN -- Specifies the DN of the group or role
whose members will be able to restart the access control manager and flush the
ACL cache. Note that these users must also have permission to view the
SLAMD status information, since the buttons to access these features are on
the status page.
View Servlet Config DN -- Specifies the DN of the group or role whose

members will be able to view the startup configuration information, including
the settings for the configuration directory and for access control.
Edit Servlet Config DN -- Specifies the DN of the group or role whose

members will be able to modify the startup configuration information,
including the settings for the configuration directory and for access control.
Note that these users must also have permission to view the servlet config
information.
View SLAMD Config DN -- Specifies the DN of the group or role whose

members will be able to view the SLAMD server configuration information
that is stored in the configuration directory, including the configuration for the
core SLAMD server, the logger, the logger thread, the client listener, the
scheduler, and the user interface.
Edit SLAMD Config DN -- Specifies the DN of the group or role whose

members will be able to modify the SLAMD server configuration information
that is stored in the configuration directory, including the configuration for the
core SLAMD server, the logger, the logger thread, the client listener, the
scheduler, and the user interface. Note that these users must also have the
capability to view the SLAMD configuration information.
View SLAMD Status DN -- Specifies the DN of the group or role whose

members will be able to view the SLAMD server status information, including
information about the core server, the scheduler status, the client listener, and
the JVM in which the SLAMD server and Tomcat are running.
Disconnect Client DN -- Specifies the DN of the group or role whose

members will be able to disconnect clients from the SLAMD server. Note that
these clients must also have the ability to view the SLAMD server status
information.
View Job Info DN -- Specifies the DN of the group or role whose members
will be able to view information about jobs that have been scheduled in the
SLAMD server, regardless of their current state.

Schedule New Jobs DN -- Specifies the DN of the group or role whose
members will be able to schedule new jobs for execution in the SLAMD
environment.
Cancel Jobs DN -- Specifies the DN of the group or role whose members will
be able to cancel jobs that are running or pending execution. Note that these
users must also have the capability to view job information.
Delete Jobs DN -- Specifies the DN of the group or role whose members will
be able to delete information about the jobs that have completed execution.
Note that these users must also have the capability to view job information.
Manage Job Folders DN -- Specifies the DN of the group or role whose

members will be able to create, delete, and manage real and virtual job folders.
Note that these users must also have the capability to view job information.
View Job Classes DN -- Specifies the DN of the group or role whose members
will be able to view the job classes that have been defined in the SLAMD
environment.
Add Job Classes DN -- Specifies the DN of the group or role whose members
will be able to define new job classes for use in the SLAMD environment.
Note that these users must also have the capability to view information about
the defined job classes.
Delete Job Classes DN -- Specifies the DN of the group or role whose

members will be able to remove job classes from the SLAMD environment.
Note that these users must also have the capability to view information about
the defined job classes.
Authenticate Clients DN -- Specifies the DN of the group or role whose

members will be allowed to authenticate as SLAMD clients to the client
listener.
Configuring the SLAMD Server to Operate in Read-Only Mode
The access control capabilities of the SLAMD server make it possible to allow
most users to have a restricted level of access to the information in the server
while allowing others to have the ability to schedule jobs, make configuration
changes, and perform other administrative tasks. However, using this access
control capability requires that all users authenticate to the server before they can
access the administrative interface.

Because it may be undesirable to require users to authenticate if they are only
going to view job information, the SLAMD server provides a read-only mode that
makes this possible without requiring authentication. When operating in read-
only mode, the SLAMD server may not be used to do anything other than view
job data. Since that means it may not be used to schedule jobs or alter the server
configuration, it is expected that if the SLAMD server is configured in read-only
mode, another instance of the server (which may or may not be on the same
system as the read-only instance) will be configured that is not in read-only mode
but does require authentication and may be used to schedule jobs and perform
administrative tasks. If multiple instances are installed on the same system, then
they should be installed in different locations and configured to listen on different
ports (see the "Configuring Tomcat" section for information on changing the port
number of the SLAMD server).
To operate the SLAMD server in read-only mode, it is only necessary to provide

an initialization parameter to the administrative servlet with a name of
"read_only" and a value of "1". When the provided Tomcat servlet engine is
used, this may be accomplished by editing the webapps/slamd/WEB-INF/web.xml
configuration file. Simply uncomment the "<init-param>" information in the
"<servlet>" tag for the com.sun.slamd.admin.AdminServlet class.
Enabling Restricted Read-Only Mode
In read-only mode, the SLAMD server prevents the user from performing a
number of actions without requiring authentication, but there is no control over
which job information the user is allowed to see. This is usually acceptable, but
in others there may be job information that should only be available to a restricted
set of users. In this case, then restricted read-only mode may provide a solution.
Restricted read-only mode is essentially the same as read-only mode with the
exception that only jobs and job folders that the administrator has explicitly
published will be available to the end user while any other jobs that may be in the
configuration directory will be visible only to users accessing the data through the
full SLAMD interface.
To enable restricted read-only mode, it is necessary to run the server in read-only

mode as described above, but it is also necessary to provide an initialization
parameter to the administrative servlet with a name of "restricted_read_only" and
a value of "1". With the provided Tomcat servlet engine, this may be
accomplished by editing the webapps/slamd/WEB-INF/web.xml configuration file.
Make sure that the "<init-param>" information in the "<servlet>" tag for the
com.sun.slamd.admin.AdminServlet class is uncommented, and change the value
of the "restricted_read_only parameter" from "0" to "1".

As mentioned above, if the administrative interface is operating in restricted read-
only mode, then only those jobs and job folders that have been explicitly
published by an administrator will be made available. This means that for
restricted read-only mode to be of any use, the administrator must have the ability
to make jobs and job folders available. This can be done through the
administrative interface, but many of these options are hidden by default. To
enable administration of features related to restricted read-only mode, follow the
"User Interface" link in the navigation sidebar and change the value of "Enable
Management of Read-Only Options" to "true".
Once this feature has been enabled, there will be a few changes in the
administrative interface. The first is that listings of completed jobs will now
contain a "Read-Only Status" column that indicates whether a job has been
published for use in restricted read-only mode. Another is that "Publish" and
"De-Publish" buttons will be displayed at the bottom of the page which makes it
possible to publish or de-publish a selected set of jobs. In all job folders other
than the default "Unclassified" folder, one or more buttons near the top of the
page will provide the ability to publish that folder, or optionally to publish the
folder and all the jobs that it contains (the "Publish Folder" button will make the
folder visible in restricted read-only mode, but none of the jobs contained in the
folder will be visible unless explicitly published by an administrator; the "Publish
Folder and Jobs" button will publish the folder and all jobs contained in it).
Optimizing jobs may also be published in the same manner as regular jobs, and
when an optimizing job is published then all the individual job iterations
associated with that optimizing job will be automatically published as well.
Configuring the Client Listener to Require Client Authentication
By default, the client listener will accept connections from any clients that
connect to it. This may be undesirable in some cases because a rogue client could
be used in an attempt to capture sensitive information or generate invalid
statistical data (although no such clients are known to exist, it is theoretically
possible for someone to construct one). To prevent this, it is possible to configure
the SLAMD server so that the client listener will require all clients to authenticate
with an authentication ID and password. If the server is configured in this
manner, then any clients that do not provide valid authentication credentials will
not be allowed to connect to the SLAMD server.
Note that there are a couple of prerequisites for being able to use this feature. The
first is that the Tomcat servlet engine must be configured to perform LDAP-based

authentication as described at the beginning of this chapter. The second is that
the SLAMD server itself must be configured with access control enabled. The
reason for these prerequisites is that the client listener uses the same access
control manager as the administrative interface, and if access control is not
enabled in the administrative interface, then the access control manager will not
be properly initialized.
Once the prerequisites have been fulfilled, it should be possible for clients to
provide authentication information to the SLAMD server, but it will not be
required. This is useful for testing the server configuration to confirm that
everything will work properly when clients are required to authenticate. To test
whether authentication will work properly, edit the slamd_client.conf
configuration file in a SLAMD client installation to provide valid values for the
AUTH_ID and AUTH_PASS configuration parameters. After this is done, running the
"./start_client.sh" script should cause the client to start up and connect and
authenticate itself to the SLAMD server. If the authentication information
provided is invalid, or if the SLAMD server is not properly configured to
authenticate clients, then the connection will be rejected. However, if all goes
well, then the client connection will be accepted.
Once you are confident that the SLAMD server has been properly configured to
allow clients to authenticate, then the client listener may be configured to require
all clients to authenticate. To do this, follow the "SLAMD Client Listener" link
in the navigation sidebar and change the value of the "Require Authentication"
parameter to "true". This change should take effect immediately without the need
to restart the SLAMD server, but note that it will only apply to any new
connections that are established -- any existing client connections will remain
established whether or not valid authentication was provided.
By default, the credentials that clients provide to the SLAMD server may be any
valid authentication ID and password in the user directory. However, this may be
undesirable because it would allow anyone with an account in the directory to use
their credentials to authenticate as a client. To prevent this, it is possible to
restrict the set of users that may authenticate to the SLAMD server as clients.
This can be done by defining a group or role whose members will be the only
ones allowed to authenticate as clients, and providing the DN of that group or role
entry as the value of the "Authenticate Clients DN" parameter in the access
control section. As with requiring authentication, this change should take effect
immediately, and after it is enabled only users in that group or role will be
allowed to authenticate as clients to the SLAMD client listener.

Using SSL with SLAMD
By default, all communication in the SLAMD environment is unencrypted.

However, it is possible to configure this communication to use SSL. SLAMD
offers multiple levels of encryption, each of which may be enabled or disabled
independently of the others:
Communication between the Tomcat servlet engine and the Web browser.
Communication between the Tomcat servlet engine and the user directory.
Communication between the SLAMD server and SLAMD clients.
Communication between the SLAMD server and the configuration directory.
Communication between the SLAMD server and the user directory.
This section describes the processes for enabling SSL for each of these types of
communication.
Configuring the JSSE Certificate Database
All SSL-based communication performed in SLAMD is handled by the Java

Secure Socket Extensions (JSSE). Therefore, it is necessary to have an
understanding of how to interact with JSSE certificate stores in order to be able to
use SSL in SLAMD.
JSSE uses two kinds of certificate stores: the key store and the trust store. The
key store is used to hold certificates for which it is necessary to have both a
public and a private key, as in cases in which the SLAMD server will need to
accept SSL-based connections from clients. The trust store is used to hold
certificates for which it is only necessary to have a public key, as in cases in
which the SLAMD server will connect as a client to an SSL-enabled directory
server. Note that the distinction between key and trust stores is purely a logical
one, as both use file formats that are identical and can be managed in the same
way.

The Java runtime offers a utility called keytool for interacting with JSSE key and
trust stores. This tool can be used to create new certificates and import existing
certificates into the certificate stores. The type of operation to perform with the
certificate stores depends upon how SSL will be used in the SLAMD
environment. If SSL will be enabled in the administrative interface or for
communication between clients and the SLAMD server, then it will be necessary
to have an SSL server certificate contained in a JSSE key store. If SSL will be
used only for communication with the configuration and/or user directory, then it
will only be necessary to import the public key used by the directory server into a
JSSE trust store.
Obtaining and Installing an SSL Server Certificate in a JSSE Key Store

There are two ways to obtain an SSL server certificate:
1. Create a certificate signing request that will be signed by an external CA.
2. Create a self-signed certificate.
The first option is beneficial, particularly for use in the administrative interface,
because it makes it possible to obtain the certificate from a trusted commercial
CA (certificate authority) like Thawte or VeriSign, or from an internally-
maintained authority. In this case, browsers are likely to already have the CA
certificate and should therefore automatically trust the certificate presented by
Tomcat. However, it can be expensive to purchase a certificate from an official
authority, and if only a limited set of clients will be used then it may be easier and
cheaper to create a self-signed certificate instead.
Regardless of whether the certificate will be self-signed or signed by an external

CA, the first step is to generate the private key for the certificate. This can be
done with a command like:
keytool -genkey -alias slamd -keyalg rsa \

-dname "CN=slamd.example.com,O=Example,C=US" \
-validity 365 -keystore slamd.keystore
In this example, the value of the "-alias" argument is a nickname to give to the
certificate in the database. The value of the "-dname" argument is the subject of
the certificate, and the value of the CN component of the subject should be the
fully-qualified address that clients will use to access the system. The value of the
"-validity" argument specifies the number of days that the certificate will be
valid. The value of the "-keystore" argument specifies the JSSE keystore in
which the key should be generated. If the specified keystore does not yet exist,
then a new one will be created.
Using SSL with SLAMD 105

At this point, creating a self-signed certificate is relatively easy. It can simply be
done by issuing the command:
keytool -selfcert -alias slamd -keystore slamd.keystore
This will create the certificate, and it will be available for use in the
administrative interface and/or the client listener.
In order to have the certificate signed by an external CA instead of creating a self-

signed certificate, the process is a little different and must be completed in
multiple steps. The first step is to generate the certificate signing request (CSR)
using a command like:
keytool -certreq -alias slamd -file slamd.csr \

-keystore slamd.keystore
This will generate a CSR and place it in the file "slamd.csr". This request may
then be provided to a certificate authority where it can be signed. The process for
obtaining the signed certificate will vary based on the CA used, but when the
process is complete the CA should provide a certificate that may be installed in
the keystore, preferably as a PKCS#7 certificate chain. To install the certificate,
use the command:
keytool -import -trustcacerts -alias slamd \

-file slamd.p7cert -keystore slamd.keystore
At this point, the certificate may be used to enable SSL in the administrative
interface and/or in the client listener.
Obtaining and Installing a Public Key in a JSSE Trust Store

The process for installing a public key in a JSSE trust store is simpler than
creating a server certificate, and only requires a single step. The command to do
this is:
keytool -import -alias slamd-cacert -file slamd.p7cacert \

-keystore slamd.truststore
In this case, "slamd.p7cacert" is the name of the file containing the PKCS#7
representation of the certificate to import, and "slamd.truststore" is the JSSE
trust store into which the certificate will be imported. If the specified trust store
file does not exist, a new one will be created.

Enabling SSL for Communication with Web Browsers
In the default installation, the administrative interface is served by the Tomcat

servlet engine. In order to enable SSL communication between clients and the
administrative interface, it is necessary to configure Tomcat to accept SSL-based
connections. The first step is to obtain an SSL server certificate as documented
above. Once that is done, edit the "conf/server.xml" file and locate the section
beginning with the comment:

Immediately below that comment is a Connector definition that can be used to

create an SSL-based listener. Remove the "" lines immediately
before and after the Connector definition so that it will no longer be treated as a
comment. Then, add the following properties into the Factory section contained
within the Connector definition:
keystoreFile="/data/slamd/conf/slamd.keystore"
keystorePass="password"
where keystoreFile specifies the full path to the JSSE keystore containing the
SSL server certificate and keystorePass specifies the password to use to access
the information contained in that keystore. Upon restarting Tomcat, it should be
possible to access the administrative interface over SSL on port 8443. If it is not
possible, then look in the logs/catalina.out log file for information about the
failure.
Note that enabling SSL in the administrative interface on port 8443 does not
automatically disable the non-SSL listener on port 8080, and therefore it will still
be possible for users to access the administrative interface in an unencrypted
manner. In order to prevent this kind of access, it is necessary to disable the non-
SSL listener. This can be done by locating the Connector definition immediately
below the comment:

The definition for the non-SSL listener should be located just above the definition
for the SSL-based listener. To disable it, simply comment out the non-SSL
Connector definition by inserting a line containing "" immediately after the definition.
Once this is done and Tomcat is restarted, then it should only accept SSL-based
connections on port 8443.

Enabling SSL for Communication with SLAMD Clients
Although configuring SSL for use in the administrative interface may prevent
unencrypted communication between Web browsers and the SLAMD server, it
does not protect the communication between SLAMD clients and the SLAMD
server. In order to do that, it is necessary to enable SSL in the client listener.
The first step is to obtain an SSL server certificate as described above. If SSL has
been enabled in the administrative interface, then the same JSSE key store may be
used to enable SSL in the client listener.
Once an appropriate key store is available, follow the "Initialization Parameters"

link in the navigation sidebar. Edit the value of the "SSL Key Store Location"
parameter to provide the absolute path to the JSSE key store containing the server
certificate, and also edit the "SSL Key Store Password" parameter to provide the
password needed to access the information in the JSSE key store.
Next, follow the "SLAMD Client Listener" link in the navigation sidebar. Edit
the "Use SSL" link to change the value from "false" to "true". Note, however,
that the client listener will not actually listen for SSL-based connections until the
SLAMD server is restarted. At this point, restart the SLAMD sever for the
change to take effect. Note, however, that doing so will interrupt any jobs that
may be in progress and disconnect any clients connected to the SLAMD server,
so do so with caution.
Once the SLAMD server has been restarted and the client listener is configured to
use SSL, the clients must be configured to communicate over SSL. To do this,
edit the slamd_client.conf configuration file and change the value of the
USE_SSL variable to "on". If the BLIND_TRUST variable is also set to "on", then the
client will automatically trust any certificate presented by the SLAMD server.
Otherwise, it will likely be necessary to specify at least the value of the
SSL_TRUST_STORE variable to contain the location of a file on the client that can be
used to trust the server's certificate.
Enabling SSL between SLAMD and the Config and User Directories
Enabling SSL in the administrative interface will prevent sensitive data from
traveling in clear text between the browser and the SLAMD server, and enabling
SSL in the client listener will prevent it between the SLAMD server and the
clients. However, neither of those options protects the information as it is

transferred between the SLAMD server and the configuration directory. Neither
do they protect communication between the SLAMD server and the user directory
when making issuing queries related to access controls. Enabling SSL between
the SLAMD server and the configuration and user directories needs to be done
separately.
Because the SLAMD server will be acting as a client of the directory server(s), it
is not necessary for the SLAMD server to have an SSL certificate for this
operation. However, it is necessary that the SLAMD server be configured to trust
the certificate presented by the directory server in order to establish a secure
connection. This can be done in a couple of ways
The traditional way to do this would be to obtain the CA certificate of the

certificate authority that signed the directory server's SSL certificate and place
that in a JSSE trust store. Then follow the "Initialization Parameters" link in the
administrative interface and specify the path to that trust store as the value of the
"SSL Trust Store Location" parameter. In most cases, it should not be necessary
to provide a value for the "SSL Trust Store Password" parameter, but some
special trust store types may require it.
Because it can inconvenient at times to obtain the CA certificate to include in a

JSSE trust store, the SLAMD server offers another approach: it can be
configured to blindly trust any SSL certificate that the directory server provides.
To do this for communication with the configuration directory, follow the
"Initialization Parameters" link in the administrative interface and make sure that
the "Blindly Trust any SSL Certificate" parameter has a value of "true". To do
this for communication with the user directory, follow the "Access Control" link
in the navigation sidebar and ensure that the "Blindly Trust any SSL Certificate"
parameter on that page has a value of "true".
Using the blind trust option is an easier and more convenient approach to trusting
the directory server's certificate than configuring an appropriate JSSE trust store,
and the strength of the encryption is not diminished in any way. However, doing
so does not provide protection against SSL "man-in-the-middle" attacks in which
a malicious user can intercept this communication and present his own certificate
instead of the directory server's, thereby gaining the ability to decrypt all the
communication. This kind of attack is not trivial to achieve, but if it is a
significant concern then it is recommended that the blind trust option be disabled
and that the JSSE trust store be used instead.
Once the SLAMD server has been configured to trust the certificate presented by
the directory server, then SSL communication may be enabled between the
configuration and/or user directories. To do this for the configuration directory,
follow the "Initialization Parameters" link in the navigation sidebar. Change the
value of the "Config Directory Port" parameter to be the secure port number for
the configuration directory, and change the value of the "Use SSL for Config

Directory" to "true". For the user directory, follow the "Access Control" link in
the sidebar and update the values of the "User Directory Port" and "Use SSL for
User Directory" parameters as necessary. Then, restart the SLAMD server and all
the configuration between the SLAMD server and the directory server will be
encrypted with SSL.
Enabling SSL Between Tomcat and the User Directory
In the previous section, instructions were provided for using SSL to protect the
communication between the SLAMD server and the user directory when
evaluating information related to access control. However, this does not protect
the communication between the Tomcat servlet engine and the user directory,
which is used to verify the credentials provided by the user when authenticating
to the application. Because this process involves providing the user's password to
the user directory for verification, it may be highly desirable to encrypt that
communication so that the password does not travel across the network in clear
text.
To enable SSL between Tomcat and the user directory, it is first necessary to stop
Tomcat using the "bin/shutdown.sh" script. Then, edit the conf/server.xml
configuration file and find the realm definition used to require authentication to
the SLAMD administrative interface. This definition should start with the line:
<Realm className="com.sun.slamd.realm.LDAPRealm"
To enable SSL, first change the value of the ldapPort property so that it contains
the correct value for the secure port of the directory server. Then, add the
following line on a line somewhere before the "/>" tag that ends the realm
definition:
useSSL="true"
Note that as with the communication between the SLAMD server and the user
directory, it is necessary for Tomcat to trust the SSL certificate presented by the
directory server, and again this trust can be established either through a properly-
configured JSSE trust store or by configuring it to blindly trust any certificate that
may be presented. If a JSSE trust store is to be provided, then it may be done by
adding the following line to the realm definition (substituting the correct path to
the SSL trust store as necessary):
sslTrustStore="/data/slamd/conf/slamd.truststore"

Alternatively, to blindly trust any SSL certificate, add the following line:
blindTrust="true"
Save the changes to the conf/server.xml file and start Tomcat using the
bin/startup.sh script. Upon the first access to the administrative interface,
Tomcat should establish a secure connection to the user directory in order to
verify the credentials provided by the user.
Copying an NSS-Based Certificate to a JSSE Keystore
As mentioned above, SLAMD uses the Java JSSE library to provide the ability to
encrypt network communication using SSL. However, the JSSE keystore format
is not the only format used to store SSL certificates. Another very popular format
is the NSS (Netscape Security Services) certificate database. It is used by a
number of products, including the Netscape and Mozilla Web browsers and many
network servers like the Sun ONE Directory Server. If you wish to ensure that
the communication between the SLAMD server and the configuration directory
server is encrypted using SSL, then it may be necessary to add the directory
server's certificate into a JSSE keystore that may be used by SLAMD.
NOTE In addition to configuring SLAMD to communicate with the

configuration directory over SSL, the process documented in this
section may be used to create a JSSE keystore that can be used with any
of the jobs provided with SLAMD that support SSL for communication
with an LDAP directory server.
In order to import the directory server's SSL certificate into a JSSE keystore that
may be used by SLAMD, it is first necessary to extract that certificate from the
directory server's NSS-based certificate database. This may be done using the
NSS certutil tool. This utility may be compiled from source code available at
"http://www.mozilla.org/projects/security/pki/nss", or it may be obtained in
binary form in some versions of the Sun ONE Directory Server or Directory
Server Resource Kit.
To extract the directory server's SSL certificate from the certificate database
using certutil, issue the command:
./certutil -L -d ../../alias -P "slapd-config-" -n server-cert -a

NOTE For the sake of simplicity, this documentation assumes that the
precompiled version provided with the Sun ONE Directory Server 5.2
(in the "shared/bin" directory under the server install root) is being
used, and that the directory server instance name is "slapd-config".
This will retrieve an ASCII version of the directory server's certificate. This
should be saved in a text file to be imported by the Java keytool utility. For the
purpose of this example, it is assumed that the certificate has been saved in the
file "/tmp/ds_cert.txt".
To use keytool to create a new certificate database and import the directory
server's certificate into it, issue the command:
keytool -import -alias server-cert -file /tmp/ds_cert.txt

-keystore ./slamd_keystore
When prompted, supply the password to use for the new JSSE keystore and
indicate that the new certificate should be trusted.
At this point, SLAMD should be configured to use SSL to communicate with the
configuration directory. To do this, follow the "Initialization Parameters" link in
the Startup Configuration section of the navigation sidebar. Specify the path to
the new JSSE keystore as the value for the "SSL Trust Store Location" argument,
and provide the password used when creating the keystore as the value of the
"SSL Trust Store Password". The "SSL Key Store Location" and "SSL Key Store
Password" settings may be left empty.

Interacting with SLAMD from the
Command Line
Most interaction with the SLAMD server is performed through the HTML-based
administrative interface. However, doing this is generally an interactive process,
which means that it is not suitable for automating tasks like scheduling jobs or
interacting with job data. To deal with this, SLAMD offers a number of
command line utilities that can be used to perform these kinds of operations.
These tools may be used in scripts to help automate the testing process.
The command-line job scheduler has been discussed in earlier sections of this
document. This section will describe a number of other command-line utilities
provided with SLAMD. Note that all these utilities are provided in the
slamd_server.jar file located in the webapps/slamd/WEB-INF/lib directory
under the SLAMD server installation. In all cases, the utilities communicate with
the SLAMD administrative interface using HTTP, so this file may be copied to
another system if it is desirable to run the utility remotely. However, some
utilities require that the SLAMD server interact with files contained on the
server's filesystem.
A number of configuration options are common to all utilities discussed in this

section. Those options include:
-h {host}-- Specifies the address of the SLAMD server system. By default, a

value of "127.0.0.1" will be used, which indicates that the command is being
run on the same system as the SLAMD server.
-p {port}-- Specifies the port number of the SLAMD server's administrative

interface. By default, this is port 8080.
-A {authID} -- Specifies the user ID that should be used to authenticate to the

SLAMD server's administrative interface. This is not needed if the SLAMD
server is not configured to require authentication.
Interacting with SLAMD from the Command Line 113

-P {authPW} -- Specifies the password that should be used to authenticate to the
SLAMD server's administrative interface. This is not needed if the SLAMD
server is not configured to require authentication.
-u {URI} -- Specifies the URI that should be used when communicating with
the SLAMD server's administrative interface. By default, this is "/slamd", and
it should not need to be changed in most configurations.
-S-- Indicates that the communication with the SLAMD server's

administrative interface should be encrypted using SSL.
-v -- Indicates that the utility should operate in verbose mode.
-H -- Displays usage information for the command and exits.
Specifying the SLAMD Configuration Directory Settings
Before SLAMD can actually be used, it must be configured with information

about the configuration directory server that will be used to hold the SLAMD
configuration and job data. This is normally done through the administrative
interface, but it can also be done using a command-line utility to help automate
this process. To do this, use the command:
java -cp slamd_server.jar SetupConfigDirectory {options}
where {options} may include:
-l {ldapHost} -- This specifies the address of the configuration directory server.

If this is not provided, then a default of "127.0.0.1" (the same system as the
SLAMD server) will be used.
-L {ldapPort} -- This specifies the port of the configuration directory server. If

this is not provided, then a default port of 389 will be used. Note that if the
communication with the configuration directory should be performed over
SSL, then this should be the secure port of the directory server.
-D {bindDN} -- This specifies the DN to use to bind to the configuration

directory server. This must be provided.
-w {bindPW} -- This specifies the password to use to bind to the configuration

directory server. This must be provided.

-b {baseDN} -- This specifies the base DN under which all SLAMD
configuration and data should be stored in the directory server. This must be
provided.
-s -- This indicates that the communication with the configuration directory

server should be protected using SSL.
Adding SLAMD Schema Information to the Configuration Directory
Before the configuration directory may be used to hold SLAMD configuration or

data, it must be updated to support the custom schema definitions that SLAMD
requires. This can be done from the command line using the command:
java -cp slamd_server.jar AddSLAMDSchema
Adding SLAMD Configuration to the Configuration Directory
Once the configuration directory has been updated with the appropriate schema
definitions, the SLAMD base-level configuration information must be added to
the configuration directory before the SLAMD server can be started. To do this
from the command line, issue the command:
java -cp slamd_server.jar AddSLAMDConfig
Starting the SLAMD Server
If the SLAMD server is stopped, it can be started from the command line using
the command:
java -cp slamd_server.jar StartSLAMD
Note that in order for this to work, the underlying servlet engine must be running
but the SLAMD server must be stopped.

Stopping the SLAMD Server
To stop the SLAMD server from the command line, use the command:
java -cp slamd_server.jar StopSLAMD
Note that this will only stop the SLAMD server itself. The underlying servlet
engine will remain running. Also note that this will terminate any jobs that may
be running at the time and the associated statistics may be lost, so care should be
taken to ensure that the SLAMD server is only stopped when it is safe to do so.
Restarting the SLAMD Server
To restart the SLAMD server from the command line, use the command:
java -cp slamd_server.jar RestartSLAMD
Note that this will only restart the SLAMD server itself. The underlying servlet
engine will remain running the entire time. Also note that this will terminate any
jobs that may be running at the time and the associated statistics may be lost, so
care should be taken to ensure that the SLAMD server is only stopped when it is
safe to do so.
Reloading Job Class Definitions
If an updated version of an existing job class is installed in the SLAMD server,

the job class definitions must be reloaded before that change will take effect. To
do this from the command line, issue the command:
java -cp slamd_server.jar ReloadJobClasses
Note that this will only work if the custom job class loader is enabled (which it is
by default). If the custom job class loader has been disabled, then it will be
necessary to restart the SLAMD server for the updated job class to be used.

Also note that this change only effects the SLAMD server. The job class must be
manually updated on all clients as well or they will continue executing the old
version of the job class.
Retrieving SLAMD Status Information
To retrieve information about the current status of the SLAMD server, use the
command:
java -cp slamd_server.jar SLAMDStatus
This will print information to standard output about the current state of the
SLAMD server, including:
Whether the server is online or offline.
How long the server has been online.
The set of client managers, clients, and resource monitor clients are connected
to the server.
The number of jobs processed since startup.
The number of jobs in the pending and running job queues.
Statistics from the JVM being used to run the SLAMD server.
Retrieving Log File Information
To retrieve information from the SLAMD server log file (by default,
webapps/slamd/WEB-INF/slamd.log) from the command line, issue the
command:
java -cp slamd_server.jar ViewLog

This will print the last 20 lines from the SLAMD log file to standard output. To
display a different number of lines, add the argument "-n {numLines}". To display
all lines from the log file, add the "-a" argument to the command line.
Retrieving Job Data
To retrieve information about one or more SLAMD jobs from the command line,
issue the command:
java -cp slamd_server.jar GetJob -j {jobID}
where {jobID} is the job ID of the job to retrieve. Note that multiple "-j {jobID}"
options can be used to retrieve information about multiple jobs, and it is also
possible to use one or more "-o {optimizingID}" options to retrieve information
about optimizing jobs. The information about the requested jobs and/or
optimizing jobs will be displayed in the order that the job IDs were provided on
the command line.
One piece of information that can be particularly useful, especially from a

command-line program, is the current state of a job and/or optimizing job. This
can be used in the process of deciding how to go about scheduling future jobs. To
facilitate this, the "-O" option may be used to display only the current state code
for the job(s) or optimizing job(s). If this option is used, then a single integer will
be printed for each job and/or optimizing job (in the order the jobs were provided
on the command line) corresponding to the current state of that job. The valid
state codes for a job are:
0 -- Unknown. This indicates that the current state of the job is not known.
This should never be returned.
1 -- No such job. This indicates that the SLAMD server does not know
anything about the requested job.
2 -- Uninitialized. This indicates that the job has been created but not yet
initialized with the user-specified configuration.
3 -- Not yet started. This indicates that the job has been scheduled but has not
yet started running for some reason (e.g., the start time has not yet arrived or
there are not a sufficient set of clients available).
4 -- Running. This indicates that the job is running on at least one client.

5 -- Completed successfully. This indicates that the job completed all the work
that it was configured to do without encountering any significant problems.
6 -- Completed but with one or more errors. This indicates that the job
completed, reached the scheduled stop time, or ran for the scheduled duration,
but encountered at least one error during processing.
7 -- Stopped because of an error. This indicates that the job stopped running
because a fatal error occurred that would not allow the job to continue.
8 -- Stopped because the maximum duration had been reached. This indicates
that the job ran for the maximum allowed duration without any significant
errors.
9 -- Stopped because the stop time had been reached. This indicates that the
job ran until it reached the scheduled stop time without any significant errors.
10 -- Stopped by administrative request. This indicates that the job was

cancelled after the request had been sent to one or more client systems. There
may or may not be statistical data available for this job.
11 -- Stopped by SLAMD server shutdown. This indicates that the job stopped
because the SLAMD server was shut down while the job was running.
12 -- Cancelled before job startup. This indicates that the job was cancelled by
an administrator before it was determined to be eligible to start running.
13 -- Temporarily disabled. This indicates that the job has been disabled by an
administrator and will not be considered eligible to start running until it is
enabled.
Saving Job Data to Tab-Delimited Text
The GetJob utility mentioned above makes it possible to obtain a significant

amount of information about a job, but the output that it generates, particularly
with regard to the statistics reported, is not well-formatted for use in external
applications. For this purpose, the ExportJob utility may be a better choice. It
may be invoked as follows:
java -cp slamd_server.jar ExportJob -j {jobID} -f {filename} {options}

where {jobID} is the job ID of the job to export, {filename} is the name of the output
file to create with the exported data, and {options} may include one or more of the
following arguments:
-l -- Indicates that the output file generated should include labels that describe
the data included in the export.
-o -- Indicates that the output file generated should include overall results from
the job. That is, the output file will contain data aggregated from all clients
and client threads.
-c -- Indicates that the output file generated should include results from the job
broken down on a per-client basis. That is, the output file will contain a
separate set of statistics for each client used to execute the job. The results
from the individual threads used by that client will be aggregated to provide an
overall view of that client.
-t -- Indicates that the output file generated should include results from the job
broken down on a per-thread basis. That is, the output file will contain a
separate set of statistics for each client thread used to execute the job.
Note that at least one of the -o, -c, and -t options must be provided to indicate
the level of detail that should be included in the resulting export file. However,
multiple such options can be included if so desired.
Cancelling a Scheduled Job
A job may be cancelled either before it is started or while it is running. This can
be done through the administrative interface, but it can also be done from the
command line using:
java -cp slamd_server.jar CancelJob -j {jobID}
where {jobID} is the job ID of the job to cancel. If an optimizing job is to be

cancelled, then use "-o {optimizingID}" rather than "-j {jobID}".

Enabling and Disabling Scheduled Jobs
Once a job has been scheduled, there are several factors that will be used to
determine whether that job is eligible for execution. If a job is disabled before it
starts running, then it will not be eligible to run until it has been enabled again.
To disable a job, use the command:
java -cp slamd_server.jar DisableJob -j {jobID}
where {jobID} is the job ID of the job to disable. Note that while optimizing jobs
themselves cannot be disabled, the individual iterations of an optimizing job can
be disabled, and disabling the first iteration will prevent any processing on the
optimizing job until it is enabled again.
To enable a job that has been disabled, use the command:
java -cp slamd_server.jar EnableJob -j {jobID}
Adding Job Classes
Normally, in order to register a job class for use with the SLAMD server, a user
should follow the "Add a New Job Class" link in the navigation sidebar. To do
this from the command line, issue the command:
java -cp slamd_server.jar AddJobClass -c {className}
where {className} is the fully-qualified name of the job class to be added. Note
that this job class must already be located in the SLAMD server's classpath,
preferably in the appropriate location under the webapps/slamd/WEB-INF/classes
directory structure.

Installing Job Packs
The AddJobClass utility may be used to add a single job class, but it is not
convenient for cases in which a number of jobs are to be registered. For that, it is
better to use a job pack. In the administrative interface, a job pack may be
installed by following the "Install a Job Pack" link in the navigation sidebar.
From the command line, this may be done using the command:
java -cp slamd_server.jar InstallJobPack -f {filePath}
where {filePath} is the absolute path to the job pack file on the SLAMD server
system. Note that unlike the administrative interface, the command-line utility
does not provide the ability to upload a job pack file from a remote system.
Creating and Deleting Job Folders
The command-line job scheduler described earlier in this document may be used
to place the scheduled jobs in specified folders, but those folders must exist
before the jobs may be scheduled. Job folders may be created using the
administrative interface, but they may also be created using the command:
java -cp slamd_server.jar CreateFolder -f {folderName}
where {folderName} is the name of the folder to create.
It is also possible to remove job folders from the command line. This may be
done with the command:
java -cp slamd_server.jar DeleteFolder -f {folderName}
Note that this command will only delete folders that are empty. To delete a folder
that includes one or more jobs, optimizing jobs, and/or uploaded files, it will be
necessary to include the "-d" argument on the command line. This indicates that
the contents of the folder should be removed before deleting the folder.

Exporting Job Data
The SLAMD server offers the ability to export job data in a format that may be
used as a backup or imported into another SLAMD server. In the administrative
interface, this can be done by following the "Export Job Data" link in the
navigation sidebar. From the command line, this may be done by executing the
command:
java -cp slamd_server.jar ExportData {options}
where {options} include:
-f {filePath}-- Specifies the path to the output file that should be created. This
is a required option.
-a -- Indicates that all data in the SLAMD server should be included in the
export. If this option is provided, then it is not necessary to use the -U, -R, or
-V options.
-U-- Indicates that the jobs, optimizing jobs, and uploaded files in the
unclassified folder should be included in the export.
-R {folderName}-- Indicates that the specified real job folder (and all jobs,
optimizing jobs, and uploaded files contained in it) should be included in the
export. This option may be used multiple times to indicate that data from
multiple folders should be exported.
-V {folderName} -- Indicates that the specified virtual job folder (and all jobs
contained in it) should be included in the export. This option may be used
multiple times to indicate that data from multiple virtual folders should be
exported.
The export command must specify which data to include. If it does not use the -a
argument, then it must use one or more of the -U, -R, or -V options.

Importing Job Data
Data that has been exported from the SLAMD server may be used as a backup or
imported into another server. This can be done from the command line by issuing
the command:
java -cp slamd_server.jar ImportData -f {filePath}
where {filePath} is the absolute path to the file (on the SLAMD server's filesystem)
containing the data to be imported.
Uploading Files
SLAMD offers the ability to store files in folders along with the job data. This is
useful for things like configuration files or other documents that might help
explain the circumstances under which the job results were obtained. The
following command may be used to store a file in a job folder:
java -cp slamd_server.jar UploadFile {options}
where {options} include:
-- Specifies the absolute path to the file on the SLAMD server

-f {filePath}
system. This is a required argument.
-- Specifies the name of the job folder into which the file should
-F {folderName}
be uploaded. If this is not provided, the file will be placed in the unclassified
folder.
-- Specifies the MIME type that should be used for the file. If this
-t {fileType}
is not provided, then a MIME type of "application/octet-stream" will be
used.
-- Specifies the description that should be used for the file.

-d {fileDescription}
This is an optional argument.

Listing Job Folders
Several of the command-line utilities offer the ability to interact with job folders.
To assist with this, another tool is included that can be used to list the folders
contained in the SLAMD server. This utility can be used like:
java -cp slamd_server.jar ListFolders
This will list the real job folders defined in the SLAMD server, with one folder
name per line. If the "-V" argument is provided, then the virtual job folders will
be listed instead of the real job folders.

Troubleshooting SLAMD Problems
Although every attempt has been made to ensure that SLAMD is robust and easy
to use, users have occasionally reported difficulties getting certain features to
work properly. This section discusses the most common problems that may arise
when using SLAMD and steps that may be taken to troubleshoot and correct the
problems.
If a problem occurs while using SLAMD and the troubleshooting steps listed here
do not identify and resolve the problem, then further assistance can be obtained
by sending an e-mail message to "slamd-ext@sun.com". That message should
include:
A detailed description of the problem, including the conditions under which it

occurred.
The SLAMD version in use.
Any log messages that may be of use when debugging the problem.
A list of any troubleshooting measures that have already been taken.
General Server Troubleshooting
For any problem that occurs within the SLAMD server itself, there are a number
of steps to help identify the cause of a problem. Some of those steps include:
Look in the SLAMD log file. By default, this file is named

"webapps/slamd/WEB-INF/slamd.log", although if the file is not there the
actual path may be determined by following the "SLAMD Logger" link in the
navigation sidebar and looking at the value of the "Log File Name" parameter.
If the SLAMD log file in its default log level does not provide any useful
information, try increasing the log level in an attempt to get more verbose
information about the problem. The log level may be set by following the
"SLAMD Server" link in the navigation sidebar. Note that some log levels can

generate a great deal of output, so it is recommended that once the problem has
been resolved, the original log level be restored. By default, only the "Job
Processing" and "Client/Server Interaction" log levels are enabled.
Look in the "logs/catalina.out" log file. Anything that the SLAMD server
writes to standard error will be placed in this file. If an uncaught exception is
thrown, a stack trace for that exception will likely be written into this file.
If the problem is that the SLAMD server appears to be hanging, then try
starting the Tomcat servlet engine as a foreground process (e.g., without
detaching from the console). This can be done by providing the "-nodetach"
argument to the startup.sh script, like "bin/startup.sh -nodetach". With
Tomcat running in the foreground, it should be possible to hold down the
control key and hit the backslash key to dump a stack trace of all threads
currently running in the JVM, which can be used to help understand what code
all threads are executing. Note that this key combination should work on both
Solaris and Linux. Other operating systems may or may not support this
capability or may use a different key combination.
If the Tomcat process appears to be hanging but is running in the background,

then try sending the process a SIGQUIT signal, like "kill -3 {pid}". This may
cause the JVM to dump a stack trace of all running threads into the
logs/catalina.out log file.
In order to provide better performance and more efficient CPU utilization, the
Tomcat process is started using the server VM provided by the Java virtual
machine. However, on some platforms the server VM is only provided with
the Java SDK and does not come as part of the JRE. If an error occurs while
attempting to run the bin/startup.sh script using the JRE rather than the Java
SDK, then try either installing the Java SDK or editing the bin/startup.sh
script to remove the "-server" flag from the CATALINA_OPTS variable
definition.
If the Tomcat process disappears whenever the user that started it logs out of
the system (particularly on Solaris 9), then try starting it using the bash shell
rather than alternatives like sh, ksh, or csh. There is a known bug on Solaris 9
systems in which the nohup command does not appear to work properly with
Java applications started from shells other than bash. Another alternative
would be to issue the command "nohup -Fap {pid}", although this is a less
desirable alternative because this will also eliminate the ability to use the
SIGQUIT signal (e.g., "kill -3 {pid}") to obtain a stack trace from the running
process.
Troubleshooting SLAMD Problems 127

General Client Troubleshooting
If a problem is experienced on the client side rather than the server side, then the
debugging process may be different. However, the the same approach may be
taken for any kind of client, whether it be the SLAMD client, client manager, or
resource monitor client:
Run the client in the foreground rather than in the background. If the client is
run as a background process (or if it is started using the client manager), then
any error messages it writes may be lost. If it is run in the foreground, then
those messages should be displayed on standard error.
Run the client with verbose mode enabled. This can be done by setting the
"VERBOSE_MODE" option to "on" in the client configuration file or by including
the "-v" argument on the command line when starting the client. A client
running in verbose mode should write a significant amount of information to
standard error about the processing that it performs, including detailed
information about any communication with the SLAMD server, and any debug
information written if the job calls the writeVerbose() method.
If the client appears to be hung or unresponsive, then use the Ctrl+\ key
combination to dump information about all threads running in the JVM. This
information may be useful for determining exactly what each thread is doing.
Note that this will only work if the client is running in the foreground. If the
client is running in the background and has its output redirected somewhere,
then executing the command "kill -3 {pid}" may also cause the JVM to
produce a stack trace of all running threads.
Make sure that the client has the latest version of all the job classes being used.
If a client is asked to execute a job about which it does not have any prior
knowledge, then it will request that job class from the server. However, if a
new version of the job class is installed in the server, the client will also need
to be updated because it would otherwise continue executing the old version of
the job class.
In order to provide better performance and more efficient CPU utilization, the
client processes are started using the server VM provided by the Java virtual
machine. However, on some platforms the server VM is only provided with
the Java SDK and does not come as part of the JRE. If an error occurs while
attempting to run the client startup scripts using the JRE rather than the Java
SDK, then try either installing the Java SDK or editing the scripts to remove
the "-server" flag from the Java command line.

If the client process disappears whenever the user that started it logs out of the
system (particularly on Solaris 9), then try starting it using the bash shell rather
than alternatives like sh, ksh, or csh. There is a known bug on Solaris 9
systems in which the nohup command does not appear to work properly with
Java applications started from shells other than bash. Another alternative
would be to issue the command "nohup -Fap {pid}", although this is a less
desirable alternative because this will also eliminate the ability to use the
SIGQUIT signal (e.g., "kill -3 {pid}") to obtain a stack trace from the running
process.
Jobs Won't Start
If a scheduled job does not start running as expected, a number of problems may
be to blame:
Verify that the clocks on all systems running SLAMD components (i.e., the
server and all kinds of clients) are synchronized. This is the most common
cause of jobs not starting when expected. In cases in which the clock of a
client system is behind that of the server, then the client will wait for the start
time to arrive before beginning the job (which can be anywhere from seconds
to years depending on the time difference between the systems). If the clock
on the client is ahead of the server, then jobs configured with a stop time may
end prematurely. It is strongly recommended that some form of time
synchronization (e.g., NTP) be enabled on any system that may run a
component of the SLAMD environment to keep all clocks synchronized.
Verify that the start time for the job has arrived (according to the clock on the
SLAMD server system), that the job is not marked as disabled, and that any
dependencies configured for the job have been satisfied. The SLAMD server
will not attempt to start a job if any of those conditions has not been met.
Verify that there are enough clients connected to the SLAMD server to process
the job. If there are not enough idle clients available, the server will not be
able to start the job. If the job requested that a specific set of clients be used,
then those specific clients must be available before it will be able to start. If
the job requested that specific set of resource monitor clients be used, then
those monitor clients must be available before it will be able to start.
Enable debug logging for the SLAMD scheduler. With the "Scheduler
Debugging" log level enabled, messages will be written to the SLAMD log file
explaining why any pending jobs may not yet be started.

Enable verbose mode on the clients and verify that the client is actually
receiving the request and is not experiencing any failures that would prevent
the job from running properly.
Running Out of Memory
If the SLAMD server runs out of available memory, then that can cause a number
of problems, including unresponsiveness or errors in the administrative interface
or even the loss of data collected by jobs that are currently running. If the server
does run out of memory, then there will likely be a message like
"java.lang.OutOfMemoryError" in the logs/catalina.out log file. If this
occurs, then it should be possible to tune various components of the SLAMD
server to prevent the problem from recurring:
Ensure that the system itself is not running low on memory or swap space. If
the underlying operating system does not have enough memory to meet the
needs of SLAMD, then SLAMD will not be able to operate properly. If this
condition exists, then check to see if there are any large processes that may be
stopped or reconfigured to reduce the amount of memory that they are using.
It may also be beneficial on Solaris systems to check whether a tmpfs
filesystem (e.g., /tmp or /var/run) contains any large files that may be
consuming large amounts of space. If so, deleting these files or moving them
to a different type of filesystem may reduce the amount of memory available.
Increase the amount of memory that will be available to SLAMD by editing

the bin/startup.sh script. If enough memory is available on the system, then
the MAX_MEMORY parameter should be increased to allow the SLAMD server to
make use of a larger amount of memory. It may also be beneficial to increase
the INITIAL_MEMORY setting to equal that of MAX_MEMORY so that it will not be
necessary later to increase the process size as more memory is used. Note,
however, that there may be a limit to the amount of memory that the JVM can
use. For example, the 32-bit JVM (or any other 32-bit process) on Solaris
systems may not use more than 4 gigabytes of memory, and similar limitations
exist on other operating systems. The 64-bit JVM may allow use of greater
amounts of memory.
Configure the clients to aggregate the thread data before returning it to the
server. By default, clients return a separate set of statistics for each thread
used to run a job. If the clients are configured to aggregate this data together,
then the client will only return one set of data to the server that combines the
information from all threads. Note that if this is done, it will not be possible to

view detailed information about each thread used to run the job, although this
is generally not a significant limitation.
Consider reducing the job cache size. The job cache is used to store job
information in memory in order to prevent the expense of repeatedly retrieving
the information from the configuration directory and converting it into an
internal form for use. If the job cache is too large, however, it may consume a
significant amount of memory. Reducing the job cache size may free memory
so that it can be used for other SLAMD processing, although it may degrade
performance when viewing job information.
Tune or disable in-progress statistics reporting by clients. If clients are

configured to report statistical data to the SLAMD server while the job is
active, then the server will need to store that data in memory. The amount of
data that it needs to store can be adjusted through the "Max Stat Intervals"
parameter in the "Real-Time Stat Listener" configuration page, and reducing it
will decrease the amount of memory required to store this information.
Disabling this capability altogether (by setting "ENABLE_REAL_TIME_STATS" to
"off" in the slamd_client.conf configuration file for all clients) will eliminate
the need for the server to store this information.
Consider increasing the statistics collection interval for long-running jobs.

When a job is running, the client will generally capture at least one data point
per collection interval per thread. Jobs that run for a large amount of time with
a small collection interval will need to store information about a large number
of data points. Increasing the collection interval will reduce the number of
data points that need to be stored, which will in turn reduce the amount of
memory required.
If the client seems to be prone to running out of memory when executing a

particular job, then there may be a problem within that job that causes
excessive memory consumption. For example, any case in which an attempt is
made to update a stat tracker before the startTracker() method has been
called can cause this condition to occur. If this problem does occur, then it
may be necessary to have the job developer locate and correct the problem.
Administrative Interface Problems
If a problem occurs while accessing the administrative interface, then there are
several steps that may be taken to debug and/or resolve the problem:

A special HTML debug mode can be enabled for the current session by either
adding a parameter named "html_debug" with a value of "1" to the request, or
by clicking the "Disabled" link next to the "HTML Debugging" label on the
status page. If this debug mode is enabled, then an additional debug menu will
be provided in the navigation sidebar that can be used to do things like
investigate active threads, system properties, request parameters, and request
that the JVM perform operations like garbage collection or enable/disable
tracing. Further, whenever this mode is enabled, debug information will be
written to the generated pages in the form of HTML comments. This debug
mode will remain enabled for the current browser session only until it is
disabled on the status page or the "html_debug=1" request parameter is
removed.
If there is a problem displaying a given page in the administrative interface, try

a different browser. SLAMD should generate HTML documents that are
complaint with the W3C HTML 4.01 specification and do not require any
client-side code execution (e.g., JavaScript). As such, it should work properly
in any browser compliant with this specification, and to date there have been
no reports of any case in which a page was not rendered properly by the
browser. However, if an oddity does occur, it may be useful to determine
whether that problem occurs only with a particular type of browser.
If the administrative interface appears sluggish and slow to respond, then first
verify that the appropriate tuning has been done for the configuration directory
(e.g., the caches have been tuned and appropriate indexes have been added). If
the problem only occurs when viewing a list of jobs in a folder that contains a
large number of jobs, then it may be beneficial to move some of those jobs into
other folders to reduce the total number of jobs in any single folder.

SLAMD License
The SLAMD Distributed Load Generation Engine (SLAMD) is licensed under

the Sun Public License Version 1.0. This is an OSI-Approved Open Source
license, and more information can be found about such licenses at
http://www.opensource.org/, but the full text of the Sun Public License Version
1.0 is provided below for reference.
SUN PUBLIC LICENSE Version 1.0
1. Definitions.
1.0.1. "Commercial Use" means distribution or otherwise making the

Covered Code available to a third party.
1.1. "Contributor" means each entity that creates or contributes to

the creation of Modifications.
1.2. "Contributor Version" means the combination of the Original Code,

prior Modifications used by a Contributor, and the Modifications made
by that particular Contributor.
1.3. "Covered Code" means the Original Code or Modifications or the

combination of the Original Code and Modifications, in each case
including portions thereof and corresponding documentation released
with the source code.
1.4. "Electronic Distribution Mechanism" means a mechanism generally

accepted in the software development community for the electronic
transfer of data.
1.5. "Executable" means Covered Code in any form other than Source
Code.
1.6. "Initial Developer" means the individual or entity identified as

the Initial Developer in the Source Code notice required by Exhibit A.
1.7. "Larger Work" means a work which combines Covered Code or

portions thereof with code not governed by the terms of this License.
1.8. "License" means this document.
1.8.1. "Licensable" means having the right to grant, to the maximum

extent possible, whether at the time of the initial grant or
subsequently acquired, any and all of the rights conveyed herein.
1.9. "Modifications" means any addition to or deletion from the
SLAMD License 133

substance or structure of either the Original Code or any previous
Modifications. When Covered Code is released as a series of files, a
Modification is:
A. Any addition to or deletion from the contents of a file containing

Original Code or previous Modifications.
B. Any new file that contains any part of the Original Code or
previous Modifications.
1.10. "Original Code" means Source Code of computer software code

which is described in the Source Code notice required by Exhibit A as
Original Code, and which, at the time of its release under this
License is not already Covered Code governed by this License.
1.10.1. "Patent Claims" means any patent claim(s), now owned or

hereafter acquired, including without limitation, method, process, and
apparatus claims, in any patent Licensable by grantor.
1.11. "Source Code" means the preferred form of the Covered Code for
making modifications to it, including all modules it contains, plus
any associated documentation, interface definition files, scripts used
to control compilation and installation of an Executable, or source
code differential comparisons against either the Original Code or
another well known, available Covered Code of the Contributor's
choice. The Source Code can be in a compressed or archival form,
provided the appropriate decompression or de-archiving software is
widely available for no charge.
1.12. "You" (or "Your") means an individual or a legal entity

exercising rights under, and complying with all of the terms of, this
License or a future version of this License issued under Section 6.1.
For legal entities, "You" includes any entity which controls, is
controlled by, or is under common control with You. For purposes of
this definition, "control" means (a) the power, direct or indirect, to
cause the direction or management of such entity, whether by contract
or otherwise, or (b) ownership of more than fifty percent (50%) of the
outstanding shares or beneficial ownership of such entity.
2. Source Code License.
2.1 The Initial Developer Grant.
The Initial Developer hereby grants You a world-wide, royalty-free,

non-exclusive license, subject to third party intellectual property
claims:
(a) under intellectual property rights (other than patent or

trademark) Licensable by Initial Developer to use, reproduce, modify,
display, perform, sublicense and distribute the Original Code (or
portions thereof) with or without Modifications, and/or as part of a
Larger Work; and
(b) under Patent Claims infringed by the making, using or selling of

Original Code, to make, have made, use, practice, sell, and offer for
sale, and/or otherwise dispose of the Original Code (or portions
thereof).
(c) the licenses granted in this Section 2.1(a) and (b) are effective
on the date Initial Developer first distributes Original Code under
the terms of this License.

(d) Notwithstanding Section 2.1(b) above, no patent license is
granted: 1) for code that You delete from the Original Code; 2)
separate from the Original Code; or 3) for infringements caused by:
i) the modification of the Original Code or ii) the combination of the
Original Code with other software or devices.
2.2. Contributor Grant.
Subject to third party intellectual property claims, each Contributor

hereby grants You a world-wide, royalty-free, non-exclusive license
(a) under intellectual property rights (other than patent or

trademark) Licensable by Contributor, to use, reproduce, modify,
display, perform, sublicense and distribute the Modifications created
by such Contributor (or portions thereof) either on an unmodified
basis, with other Modifications, as Covered Code and/or as part of a
Larger Work; and
(b) under Patent Claims infringed by the making, using, or selling of

Modifications made by that Contributor either alone and/or in
combination with its Contributor Version (or portions of such
combination), to make, use, sell, offer for sale, have made, and/or
otherwise dispose of: 1) Modifications made by that Contributor (or
portions thereof); and 2) the combination of Modifications made by
that Contributor with its Contributor Version (or portions of such
combination).
(c) the licenses granted in Sections 2.2(a) and 2.2(b) are effective
on the date Contributor first makes Commercial Use of the Covered
Code.
(d) notwithstanding Section 2.2(b) above, no patent license is

granted: 1) for any code that Contributor has deleted from the
Contributor Version; 2) separate from the Contributor Version; 3) for
infringements caused by: i) third party modifications of Contributor
Version or ii) the combination of Modifications made by that
Contributor with other software (except as part of the Contributor
Version) or other devices; or 4) under Patent Claims infringed by
Covered Code in the absence of Modifications made by that Contributor.
3. Distribution Obligations.
3.1. Application of License.
The Modifications which You create or to which You contribute are

governed by the terms of this License, including without limitation
Section 2.2. The Source Code version of Covered Code may be
distributed only under the terms of this License or a future version
of this License released under Section 6.1, and You must include a
copy of this License with every copy of the Source Code You
distribute. You may not offer or impose any terms on any Source Code
version that alters or restricts the applicable version of this
License or the recipients' rights hereunder. However, You may include
an additional document offering the additional rights described in
Section 3.5.
3.2. Availability of Source Code.
Any Modification which You create or to which You contribute must be

made available in Source Code form under the terms of this License
either on the same media as an Executable version or via an accepted
Electronic Distribution Mechanism to anyone to whom you made an
SLAMD License 135

Executable version available; and if made available via Electronic
Distribution Mechanism, must remain available for at least twelve (12)
months after the date it initially became available, or at least six
(6) months after a subsequent version of that particular Modification
has been made available to such recipients. You are responsible for
ensuring that the Source Code version remains available even if the
Electronic Distribution Mechanism is maintained by a third party.
3.3. Description of Modifications.
You must cause all Covered Code to which You contribute to contain a
file documenting the changes You made to create that Covered Code and
the date of any change. You must include a prominent statement that
the Modification is derived, directly or indirectly, from Original
Code provided by the Initial Developer and including the name of the
Initial Developer in (a) the Source Code, and (b) in any notice in an
Executable version or related documentation in which You describe the
origin or ownership of the Covered Code.
3.4. Intellectual Property Matters.
(a) Third Party Claims.
If Contributor has knowledge that a license under a third party's

intellectual property rights is required to exercise the rights
granted by such Contributor under Sections 2.1 or 2.2, Contributor
must include a text file with the Source Code distribution titled
"LEGAL'' which describes the claim and the party making the claim in
sufficient detail that a recipient will know whom to contact. If
Contributor obtains such knowledge after the Modification is made
available as described in Section 3.2, Contributor shall promptly
modify the LEGAL file in all copies Contributor makes available
thereafter and shall take other steps (such as notifying appropriate
mailing lists or newsgroups) reasonably calculated to inform those who
received the Covered Code that new knowledge has been obtained.
(b) Contributor APIs.
If Contributor's Modifications include an application programming

interface ("API") and Contributor has knowledge of patent licenses
which are reasonably necessary to implement that API, Contributor must
also include this information in the LEGAL file.
(c) Representations.
Contributor represents that, except as disclosed pursuant to Section

3.4(a) above, Contributor believes that Contributor's Modifications
are Contributor's original creation(s) and/or Contributor has
sufficient rights to grant the rights conveyed by this License.
3.5. Required Notices.
You must duplicate the notice in Exhibit A in each file of the Source
Code. If it is not possible to put such notice in a particular Source
Code file due to its structure, then You must include such notice in a
location (such as a relevant directory) where a user would be likely
to look for such a notice. If You created one or more Modification(s)
You may add your name as a Contributor to the notice described in
Exhibit A. You must also duplicate this License in any documentation
for the Source Code where You describe recipients' rights or ownership
rights relating to Covered Code. You may choose to offer, and to
charge a fee for, warranty, support, indemnity or liability

obligations to one or more recipients of Covered Code. However, You
may do so only on Your own behalf, and not on behalf of the Initial
Developer or any Contributor. You must make it absolutely clear than
any such warranty, support, indemnity or liability obligation is
offered by You alone, and You hereby agree to indemnify the Initial
Developer and every Contributor for any liability incurred by the
Initial Developer or such Contributor as a result of warranty,
support, indemnity or liability terms You offer.
3.6. Distribution of Executable Versions.
You may distribute Covered Code in Executable form only if the

requirements of Section 3.1-3.5 have been met for that Covered Code,
and if You include a notice stating that the Source Code version of
the Covered Code is available under the terms of this License,
including a description of how and where You have fulfilled the
obligations of Section 3.2. The notice must be conspicuously included
in any notice in an Executable version, related documentation or
collateral in which You describe recipients' rights relating to the
Covered Code. You may distribute the Executable version of Covered
Code or ownership rights under a license of Your choice, which may
contain terms different from this License, provided that You are in
compliance with the terms of this License and that the license for the
Executable version does not attempt to limit or alter the recipient's
rights in the Source Code version from the rights set forth in this
License. If You distribute the Executable version under a different
license You must make it absolutely clear that any terms which differ
from this License are offered by You alone, not by the Initial
Developer or any Contributor. You hereby agree to indemnify the
Initial Developer and every Contributor for any liability incurred by
the Initial Developer or such Contributor as a result of any such
terms You offer.
3.7. Larger Works.
You may create a Larger Work by combining Covered Code with other code
not governed by the terms of this License and distribute the Larger
Work as a single product. In such a case, You must make sure the
requirements of this License are fulfilled for the Covered Code.
4. Inability to Comply Due to Statute or Regulation.
If it is impossible for You to comply with any of the terms of this

License with respect to some or all of the Covered Code due to
statute, judicial order, or regulation then You must: (a) comply with
the terms of this License to the maximum extent possible; and (b)
describe the limitations and the code they affect. Such description
must be included in the LEGAL file described in Section 3.4 and must
be included with all distributions of the Source Code. Except to the
extent prohibited by statute or regulation, such description must be
sufficiently detailed for a recipient of ordinary skill to be able to
understand it.
5. Application of this License.
This License applies to code to which the Initial Developer has

attached the notice in Exhibit A and to related Covered Code.
6. Versions of the License.
6.1. New Versions.
SLAMD License 137

Sun Microsystems, Inc. ("Sun") may publish revised and/or new versions
of the License from time to time. Each version will be given a
distinguishing version number.
6.2. Effect of New Versions.
Once Covered Code has been published under a particular version of the
License, You may always continue to use it under the terms of that
version. You may also choose to use such Covered Code under the terms
of any subsequent version of the License published by Sun. No one
other than Sun has the right to modify the terms applicable to Covered
Code created under this License.
6.3. Derivative Works.
If You create or use a modified version of this License (which you may
only do in order to apply it to code which is not already Covered Code
governed by this License), You must: (a) rename Your license so that
the phrases "Sun," "Sun Public License," or "SPL" or any confusingly
similar phrase do not appear in your license (except to note that your
license differs from this License) and (b) otherwise make it clear
that Your version of the license contains terms which differ from the
Sun Public License. (Filling in the name of the Initial Developer,
Original Code or Contributor in the notice described in Exhibit A
shall not of themselves be deemed to be modifications of this
License.)
7. DISCLAIMER OF WARRANTY.
COVERED CODE IS PROVIDED UNDER THIS LICENSE ON AN "AS IS'' BASIS,

WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
WITHOUT LIMITATION, WARRANTIES THAT THE COVERED CODE IS FREE OF
DEFECTS, MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING.
THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE COVERED CODE
IS WITH YOU. SHOULD ANY COVERED CODE PROVE DEFECTIVE IN ANY RESPECT,
YOU (NOT THE INITIAL DEVELOPER OR ANY OTHER CONTRIBUTOR) ASSUME THE
COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER
OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF
ANY COVERED CODE IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.
8. TERMINATION.
8.1. This License and the rights granted hereunder will terminate
automatically if You fail to comply with terms herein and fail to cure
such breach within 30 days of becoming aware of the breach. All
sublicenses to the Covered Code which are properly granted shall
survive any termination of this License. Provisions which, by their
nature, must remain in effect beyond the termination of this License
shall survive.
8.2. If You initiate litigation by asserting a patent infringement

claim (excluding declaratory judgment actions) against Initial Developer
or a Contributor (the Initial Developer or Contributor against whom
You file such action is referred to as "Participant") alleging that:
(a) such Participant's Contributor Version directly or indirectly

infringes any patent, then any and all rights granted by such
Participant to You under Sections 2.1 and/or 2.2 of this License
shall, upon 60 days notice from Participant terminate prospectively,
unless if within 60 days after receipt of notice You either: (i)
agree in writing to pay Participant a mutually agreeable reasonable
royalty for Your past and future use of Modifications made by such

Participant, or (ii) withdraw Your litigation claim with respect to
the Contributor Version against such Participant. If within 60 days
of notice, a reasonable royalty and payment arrangement are not
mutually agreed upon in writing by the parties or the litigation claim
is not withdrawn, the rights granted by Participant to You under
Sections 2.1 and/or 2.2 automatically terminate at the expiration of
the 60 day notice period specified above.
(b) any software, hardware, or device, other than such Participant's

Contributor Version, directly or indirectly infringes any patent, then
any rights granted to You by such Participant under Sections 2.1(b)
and 2.2(b) are revoked effective as of the date You first made, used,
sold, distributed, or had made, Modifications made by that
Participant.
8.3. If You assert a patent infringement claim against Participant

alleging that such Participant's Contributor Version directly or
indirectly infringes any patent where such claim is resolved (such as
by license or settlement) prior to the initiation of patent
infringement litigation, then the reasonable value of the licenses
granted by such Participant under Sections 2.1 or 2.2 shall be taken
into account in determining the amount or value of any payment or
license.
8.4. In the event of termination under Sections 8.1 or 8.2 above, all
end user license agreements (excluding distributors and resellers)
which have been validly granted by You or any distributor hereunder
prior to termination shall survive termination.
9. LIMITATION OF LIABILITY.
UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER TORT

(INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL YOU, THE INITIAL
DEVELOPER, ANY OTHER CONTRIBUTOR, OR ANY DISTRIBUTOR OF COVERED CODE,
OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR
ANY INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY
CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL,
WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER
COMMERCIAL DAMAGES OR LOSSES, EVEN IF SUCH PARTY SHALL HAVE BEEN
INFORMED OF THE POSSIBILITY OF SUCH DAMAGES. THIS LIMITATION OF
LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL INJURY
RESULTING FROM SUCH PARTY'S NEGLIGENCE TO THE EXTENT APPLICABLE LAW
PROHIBITS SUCH LIMITATION. SOME JURISDICTIONS DO NOT ALLOW THE
EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO
THIS EXCLUSION AND LIMITATION MAY NOT APPLY TO YOU.
10. U.S. GOVERNMENT END USERS.
The Covered Code is a "commercial item," as that term is defined in 48

C.F.R. 2.101 (Oct. 1995), consisting of "commercial computer software"
and "commercial computer software documentation," as such terms are
used in 48 C.F.R. 12.212 (Sept. 1995). Consistent with 48 C.F.R.
12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4 (June 1995), all
U.S. Government End Users acquire Covered Code with only those rights
set forth herein.
11. MISCELLANEOUS.
This License represents the complete agreement concerning subject

matter hereof. If any provision of this License is held to be
unenforceable, such provision shall be reformed only to the extent
necessary to make it enforceable. This License shall be governed by
SLAMD License 139

California law provisions (except to the extent applicable law, if
any, provides otherwise), excluding its conflict-of-law provisions.
With respect to disputes in which at least one party is a citizen of,
or an entity chartered or registered to do business in the United
States of America, any litigation relating to this License shall be
subject to the jurisdiction of the Federal Courts of the Northern
District of California, with venue lying in Santa Clara County,
California, with the losing party responsible for costs, including
without limitation, court costs and reasonable attorneys' fees and
expenses. The application of the United Nations Convention on
Contracts for the International Sale of Goods is expressly excluded.
Any law or regulation which provides that the language of a contract
shall be construed against the drafter shall not apply to this
License.
12. RESPONSIBILITY FOR CLAIMS.
As between Initial Developer and the Contributors, each party is

responsible for claims and damages arising, directly or indirectly,
out of its utilization of rights under this License and You agree to
work with Initial Developer and Contributors to distribute such
responsibility on an equitable basis. Nothing herein is intended or
shall be deemed to constitute any admission of liability.
13. MULTIPLE-LICENSED CODE.
Initial Developer may designate portions of the Covered Code as

"Multiple-Licensed". "Multiple-Licensed" means that the Initial
Developer permits you to utilize portions of the Covered Code under
Your choice of the alternative licenses, if any, specified by the
Initial Developer in the file described in Exhibit A.
Exhibit A -Sun Public License Notice.
The contents of this file are subject to the Sun Public License
Version 1.0 (the "License"); you may not use this file except in
compliance with the License. A copy of the License is available at
http://www.sun.com/
The Original Code is _________________. The Initial Developer of the

Original Code is ___________. Portions created by ______ are Copyright
(C)_________. All Rights Reserved.
Contributor(s): ______________________________________.
Alternatively, the contents of this file may be used under the terms
of the _____ license (the "[___] License"), in which case the
provisions of [______] License are applicable instead of those above.
If you wish to allow use of your version of this file only under the
terms of the [____] License and not to allow others to use your
version of this file under the SPL, indicate your decision by deleting
the provisions above and replace them with the notice and other
provisions required by the [___] License. If you do not delete the
provisions above, a recipient may use your version of this file under
either the SPL or the [___] License."
[NOTE: The text of this Exhibit A may differ slightly from the text of
the notices in the Source Code files of the Original Code. You should
use the text of this Exhibit A rather than the text found in the
Original Code Source Code for Your Modifications.]

Slamd Admin Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Slamd Admin Guide

Uploaded by

Copyright:

Available Formats

Administration and Usage Guide

SLAMD Distributed Load Generation Engine

3. Installing the SLAMD Server....................................................................................8

4. Using SLAMD Clients.............................................................................................12

5. Using the Administration Interface.......................................................................29

6. Scheduling Jobs for Execution.............................................................................31

7. Managing Scheduled Jobs.....................................................................................40

8. Viewing Job Execution Results.............................................................................48

10.Organizing Job Information..................................................................................60

2 SLAMD Administrator's Guide

11.Adding New Job Classes......................................................................................65

12.Using the Standalone Client.................................................................................67

13.Configuring the SLAMD Server............................................................................69

14.Starting and Stopping SLAMD..............................................................................86

15.Tuning the Configuration Directory.....................................................................89

17.Configuring Access Control.................................................................................95

18.Using SSL with SLAMD.......................................................................................105

19.Interacting with SLAMD from the Command Line............................................114

20.Troubleshooting SLAMD Problems...................................................................126

4 SLAMD Administrator's Guide

The SLAMD Distributed Load Generation Engine is a Java-based application

6 SLAMD Administrator's Guide

NOTE If SLAMD is to be used in a purely text-based environment, then it is

1. Copy the installation archive "slamd-1.8.0.tar.gz" onto the server system

2. Go into the newly-created slamd directory.

8 SLAMD Administrator's Guide

7. Follow the "Initialization Parameters" link to a page on which it is possible to

Installing the SLAMD Server 9

10 SLAMD Administrator's Guide

Installing the SLAMD Server 11

Because SLAMD is a distributed load generation engine, the SLAMD server

1. Copy the "slamd-client-1.8.0.tar.gz" archive onto the client system and

12 SLAMD Administrator's Guide

Using SLAMD Clients 13

14 SLAMD Administrator's Guide

Once the SLAMD client is installed and configured, it may be started by

Using the Client Manager

Using SLAMD Clients 15

Using the Swing-Based GUI Client

The standard SLAMD client uses a command-line interface, which makes it

16 SLAMD Administrator's Guide

Using the Resource Monitor Client

To install the resource monitor client, copy the slamd_monitor_client-

Using SLAMD Clients 17

18 SLAMD Administrator's Guide

monitor_class -- Specifies the fully-qualified name of the Java class that

Using SLAMD Clients 19

SLAMD is provided with several resource monitors. The remainder of this

The VMStat Resource Monitor

Free Memory -- A measure of the amount of free memory on the system.

capture_cpu_utilization -- Indicates whether the CPU utilization statistic

capture_cpu_busy -- Indicates whether the CPU busy time statistic should be

20 SLAMD Administrator's Guide

capture_cpu_system -- Indicates whether the CPU system time statistic should

capture_cpu_idle -- Indicates whether the CPU idle time statistic should be

capture_free_memory -- Indicates whether the free memory statistic should be

peak_utilization_log_threshold -- Specifies the threshold at which the

average_utilization_log_threshold -- Specifies the threshold at which the

The IOStat Resource Monitor

Using SLAMD Clients 21

The NetStat Resource Monitor

Solaris, using the command "kstat -c net :::*bytes" to capture information

Linux, by reading the "/proc/net/dev" file providing information about kernel

HP-UX, using the command "netstat -s -p tcp" to capture information