PM_spec revision 50718ea6
1 Proxy Management Protocol 2 Draft Version 1.0 3 Ralph Mor, X Consortium 4 5 6The Proxy Management Protocol is an ICE based protocol that provides a way 7for application servers to easily locate proxy services available to them. 8 9Typically, a service called a "proxy manager" is responsible for resolving 10requests for proxy services, starting new proxies when appropriate, and 11keeping track of all of the available proxy services. The proxy manager 12strives to reuse existing proxies whenever possible. 13 14In order to request a proxy service, the GET_PROXY_ADDR message is sent to 15the proxy manager. The proxy manager will in turn forward this message to 16a proxy that it thinks can satisfy the request. 17 18GET_PROXY_ADDR 19 proxy-service : STRING 20 server-address : STRING 21 host-address : STRING 22 options : STRING 23 auth-data-len : CARD16 24 auth-name : STRING or None 25 auth-data : LISTofCARD8 or None 26 27 --> 28 29 status : CARD8 30 proxy-address : STRING 31 failure-reason : STRING 32 33 34proxy-service is the name of the proxy service to be requested, for example 35"LBX". proxy-service is a case insensitive string. 36 37server-address is the network address of the target server. The format of 38the address is specific to proxy-service. For example, for a proxy service 39of "LBX", the address would be an X display address (e.g, "wkstn.x.org:0"). 40 41host-address is the network address of the host on which the proxied 42application will run. This information might be used by the proxy to 43restrict access to a specific host. 44 45options are proxy specific options that will be passed to the proxy. The 46details of these options are not specified here. Their syntax and 47semantics are defined by each proxy service. 48 49If auth-data-len is nonzero, then auth-name and auth-data contain 50authentication or authorization information that should be passed to 51the proxy. The proxy will typically use this to authenticate and 52authorize itself to the target server. The details of how the 53auth fields are used are specific to each proxy service. 54 55 56After sending GET_PROXY_ADDR the proxy manager expects a reply from 57the proxy. The status field of the reply indicates if the request can 58be satisfied. 59 60If status is Success, proxy-address will contain the network address of the 61proxy willing to handle this request. The format of the proxy address is 62specific to the proxy service being used. For example, for a proxy service 63of "LBX", the proxy address would be the X display address of the proxy 64(e.g, "gateway.x.org:63"). The proxy manager will forward the successful 65GET_PROXY_ADDR reply to whomever requested the proxy service. 66 67If status is Unable, the proxy is not able to satisfy the request but 68it believes some other proxy might be able to do so. Proxy-address is 69the empty string and failure-reason indicates the reason for failure. 70The proxy manager may choose to forward the original GET_PROXY_ADDR to 71another already running proxy, or it may choose to start up a new 72proxy. In the event that the proxy manager can not find or start a 73proxy, it will send a GET_PROXY_ADDR reply (with status Failure and an 74appropriate failure-reason) to whomever requested the proxy service. 75 76If status is Failure, the proxy is not able to satisfy the request and 77in addition is informing the requester that the request is invalid in 78some way and should not be retried. 79 80 81If the proxy manager starts up a new proxy, the proxy manager will 82need an indication from the proxy that it is ready to accept 83requests. The proxy is required to send a START_PROXY message to the 84proxy manager to identify itself and signal its readiness to receive 85requests. 86 87START_PROXY 88 proxy-service : STRING (name of proxy service, e.g. "LBX") 89 90 91When the proxy manager receives the START_PROXY message from the 92proxy it checks that the proxy-service is the one that it's expecting. 93If the proxy-service is incorrect, an IceBadValue error will be sent 94to the proxy. Otherwise, the proxy manager will forward the original 95GET_PROXY_ADDR request to the proxy and the proxy will respond to the 96GET_PROXY_ADDR request in the same way as discussed above. 97 98 99Protocol 100-------- 101 102ICE protocol name is "PROXY_MANAGEMENT". 103The major opcode is assigned at run-time by ICE. 104 105 106Types 107----- 108 109STRING 110 2 CARD16 length 111 n LISTofCARD8 the string 112 p p = pad(2+n,8) 113 114 115 116Encoding 117-------- 118 119GET_PROXY_ADDR 120 121 1 ? PROXY_MANAGEMENT 122 1 1 opcode 123 2 n auth-data-len (in bytes) 124 4 (a+b+c+d+e+n+p)/8 length of remaining data in 8-byte units 125 a STRING proxy-service 126 b STRING server-address 127 c STRING host-address 128 d STRING options 129 e STRING auth-name (if auth-data-len > 0) 130 n LISTofCARD8 auth-data (if auth-data-len > 0) 131 p unused, p=pad(n,8) 132 133GET_PROXY_ADDR_REPLY 134 135 1 ? PROXY_MANAGEMENT 136 1 2 opcode 137 1 CARD8 status 138 0 Unable 139 1 Success 140 2 Failure 141 1 unused 142 4 (a+b)/8 length of remaining data in 8-byte units 143 a STRING proxy-address 144 b STRING failure-reason 145 146 147START_PROXY 148 149 1 ? PROXY_MANAGEMENT 150 1 3 opcode 151 2 unused 152 4 a/8 length of remaining data in 8-byte units 153 a STRING proxy-service 154