GridSAM Quick Start Guide

Introduction

The quick start document guides you through the steps to deploy an instance of the GridSAM web service as well as submitting and monitoring your first JSDL job. For advance deployment scenario and configuration, please consult the Deployment Guide in the GridSAM Service module.

Installing GridSAM using the OMII Stack Installer

The OMII distribution bundles GridSAM in the Managed Programme component. Please follow the instruction given in the OMII-UK Development Kit Installation Guide Installing Software Components section to install GridSAM.

Once you have verified the GridSAM service and client have been setup successfully, you can proceed to the section "Submitting a Job" in this guide.

Installing GridSAM from the binary distribution

If you are installing GridSAM separately from the OMII-UK Development Kit release. You need to follow the instruction given here.

Pre-requisites

The following pre-requisites and the indirect dependencies must be installed and tested prior to installing GridSAM.

  • OMII-UK Development Kit - Client (3.4.2 or later) must be installed and tested according to the OMII installation procedure. This is ONLY REQUIRED if you intend to use the GridSAM client tools. The installation directory will be referred to as OMIICLIENT_HOME in this document. The GridSAM tools assume the default to be $HOME/OMIICLIENT unless specified.
  • OMII-UK Development Kit - Server (3.4.2 or later) must be installed and tested according to the OMII installation procedure. This is ONLY REQUIRED if you intend to deploy a GridSAM service instance. This will be referred to as OMII_HOME in this document. The GridSAM tools assume this to be /usr/local/OMII unless specified.
  • Apache Ant (1.6.5 or later) must be installed and available in your PATH in order to install the GridSAM client and server distribution without using the OMII Stack Installer.

Downloading GridSAM

Official GridSAM binary releases can be downloaded here.

Distributions are packaged in .tar.gz and .zip formats. Packages named GridSAM-X.Y.Z-server.tar.gz is the server binary distribution, while GridSAM-X.Y.Z-client.[tar.gz|zip] is the client binary distribution. Package named GridSAM-X.Y.Z-src.tar.gz contains the source distribution.

To follow the Quick Start Guide, you must download the the server and client distribution

To build a binary release from source code, please consult the Developer Guide for instruction.

Installing the GridSAM service

  1. Please ensure the OMII container is not running.
  2. Place the GridSAM-X.Y.Z-server.tar.gz archive in a temporary directory (e.g. /tmp).
  3. Unpack the archive using the GNU tar command.
    $> cd /tmp
    
    $> tar zxvf GridSAM-X.Y.Z-server.tar.gz
    
    $> cd GridSAM-X.Y.Z-server
    
    $> ls -l
    -rw-r--r--    1 wwhl  wwhl      1531 May 26 15:01 LICENCE.txt
    -rw-r--r--    1 wwhl  wwhl      4274 May 27 12:21 build.xml
    drwxr-xr-x    3 wwhl  wwhl       102 May 26 15:01 config
    drwxr-xr-x   43 wwhl  wwhl      1462 May 27 12:26 docs
    -rw-r--r--    1 wwhl  wwhl  16385683 May 27 12:21 gridsam.war
  4. If you have a previous version of GridSAM service installed, you need to first uninstall it using the command:
    $> ant uninstall -Domii.server.home=${OMII_HOME}
  5. To install, execute the installation Ant script,
    $> ant install -Domii.server.home=${OMII_HOME}
  6. Look for the line "BUILD SUCCESSFUL" in the output which indicates the installation has completed successfully.

Installing the GridSAM client

  1. Place the GridSAM-X.Y.Z-client.[tar.gz|zip] archive in a temporary directory (e.g. /tmp).
  2. Unpack the archive using the GNU tar or the zip command.
    $> cd /tmp
    
    $> tar zxvf GridSAM-X.Y.Z-client.tar.gz
    
    (or $> unzip GridSAM-X.Y.Z-client.zip)
    
    $> cd GridSAM-X.Y.Z-client
    
    $> ls -l 
    -rw-r--r--    1 wwhl  wwhl    1531 May 26 15:01 LICENCE.txt
    drwxr-xr-x   12 wwhl  wwhl     408 May 27 12:21 bin
    -rw-r--r--    1 wwhl  wwhl    3098 May 27 12:21 build.xml
    drwxr-xr-x    2 wwhl  wwhl      31 May 27 12:21 conf
    drwxr-xr-x    3 wwhl  wwhl     102 May 26 15:01 data
    drwxr-xr-x   43 wwhl  wwhl    1462 May 27 12:26 docs
    drwxr-xr-x   15 wwhl  wwhl     510 May 27 12:21 lib
  3. If you have a previous version of GridSAM client installed, you need to first uninstall it using the command:
    $> ant uninstall -Domii.client.home=${OMIICLIENT_HOME}
  4. To install, execute the installation Ant script,
    $> ant install -Domii.client.home=${OMII_CLIENT_HOME}
  5. Look for the line "BUILD SUCCESSFUL" in the output which indicates the installation has completed successfully.

