Using GramClient.exe

 

A command line GRAM client (GramClient.exe) is included in the Bin directory where GRAM was installed.  In order to use the client, the first step is to import a client certificate into the certificate store.

 

The command line client is similar in syntax and options to the GT4 GRAM client globusrun-ws. It supports two basic modes of operation, batch and interactive. Batch mode will submit a job and immediately exit, providing you with a job EPR you can later use to query for the job’s status or kill it. Interactive mode will wait for the job to complete (or terminate due to failure) before returning control to the user and will display job state change notification messages. For batch mode, a client certificate DN or file can be specified on the command line, if one is not specified, a Certificate Selection Dialog box will allow you to interactively choose a client certificate from the certificate store.

 

Command Line Options

GramClient.exe /help | /version

GramClient.exe [/submit | /status | /kill] <other options (see below)>

 

/help                        Prints out a help/usage message indicating all the command line options

/version                Displays the current program version

 

Modes of operation:

/submit       Submits (or resubmits) a job to a job host in one of two output modes:

batch (/batch) or interactive (default).

/status       Reports the current state of the job and exits. Requires specification of a job EPR (/j option)

/kill         Requests the immediate cancellation of the job and exits.

Requires specification of a job EPR (/j option)

 

Other Options

/F:<contact>

/factory:<contact>

This option specifies the EPR of the job factory service that will be used to create the job.

Format: [protocol://]{hostname|hostaddr}[:port][/service]

Default: https://localhost:8443/wsrf/services/ManagedJobFactoryService

/Ft:<type>

/factoryType:<type>

In the absence of /factory-epr-file, this specifies a type of scheduler.

Default: 'Fork' for single jobs and 'Multi' for multijobs

/Ff:<filename>

/factoryEprFile:<filename>

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:<filename>

/jobDescriptionFile:<filename>

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_GRAM submission messages.

/c:"<program> [args ...]"

/jobCommand:"<program> [args]"

This option causes GramClient to generate a simple job description with the named program and arguments.

/o:<filename>

/jobEprOutputFile:<filename>

The created ManagedJob EPR will be written to the indicated file following successful submission. The file will not be written if the submission fails.

/j:<filename>

/jobEprFile:<filename>

Causes the EPR for the ManagedJob to be read from the given file. This EPR is used as the endpoint for service requests.

/so:<filename>

/stdoutFile:<filename>

Append standard output stream to the specified file instead of to stdout.

/se:<filename>

/stderrFile:<filename>

Append standard error stream to the specified file instead of to stderr.

/b, /batch

Enables batch mode. the tool prints the resulting ManagedJob EPR as the sole standard output (unless in quiet mode) and exits.

/q, /quiet

All non-fatal status and protocol-related messages are suppressed.

/cert:<CN=...>

/clientCertDn:<CN=...>

Indicate the DN of the certificate to be used for client authentication. Will be loaded from the Current User/Personal certificate store. The certificate must have an associated private key. This argument is optional - if omitted, the desired client certificate can be selected using the Certificate Dialog.

/cf:<filename>

/clientCertFile:<filename>

The path to a DER (PEM) encoded file containing a certificate to be used for client authentication. The file must also contain a private key. This is an alternative to using a certificate in the Certificate Store.

/sig, /signMessages

Forces the inclusion of an XML signature even if transport level security (https) is also used. This option is required when submitting a job to a GRAM.NET service.

/term:+<HH:MM>|<mm/dd/yyyy HH:MM>

/termination:+<HH:MM>

             |<mm/dd/yyyy HH:MM>

Set a termination time for the job (+relative to now).

Default: +24:00

/dbg, /debug

Display message and debug output on stderr.

 

Example Usage:

 

The following command remotely executes “/bin/hostname” on a Unix host running a GRAM service. The GramClient will be “interactive mode” and therefore wait until the job has completed before returning.

 

GramClient.exe /submit /F:https://myGT4host.com:8443/wsrf/services/ManagedJobFactoryService /c:”/bin/hostname”

 

The following submits the command “c:\Windows\System32\qprocess.exe” in batch mode (this command only works on Windows hosts running the GRAM service). The job’s EPR is saved to the file “jobEPR”. Note that the /sig options is required when submitting to a GRAM.NET service.

 

GramClient.exe /submit /F:https://myGRAMdotNetHost.com:443/ManagedJobFactoryService.asmx /c:”c:\windows\system32\qprocess.exe” /sig /batch /o:jobEPR

 

The following submits the job described by the file “job.xml” to the job factory service at https://myGT4host.com:8443/wsrf/services/ManagedJobFactoryService. This job will be submitted in batch mode and use the certificate identified when submitting the job.

 

GramClient.exe /submit /F:https://myGT4host.com:8443/wsrf/services/ManagedJobFactoryService /f:job.xml /cert:

“CN=Glenn S. Wasson 4, E=gsw2c@virginia.edu, OU=UVA Standard PKI User, O=University of Virginia, C=US” /batch

 

The following polls a job for its status. The job EPR is loaded from the file “jobEPR”.

 

GramClient.exe /status /j:jobEPR

 

The following kills a job whose EPR is stored in the file “jobEPR”.

 

GramClient.exe /kill /j:jobEPR

 

Use Case:

This use case walks through the process of submitting a job to a remote host running GT4 and then retrieving the output using GridFTP.NET’s GUI client. We will use the following job description file (which we assume to be saved in the file job.xml):

<?xml version="1.0" encoding="UTF-8"?>

<job xmlns="http://www.globus.org/namespaces/2004/10/gram/job/description">

  <executable>/bin/hostname</executable>

  <stdout>hostout.txt</stdout>

</job>

 

In order to submit this job to a GT4 GRAM service, use the following command (replacing myGT4host.com with the hostname and port of your machine running the GT4 container).

 

GramClient.exe /F:https://myGT4host.com:8443/wsrf/services/ManagedJobFactoryService /f:job.xml /batch /o:jobEPR

 

To poll the status of this job, use the command:

 

GramClient.exe /status /j:jobEPR

 

When the job status is “Done”, we can check the output file (“hostout.txt”) using GridFTP.NET – we will use the GridFTP.NET GUI. Run the GridFTP.NET GUI and click on the “New Site” button in the “GridFTP Sites” window. This will bring up a dialog like the one below. Replace “myGT4host.com” with the hostname for the GT4 machine you are using.

Then click the “Select” button and choose your personal certificate in the dialog box that appears. Highlight the certificate and click “Ok”.

The “Site Properties” window should now look something like this (with your hostname and certificate details).

Click “Create”. Now highlight the new site in the “GridFTP Sites” window (as shown below) and click “Connect”.

After GridFTP connects, you should see a window similar to this one. The tab that is labeled “opteron1” in the image below will instead contain your GridFTP host’s name and your directory and files contents will be different. In the right hand window, find “test.txt” and double-click on it. This will download the file using the GridFTP protocol and display the file’s contents using the program associated with the file’s extension (in the case of .txt, this is usually Notepad). You should now see a file containing the hostname of the machine to which you submitted your job.

 

 

Notes on Interactive Job Submission:

When a job is submitted interactively, the GramClient automatically listen for asynchronous notification messages from the GRAM service about changes in the state of the submitted job (e.g. Active, Staging, Done, Cleanup, etc.). However, some network configurations will not permit these messages from the GRAM service to reach the GramClient. Firewalls can block these notifications. Also, if the GramClient is behind a VPN, the IP address that it gives to the GRAM service may not be visible to the GRAM service and therefore notification messages cannot be received. We recommend using interactive job submission only when the client is running on a machine with a fixed IP address.