1globus_gram_protocol_definitiognl(o3b)us_gram_protgolcooblus_gram_protocol_definition(3)
2
6 globus_gram_protocol_definition - GRAM Protocol Definition
7 The GRAM Protocol is used to handle communication between the
9 Gatekeeper, Job Manager, and GRAM Clients. The protocol is based on a
10 subset of the HTTP/1.1 protocol, with a small set of message types and
11 responses sent as the body of the HTTP requests and responses. This
12 document describes GRAM Protocol version 2.
13 Framing
15 GRAM messages are framed in HTTP/1.1 messages. However, only a small
16 subset of the HTTP specification is used or understood by the GRAM
17 system. All GRAM requests are HTTP POST messages. Only the following
18 HTTP headers are understood:
19 • Host
21 • Content-Type (set to 'application/x-globus-gram' in all cases)
23 • Content-Length
25 • Connection (set to 'close' in all HTTP responses)
27 Only the following status codes are supported in response's HTTP
29 Status-Lines:
30 • 200 OK
32 • 403 Forbidden
34 • 404 Not Found
36 • 500 Internal Server Error
38 • 400 Bad Request
40 Message Format
42 All messages use the carriage return (ASCII value 13) followed by line
43 feed (ASCII value 10) sequence to delimit lines. In all cases, a blank
44 line separates the HTTP header from the message body. All
45 application/x-globus-gram message bodies consist of attribute names
46 followed by a colon, a space, and then the value of the attribute. When
47 the value may contain a newline or double-quote character, a special
48 escaping rule is used to encapsulate the complete string. This
49 encapsulation consists of surrounding the string with double-quotes,
50 and escaping all double-quote and backslash characters within the
51 string with a backslash. All other characters are sent without
52 modification. For example, the string
53 rsl: &( executable = "/bin/echo" )
55 ( arguments = "hello" )
56 becomes
59 rsl: "&( executable =
61 (arguments =
62 This is the only form of quoting which application/x-globus-gram
65 messages support. Use of % HEX HEX escapes (such as seen in URL
66 encodings) is not meaningful for this protocol.
67 Message Types
69 Ping Request
70 A ping request is used to verify that the gatekeeper is configured
71 properly to handle a named service. The ping request consists of the
72 following:
73 POST ping/job-manager-name HTTP/1.1
75 Host: host-name
76 Content-Type: application/x-globus-gram
77 Content-Length: message-size
78 protocol-version: version
80 The values of the message-specific strings are
82 job-manager-name
84 The name of the service to have the gatekeeper check. The service
85 name corresponds to one of the gatekeeper's configured grid-
86 services, and is usually of the form 'jobmanager-<em>scheduler-
87 type</em>'.
88 host-name
90 The name of the host on which the gatekeeper is running. This
91 exists only for compatibility with the HTTP/1.1 protocol.
92 message-size
94 The length of the content of the message, not including the
95 HTTP/1.1 header.
96 version
98 The version of the GRAM protocol which is being used. For the
99 protocol defined in this document, the value must be the string
100 '2'.
101 Job Request
103 A job request is used to scheduler a job remotely using GRAM. The ping
104 request consists of the HTTP framing described above with the request-
105 URI consisting of job-manager-name, where job-manager name is the name
106 of the service to use to schedule the job. The format of a job request
107 message consists of the following:
108 POST job-manager-name[@user-name] HTTP/1.1
110 Host: host-name
111 Content-Type: application/x-globus-gram
112 Content-Length: message-size
113 protocol-version: version
115 job-state-mask: mask
116 callback-url: callback-contact
117 rsl: rsl-description
118 The values of the emphasized text items are as below:
120 job-manager-name
122 The name of the service to submit the job request to. The service
123 name corresponds to one of the gatekeeper's configured grid-
124 services, and is usually of the form 'jobmanager-<em>scheduler-
125 type</em>'.
126 user-name
128 Starting with GT4.0, a client may request that a certain account by
129 used by the gatekeeper to start the job manager. This is done
130 optionally by appending the @ symbol and the local user name that
131 the job should be run as to the job-manager-name. If the @ and
132 username are not present, then the first grid map entry will be
133 used. If the client credential is not authorized in the grid map to
134 use the specified account, an authorization error will occur in the
135 gatekeeper.
136 host-name
138 The name of the host on which the gatekeeper is running. This
139 exists only for compatibility with the HTTP/1.1 protocol.
140 message-size
142 The length of the content of the message, not including the
143 HTTP/1.1 header.
144 version
146 The version of the GRAM protocol which is being used. For the
147 protocol defined in this document, the value must be the string
148 '2'.
149 mask
151 An integer representation of the job state mask. This value is
152 obtained from a bitwise-OR of the job state values which the client
153 wishes to receive job status callbacks about. These meanings of the
154 various job state values are defined in the GRAM Protocol API
155 documentation.
156 callback-contact
158 A https URL which defines a GRAM protocol listener which will
159 receive job state updates. The from a bitwise-OR of the job state
160 values which the client wishes to receive job status callbacks
161 about. The job status update messages are defined below.
162 rsl-description
164 A quoted string containing the RSL description of the job request.
165 Status Request
167 A status request is used by a GRAM client to get the current job state
168 of a running job. This type of message can only be sent to a job
169 manager's job-contact (as returned in the reply to a job request
170 message). The format of a job request message consists of the
171 following:
172 POST job-contact HTTP/1.1
174 Host: host-name
175 Content-Type: application/x-globus-gram
176 Content-Length: message-size
177 protocol-version: version
179 'status'
180 The values of the emphasized text items are as below:
182 job-contact
184 The job contact string returned in a response to a job request
185 message, or determined by querying the MDS system.
186 host-name
188 The name of the host on which the job manager is running. This
189 exists only for compatibility with the HTTP/1.1 protocol.
190 message-size
192 The length of the content of the message, not including the
193 HTTP/1.1 header.
194 version
196 The version of the GRAM protocol which is being used. For the
197 protocol defined in this document, the value must be the string
198 '2'.
199 Callback Register Request
201 A callback register request is used by a GRAM client to register a new
202 callback contact to receive GRAM job state updates. This type of
203 message can only be sent to a job manager's job-contact (as returned in
204 the reply to a job request message). The format of a job request
205 message consists of the following:
206 POST job-contact HTTP/1.1
208 Host: host-name
209 Content-Type: application/x-globus-gram
210 Content-Length: message-size
211 protocol-version: version
213 'register <em>mask</em> <em>callback-contact</em>'
214 The values of the emphasized text items are as below:
216 job-contact
218 The job contact string returned in a response to a job request
219 message, or determined by querying the MDS system.
220 host-name
222 The name of the host on which the job manager is running. This
223 exists only for compatibility with the HTTP/1.1 protocol.
224 message-size
226 The length of the content of the message, not including the
227 HTTP/1.1 header.
228 version
230 The version of the GRAM protocol which is being used. For the
231 protocol defined in this document, the value must be the string
232 '2'.
233 mask
235 An integer representation of the job state mask. This value is
236 obtained from a bitwise-OR of the job state values which the client
237 wishes to receive job status callbacks about. These meanings of the
238 various job state values are defined in the GRAM Protocol API
239 documentation.
240 callback-contact
242 A https URL which defines a GRAM protocol listener which will
243 receive job state updates. The from a bitwise-OR of the job state
244 values which the client wishes to receive job status callbacks
245 about. The job status update messages are defined below.
246 Callback Unregister Request
248 A callback unregister request is used by a GRAM client to request that
249 the job manager no longer send job state updates to the specified
250 callback contact. This type of message can only be sent to a job
251 manager's job-contact (as returned in the reply to a job request
252 message). The format of a job request message consists of the
253 following:
254 POST job-contact HTTP/1.1
256 Host: host-name
257 Content-Type: application/x-globus-gram
258 Content-Length: message-size
259 protocol-version: version
261 'unregister <em>callback-contact</em>'
262 The values of the emphasized text items are as below:
264 job-contact
266 The job contact string returned in a response to a job request
267 message, or determined by querying the MDS system.
268 host-name
270 The name of the host on which the job manager is running. This
271 exists only for compatibility with the HTTP/1.1 protocol.
272 message-size
274 The length of the content of the message, not including the
275 HTTP/1.1 header.
276 version
278 The version of the GRAM protocol which is being used. For the
279 protocol defined in this document, the value must be the string
280 '2'.
281 callback-contact
283 A https URL which defines a GRAM protocol listener which should no
284 longer receive job state updates. The from a bitwise-OR of the job
285 state values which the client wishes to receive job status
286 callbacks about. The job status update messages are defined below.
287 Job Cancel Request
289 A job cancel request is used by a GRAM client to request that the job
290 manager terminate a job. This type of message can only be sent to a job
291 manager's job-contact (as returned in the reply to a job request
292 message). The format of a job request message consists of the
293 following:
294 POST job-contact HTTP/1.1
296 Host: host-name
297 Content-Type: application/x-globus-gram
298 Content-Length: message-size
299 protocol-version: version
301 'cancel'
302 The values of the emphasized text items are as below:
304 job-contact
306 The job contact string returned in a response to a job request
307 message, or determined by querying the MDS system.
308 host-name
310 The name of the host on which the job manager is running. This
311 exists only for compatibility with the HTTP/1.1 protocol.
312 message-size
314 The length of the content of the message, not including the
315 HTTP/1.1 header.
316 version
318 The version of the GRAM protocol which is being used. For the
319 protocol defined in this document, the value must be the string
320 '2'.
321 Job Signal Request
323 A job signal request is used by a GRAM client to request that the job
324 manager process a signal for a job. The arguments to the various
325 signals are discussed in the globus_gram_protocol_job_signal_t
326 documentation.
327 POST job-contact HTTP/1.1
329 Host: host-name
330 Content-Type: application/x-globus-gram
331 Content-Length: message-size
332 protocol-version: version
334 '<em>signal</em>'
335 The values of the emphasized text items are as below:
337 job-contact
339 The job contact string returned in a response to a job request
340 message, or determined by querying the MDS system.
341 host-name
343 The name of the host on which the job manager is running. This
344 exists only for compatibility with the HTTP/1.1 protocol.
345 message-size
347 The length of the content of the message, not including the
348 HTTP/1.1 header.
349 version
351 The version of the GRAM protocol which is being used. For the
352 protocol defined in this document, the value must be the string
353 '2'.
354 signal
356 A quoted string containing the signal number and it's parameters.
357 Job State Updates
359 A job status update message is sent by the job manager to all
360 registered callback contacts when the job's status changes. The format
361 of the job status update messages is as follows:
362 POST callback-contact HTTP/1.1
364 Host: host-name
365 Content-Type: application/x-globus-gram
366 Content-Length: message-size
367 protocol-version: version
369 job-manager-url: job-contact
370 status: status-code
371 failure-code: failure-code
372 The values of the emphasized text items are as below:
374 callback-contact
376 The callback contact string registered with the job manager either
377 by being passed as the callback-contact in a job request message or
378 in a callback register message.
379 host-name
381 The host part of the callback-contact URL. This exists only for
382 compatibility with the HTTP/1.1 protocol.
383 message-size
385 The length of the content of the message, not including the
386 HTTP/1.1 header.
387 version
389 The version of the GRAM protocol which is being used. For the
390 protocol defined in this document, the value must be the string
391 '2'.
392 job-contact
394 The job contact of the job which has changed states.
395 Proxy Delegation
397 A proxy delegation message is sent by the client to the job manager to
398 initiate a delegation handshake to generate a new proxy credential for
399 the job manager. This credential is used by the job manager or the job
400 when making further secured connections. The format of the delegation
401 message is as follows:
402 POST callback-contact HTTP/1.1
404 Host: host-name
405 Content-Type: application/x-globus-gram
406 Content-Length: message-size
407 protocol-version: version
409 'renew'
410 If a successful (200) reply is sent in response to this message, then
412 the client will proceed with a GSI delegation handshake. The tokens in
413 this handshake will be framed with a 4 byte big-endian token length
414 header. The framed tokens will then be wrapped using the
415 GLOBUS_IO_SECURE_CHANNEL_MODE_SSL_WRAP wrapping mode. The job manager
416 will frame response tokens in the same manner. After the job manager
417 receives its final delegation token, it will respond with another
418 response message that indicates whether the delegation was processed or
419 not. This response message is a standard GRAM response message.
420 Note on Security Attributes
422 The following security attributes are needed to communicate with the
423 Gatekeeper:
424 • Authentication must be done using GSSAPI mutual authentication
426 • Messages must be wrapped with support for the delegation message.
428 When using Globus I/O, this is accomplished by using the the
429 GLOBUS_IO_SECURE_CHANNEL_MODE_GSI_WRAP wrapping mode.
430 Changes
432 2004-08-11 Added information about gridmap choosing
433Version 13.6 Wed May 25 20g2l2obus_gram_protocol_definition(3)