Running the GridSAM Service

Restart the OMII container after the installation has completed.

$> cd ${OMII_HOME}
$> ./bin/startomii.sh
Starting up tomcat
Using JRE_HOME:       /user/local/jdk1.5.0_10
Waiting for container....!.. Container started.
$>

The default setup provides local fork launching. Please consult the Deployment Guide for advance configuration instruction.

To verify the GridSAM service is deployed successfully, consult the GridSAM log file $OMII_HOME/tomcat/logs/gridsam.log and look for the lines

...
2005-04-20 09:29:37,394 INFO  [JobManagerConfigurator] (main:) GridSAM machinery initialising...
2005-04-20 09:29:39,189 INFO  [JobManagerConfigurator] (main:) loading module description from classpath jobmanager.xml
2005-04-20 09:29:46,597 INFO  [JobManagerConfigurator] (main:) GridSAM machinery initialised
...

The GridSAM service is initialised correctly if there is no ERROR messages originated from the gridsam webapp in the log file.

You may use the installation test tool to verify the service has been properly deployed

$> cd /tmp/GridSAM-X.Y.Z-server
$> ant test-install -Dtomcat.protocol=${OMII_TOMCAT_PROTOCOL} -Dtomcat.port=${OMII_TOMCAT_PORT}

Default values for OMII_TOMCAT_PROTOCOL is https and for OMII_TOMCAT_PORT is 18443.
(NOTE: the secure version of http, the https, will return an error)

Submitting a Job

Assuming you have access to a GridSAM service (i.e. The OMII container trusts the certificate configured in your OMII Client distribution) and you have been given the URL to a WSDL document describing the remote GridSAM service. You can start submitting jobs to the GridSAM instance.

For example, you have deployed a GridSAM instance on the localhost by following the Quick Start guide. To ensure the service is running, you can use a browser to inspect the WSDL document of the GridSAM instance at https://localhost:18443/gridsam/services/gridsam?WSDL.

Create a Job Submission Description Language (JSDL) document to describe the job you would like to submit, for example

<?xml version="1.0" encoding="UTF-8"?>
<JobDefinition xmlns="http://schemas.ggf.org/jsdl/2005/11/jsdl">
    <JobDescription>
        <Application>
            <POSIXApplication xmlns="http://schemas.ggf.org/jsdl/2005/11/jsdl-posix">
                <Executable>/bin/echo</Executable>
                <Argument>hello world</Argument>
            </POSIXApplication>
        </Application>
    </JobDescription>
</JobDefinition>

The JSDL document describes a POSIX job, which executes the /bin/echo executable with the argument "hello world". Save this file to a directory of your choosing (e.g. $HOME/helloworld.jsdl).

To submit the job to a GridSAM instance, you can use the command gridsam-submit

Tip: The gridsam-* commands are installed in gridsam/bin inside the OMII Client distribution. Add the directory to your PATH environment, so that the gridsam-* commands are available to your shell.

$> ${OMIICLIENT_HOME}/gridsam/bin/gridsam-submit -help
usage: gridsam-submit [options] path-to-jsdl
GridSAM Job Submission Client
 -j <path-to-jsdl>               path to the JSDL file
 -myproxy                        enable myproxy
 -myproxyhost <hostname>         hostname of the MyProxy server
 -myproxypassword                password to access the MyProxy
                                 credential. The user will be prompted if the value is omitted.
 -myproxyport <port-number>      port of the MyProxy server. If omitted,
                                 default to 7512
 -myproxyuser <username>         username of the MyProxy credential. If
                                 omitted, the system property user.name is used.
 -s <service-endpoint-address>   The endpoint address of the GridSAM
                                 service
 -sn <service-name>              Logical name of the GridSAM service
                                 defined in ~/.gridsam/services.properties
                    
                
