Move documentation from xorg-docs module

Signed-off-by: Alan Coopersmith <alan.coopersmith@sun.com>

1 files changed, 153 insertions, 0 deletions

diff --git a/PM_spec b/PM_spec
new file mode 100644
index 0000000..b371d46
--- /dev/null
+++ b/PM_spec
@@ -0,0 +1,153 @@
+			 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