154 lines
5.0 KiB
Plaintext
154 lines
5.0 KiB
Plaintext
Proxy Management Protocol
|
|
Draft Version 1.0
|
|
Ralph Mor, X Consortium
|
|
|
|
|
|
The Proxy Management Protocol is an ICE based protocol that provides a way
|
|
for application servers to easily locate proxy services available to them.
|
|
|
|
Typically, a service called a "proxy manager" is responsible for resolving
|
|
requests for proxy services, starting new proxies when appropriate, and
|
|
keeping track of all of the available proxy services. The proxy manager
|
|
strives to reuse existing proxies whenever possible.
|
|
|
|
In order to request a proxy service, the GET_PROXY_ADDR message is sent to
|
|
the proxy manager. The proxy manager will in turn forward this message to
|
|
a proxy that it thinks can satisfy the request.
|
|
|
|
GET_PROXY_ADDR
|
|
proxy-service : STRING
|
|
server-address : STRING
|
|
host-address : STRING
|
|
options : STRING
|
|
auth-data-len : CARD16
|
|
auth-name : STRING or None
|
|
auth-data : LISTofCARD8 or None
|
|
|
|
-->
|
|
|
|
status : CARD8
|
|
proxy-address : STRING
|
|
failure-reason : STRING
|
|
|
|
|
|
proxy-service is the name of the proxy service to be requested, for example
|
|
"LBX". proxy-service is a case insensitive string.
|
|
|
|
server-address is the network address of the target server. The format of
|
|
the address is specific to proxy-service. For example, for a proxy service
|
|
of "LBX", the address would be an X display address (e.g, "wkstn.x.org:0").
|
|
|
|
host-address is the network address of the host on which the proxied
|
|
application will run. This information might be used by the proxy to
|
|
restrict access to a specific host.
|
|
|
|
options are proxy specific options that will be passed to the proxy. The
|
|
details of these options are not specified here. Their syntax and
|
|
semantics are defined by each proxy service.
|
|
|
|
If auth-data-len is nonzero, then auth-name and auth-data contain
|
|
authentication or authorization information that should be passed to
|
|
the proxy. The proxy will typically use this to authenticate and
|
|
authorize itself to the target server. The details of how the
|
|
auth fields are used are specific to each proxy service.
|
|
|
|
|
|
After sending GET_PROXY_ADDR the proxy manager expects a reply from
|
|
the proxy. The status field of the reply indicates if the request can
|
|
be satisfied.
|
|
|
|
If status is Success, proxy-address will contain the network address of the
|
|
proxy willing to handle this request. The format of the proxy address is
|
|
specific to the proxy service being used. For example, for a proxy service
|
|
of "LBX", the proxy address would be the X display address of the proxy
|
|
(e.g, "gateway.x.org:63"). The proxy manager will forward the successful
|
|
GET_PROXY_ADDR reply to whomever requested the proxy service.
|
|
|
|
If status is Unable, the proxy is not able to satisfy the request but
|
|
it believes some other proxy might be able to do so. Proxy-address is
|
|
the empty string and failure-reason indicates the reason for failure.
|
|
The proxy manager may choose to forward the original GET_PROXY_ADDR to
|
|
another already running proxy, or it may choose to start up a new
|
|
proxy. In the event that the proxy manager can not find or start a
|
|
proxy, it will send a GET_PROXY_ADDR reply (with status Failure and an
|
|
appropriate failure-reason) to whomever requested the proxy service.
|
|
|
|
If status is Failure, the proxy is not able to satisfy the request and
|
|
in addition is informing the requester that the request is invalid in
|
|
some way and should not be retried.
|
|
|
|
|
|
If the proxy manager starts up a new proxy, the proxy manager will
|
|
need an indication from the proxy that it is ready to accept
|
|
requests. The proxy is required to send a START_PROXY message to the
|
|
proxy manager to identify itself and signal its readiness to receive
|
|
requests.
|
|
|
|
START_PROXY
|
|
proxy-service : STRING (name of proxy service, e.g. "LBX")
|
|
|
|
|
|
When the proxy manager receives the START_PROXY message from the
|
|
proxy it checks that the proxy-service is the one that it's expecting.
|
|
If the proxy-service is incorrect, an IceBadValue error will be sent
|
|
to the proxy. Otherwise, the proxy manager will forward the original
|
|
GET_PROXY_ADDR request to the proxy and the proxy will respond to the
|
|
GET_PROXY_ADDR request in the same way as discussed above.
|
|
|
|
|
|
Protocol
|
|
--------
|
|
|
|
ICE protocol name is "PROXY_MANAGEMENT".
|
|
The major opcode is assigned at run-time by ICE.
|
|
|
|
|
|
Types
|
|
-----
|
|
|
|
STRING
|
|
2 CARD16 length
|
|
n LISTofCARD8 the string
|
|
p p = pad(2+n,8)
|
|
|
|
|
|
|
|
Encoding
|
|
--------
|
|
|
|
GET_PROXY_ADDR
|
|
|
|
1 ? PROXY_MANAGEMENT
|
|
1 1 opcode
|
|
2 n auth-data-len (in bytes)
|
|
4 (a+b+c+d+e+n+p)/8 length of remaining data in 8-byte units
|
|
a STRING proxy-service
|
|
b STRING server-address
|
|
c STRING host-address
|
|
d STRING options
|
|
e STRING auth-name (if auth-data-len > 0)
|
|
n LISTofCARD8 auth-data (if auth-data-len > 0)
|
|
p unused, p=pad(n,8)
|
|
|
|
GET_PROXY_ADDR_REPLY
|
|
|
|
1 ? PROXY_MANAGEMENT
|
|
1 2 opcode
|
|
1 CARD8 status
|
|
0 Unable
|
|
1 Success
|
|
2 Failure
|
|
1 unused
|
|
4 (a+b)/8 length of remaining data in 8-byte units
|
|
a STRING proxy-address
|
|
b STRING failure-reason
|
|
|
|
|
|
START_PROXY
|
|
|
|
1 ? PROXY_MANAGEMENT
|
|
1 3 opcode
|
|
2 unused
|
|
4 a/8 length of remaining data in 8-byte units
|
|
a STRING proxy-service
|