1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408
|
/**
@page globus_gram_protocol GRAM Protocol Definition
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.
<h2>Framing</h2>
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:
- Host
- Content-Type (set to "application/x-globus-gram" in all cases)
- Content-Length
- Connection (set to "close" in all HTTP responses)
Only the following status codes are supported in response's
HTTP Status-Lines:
- 200 OK
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
- 400 Bad Request
<h2>Message Format</h2>
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
<b>application/x-globus-gram</b> 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
@code
rsl: &( executable = "/bin/echo" )
( arguments = "hello" )
@endcode
becomes
@code
rsl: "&( executable = \"bin/echo\" )
(arguments = \"hello\" )"
@endcode
This is the only form of quoting which <b>application/x-globus-gram</b>
messages support. Use of % HEX HEX escapes (such as seen in URL encodings) is
not meaningful for this protocol.
<h2>Message Types</h2>
<h3>Ping Request</h3>
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:
<pre>
POST ping/<em>job-manager-name</em> HTTP/1.1
Host: <em>host-name</em>
Content-Type: application/x-globus-gram
Content-Length: <em>message-size</em>
protocol-version: <em>version</em>
</pre>
The values of the message-specific strings are
<dl>
<dt><em>job-manager-name</em></dt>
<dd>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>".</dd>
<dt><em>host-name</em></dt>
<dd>The name of the host on which the gatekeeper is running. This exists
only for compatibility with the HTTP/1.1 protocol.</dd>
<dt><em>message-size</em></dt>
<dd>The length of the content of the message, not including the HTTP/1.1
header.</dd>
<dt><em>version</em></dt>
<dd>The version of the GRAM protocol which is being used. For the
protocol defined in this document, the value must be the string "2".</dd>
</dl>
<h3>Job Request</h3>
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
<em>job-manager-name</em>, where <em>job-manager name</em> is
the name of the service to use to schedule the job. The format of a job request
message consists of the following:
<pre>
POST <em>job-manager-name</em>[\@<em>user-name</em>] HTTP/1.1
Host: <em>host-name</em>
Content-Type: application/x-globus-gram
Content-Length: <em>message-size</em>
protocol-version: <em>version</em>
job-state-mask: <em>mask</em>
callback-url: <em>callback-contact</em>
rsl: <em>rsl-description</em>
</pre>
The values of the emphasized text items are as below:
<dl>
<dt><em>job-manager-name</em></dt>
<dd>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>".</dd>
<dt><em>user-name</em></dt>
<dd>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 <em>job-manager-name</em>. 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.</dd>
<dt><em>host-name</em></dt>
<dd>The name of the host on which the gatekeeper is running. This exists
only for compatibility with the HTTP/1.1 protocol.</dd>
<dt><em>message-size</em></dt>
<dd>The length of the content of the message, not including the HTTP/1.1
header.</dd>
<dt><em>version</em></dt>
<dd>The version of the GRAM protocol which is being used. For the
protocol defined in this document, the value must be the string
"2".</dd>
<dt><em>mask</em></dt>
<dd>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
@ref globus_gram_protocol_job_state_t "GRAM Protocol API documentation".
</dd>
<dt><em>callback-contact</em></dt>
<dd>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
@ref globus_gram_protocol_job_state_updates "below".</dd>
<dt><em>rsl-description</em></dt>
<dd>A quoted string containing the RSL description of the job request.</dd>
</dl>
<h3>Status Request</h3>
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:
<pre>
POST <em>job-contact</em> HTTP/1.1
Host: <em>host-name</em>
Content-Type: application/x-globus-gram
Content-Length: <em>message-size</em>
protocol-version: <em>version</em>
"status"
</pre>
The values of the emphasized text items are as below:
<dl>
<dt><em>job-contact</em></dt>
<dd>The job contact string returned in a response to a job request
message, or determined by querying the MDS system.</dd>
<dt><em>host-name</em></dt>
<dd>The name of the host on which the job manager is running. This exists
only for compatibility with the HTTP/1.1 protocol.</dd>
<dt><em>message-size</em></dt>
<dd>The length of the content of the message, not including the HTTP/1.1
header.</dd>
<dt><em>version</em></dt>
<dd>The version of the GRAM protocol which is being used. For the
protocol defined in this document, the value must be the string
"2".</dd>
</dl>
<h3>Callback Register Request</h3>
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:
<pre>
POST <em>job-contact</em> HTTP/1.1
Host: <em>host-name</em>
Content-Type: application/x-globus-gram
Content-Length: <em>message-size</em>
protocol-version: <em>version</em>
"register <em>mask</em> <em>callback-contact</em>"
</pre>
The values of the emphasized text items are as below:
<dl>
<dt><em>job-contact</em></dt>
<dd>The job contact string returned in a response to a job request
message, or determined by querying the MDS system.</dd>
<dt><em>host-name</em></dt>
<dd>The name of the host on which the job manager is running. This exists
only for compatibility with the HTTP/1.1 protocol.</dd>
<dt><em>message-size</em></dt>
<dd>The length of the content of the message, not including the HTTP/1.1
header.</dd>
<dt><em>version</em></dt>
<dd>The version of the GRAM protocol which is being used. For the
protocol defined in this document, the value must be the string
"2".</dd>
<dt><em>mask</em></dt>
<dd>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 @ref globus_gram_protocol_job_state_t
"GRAM Protocol API documentation".
</dd>
<dt><em>callback-contact</em></dt>
<dd>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 @ref globus_gram_protocol_job_state_updates
"below".
</dd>
</dl>
<h3>Callback Unregister Request</h3>
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:
<pre>
POST <em>job-contact</em> HTTP/1.1
Host: <em>host-name</em>
Content-Type: application/x-globus-gram
Content-Length: <em>message-size</em>
protocol-version: <em>version</em>
"unregister <em>callback-contact</em>"
</pre>
The values of the emphasized text items are as below:
<dl>
<dt><em>job-contact</em></dt>
<dd>The job contact string returned in a response to a job request
message, or determined by querying the MDS system.</dd>
<dt><em>host-name</em></dt>
<dd>The name of the host on which the job manager is running. This exists
only for compatibility with the HTTP/1.1 protocol.</dd>
<dt><em>message-size</em></dt>
<dd>The length of the content of the message, not including the HTTP/1.1
header.</dd>
<dt><em>version</em></dt>
<dd>The version of the GRAM protocol which is being used. For the
protocol defined in this document, the value must be the string
"2".</dd>
<dt><em>callback-contact</em></dt>
<dd>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 @ref
globus_gram_protocol_job_state_updates "below".
</dd>
</dl>
<h3>Job Cancel Request</h3>
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:
<pre>
POST <em>job-contact</em> HTTP/1.1
Host: <em>host-name</em>
Content-Type: application/x-globus-gram
Content-Length: <em>message-size</em>
protocol-version: <em>version</em>
"cancel"
</pre>
The values of the emphasized text items are as below:
<dl>
<dt><em>job-contact</em></dt>
<dd>The job contact string returned in a response to a job request
message, or determined by querying the MDS system.</dd>
<dt><em>host-name</em></dt>
<dd>The name of the host on which the job manager is running. This exists
only for compatibility with the HTTP/1.1 protocol.</dd>
<dt><em>message-size</em></dt>
<dd>The length of the content of the message, not including the HTTP/1.1
header.</dd>
<dt><em>version</em></dt>
<dd>The version of the GRAM protocol which is being used. For the
protocol defined in this document, the value must be the string
"2".</dd>
</dl>
<h3>Job Signal Request</h3>
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 @ref globus_gram_protocol_job_signal_t documentation.
<pre>
POST <em>job-contact</em> HTTP/1.1
Host: <em>host-name</em>
Content-Type: application/x-globus-gram
Content-Length: <em>message-size</em>
protocol-version: <em>version</em>
"<em>signal</em>"
</pre>
The values of the emphasized text items are as below:
<dl>
<dt><em>job-contact</em></dt>
<dd>The job contact string returned in a response to a job request
message, or determined by querying the MDS system.</dd>
<dt><em>host-name</em></dt>
<dd>The name of the host on which the job manager is running. This exists
only for compatibility with the HTTP/1.1 protocol.</dd>
<dt><em>message-size</em></dt>
<dd>The length of the content of the message, not including the HTTP/1.1
header.</dd>
<dt><em>version</em></dt>
<dd>The version of the GRAM protocol which is being used. For the
protocol defined in this document, the value must be the string
"2".</dd>
<dt><em>signal</em></dt>
<dd>A quoted string containing the signal number and it's
parameters.</dd>
</dl>
@anchor globus_gram_protocol_job_state_updates
<h3>Job State Updates</h3>
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:
<pre>
POST <em>callback-contact</em> HTTP/1.1
Host: <em>host-name</em>
Content-Type: application/x-globus-gram
Content-Length: <em>message-size</em>
protocol-version: <em>version</em>
job-manager-url: <em>job-contact</em>
status: <em>status-code</em>
failure-code: <em>failure-code</em>
</pre>
The values of the emphasized text items are as below:
<dl>
<dt><em>callback-contact</em></dt>
<dd>The callback contact string registered with the job manager either
by being passed as the <em>callback-contact</em> in a job request
message or in a callback register message.</dd>
<dt><em>host-name</em></dt>
<dd>The host part of the callback-contact URL. This exists
only for compatibility with the HTTP/1.1 protocol.</dd>
<dt><em>message-size</em></dt>
<dd>The length of the content of the message, not including the HTTP/1.1
header.</dd>
<dt><em>version</em></dt>
<dd>The version of the GRAM protocol which is being used. For the
protocol defined in this document, the value must be the string
"2".</dd>
<dt><em>job-contact</em></dt>
<dd>The job contact of the job which has changed states.</dd>
</dl>
@anchor globus_gram_protocol_delegation
<h3>Proxy Delegation</h3>
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:
<pre>
POST <em>callback-contact</em> HTTP/1.1
Host: <em>host-name</em>
Content-Type: application/x-globus-gram
Content-Length: <em>message-size</em>
protocol-version: <em>version</em>
"renew"
</pre>
If a successful (200) reply is sent in response to this message, then the
client will procede 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.
<h4>Note on Security Attributes</h4>
The following security attributes are needed to communicate with the
Gatekeeper:
- Authentication must be done using GSSAPI mutual authentication
- 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.
<h4>Changes</h4>
2004-08-11 Added information about gridmap choosing
*/
|