1globus_gram_protocol(3) globus gram protocol globus_gram_protocol(3)
2
6 globus_gram_protocol - GRAM Protocol Definition The GRAM Protocol is
7 used to handle communication between the Gatekeeper, Job Manager, and
8 GRAM Clients.
9 The protocol is based on a subset of the HTTP/1.1 protocol, with a
11 small set of message types and responses sent as the body of the HTTP
12 requests and responses. This document describes GRAM Protocol version
13 2.
14 Framing
16 GRAM messages are framed in HTTP/1.1 messages. However, only a small
17 subset of the HTTP specification is used or understood by the GRAM
18 system. All GRAM requests are HTTP POST messages. Only the following
19 HTTP headers are understood:
20 · Host
22 · Content-Type (set to 'application/x-globus-gram' in all cases)
24 · Content-Length
26 · Connection (set to 'close' in all HTTP responses)
28 Only the following status codes are supported in response's HTTP
30 Status-Lines:
31 · 200 OK
33 · 403 Forbidden
35 · 404 Not Found
37 · 500 Internal Server Error
39 · 400 Bad Request
41 Message Format
43 All messages use the carriage return (ASCII value 13) followed by line
44 feed (ASCII value 10) sequence to delimit lines. In all cases, a blank
45 line separates the HTTP header from the message body. All
46 application/x-globus-gram message bodies consist of attribute names
47 followed by a colon, a space, and then the value of the attribute. When
48 the value may contain a newline or double-quote character, a special
49 escaping rule is used to encapsulate the complete string. This
50 encapsulation consists of surrounding the string with double-quotes,
51 and escaping all double-quote and backslash characters within the
52 string with a backslash. All other characters are sent without
53 modification. For example, the string
54 rsl: &( executable = '/bin/echo' )
56 ( arguments = 'hello' )
57 becomes
60 rsl: '&( executable = ´bin/echo´ )
62 (arguments = ´hello´ )'
63 This is the only form of quoting which application/x-globus-gram
66 messages support. Use of % HEX HEX escapes (such as seen in URL
67 encodings) is not meaningful for this protocol.
68 Message Types
70 Ping Request
71 A ping request is used to verify that the gatekeeper is configured
72 properly to handle a named service. The ping request consists of the
73 following:
74 POST ping/job-manager-name HTTP/1.1
76 Host: host-name
77 Content-Type: application/x-globus-gram
78 Content-Length: message-size
79 protocol-version: version
81 The values of the message-specific strings are
83 job-manager-name
85 The name of the service to have the gatekeeper check. The service
86 name corresponds to one of the gatekeeper's configured grid-
87 services, and is usually of the form 'jobmanager-<em>scheduler-
88 type</em>'.
89 host-name
91 The name of the host on which the gatekeeper is running. This
92 exists only for compatibility with the HTTP/1.1 protocol.
93 message-size
95 The length of the content of the message, not including the
96 HTTP/1.1 header.
97 version
99 The version of the GRAM protocol which is being used. For the
100 protocol defined in this document, the value must be the string
101 '2'.
102 Job Request
104 A job request is used to scheduler a job remotely using GRAM. The ping
105 request consists of the HTTP framing described above with the request-
106 URI consisting of job-manager-name, where job-manager name is the name
107 of the service to use to schedule the job. The format of a job request
108 message consists of the following:
109 POST job-manager-name[@user-name] HTTP/1.1
111 Host: host-name
112 Content-Type: application/x-globus-gram
113 Content-Length: message-size
114 protocol-version: version
116 job-state-mask: mask
117 callback-url: callback-contact
118 rsl: rsl-description
119 The values of the emphasized text items are as below:
121 job-manager-name
123 The name of the service to submit the job request to. The service
124 name corresponds to one of the gatekeeper's configured grid-
125 services, and is usually of the form 'jobmanager-<em>scheduler-
126 type</em>'.
127 user-name
129 Starting with GT4.0, a client may request that a certain account by
130 used by the gatekeeper to start the job manager. This is done
131 optionally by appending the @ symbol and the local user name that
132 the job should be run as to the job-manager-name. If the @ and
133 username are not present, then the first grid map entry will be
134 used. If the client credential is not authorized in the grid map to
135 use the specified account, an authorization error will occur in the
136 gatekeeper.
137 host-name
139 The name of the host on which the gatekeeper is running. This
140 exists only for compatibility with the HTTP/1.1 protocol.
141 message-size
143 The length of the content of the message, not including the
144 HTTP/1.1 header.
145 version
147 The version of the GRAM protocol which is being used. For the
148 protocol defined in this document, the value must be the string
149 '2'.
150 mask
152 An integer representation of the job state mask. This value is
153 obtained from a bitwise-OR of the job state values which the client
154 wishes to receive job status callbacks about. These meanings of the
155 various job state values are defined in the GRAM Protocol API
156 documentation.
157 callback-contact
159 A https URL which defines a GRAM protocol listener which will
160 receive job state updates. The from a bitwise-OR of the job state
161 values which the client wishes to receive job status callbacks
162 about. The job status update messages are defined below.
163 rsl-description
165 A quoted string containing the RSL description of the job request.
166 Status Request
168 A status request is used by a GRAM client to get the current job state
169 of a running job. This type of message can only be sent to a job
170 manager's job-contact (as returned in the reply to a job request
171 message). The format of a job request message consists of the
172 following:
173 POST job-contact HTTP/1.1
175 Host: host-name
176 Content-Type: application/x-globus-gram
177 Content-Length: message-size
178 protocol-version: version
180 'status'
181 The values of the emphasized text items are as below:
183 job-contact
185 The job contact string returned in a response to a job request
186 message, or determined by querying the MDS system.
187 host-name
189 The name of the host on which the job manager is running. This
190 exists only for compatibility with the HTTP/1.1 protocol.
191 message-size
193 The length of the content of the message, not including the
194 HTTP/1.1 header.
195 version
197 The version of the GRAM protocol which is being used. For the
198 protocol defined in this document, the value must be the string
199 '2'.
200 Callback Register Request
202 A callback register request is used by a GRAM client to register a new
203 callback contact to receive GRAM job state updates. This type of
204 message can only be sent to a job manager's job-contact (as returned in
205 the reply to a job request message). The format of a job request
206 message consists of the following:
207 POST job-contact HTTP/1.1
209 Host: host-name
210 Content-Type: application/x-globus-gram
211 Content-Length: message-size
212 protocol-version: version
214 'register <em>mask</em> <em>callback-contact</em>'
215 The values of the emphasized text items are as below:
217 job-contact
219 The job contact string returned in a response to a job request
220 message, or determined by querying the MDS system.
221 host-name
223 The name of the host on which the job manager is running. This
224 exists only for compatibility with the HTTP/1.1 protocol.
225 message-size
227 The length of the content of the message, not including the
228 HTTP/1.1 header.
229 version
231 The version of the GRAM protocol which is being used. For the
232 protocol defined in this document, the value must be the string
233 '2'.
234 mask
236 An integer representation of the job state mask. This value is
237 obtained from a bitwise-OR of the job state values which the client
238 wishes to receive job status callbacks about. These meanings of the
239 various job state values are defined in the GRAM Protocol API
240 documentation.
241 callback-contact
243 A https URL which defines a GRAM protocol listener which will
244 receive job state updates. The from a bitwise-OR of the job state
245 values which the client wishes to receive job status callbacks
246 about. The job status update messages are defined below.
247 Callback Unregister Request
249 A callback unregister request is used by a GRAM client to request that
250 the job manager no longer send job state updates to the specified
251 callback contact. This type of message can only be sent to a job
252 manager's job-contact (as returned in the reply to a job request
253 message). The format of a job request message consists of the
254 following:
255 POST job-contact HTTP/1.1
257 Host: host-name
258 Content-Type: application/x-globus-gram
259 Content-Length: message-size
260 protocol-version: version
262 'unregister <em>callback-contact</em>'
263 The values of the emphasized text items are as below:
265 job-contact
267 The job contact string returned in a response to a job request
268 message, or determined by querying the MDS system.
269 host-name
271 The name of the host on which the job manager is running. This
272 exists only for compatibility with the HTTP/1.1 protocol.
273 message-size
275 The length of the content of the message, not including the
276 HTTP/1.1 header.
277 version
279 The version of the GRAM protocol which is being used. For the
280 protocol defined in this document, the value must be the string
281 '2'.
282 callback-contact
284 A https URL which defines a GRAM protocol listener which should no
285 longer receive job state updates. The from a bitwise-OR of the job
286 state values which the client wishes to receive job status
287 callbacks about. The job status update messages are defined below.
288 Job Cancel Request
290 A job cancel request is used by a GRAM client to request that the job
291 manager terminate a job. This type of message can only be sent to a job
292 manager's job-contact (as returned in the reply to a job request
293 message). The format of a job request message consists of the
294 following:
295 POST job-contact HTTP/1.1
297 Host: host-name
298 Content-Type: application/x-globus-gram
299 Content-Length: message-size
300 protocol-version: version
302 'cancel'
303 The values of the emphasized text items are as below:
305 job-contact
307 The job contact string returned in a response to a job request
308 message, or determined by querying the MDS system.
309 host-name
311 The name of the host on which the job manager is running. This
312 exists only for compatibility with the HTTP/1.1 protocol.
313 message-size
315 The length of the content of the message, not including the
316 HTTP/1.1 header.
317 version
319 The version of the GRAM protocol which is being used. For the
320 protocol defined in this document, the value must be the string
321 '2'.
322 Job Signal Request
324 A job signal request is used by a GRAM client to request that the job
325 manager process a signal for a job. The arguments to the various
326 signals are discussed in the globus_gram_protocol_job_signal_t
327 documentation.
328 POST job-contact HTTP/1.1
330 Host: host-name
331 Content-Type: application/x-globus-gram
332 Content-Length: message-size
333 protocol-version: version
335 '<em>signal</em>'
336 The values of the emphasized text items are as below:
338 job-contact
340 The job contact string returned in a response to a job request
341 message, or determined by querying the MDS system.
342 host-name
344 The name of the host on which the job manager is running. This
345 exists only for compatibility with the HTTP/1.1 protocol.
346 message-size
348 The length of the content of the message, not including the
349 HTTP/1.1 header.
350 version
352 The version of the GRAM protocol which is being used. For the
353 protocol defined in this document, the value must be the string
354 '2'.
355 signal
357 A quoted string containing the signal number and it's parameters.
358 Job State Updates
360 A job status update message is sent by the job manager to all
361 registered callback contacts when the job's status changes. The format
362 of the job status update messages is as follows:
363 POST callback-contact HTTP/1.1
365 Host: host-name
366 Content-Type: application/x-globus-gram
367 Content-Length: message-size
368 protocol-version: version
370 job-manager-url: job-contact
371 status: status-code
372 failure-code: failure-code
373 The values of the emphasized text items are as below:
375 callback-contact
377 The callback contact string registered with the job manager either
378 by being passed as the callback-contact in a job request message or
379 in a callback register message.
380 host-name
382 The host part of the callback-contact URL. This exists only for
383 compatibility with the HTTP/1.1 protocol.
384 message-size
386 The length of the content of the message, not including the
387 HTTP/1.1 header.
388 version
390 The version of the GRAM protocol which is being used. For the
391 protocol defined in this document, the value must be the string
392 '2'.
393 job-contact
395 The job contact of the job which has changed states.
396 Proxy Delegation
398 A proxy delegation message is sent by the client to the job manager to
399 initiate a delegation handshake to generate a new proxy credential for
400 the job manager. This credential is used by the job manager or the job
401 when making further secured connections. The format of the delegation
402 message is as follows:
403 POST callback-contact HTTP/1.1
405 Host: host-name
406 Content-Type: application/x-globus-gram
407 Content-Length: message-size
408 protocol-version: version
410 'renew'
411 If a successful (200) reply is sent in response to this message, then
413 the client will procede with a GSI delegation handshake. The tokens in
414 this handshake will be framed with a 4 byte big-endian token length
415 header. The framed tokens will then be wrapped using the
416 GLOBUS_IO_SECURE_CHANNEL_MODE_SSL_WRAP wrapping mode. The job manager
417 will frame response tokens in the same manner. After the job manager
418 receives its final delegation token, it will respond with another
419 response message that indicates whether the delegation was processed or
420 not. This response message is a standard GRAM response message.
421 Note on Security Attributes
423 The following security attributes are needed to communicate with the
424 Gatekeeper:
425 · Authentication must be done using GSSAPI mutual authentication
427 · Messages must be wrapped with support for the delegation message.
429 When using Globus I/O, this is accomplished by using the the
430 GLOBUS_IO_SECURE_CHANNEL_MODE_GSI_WRAP wrapping mode.
431 Changes
433 2004-08-11 Added information about gridmap choosing
434Version 9.7 Tue Jun 7 2011 globus_gram_protocol(3)