GLOBUS_GRAM_PROTOCOL_DEFINITION(3)

📦
version 13.6 · 6 versions
, in fedora 43, fedora 44, ubuntu resolute, ubuntu stonking

💖 globus_gram_protocol_definition(3) 💖

okay bestie, buckle up — this is globus_gram_protocol_definition(3) from the Library Functions Manual, section 3, and it's the whole tea on the GRAM Protocol. it's giving ✨ networking lore ✨ and we're doing it line by line, no skips, no cap.

🌈 NAME 🌈

globus_gram_protocol_definition — GRAM Protocol Definition. periodt.

The GRAM Protocol is what handles all the communication between the Gatekeeper, the Job Manager, and GRAM Clients. It's built on a subset of the HTTP/1.1 protocol — like, the itty-bitty subset — 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. 💅

🎀 Framing 🎀

GRAM messages are framed inside HTTP/1.1 messages. BUT — and this is the important part, bestie — only a tiny slice of the HTTP spec is actually used or understood by the GRAM system. All GRAM requests are HTTP POST messages. That's it. That's the vibe.

Only these HTTP headers are understood:

  • Host
  • Content-Type (set to "application/x-globus-gram" in all cases)
  • Content-Length
  • Connection (set to "close" in all HTTP responses)

And only these status codes are supported in the response's HTTP Status-Lines:

  • 200 OK
  • 403 Forbidden
  • 404 Not Found
  • 500 Internal Server Error
  • 400 Bad Request

that's the whole menu, we don't do extras here 🫶

🦋 Message Format 🦋

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 application/x-globus-gram message bodies are made of attribute names followed by a colon, a space, and then the value of the attribute.

Now here's the cute part: when the value might contain a newline or a double-quote character, a special escaping rule is used to encapsulate the complete string. This encapsulation consists of:

  1. surrounding the string with double-quotes, and
  2. escaping all double-quote and backslash characters within the string with a backslash.

All other characters are sent without modification. so chill, nothing else gets touched ✨

For example, the string:

rsl: &( executable = "/bin/echo" )
 ( arguments = "hello" )

becomes:

