.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