ProxyRenewal README

diff --git a/org.glite.px.proxyrenewal/README b/org.glite.px.proxyrenewal/README
new file mode 100644 (file)
index 0000000..44195df
--- /dev/null
+++ b/org.glite.px.proxyrenewal/README
@@ -0,0 +1,43 @@
+The proxy renewal daemon runs as an internal component of the WMS node,
+which is responsible for keeping proxy certificates valid throughout all the
+lifetime of corresponding jobs. The daemon maintains a repository of proxy
+certificates that have been registered by the WMS for renewal. After
+succesfull registration of a proxy, the WMS refers to the repository file
+whenever it needs access the proxy of a particular job. When the finishes
+the WMS unregisters the proxy from the repository.
+
+The proxy renewal daemon uses a simple text-based protocol to communicate
+with the clients (i.e., the WMS components). The communication is done over
+a local unix socket entirely. The renewal daemon do not expose any network
+interface. In order for the clients to be able to communicate over the
+socket and access the proxies from the repositoru, they have to run under
+the same unix id as the renewal daemon. By default, the glite user account
+is used as the common service user.
+
+In order to keep the proxy certificates, the renewal daemon periodally
+contacts a MyProxy server and retrieves a fresh proxy. Therefore, for the
+renewal mechanism to be working, the users have to store their credentials
+in a MyProxy server first. When contacting the MyProxy server, the renewal
+daemon authenticates itself using an X.509 certificate and key (usualy the
+WMS credentials). The configuration of the MyProxy server has to 
+allow renewal requests done with these credentials.
+
+When VOMS attributes are renewed the renewal daemon uses credentials of the
+user, thus the process resembles the common way how VOMS attributes are
+obtained and no special authorization is needed on the VOMS server side.
+
+The renewals are attempted well before a proxy is about to expire. If an
+attempt fails, other ones are triggered until either one of them succeeds or
+the proxy expires. If a proxy cannot be renewed, its record is removed from
+the repository. Informatioo about renewal attempts are logged via syslog,
+additional detailed information can be enabled using the -d switch.
+
+The repository used by the proxy renewal daemon is a directory containg all
+registered proxy certificates along with some additional information. Names
+of the files always start with a hash computed from the X.509 subject name
+of the proxy. Besides the actual credentials, the daemon stores for each
+registered proxy also a list of job identifiers identifying jobs that were
+submitted with the related identity. In order to decrease the management
+overheads, the renewal daemon aggregates multiple proxy certificates of the
+same identity into a single proxy in the repository. Using this precaution
+decreases the number of renewal attempts and overall management operations.