.TH "globus_gram_protocol_definition" 3 "Tue Jul 5 2022" "Version 13.6" "globus_gram_protocol" \" -*- nroff -*-
.ad l
.nh
.SH NAME
globus_gram_protocol_definition \- GRAM Protocol Definition
.PP
The GRAM Protocol is used to handle communication between the Gatekeeper, Job Manager, and GRAM Clients\&. The protocol is based on a subset of the HTTP/1\&.1 protocol, with a small set of message types and responses sent as the body of the HTTP requests and responses\&. This document describes GRAM Protocol version 2\&.
.PP
.SS "Framing"
.PP
GRAM messages are framed in HTTP/1\&.1 messages\&. However, only a small subset of the HTTP specification is used or understood by the GRAM system\&. All GRAM requests are HTTP POST messages\&. Only the following HTTP headers are understood:
.IP "\(bu" 2
Host
.IP "\(bu" 2
Content-Type (set to 'application/x-globus-gram' in all cases)
.IP "\(bu" 2
Content-Length
.IP "\(bu" 2
Connection (set to 'close' in all HTTP responses)
.PP
.PP
Only the following status codes are supported in response's HTTP Status-Lines:
.IP "\(bu" 2
200 OK
.IP "\(bu" 2
403 Forbidden
.IP "\(bu" 2
404 Not Found
.IP "\(bu" 2
500 Internal Server Error
.IP "\(bu" 2
400 Bad Request
.PP
.PP
.SS "Message Format"
.PP
All messages use the carriage return (ASCII value 13) followed by line feed (ASCII value 10) sequence to delimit lines\&. In all cases, a blank line separates the HTTP header from the message body\&. All \fBapplication/x-globus-gram\fP message bodies consist of attribute names followed by a colon, a space, and then the value of the attribute\&. When the value may contain a newline or double-quote character, a special escaping rule is used to encapsulate the complete string\&. This encapsulation consists of surrounding the string with double-quotes, and escaping all double-quote and backslash characters within the string with a backslash\&. All other characters are sent without modification\&. For example, the string
.PP
.nf
rsl: &( executable = "/bin/echo" )
( arguments = "hello" )
.fi
.PP
becomes
.PP
.nf
rsl: "&( executable = \"bin/echo\" )
(arguments = \"hello\" )"
.fi
.PP
.PP
This is the only form of quoting which \fBapplication/x-globus-gram\fP messages support\&. Use of % HEX HEX escapes (such as seen in URL encodings) is not meaningful for this protocol\&.
.PP
.SS "Message Types"
.PP
.SS "Ping Request"
.PP
A ping request is used to verify that the gatekeeper is configured properly to handle a named service\&. The ping request consists of the following:
.PP
.PP
.nf
POST ping/\fIjob-manager-name\fP HTTP/1\&.1
Host: \fIhost-name\fP
Content-Type: application/x-globus-gram
Content-Length: \fImessage-size\fP
protocol-version: \fIversion\fP
.fi
.PP
.PP
The values of the message-specific strings are
.IP "\fB\fIjob-manager-name\fP \fP" 1c
The name of the service to have the gatekeeper check\&. The service name corresponds to one of the gatekeeper's configured grid-services, and is usually of the form 'jobmanager-scheduler-type'\&.
.IP "\fB\fIhost-name\fP \fP" 1c
The name of the host on which the gatekeeper is running\&. This exists only for compatibility with the HTTP/1\&.1 protocol\&.
.IP "\fB\fImessage-size\fP \fP" 1c
The length of the content of the message, not including the HTTP/1\&.1 header\&.
.IP "\fB\fIversion\fP \fP" 1c
The version of the GRAM protocol which is being used\&. For the protocol defined in this document, the value must be the string '2'\&.
.PP
.PP
.SS "Job Request"
.PP
A job request is used to scheduler a job remotely using GRAM\&. The ping request consists of the HTTP framing described above with the request-URI consisting of \fIjob-manager-name\fP, where \fIjob-manager name\fP is the name of the service to use to schedule the job\&. The format of a job request message consists of the following:
.PP
.PP
.nf
POST \fIjob-manager-name\fP[@\fIuser-name\fP] HTTP/1\&.1
Host: \fIhost-name\fP
Content-Type: application/x-globus-gram
Content-Length: \fImessage-size\fP
protocol-version: \fIversion\fP
job-state-mask: \fImask\fP
callback-url: \fIcallback-contact\fP
rsl: \fIrsl-description\fP
.fi
.PP
.PP
The values of the emphasized text items are as below:
.IP "\fB\fIjob-manager-name\fP \fP" 1c
The name of the service to submit the job request to\&. The service name corresponds to one of the gatekeeper's configured grid-services, and is usually of the form 'jobmanager-scheduler-type'\&.
.IP "\fB\fIuser-name\fP \fP" 1c
Starting with GT4\&.0, a client may request that a certain account by used by the gatekeeper to start the job manager\&. This is done optionally by appending the @ symbol and the local user name that the job should be run as to the \fIjob-manager-name\fP\&. If the @ and username are not present, then the first grid map entry will be used\&. If the client credential is not authorized in the grid map to use the specified account, an authorization error will occur in the gatekeeper\&.
.IP "\fB\fIhost-name\fP \fP" 1c
The name of the host on which the gatekeeper is running\&. This exists only for compatibility with the HTTP/1\&.1 protocol\&.
.IP "\fB\fImessage-size\fP \fP" 1c
The length of the content of the message, not including the HTTP/1\&.1 header\&.
.IP "\fB\fIversion\fP \fP" 1c
The version of the GRAM protocol which is being used\&. For the protocol defined in this document, the value must be the string '2'\&.
.IP "\fB\fImask\fP \fP" 1c
An integer representation of the job state mask\&. This value is obtained from a bitwise-OR of the job state values which the client wishes to receive job status callbacks about\&. These meanings of the various job state values are defined in the \fBGRAM Protocol API documentation\fP\&.
.IP "\fB\fIcallback-contact\fP \fP" 1c
A https URL which defines a GRAM protocol listener which will receive job state updates\&. The from a bitwise-OR of the job state values which the client wishes to receive job status callbacks about\&. The job status update messages are defined \fBbelow\fP\&.
.IP "\fB\fIrsl-description\fP \fP" 1c
A quoted string containing the RSL description of the job request\&.
.PP
.PP
.SS "Status Request"
.PP
A status request is used by a GRAM client to get the current job state of a running job\&. This type of message can only be sent to a job manager's job-contact (as returned in the reply to a job request message)\&. The format of a job request message consists of the following:
.PP
.nf
POST \fIjob-contact\fP HTTP/1\&.1
Host: \fIhost-name\fP
Content-Type: application/x-globus-gram
Content-Length: \fImessage-size\fP
protocol-version: \fIversion\fP
'status'
.fi
.PP
.PP
The values of the emphasized text items are as below:
.IP "\fB\fIjob-contact\fP \fP" 1c
The job contact string returned in a response to a job request message, or determined by querying the MDS system\&.
.IP "\fB\fIhost-name\fP \fP" 1c
The name of the host on which the job manager is running\&. This exists only for compatibility with the HTTP/1\&.1 protocol\&.
.IP "\fB\fImessage-size\fP \fP" 1c
The length of the content of the message, not including the HTTP/1\&.1 header\&.
.IP "\fB\fIversion\fP \fP" 1c
The version of the GRAM protocol which is being used\&. For the protocol defined in this document, the value must be the string '2'\&.
.PP
.PP
.SS "Callback Register Request"
.PP
A callback register request is used by a GRAM client to register a new callback contact to receive GRAM job state updates\&. This type of message can only be sent to a job manager's job-contact (as returned in the reply to a job request message)\&. The format of a job request message consists of the following:
.PP
.nf
POST \fIjob-contact\fP HTTP/1\&.1
Host: \fIhost-name\fP
Content-Type: application/x-globus-gram
Content-Length: \fImessage-size\fP
protocol-version: \fIversion\fP
'register mask callback-contact'
.fi
.PP
.PP
The values of the emphasized text items are as below:
.IP "\fB\fIjob-contact\fP \fP" 1c
The job contact string returned in a response to a job request message, or determined by querying the MDS system\&.
.IP "\fB\fIhost-name\fP \fP" 1c
The name of the host on which the job manager is running\&. This exists only for compatibility with the HTTP/1\&.1 protocol\&.
.IP "\fB\fImessage-size\fP \fP" 1c
The length of the content of the message, not including the HTTP/1\&.1 header\&.
.IP "\fB\fIversion\fP \fP" 1c
The version of the GRAM protocol which is being used\&. For the protocol defined in this document, the value must be the string '2'\&.
.IP "\fB\fImask\fP \fP" 1c
An integer representation of the job state mask\&. This value is obtained from a bitwise-OR of the job state values which the client wishes to receive job status callbacks about\&. These meanings of the various job state values are defined in the \fBGRAM Protocol API documentation\fP\&.
.IP "\fB\fIcallback-contact\fP \fP" 1c
A https URL which defines a GRAM protocol listener which will receive job state updates\&. The from a bitwise-OR of the job state values which the client wishes to receive job status callbacks about\&. The job status update messages are defined \fBbelow\fP\&.
.PP
.PP
.SS "Callback Unregister Request"
.PP
A callback unregister request is used by a GRAM client to request that the job manager no longer send job state updates to the specified callback contact\&. This type of message can only be sent to a job manager's job-contact (as returned in the reply to a job request message)\&. The format of a job request message consists of the following:
.PP
.nf
POST \fIjob-contact\fP HTTP/1\&.1
Host: \fIhost-name\fP
Content-Type: application/x-globus-gram
Content-Length: \fImessage-size\fP
protocol-version: \fIversion\fP
'unregister callback-contact'
.fi
.PP
.PP
The values of the emphasized text items are as below:
.IP "\fB\fIjob-contact\fP \fP" 1c
The job contact string returned in a response to a job request message, or determined by querying the MDS system\&.
.IP "\fB\fIhost-name\fP \fP" 1c
The name of the host on which the job manager is running\&. This exists only for compatibility with the HTTP/1\&.1 protocol\&.
.IP "\fB\fImessage-size\fP \fP" 1c
The length of the content of the message, not including the HTTP/1\&.1 header\&.
.IP "\fB\fIversion\fP \fP" 1c
The version of the GRAM protocol which is being used\&. For the protocol defined in this document, the value must be the string '2'\&.
.IP "\fB\fIcallback-contact\fP \fP" 1c
A https URL which defines a GRAM protocol listener which should no longer receive job state updates\&. The from a bitwise-OR of the job state values which the client wishes to receive job status callbacks about\&. The job status update messages are defined \fBbelow\fP\&.
.PP
.PP
.SS "Job Cancel Request"
.PP
A job cancel request is used by a GRAM client to request that the job manager terminate a job\&. This type of message can only be sent to a job manager's job-contact (as returned in the reply to a job request message)\&. The format of a job request message consists of the following:
.PP
.nf
POST \fIjob-contact\fP HTTP/1\&.1
Host: \fIhost-name\fP
Content-Type: application/x-globus-gram
Content-Length: \fImessage-size\fP
protocol-version: \fIversion\fP
'cancel'
.fi
.PP
.PP
The values of the emphasized text items are as below:
.IP "\fB\fIjob-contact\fP \fP" 1c
The job contact string returned in a response to a job request message, or determined by querying the MDS system\&.
.IP "\fB\fIhost-name\fP \fP" 1c
The name of the host on which the job manager is running\&. This exists only for compatibility with the HTTP/1\&.1 protocol\&.
.IP "\fB\fImessage-size\fP \fP" 1c
The length of the content of the message, not including the HTTP/1\&.1 header\&.
.IP "\fB\fIversion\fP \fP" 1c
The version of the GRAM protocol which is being used\&. For the protocol defined in this document, the value must be the string '2'\&.
.PP
.PP
.SS "Job Signal Request"
.PP
A job signal request is used by a GRAM client to request that the job manager process a signal for a job\&. The arguments to the various signals are discussed in the \fBglobus_gram_protocol_job_signal_t\fP documentation\&.
.PP
.nf
POST \fIjob-contact\fP HTTP/1\&.1
Host: \fIhost-name\fP
Content-Type: application/x-globus-gram
Content-Length: \fImessage-size\fP
protocol-version: \fIversion\fP
'signal'
.fi
.PP
.PP
The values of the emphasized text items are as below:
.IP "\fB\fIjob-contact\fP \fP" 1c
The job contact string returned in a response to a job request message, or determined by querying the MDS system\&.
.IP "\fB\fIhost-name\fP \fP" 1c
The name of the host on which the job manager is running\&. This exists only for compatibility with the HTTP/1\&.1 protocol\&.
.IP "\fB\fImessage-size\fP \fP" 1c
The length of the content of the message, not including the HTTP/1\&.1 header\&.
.IP "\fB\fIversion\fP \fP" 1c
The version of the GRAM protocol which is being used\&. For the protocol defined in this document, the value must be the string '2'\&.
.IP "\fB\fIsignal\fP \fP" 1c
A quoted string containing the signal number and it's parameters\&.
.PP
.PP
.SS "Job State Updates"
.PP
A job status update message is sent by the job manager to all registered callback contacts when the job's status changes\&. The format of the job status update messages is as follows:
.PP
.nf
POST \fIcallback-contact\fP HTTP/1\&.1
Host: \fIhost-name\fP
Content-Type: application/x-globus-gram
Content-Length: \fImessage-size\fP
protocol-version: \fIversion\fP
job-manager-url: \fIjob-contact\fP
status: \fIstatus-code\fP
failure-code: \fIfailure-code\fP
.fi
.PP
.PP
The values of the emphasized text items are as below:
.IP "\fB\fIcallback-contact\fP \fP" 1c
The callback contact string registered with the job manager either by being passed as the \fIcallback-contact\fP in a job request message or in a callback register message\&.
.IP "\fB\fIhost-name\fP \fP" 1c
The host part of the callback-contact URL\&. This exists only for compatibility with the HTTP/1\&.1 protocol\&.
.IP "\fB\fImessage-size\fP \fP" 1c
The length of the content of the message, not including the HTTP/1\&.1 header\&.
.IP "\fB\fIversion\fP \fP" 1c
The version of the GRAM protocol which is being used\&. For the protocol defined in this document, the value must be the string '2'\&.
.IP "\fB\fIjob-contact\fP \fP" 1c
The job contact of the job which has changed states\&.
.PP
.PP
.SS "Proxy Delegation"
.PP
A proxy delegation message is sent by the client to the job manager to initiate a delegation handshake to generate a new proxy credential for the job manager\&. This credential is used by the job manager or the job when making further secured connections\&. The format of the delegation message is as follows:
.PP
.nf
POST \fIcallback-contact\fP HTTP/1\&.1
Host: \fIhost-name\fP
Content-Type: application/x-globus-gram
Content-Length: \fImessage-size\fP
protocol-version: \fIversion\fP
'renew'
.fi
.PP
.PP
If a successful (200) reply is sent in response to this message, then the client will proceed with a GSI delegation handshake\&. The tokens in this handshake will be framed with a 4 byte big-endian token length header\&. The framed tokens will then be wrapped using the GLOBUS_IO_SECURE_CHANNEL_MODE_SSL_WRAP wrapping mode\&. The job manager will frame response tokens in the same manner\&. After the job manager receives its final delegation token, it will respond with another response message that indicates whether the delegation was processed or not\&. This response message is a standard GRAM response message\&.
.PP
.SS "Note on Security Attributes"
.PP
The following security attributes are needed to communicate with the Gatekeeper:
.IP "\(bu" 2
Authentication must be done using GSSAPI mutual authentication
.IP "\(bu" 2
Messages must be wrapped with support for the delegation message\&. When using Globus I/O, this is accomplished by using the the GLOBUS_IO_SECURE_CHANNEL_MODE_GSI_WRAP wrapping mode\&.
.PP
.PP
.SS "Changes"
.PP
2004-08-11 Added information about gridmap choosing