$> ${OMIICLIENT_HOME}/gridsam/bin/gridsam-submit -s "https://localhost:18443/gridsam/services/gridsam" ${HOME}/helloworld.jsdl

urn:gridsam:ff80808201afccc00101afccc3900001

The gridsam-submit command writes the job identifier ('urn:gridsam:ff80808201afccc00101afccc3900001' in the example above) to the standard output upon successful submission. The job identifier can then be used to obtain status or control the execution of the submitted job.

Monitoring a Job

Given a GridSAM job identifier, the user who submitted the job (i.e.. identified by the certificate configured in the OMII client installation) can use the gridsam-status command to query the state of the job.

$> ${OMIICLIENT_HOME}/gridsam/bin/gridsam-status -help
usage: gridsam-status [-s service-endpoint-address | -sn service-name] [-j job-id]
                      [-o omii-conf-dir] [-xml] [-wssec on | off] job-id
GridSAM Job Status Client
 -j <job-id>                     ID of the job to be queried
 -s <service-endpoint-address>   The endpoint address of the GridSAM
                                 service
 -sn <service-name>              Logical name of the GridSAM service
                                 defined in ~/.gridsam/services.properties
 -x                              display job status as GridSAM JobStatus
                                 XML


$> ${OMIICLIENT_HOME}/gridsam/bin/gridsam-status -s "http://localhost:18080/gridsam/services/gridsam" \
    -j urn:gridsam:ff80808201afccc00101afccc3900001

Job Progress: pending -> staging-in -> staged-in -> active -> executed -> staging-out -> staged-out -> done

-- pending - 2005-01-26T16:13:47+00:00 --
job is being scheduled
-- staging-in - 2005-01-26T16:13:47+00:00 --
Staging files...
-- staged-in - 2005-01-26T16:13:47+00:00 ---
0 files staged in
-- active - 2005-01-26T16:13:48+00:00 --
'/bin/echo hello world' is being forked
-- executed - 2005-01-26T16:13:48+00:00 --
'/bin/echo hello world' completed with exit code 0
-- staging-out - 2005-01-26T16:13:48+00:00 --
Staging files out...
-- staged-out - 2005-01-26T16:13:48+00:00 --
0 files staged out
-- done - 2005-01-26T16:13:48+00:00 --
Job completed

**************
Job Properties
**************
urn:gridsam:exitcode=0

The gridsam-status command displays the progress and properties associated with a job previously submitted to the GridSAM instance identified by the -j parameter.

To retrieve a machine-parsable output, use the -x parameter to instruct the command to display the job status as a JobStatus/ XML document.

$> ${OMIICLIENT_HOME}/gridsam/bin/gridsam-status -s "http://localhost:18080/gridsam/services/gridsam" \
        -x urn:gridsam:ff80808201afccc00101afccc3900001

<?xml version="1.0" encoding="UTF-8"?>
<ns1:JobStatus xmlns:ns1="http://www.icenigrid.org/service/gridsam">
  <ns1:Stage>
    <ns1:State>pending</ns1:State>
    <ns1:Description>job is being scheduled</ns1:Description>
    <ns1:Time>2005-01-26T16:13:47+00:00</ns1:Time>
  </ns1:Stage>
  <ns1:Stage>
    <ns1:State>staging-in</ns1:State>
    <ns1:Description>Staging files...</ns1:Description>
    <ns1:Time>2005-01-26T16:13:47+00:00</ns1:Time>
  </ns1:Stage>
  <ns1:Stage>
    <ns1:State>staged-in</ns1:State>
    <ns1:Description>0 files staged in</ns1:Description>
    <ns1:Time>2005-01-26T16:13:47+00:00</ns1:Time>
  </ns1:Stage>
  <ns1:Stage>
    <ns1:State>active</ns1:State>
    <ns1:Description>'/bin/echo hello world' is being forked</ns1:Description>
    <ns1:Time>2005-01-26T16:13:48+00:00</ns1:Time>
  </ns1:Stage>
  <ns1:Stage>
    <ns1:State>executed</ns1:State>
    <ns1:Description>'/bin/echo hello world' completed with exit code 0</ns1:Description>
    <ns1:Time>2005-01-26T16:13:48+00:00</ns1:Time>
  </ns1:Stage>
  <ns1:Stage>
    <ns1:State>staging-out</ns1:State>
    <ns1:Description>Staging files out...</ns1:Description>
    <ns1:Time>2005-01-26T16:13:48+00:00</ns1:Time>
  </ns1:Stage>
  <ns1:Stage>
    <ns1:State>staged-out</ns1:State>
    <ns1:Description>0 files staged out</ns1:Description>
    <ns1:Time>2005-01-26T16:13:48+00:00</ns1:Time>
  </ns1:Stage>
  <ns1:Stage>
    <ns1:State>done</ns1:State>
    <ns1:Description>Job completed</ns1:Description>
    <ns1:Time>2005-01-26T16:13:48+00:00</ns1:Time>
  </ns1:Stage>
  <ns1:Property name="urn:gridsam:exitcode">0</ns1:Property>
