Documente Academic
Documente Profesional
Documente Cultură
Version 1.8.1
December 2004
Contents
1. Introduction...............................................................................................................5
2. Installation Prerequisites.........................................................................................6
9. Optimizing Jobs......................................................................................................52
Pausing an Optimizing Job.....................................................................................................56
Scheduling Optimizing Jobs from the Command Line..........................................................57
16.Configuring Tomcat...............................................................................................91
3
Configuring the Client Listener to Require Client Authentication........................................103
21.SLAMD License....................................................................................................133
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.
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.
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:
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.
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.
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.
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.
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:
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:
./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).
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
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.
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.
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.
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:
The configuration file may also have additional properties, specific to that
monitor class.
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.
The VMStat resource monitor may be used on Solaris, Linux, HP-UX, and AIX
systems. It supports the following configuration parameters:
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".
AIX, using the command "netstat -ss -p tcp" to capture information about
the number of bytes of TCP traffic transferred.
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:
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 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.
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.
Entry Cache Size -- The estimated size of the entry cache, measured in
megabytes.
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.
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.
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.
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
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.
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
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.
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.
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
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
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).
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.
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
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.
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:
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
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.
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.
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.
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.
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
Once the configuration file has been edited, it may be used to schedule the job for
execution. This can be done using the command:
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.
-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 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.
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.
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,
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.
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 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:
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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:
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
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.
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.
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.
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
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.
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.
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
specify either the IP address or DNS hostname (as long as those names can be
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.
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.
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.
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.
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:
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_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.
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.
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.
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.
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 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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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 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:
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:
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:
-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.
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.
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.
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
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.
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 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.
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.
Changes to this parameter will take effect immediately, without the need to
restart the SLAMD server.
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.
Changes to this parameter will take effect immediately, without the need to
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.
Changes to this parameter will take effect immediately, without the need to
restart the SLAMD server.
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).
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.
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
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.
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.
Changes to this parameter are not applied automatically and require that
the SLAMD server be restarted.
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.
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.
Changes to this parameter are not applied automatically and require that
the SLAMD server be restarted.
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.
Changes to this parameter are not applied automatically and require that
the SLAMD server be restarted.
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.
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
restart the SLAMD server.
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.
Changes to this parameter are applied automatically and without a need to
restart the SLAMD server.
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
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.
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.
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.
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
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.
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 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.
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:
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.).
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:
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.
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.
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.
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.
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.
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
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
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.
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.
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
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.
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 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.
After Tomcat is restarted, any file placed in the webapps/ROOT directory will be
accessible from the root of the server.
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",
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.
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 "<!--" and "-->" 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:
loginIDAttribute -- Specifies the LDAP attribute that will be used to store the
login ID attribute. By default, the login ID attribute will be "uid".
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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 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.
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.
This will create the certificate, and it will be available for use in the
administrative interface and/or the client listener.
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:
At this point, the certificate may be used to enable SSL in the administrative
interface and/or in the client listener.
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.
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 before the
Connector definition and 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.
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.
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
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
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
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"
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.
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.
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:
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:
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.
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.
-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.
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:
If the SLAMD server is stopped, it can be started from the command line using
the command:
Note that in order for this to work, the underlying servlet engine must be running
but the SLAMD server must be stopped.
To stop the SLAMD server from the command line, use the command:
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.
To restart the SLAMD server from the command line, use the command:
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.
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.
To retrieve information about the current status of the SLAMD server, use the
command:
This will print information to standard output about the current state of the
SLAMD server, including:
The set of client managers, clients, and resource monitor clients are connected
to the server.
Statistics from the JVM being used to run the SLAMD server.
To retrieve information from the SLAMD server log file (by default,
webapps/slamd/WEB-INF/slamd.log) from the command line, issue the
command:
To retrieve information about one or more SLAMD jobs from the command line,
issue the command:
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.
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.
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.
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.
-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.
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:
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:
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.
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:
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.
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:
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.
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:
It is also possible to remove job folders from the command line. This may be
done with the command:
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.
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:
-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.
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:
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:
-- 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.
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:
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.
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:
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:
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
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.
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.
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 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.
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.
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
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.
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:
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.
1. Definitions.
1.5. "Executable" means Covered Code in any form other than Source
Code.
B. Any new file that contains any part of the Original Code or
previous Modifications.
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.
(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.
(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.
3. Distribution Obligations.
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.
(c) Representations.
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
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.
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.
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.
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.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.
11. MISCELLANEOUS.
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/
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.]