1globus_gram_protocol_definitiognl(o3b)us_gram_protgolcooblus_gram_protocol_definition(3)
2
3
4

NAME

6       globus_gram_protocol_definition - GRAM Protocol Definition
7
8       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
14   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
20       · Host
21
22       · Content-Type (set to 'application/x-globus-gram' in all cases)
23
24       · Content-Length
25
26       · Connection (set to 'close' in all HTTP responses)
27
28       Only the following status codes are supported in response's HTTP
29       Status-Lines:
30
31       · 200 OK
32
33       · 403 Forbidden
34
35       · 404 Not Found
36
37       · 500 Internal Server Error
38
39       · 400 Bad Request
40
41   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
54       rsl: &( executable = "/bin/echo" )
55        ( arguments = "hello" )
56
57
58        becomes
59
60       rsl: "&( executable =
61         (arguments =
62
63
64       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
68   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
74           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
79           protocol-version: version
80
81       The values of the message-specific strings are
82
83       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
89       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
93       message-size
94           The length of the content of the message, not including the
95           HTTP/1.1 header.
96
97       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
102   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
109           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
114           protocol-version: version
115           job-state-mask: mask
116           callback-url: callback-contact
117           rsl: rsl-description
118
119       The values of the emphasized text items are as below:
120
121       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
127       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
137       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
141       message-size
142           The length of the content of the message, not including the
143           HTTP/1.1 header.
144
145       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
150       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
157       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
163       rsl-description
164           A quoted string containing the RSL description of the job request.
165
166   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
173           POST job-contact HTTP/1.1
174           Host: host-name
175           Content-Type: application/x-globus-gram
176           Content-Length: message-size
177
178           protocol-version: version
179           'status'
180
181       The values of the emphasized text items are as below:
182
183       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
187       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
191       message-size
192           The length of the content of the message, not including the
193           HTTP/1.1 header.
194
195       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
200   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
207           POST job-contact HTTP/1.1
208           Host: host-name
209           Content-Type: application/x-globus-gram
210           Content-Length: message-size
211
212           protocol-version: version
213           'register <em>mask</em> <em>callback-contact</em>'
214
215       The values of the emphasized text items are as below:
216
217       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
221       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
225       message-size
226           The length of the content of the message, not including the
227           HTTP/1.1 header.
228
229       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
234       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
241       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
247   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
255           POST job-contact HTTP/1.1
256           Host: host-name
257           Content-Type: application/x-globus-gram
258           Content-Length: message-size
259
260           protocol-version: version
261           'unregister <em>callback-contact</em>'
262
263       The values of the emphasized text items are as below:
264
265       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
269       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
273       message-size
274           The length of the content of the message, not including the
275           HTTP/1.1 header.
276
277       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
282       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
288   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
295           POST job-contact HTTP/1.1
296           Host: host-name
297           Content-Type: application/x-globus-gram
298           Content-Length: message-size
299
300           protocol-version: version
301           'cancel'
302
303       The values of the emphasized text items are as below:
304
305       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
309       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
313       message-size
314           The length of the content of the message, not including the
315           HTTP/1.1 header.
316
317       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
322   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
328           POST job-contact HTTP/1.1
329           Host: host-name
330           Content-Type: application/x-globus-gram
331           Content-Length: message-size
332
333           protocol-version: version
334           '<em>signal</em>'
335
336       The values of the emphasized text items are as below:
337
338       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
342       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
346       message-size
347           The length of the content of the message, not including the
348           HTTP/1.1 header.
349
350       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
355       signal
356           A quoted string containing the signal number and it's parameters.
357
358   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
363           POST callback-contact HTTP/1.1
364           Host: host-name
365           Content-Type: application/x-globus-gram
366           Content-Length: message-size
367
368           protocol-version: version
369           job-manager-url: job-contact
370           status: status-code
371           failure-code: failure-code
372
373       The values of the emphasized text items are as below:
374
375       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
380       host-name
381           The host part of the callback-contact URL. This exists only for
382           compatibility with the HTTP/1.1 protocol.
383
384       message-size
385           The length of the content of the message, not including the
386           HTTP/1.1 header.
387
388       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
393       job-contact
394           The job contact of the job which has changed states.
395
396   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
403           POST callback-contact HTTP/1.1
404           Host: host-name
405           Content-Type: application/x-globus-gram
406           Content-Length: message-size
407
408           protocol-version: version
409           'renew'
410
411       If a successful (200) reply is sent in response to this message, then
412       the client will procede 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
421   Note on Security Attributes
422       The following security attributes are needed to communicate with the
423       Gatekeeper:
424
425       · Authentication must be done using GSSAPI mutual authentication
426
427       · 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
431   Changes
432       2004-08-11 Added information about gridmap choosing
433
434
435
436Version 13.2                    Tue Jan 28 20g2l0obus_gram_protocol_definition(3)
Impressum