</ns1:JobStatus>

Terminating a Job

Given a GridSAM job identifier, the user who submitted the job (i.e.. identified by the certificate configured in the OMII client installation) can use the gridsam-terminate command to terminate a running job.

$> ${OMIICLIENT_HOME}/gridsam/bin/gridsam-terminate -s "http://localhost:18080/gridsam/services/gridsam" \
        urn:gridsam:ff80808201afccc00101afccc3900001

Job termination in GridSAM happens asynchronously. You can use the gridsam-status command to determine whether the job has been completely terminated.

Advance Job Submission

File Staging

A job usually involves data files that need to be staged into the remote job execution environment and staged out at the end of the execution.

The GridSAM service supports a variety of data staging methods (e.g. FTP, SFTP, GridFTP, WebDAV, HTTP(read only) ). For unsecured usage, the GridSAM distribution bundles a small anonymous FTP server for users to stage files in/out from the machine they are executing the gridsam-submit command.

WARNING: Please ensure you understand the security implication of FTP before considering using this mode of data staging. You are potentially opening up your file system for remote anonymous access by using the gridsam-ftp-server command.

For example, the following JSDL document describes a job that runs the /bin/cat executable on the virtual files dir1/file1.txt and dir2/subdir1/file2.txt made available by the GridSAM service by staging in the files from http:// and ftp:// sources respectively. The standard output and standard error streams of the application are written to the virtual files stdout.txt and stderr.txt. The virtual file stdout.txt will be staged out to the ftp:// target upon successful execution of the job.

<JobDefinition xmlns="http://schemas.ggf.org/jsdl/2005/11/jsdl">
    <JobDescription>
        <Application>
            <POSIXApplication xmlns="http://schemas.ggf.org/jsdl/2005/11/jsdl-posix">
                <Executable>/bin/cat</Executable>
                <Argument>dir1/file1.txt dir2/subdir1/file2.txt</Argument>
                <Output>stdout.txt</Output>
                <Error>stderr.txt</Error>
            </POSIXApplication>
        </Application>
        <DataStaging>
            <FileName>dir1/file1.txt</FileName>
            <CreationFlag >overwrite</CreationFlag>
            <Source>
                <URI>http://www.doc.ic.ac.uk/~wwhl/download/helloworld.txt</URI>
            </Source>
        </DataStaging>
        <DataStaging>
            <FileName>dir2/subdir1/file2.txt</FileName>
            <CreationFlag>overwrite</CreationFlag>
            <Source>
                <URI>ftp://anonymous@myhost:19245/input/file.txt</URI>
            </Source>
        </DataStaging>
        <DataStaging>
            <FileName>stdout.txt</FileName>
            <CreationFlag>overwrite</CreationFlag>
            <Target>
                <URI>ftp://anonymous@myhost:19245/output/file.txt</URI>
            </Target>
        </DataStaging>
    </JobDescription>
</JobDefinition>

To use the gridsam-ftp-server command to serve files in the directory /my/datastaging/directory through anonymous FTP,

$> ${OMIICLIENT_HOME}/gridsam/bin/gridsam-ftp-server
    2005-04-20 09:44:29,701 FATAL [GridSAMFTPServer] (main:) Invalid command-line options: -p-d
    usage: gridsam-ftp-server: GridSAM Anonymous FTP Server
     -d <dir>    Root Directory
     -l          Server only available to localhost
     -p <port>   FTP Port

                