rsl: "&( executable = \"bin/echo\" )
  (arguments = \"hello\" )"

This is the only form of quoting which application/x-globus-gram messages support. Use of % HEX HEX escapes (such as seen in URL encodings) is not meaningful for this protocol. like, don't even try it, bestie 💀

👑 Message Types 👑

💖 Ping Request 💖

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:

POST ping/job-manager-name HTTP/1.1
Host: host-name
Content-Type: application/x-globus-gram
Content-Length: message-size

protocol-version: version

The values of the message-specific strings are:

  • job-manager-name — 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-<em>scheduler-type</em>".
  • host-name — the name of the host on which the gatekeeper is running. This exists only for compatibility with the HTTP/1.1 protocol.
  • message-size — the length of the content of the message, not including the HTTP/1.1 header.
  • version — the version of the GRAM protocol which is being used. For the protocol defined in this document, the value must be the string "2".

🌸 Job Request 🌸

A job request is used to schedule a job remotely using GRAM. (the original page says "the ping request consists of the HTTP framing described above" here — we're just quoting it, don't come for me 🙈) with the request-URI consisting of job-manager-name, where job-manager-name is the name of the service to use to schedule the job. The format of a job request message consists of the following:

POST job-manager-name[@user-name] HTTP/1.1
Host: host-name
Content-Type: application/x-globus-gram
Content-Length: message-size

protocol-version: version
job-state-mask: mask
callback-url: callback-contact
rsl: rsl-description

The values of the emphasized text items are as below:

  • job-manager-name — 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-<em>scheduler-type</em>".
  • user-name — starting with GT4.0, a client may request that a certain account be 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 job-manager-name. 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. 🚨
  • host-name — the name of the host on which the gatekeeper is running. This exists only for compatibility with the HTTP/1.1 protocol.
  • message-size — the length of the content of the message, not including the HTTP/1.1 header.
  • version — the version of the GRAM protocol which is being used. For the protocol defined in this document, the value must be the string "2".
  • mask — 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. The meanings of the various job state values are defined in the GRAM Protocol API documentation.
  • callback-contact — 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 below.
  • rsl-description — a quoted string containing the RSL description of the job request.

⭐ Status Request ⭐

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:

POST job-contact HTTP/1.1
Host: host-name
Content-Type: application/x-globus-gram
Content-Length: message-size

protocol-version: version
"status"

The values of the emphasized text items are as below:

  • job-contact — the job contact string returned in a response to a job request message, or determined by querying the MDS system.
  • host-name — the name of the host on which the job manager is running. This exists only for compatibility with the HTTP/1.1 protocol.
  • message-size — the length of the content of the message, not including the HTTP/1.1 header.
  • version — the version of the GRAM protocol which is being used. For the protocol defined in this document, the value must be the string "2".

💜 Callback Register Request 💜

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:

POST job-contact HTTP/1.1
Host: host-name
Content-Type: application/x-globus-gram
Content-Length: message-size

protocol-version: version
"register <em>mask</em> <em>callback-contact</em>"

The values of the emphasized text items are as below:

  • job-contact — the job contact string returned in a response to a job request message, or determined by querying the MDS system.
  • host-name — the name of the host on which the job manager is running. This exists only for compatibility with the HTTP/1.1 protocol.
  • message-size — the length of the content of the message, not including the HTTP/1.1 header.
  • version — the version of the GRAM protocol which is being used. For the protocol defined in this document, the value must be the string "2".
  • mask — 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. The meanings of the various job state values are defined in the GRAM Protocol API documentation.
  • callback-contact — 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 below.

🍓 Callback Unregister Request 🍓

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:

POST job-contact HTTP/1.1
Host: host-name
Content-Type: application/x-globus-gram
Content-Length: message-size

protocol-version: version
"unregister <em>callback-contact</em>"

The values of the emphasized text items are as below:

  • job-contact — the job contact string returned in a response to a job request message, or determined by querying the MDS system.
  • host-name — the name of the host on which the job manager is running. This exists only for compatibility with the HTTP/1.1 protocol.
  • message-size — the length of the content of the message, not including the HTTP/1.1 header.
  • version — the version of the GRAM protocol which is being used. For the protocol defined in this document, the value must be the string "2".
  • callback-contact — 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 below.

🔥 Job Cancel Request 🔥

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:

POST job-contact HTTP/1.1
Host: host-name
Content-Type: application/x-globus-gram
Content-Length: message-size

protocol-version: version
"cancel"

The values of the emphasized text items are as below:

  • job-contact — the job contact string returned in a response to a job request message, or determined by querying the MDS system.
  • host-name —
and that's literally where part 1 cuts off, bestie 😭 the host-name deets (and everything after) roll in with the next part, so don't go anywhere 🍓
  • host-name — the name of the host where the job manager is chillin'. lowkey it only exists for HTTP/1.1 compatibility, no cap 💅
  • message-size — how long the content of the message is. that's the body only, bestie, the HTTP/1.1 header does NOT count 💖
  • version — which version of the GRAM protocol we're on. for the protocol in this doc, it literally must be the string "2". periodt ✨

📡 Job Signal Request 📡

So a job signal request is what a GRAM client sends when it wants the job manager to process a signal for a job. and like, the arguments to the different signals? those are all discussed over in the globus_gram_protocol_job_signal_t documentation, go check it 🫶

POST job-contact HTTP/1.1
Host: host-name
Content-Type: application/x-globus-gram
Content-Length: message-size

protocol-version: version
"<em>signal</em>"

and the values of those emphasized bits, bestie, are giving:

  • job-contact — the job contact string that came back in a response to a job request message, or that you found by querying the MDS system 🔍
  • host-name — the name of the host running the job manager. only here for HTTP/1.1 compatibility, fr fr.
  • message-size — the length of the content of the message, not counting the HTTP/1.1 header.
  • version — the GRAM protocol version in use. for the protocol in this document it must be the string "2". no negotiating 💀
  • signal — a quoted string holding the signal number and its parameters.

🦋 Job State Updates 🦋

okay so the job status update message is what the job manager sends out to all registered callback contacts the second the job's status changes. main character energy, it announces itself. here's the format:

POST callback-contact HTTP/1.1
Host: host-name
Content-Type: application/x-globus-gram
Content-Length: message-size

protocol-version: version
job-manager-url: job-contact
status: status-code
failure-code: failure-code

and the values of the emphasized items:

  • callback-contact — the callback contact string that got registered with the job manager, either by being passed as the callback-contact in a job request message, or in a callback register message 📝
  • host-name — the host part of the callback-contact URL. exists only for HTTP/1.1 compatibility, iykyk.
  • message-size — the length of the content of the message, not including the HTTP/1.1 header.
  • version — the GRAM protocol version being used. for the protocol in this doc, it must be the string "2" 🌈
  • job-contact — the job contact of the job that changed states. the glow-up (or the flop) in question 💅

🔐 Proxy Delegation 🔐

A proxy delegation message is sent by the client to the job manager to kick off a delegation handshake, and the whole point is generating a brand-new proxy credential for the job manager. that credential then gets used by the job manager — or by the job itself — when it makes further secured connections. here's the format:

POST callback-contact HTTP/1.1
Host: host-name
Content-Type: application/x-globus-gram
Content-Length: message-size

protocol-version: version
"renew"

So if a successful (200) reply comes back for this message, the client proceeds with a GSI delegation handshake. the tokens in that handshake get framed with a 4 byte big-endian token length header. then those framed tokens get wrapped using the GLOBUS_IO_SECURE_CHANNEL_MODE_SSL_WRAP wrapping mode. and the job manager frames its response tokens the exact same way, no notes. after the job manager receives its final delegation token, it responds with another response message telling you whether the delegation was processed or not. that response message? it's a standard GRAM response message ✨

🛡️ Note on Security Attributes 🛡️

the following security attributes are needed to communicate with the Gatekeeper, don't skip these bestie:

  • Authentication must be done using GSSAPI mutual authentication 🤝
  • Messages must be wrapped with support for the delegation message. when you're using Globus I/O, you do this by using the GLOBUS_IO_SECURE_CHANNEL_MODE_GSI_WRAP wrapping mode 🔥

📝 Changes 📝

  • 2004-08-11 — Added information about gridmap choosing 🎀

and that's a wrap, bestie 💖 this was globus_gram_protocol, Version 13.6, dated 2004-08-11, and yes the page title is still doing its little globus_gra..._definition(3) truncation moment 🙈 slay, go read the other pages, ily, bye 👑

📦 where this page comes from