Name
globusrun-ws — Official job submission client for WS GRAM
Synopsis
globusrun-ws -submit [-batch] [-quiet] [-no-cleanup] [-streaming] [-streaming-out filename] [-streaming-err filename] [-host-authz] [-self-authz] [-subject-authz subject name] [-private] [-http-timeout milliseconds] [-debug] [-allow-ipv6] [-passive] [-nodcau] [[-factory-epr-file filename] [[-factory contact] | [-factory-type type]]] [[-submission-id uuid] | [-submission-id-file filename]] [-submission-id-output-file filename] [-job-epr-output-file filename] [-job-delegate] [-staging-delegate] [-job-credential-file filename] [-staging-credential-file filename] [-transfer-credential-file filename] [-termination
[+HH:MMmm/dd/yyyy HH:MM]
] [[-job-description-file filename] | [-job-command [--] program arg ...]]
globusrun-ws -validate -job-description-file filename
globusrun-ws -monitor -job-epr-file filename [-quiet] [-no-cleanup] [-streaming] [-streaming-out filename] [-streaming-err filename] [-host-authz] [-self-authz] [-subject-authz subject name] [-private] [-http-timeout milliseconds] [-debug] [-allow-ipv6] [-passive] [-nodcau]
globusrun-ws -status -job-epr-file filename [-host-authz] [-self-authz] [-subject-authz subject name] [-private] [-http-timeout milliseconds] [-debug]
globusrun-ws -kill -job-epr-file filename [-host-authz] [-self-authz] [-subject-authz subject name] [-private] [-http-timeout milliseconds] [-debug]
globusrun-ws -help
globusrun-ws -usage [-submit] [-validate] [-monitor] [-status] [-kill]
globusrun-ws -version(s)
Description
globusrun-ws (WS GRAMclient) is a program for submitting and
managing jobs to a local or remote job host. WS GRAMprovides secure
job submission to many types of job scheduler for users who have the
right to access a job hosting resource in a Grid environment. All
WS GRAMsubmission options are supported transparently through the
embedded request document input. globusrun-ws offers
additional features to fetch job output files incrementally during the
run as well as to automatically delegate credentials needed for
certain optional WS GRAMfeatures. Online and batch submission modes
are supported with reattachment (recovery) for jobs whether they were
started with this client or another WS GRAMclient application.
Command options
Quiet mode
A variety of protocol status messages, warning messages, and output data may be printed to standard output and error under multiple command modes. The quiet mode suppresses all but fatal standard error messages in order to have clean outputs for use in scripting or with the streaming output mode where application output is retrieved and output.
- -q, -quiet
If supplied, all non-fatal status and protocol-related messages are suppressed.
Debug mode
- -dbg, -debug
If supplied, all soap messages and ftp control messages will be displayed on stderr.
Protocol Options
Service authorization
Usually, secure communication includes mutual authentication. In addition to the service authorizing the client for the requested operation(s), an authorization decision is made by the client to determine whether the remote service is the one intended.
- -host, -host-authz
The GSI "host authorization" rule is used to verify that the service is using a host credential appropriate for the underlying service address information. This is the default.
- -self, -self-authz
The GSI "self authorization" rule is used to verify that the service is using a (proxy) credential derived from the same identity as the client's.
- -subject, -subject-authz subject name
The service must be using a credential with the exact subject name provided by this option.
Security Protocol
The client uses secure transport for all https endpoints and secure message for http. Secure conversation is currently unsupported.
- -p, -private
If supplied, privacy-protection is enabled between globusrun-ws and WS GRAMor GridFTP services. It is a fatal error to select privacy protection if it is not available due to build options or other security settings. Note: Currently only supported with https endpoints.
Signal handling
- -n, -no-cleanup
If supplied, the default behavior of trapping interrupts (SIG_INTR) and cancelling the job is disabled. Instead, the interrupt simply causes the tool to exit without affecting the ManagedJob resource.
Submit options
- -submit
The -submit command submits (or resubmits) a job to a job host using an XML-based job description document. The -submit command can submit jobs in one of three output modes: batch, interactive, or interactive-streaming.
Output Mode
The user can select several tool behaviors following submission. In batch mode, the tool prints the resulting ManagedJob EPR as the sole standard output (unless in quiet mode) and exits. In interactive mode, the tool keeps running in order to monitor job status. Interactive mode is qualitatively equivalent to a batch-mode submission immediately followed a second invocation of globusrun-ws using the -monitor command. In interactive mode, an optional streaming mode where job output files are fetched and output from globusrun-ws.
- -b, -batch
If supplied, the batch mode is enabled. The default is interactive mode. The tool prints the resulting ManagedJob EPR as the sole standard output (unless in quiet mode) and exits.
- -s, -streaming
The standard output and standard error files of the job are monitored and data is written to the corresponding output of globusrun-ws. The standard output will contain ONLY job output data, while the standard error may be a mixture of job error output as well as globusrun-ws messages, unless the quiet mode is also enabled.
Streaming output depends on the ability to access job outputs via GridFTP. If -streaming mode is selected and the job description does not already specify output file redirection for the job host, then globusrun-ws adds unique output file name redirections and automatic cleanup directives to the job description.
If you are using -batch mode, but intend to use -streaming with -monitor, you may want to still include -streaming. -streaming always introduces a 'CleanUp Hold' state which ensures that all the data is streamed before the files are destroyed. If you do use -streaming with -batch, you must come back with -monitor so the hold can be released.
This option implies -staging-delegate if the stdout and stderr entries are not specified in the job description.
- -so, -stdout-file filename
append stdout out stream to the specified file instead of to stdout.
- -se, -stderr-file filename
append stderr out stream to the specified file instead of to stderr.
Streaming Options
Streaming makes use of GridFTP client calls to retrieve user data. The following options apply to such transfers.
- -ipv6, -allow-ipv6
Allow streaming transfers to use IPV6.
- -passive
Force streaming transfers to use MODE S to allow for passive mode transfers. (Useful if you're behind a firewall, but expensive because there is no connection caching).
- -nodcau
Disable data channel authentication on streaming transfers
Factory information
Addressing information for the ManagedJobFactory target of this submission must be provided. If neither option is specified, and no EPR is supplied in the job description, then "-factory localhost -factory-type fork" is assumed.
- -Ff, -factory-epr-file filename
If supplied, this option causes the EPR for the ManagedJobFactory to be read from the given file. This EPR is used as the service endpoint for submission of the job.
- -F, -factory contact
If supplied, this option causes an EPR to be constructed using ad-hoc methods that depend on GT implementation details. For interoperability to other implementations of WS_GRAM, the -factory-epr-file option should be used instead.
[protocol://]{hostname|hostaddr}[:port][/service]
Default values form the following contact information if not overridden:
https://localhost:8443/wsrf/services/ManagedJobFactoryService
- -Ft, -factory-type type
In the absence of -factory-epr-file, this option refines the behavior of the -factory option to select a specific type of scheduler. The default is "Fork" for single jobs and "Multi" for multijobs.
Job description
A description of the job to be submitted must be provided with the -submit command, either using the WS GRAMXML description syntax or a simpler Unix command and argument list.
- -f, -job-description-file filename
If supplied, this option causes the job description to be read from the given file. This description is modified according to the other options and passed in the WS GRAMsubmission messages. The root element of this file must be 'job' for a single job or 'multiJob' for a multijob.
- -c, -job-command [--] prog [arg ...]
If supplied, this option take all remaining globusrun-ws arguments as its arguments; therefore it must appear last among globusrun-ws options. This option causes globusrun-ws to generate a simple job description with the named program and arguments.
Submission ID
A submission ID may be used in the WS GRAMprotocol for robust reliability in the face of message faults or other transient errors to ensure that at most one instance of a job is executed, i.e. to prevent accidental duplication of jobs under rare circumstances with client retry on failure. The globusrun-ws tool always uses this feature, requiring either a submission ID to be passed in as input or a new unique ID to be created by the tool itself. If a new ID is created, it should be captured by the user who wishes to exploit this reliability interface. The ID in use, whether created or passed as input, will be written to the optional output file when provided, as well as to the standard error output unless the quiet mode is in effect.
If a user is unsure whether a job was submitted successfully, he should resubmit using the same ID as was used for the previous attempt.
- -I, -submission-id ID
If supplied, this option causes the job to be submitted using the given ID in the reliability protocol.
- -If, -submission-id-file filename
If supplied, this option causes the ID to be read from the given file. It is an error to use both mechanisms to provide an input ID.
- -Io, -submission-id-output-file filename
If supplied, the ID in use is written to the given file, whether this ID was provided by the user or given by one of the above input options.
Job EPR output
A successful submission will create a new ManagedJob resource with its own unique EPR for messaging. The globusrun-ws tool will output this EPR to a file when requested and as the sole standard output when running in batch mode. When running in streaming output mode, it is possible that the EPR will not be output and the user's only recourse is to submit again with the same submission ID and job request in order to reattach to the existing job.
- -o, -job-epr-output-file filename
If supplied, the created ManagedJob EPR will be written to the given file following successful submission. The file will not be written if the submission fails.
Delegation
The job description supports the optional identification of delegated credentials for use by the WS GRAMservices. These features are passed through globusrun-ws without modification. However, globusrun-ws can also perform delegation and construct these optional request elements before submitting it to the service. The only delegation performed by default (if an endpoint does not already exist) is the multijob level jobCredential.
- -J, -job-delegate
If supplied AND the job description does not already provide a jobCredential element, globusrun-ws will delegate the client credential to WS GRAMand introduce the corresponding element to the submission input.
- -S, -staging-delegate
If supplied AND the job description does include staging or cleanup directives AND the job description does not already provide the necessary stagingCredential or transferCredential element(s), globusrun-ws will delegate the client credential to WS GRAM and RFT, and introduce the corresponding elements to the submission input.
This option is implied by -streaming
- -Jf, -job-credential-file filename:
If supplied AND the job description does not already provide a jobCredential element, globusrun-ws will copy the supplied epr into the job description. This should be an epr returned from the DelegationFactoryService intended for use by the job (or, in the case of a multijob, for authenticating to the subjobs).
note: for multijob descriptions, only the top level jobCredential will be copied into.
- -Sf, -staging-credential-file filename:
If supplied AND the job description does not already provide a stagingCredential element, globusrun-ws will copy the supplied epr into the job description. This should be an epr returned from the DelegationFactoryService intended for use with the RFT service associated with the ManagedJobService.
note: this option is ignored for multijobs.
- -Tf, -transfer-credential-file filename:
If supplied, globusrun-ws will copy the epr into each of the stage in, stage out, and cleanup elements that do not already contain a transferCredential element. This should be an epr returned from the DelegationFactoryService intended for use by RFT to authenticate with the target gridftp server.
note: this option is ignored for multijobs.
Lifetime
The ManagedJob resource supports lifetime management in the form of a scheduled destruction. The default lifetime requested by the client is infinite, subject to server policies.
- -term, -termination mm/dd/yyyy HH:MM
Set an absolute termination time.
- -term, -termination +HH:MM
Set a termination time relative to the successful creation of the job. The default is +24:00
Validate options
- -validate
The -validate command checks the job description for syntax errors and a subset of semantic errors without making any service requests.
Monitor options
- -monitor
The -monitor command attaches to an existing job in interactive or interactive-streaming output modes.
Status options
- -status
The -status command reports the current state of the job and exits. See the External States of the Managed Job Services section of the developer guid for information on valid job states.
See the Job options for the -monitor command.
Job Handling
For every job that globusrun-ws delegates a credential, globusrun will augment the user's job description, adding annotations that will later tell globusrun-ws to destroy the credential after the job has been destroyed. Below are 2 job annotation examples. globusrun-ws only delegated the job cred...
<extensions>
<globusrunAnnotation>
<automaticJobDelegation>true</automaticJobDelegation>
<automaticStagingDelegation>false</automaticStagingDelegation>
<automaticStageInDelegation>false</automaticStageInDelegation>
<automaticStageOutDelegation>false</automaticStageOutDelegation>
<automaticCleanUpDelegation>false</automaticCleanUpDelegation>
</globusrunAnnotation>
</extensions>
globusrun-ws delegated the job, staging and stage in cred...
<extensions>
<globusrunAnnotation>
<automaticJobDelegation>true</automaticJobDelegation>
<automaticStagingDelegation>true</automaticStagingDelegation>
<automaticStageInDelegation>true</automaticStageInDelegation>
<automaticStageOutDelegation>false</automaticStageOutDelegation>
<automaticCleanUpDelegation>false</automaticCleanUpDelegation>
</globusrunAnnotation>
</extensions>