$> ${OMIICLIENT_HOME}/gridsam/bin/gridsam-ftp-server -d /tmp/datastaging/directory -p 19245
2005-01-26 17:00:51,958 WARN  [GridSAMFTPServer] (main:) . is exposed through FTP at ftp://anonymous@127.0.0.2:19245/
2005-01-26 17:00:51,963 WARN  [GridSAMFTPServer] (main:) Please make sure you understand the security implication of using anonymous FTP for file staging.
FtpServer.server.config.root.dir = /my/datastaging/directory
FtpServer.server.config.data = /home/testuser/.gridsam/ftp-19106c7:101aff7dd50:-8000
FtpServer.server.config.server.host = myhost.somedomain.net
FtpServer.server.config.port = 19245
Started FTP

The directory /my/datastaging/directory would be exposed as the root directory of the FTP server accessible on the running host at port 19245. It can be accessed with any FTP client, for example on UNIX

$> ftp myhost.somedomain.net 19245
Connected to myhost.somedomain.net.
220 Service ready for new user
Name (myhost.somedomain.net:yourname): anonymous
331 Guest login ok, send your complete e-mail address as password
Password:
230 User logged in, proceed
Remote system type is UNIX.
ftp>

For testing purpose on the same host, you can use the -l parameter to instruct the command to make the FTP server only available to the localhost, otherwise the server would be bounded to the public network interface of the host.

GridFTP File Staging and MyProxy

GridSAM supports GridFTP file transfer (gsiftp://) and GRAM submission. In order to delegate the identity of the user to the GridSAM server, a JSDL extension is introduced in GridSAM to allow a MyProxy credential to be retrieved and used by GridSAM to act on behalf of the user.

User can add the myproxy:MyProxy/ element into the JSDL manually (jsdl:JobDefinition/myproxy:MyProxy), for example

<?xml version="1.0" encoding="UTF-8"?>
<JobDefinition xmlns="http://schemas.ggf.org/jsdl/2005/11/jsdl">
    <JobDescription>
        <POSIXApplication xmlns="http://schemas.ggf.org/jsdl/2005/11/jsdl-posix">
            <Executable>/bin/echo</Executable>
            <Argument>hello world</Argument>
        </POSIXApplication>
    </JobDescription>
    <MyProxy xmlns="urn:gridsam:myproxy">
        <ProxyServer>myproxy.ncsa.uiuc.edu</ProxyServer>
        <ProxyServerDN>/C=US/O=National Center for Supercomputing Applications/CN=bosco.ncsa.uiuc.edu</ProxyServerDN>
        <ProxyServerPort>7512</ProxyServerPort>
        <ProxyServerUserName>myusername</ProxyServerUserName>
        <ProxyServerPassPhrase>mypassphrase</ProxyServerPassPhrase>
        <ProxyServerLifetime>7512</ProxyServerLifetime>
    </MyProxy>
</JobDefinition>

Or let the command-line tool to do the hard work

$> ${OMIICLIENT_HOME}/gridsam/bin/gridsam-submit -sn ngs \
        -myproxy -myproxyuser myusername -myproxyhost myproxy.ncsa.uiuc.edu \
        -j ${HOME}/helloworld.jsdl
MyProxy passphrase: ********

urn:gridsam:ff80808201afccc00101afccc3900001

The credential will be used by the GridSAM service when a GridFTP file staging or a Globus GRAM submission is requested.

MPI Application

GridSAM has implemented a non-standard JSDL extension for executing MPI application. To submit a MPI application, your JSDL needs to specify an mpi:MPIApplication element similar to the jsdl-posix:POSIXApplication.

<JobDefinition xmlns="http://schemas.ggf.org/jsdl/2005/11/jsdl">
    <JobDescription>
        <Application>
            <mpi:MPIApplication xmlns="http://schemas.ggf.org/jsdl/2005/11/jsdl-posix" xmlns:mpi="urn:gridsam:mpi">
                <Executable>/usr/local/applications/chemistry/dlpoly_3.01/DLPOLY.Y</Executable>
                <Output>stdout.txt</Output>
                <Environment name="NGSMODULES">gm:dlpoly:intel-math</Environment>
                <mpi:ProcessorCount>8</mpi:ProcessorCount>
            </mpi:MPIApplication>
        </Application>
        <DataStaging>
            <FileName>stdout.txt</FileName>
            <CreationFlag>overwrite</CreationFlag>
            <DeleteOnTermination>true</DeleteOnTermination>
            <Target>
                <URI>ftp://gridsam.lesc.doc.ic.ac.uk:45521/public/test.txt</URI>
            </Target>
        </DataStaging>
    </JobDescription>
</JobDefinition>

The mpi:MPIApplication element is an extension to the standard jsdl-posix:POSIXApplication element. The mpi:ProcessorCount element specifies the number of processors to be used by the application. Here's an example to execute the DLPOLY application on the National Grid Service. MPI support is currently only implemented by the Globus 2.4.3 plugin. Please consult your service administrator to see whether MPI is supported.

Frequently used GridSAM Services

For most gridsam-* command, the user needs to specify the URL to the WSDL document describing the location of the GridSAM service to be used. This is cumbersome to remember and type.

GridSAM clients allow user to specify the service by name by storing frequently used service locations in a properties file.

Create a directory .gridsam in the user's home directory

$> mkdir ~/.gridsam

Create a file named services.properties in the directory you have just created. The content of the file contains a list of name-value pairs. The value being the endpoint address (URI) of the the GridSAM service. For example

imperial=http://www.ic.ac.uk/gridsam/services/gridsam
ngs=http://www.ngs.ac.uk/gridsam/services/gridsam

Once the entries are defined, user can refer to the service by name. For example, to use the Imperial GridSAM service,

$> ${OMIICLIENT_HOME}/gridsam/bin/gridsam-submit -sn imperial uname.jsdl

Switch to PBS DRM Connector

Since version 2.1.0, GridSAM supports resource managers including OpenPBS/Torque/PBSPro and LSF. These resource managers are supported by a new PBSDRMConnector. Make sure you have successfully installed OpenPBS/Torque (you can use qsub and qstat to verify that this has been completed successfully). In this quickstart guide, and to simplify configuration, it has been assumed that the GridSAM server is installed in the head node of the cluster. Configure GridSAM to use the PBSDRMConnector.

  $> vi ${OMII_HOME}/apache-tomcat-5.5.23/webapps/gridsam/WEB-INF/classes/jobmanager.xml

Find the following line in the jobmanager.xml

  <sub-module descriptor="jobmanager-fork.xml"/>

And, to use PBSDRMConnector, change the value jobmanager-fork.xml to jobmanager-gos.xml. Configure the PBSDRMConnector, if necessary. Make sure there is a default job queue in OpenPBS/Torque called default, or change the defaultQueueName in configuration file batch_config.xml accordingly.

  $> vi ${OMII_HOME}/apache-tomcat-5.5.23/webapps/gridsam/WEB-INF/classes/batch_config.xml

Restart the GridsSAM server.

  $> cd ${OMII_HOME}/bin
  $> ./stopomii.sh
  $> ./startomii.sh

Enable security features

GridSAM supports two security features, called pool accounts and private working directory, since version 2.1.0. Pool accounts maps global user DNs to local user accounts in Operating Systems. With pool accounts, each global user submits jobs with a different local user account, so that different users' applications can be isolated to prevent conflict. It also makes it easier for resource managers to perform resource-consumption accounting for different users. Private working directory allows each user to have their own working directories, which are accessible only to themselves. This means that a user's input files, temporary files, and output files can be kept confidential. Currently, the two security features discussed above are only supported by PBSDRMConnector, which connects OpenPBS/Torque/PBSPro and LSF. To enable the security features, switch to PBSDRMConnector and enable the security features through the root account. Switch to root account.

  $> su -

Enable the security features.

  $> cd gridsam-server
  $> ant enableSecurity -Domii.server.home=${OMII_HOME} -Dtomcat.home=${OMII_HOME}/apache-tomcat-5.5.23

Look for the line

  BUILD SUCCESSFUL

in the output which indicates the security features have been enabled successfully. Configure the user mapping. The administrator of the GridSAM server should config a user mapping for each user DN.

  $> vi ${OMII_HOME}/apache-tomcat-5.5.23/webapps/gridsam/WEB-INF/classes/usermap_config.xml

The usermap_config.xml has many items each for a user mapping. The following is an example item for user gos.

  <item id="OU=gos, O=OMII, EMAILADDRESS=support@cngrid.org, C=UK, ST=Soton, CN=omiitest11.omii.ac.uk">
    <localUN>gos</localUN>
    <homeDir>/home/gos/workdir</homeDir>
  </item>

The id indicates the user DN, the localUN is the local user account, and the homeDir is the parent directory of all working directories of this user. The keytool can be used to get the user DN of a client user from a certification or keystore.

  $> keytool -printcert -file omii.crt -v
  $> keytool -list -keystore omii.ks -v

Decide the policy for users without user mapping. After enabling the security features, it is necessary to decide the policy for users without user mapping. By default, global users must has a user mapping to submit jobs. If you want to allow users without user mapping to submit jobs using their OMII-UK server account, open the security_config.xml file and change the configuration value of forceUserMapping to false.

  $> vi ${OMII_HOME}/apache-tomcat-5.5.23/webapps/gridsam/WEB-INF/classes/security_config.xml

File Stage Configuration

After installation of PBS/LSF, we provide Reliable Asynchronous File Stage-in/Stage-out as a default configuration. Make sure you have successfully installed GridSAM and enabled the PBSDRMConnector. Configure the filejob_config.xml

  $> vi ${OMII_HOME}/apache-tomcat-5.5.23/webapps/gridsam/WEB-INF/classes/ filejob_config.xml

Each protocol has been configured with 10 times retry and 10 second delay between the retry as the default configuration except local file operation. You can also modify the configuration of local file operation to support retry mechanism.

  org.icenigrid.gridsam.core.plugin.transfer.http.delay
  org.icenigrid.gridsam.core.plugin.transfer.http.retry
  org.icenigrid.gridsam.core.plugin.transfer.ftp.delay
  org.icenigrid.gridsam.core.plugin.transfer.ftp.retry
  org.icenigrid.gridsam.core.plugin.transfer.sftp.delay
  org.icenigrid.gridsam.core.plugin.transfer.sftp.retry
  org.icenigrid.gridsam.core.plugin.transfer.gsiftp.delay
  org.icenigrid.gridsam.core.plugin.transfer.gsiftp.retry
  org.icenigrid.gridsam.core.plugin.transfer.https.delay
  org.icenigrid.gridsam.core.plugin.transfer.https.retry
  org.icenigrid.gridsam.core.plugin.transfer.webdav.delay
  org.icenigrid.gridsam.core.plugin.transfer.webdav.retry
  org.icenigrid.gridsam.core.plugin.transfer.local.delay
  org.icenigrid.gridsam.core.plugin.transfer.local.retry

Restart the gridsam server.

  $> cd ${OMII_HOME}/bin
  $> ./stopomii.sh
  $> ./startomii.sh

Shutting down GridSAM

GridSAM persists and restarts unfinished job upon container restarts. However, it is still wise to shutdown the container gracefully.

$> cd ${OMII_HOME}
$> ./bin/stopomii.sh
Shutting down tomcat
Server running under PID of 17171 detected
Waiting....!.... HTTP server stopped.
Waiting Process stopped.

You should see a message in the GridSAM log file, $OMII_HOME/tomcat/logs/gridsam.log, similar to:

..
2008-06-21 17:28:01,454 INFO  [GridSAMService] service shutdown complete
2008-06-21 17:28:01,745 INFO  [ForkDRMConnectorManager] ForkDRMConnectorManager shutdown complete
2008-06-21 17:28:01,746 INFO  [JobManagerConfigurator] GridSAM machinery shutdown properly
..

What next?

By now, You should have successfully deployed the GridSAM Web Service that uses the Fork DRMConnector for launching jobs. You should have successfully submitted a simple job to a GridSAM instance and monitored the state change of a job using the GridSAM tools.

If you will be administering a GridSAM Web Service, you are advised to consult the Deployment Guide in the GridSAM Service module to configure the GridSAM service for production usage according to your architectural requirement and backend infrastructure.

If you are an end-user of a GridSAM Web Service, you are advised to read through the Job Submission Description Language specification to understand the features of the language. Also, you should study the GridSAM JSDL feature matrix} to understand what you can/cannot do with the current GridSAM implementations. You can find more information on the GridSAM client-side tools in the {{{gridsam-client/userguide.html}User Guide in the GridSAM Client module.