Update NEWS and initscript/README.stap-server with details of changes

due to recent commits.

1 files changed, 93 insertions, 0 deletions

diff --git a/initscript/README.systemtap b/initscript/README.systemtap
index 5c6cac15..ebce285e 100644
--- a/initscript/README.systemtap
+++ b/initscript/README.systemtap
@@ -9,6 +9,7 @@ INDEX
 3. Files
 4. Configuration Format
 5. How to use
+6. Authentication and Authorization
 
 1. Introduction
 ===============
@@ -353,3 +354,95 @@ script2_REQ=script1
  # vi /etc/systemtap/config
  AUTOCOMPILE=no
  ALLOW_CACHEONLY=yes
+
+6. Authentication and Authorization
+===================================
+
+6.1 Authentication
+6.1.1 SSL
+  The stap-server service must authenticate itself to each client using SSL
+  before it can be trusted.
+
+6.1.2 Unprivileged Users (Module Signing)
+  If the stap-server service will be used to service requests for unprivileged
+  users (the --unprivileged option) it must also sign compiled modules using
+  a trusted signing certificate.
+
+6.1.3 Certification
+  The same certificate is used for both of these purposes. It resides in the
+  file /var/lib/stap-server/.systemtap/ssl/server/stap.cert on the host which
+  is running the stap-server service.
+
+6.2 Authorization
+6.2.1 SSL
+  After starting the stap-server service for the first time, the sysadmin
+  must authorize the stap-server service as a trusted ssl. To
+  do this, on each host from which a client will access the stap-server service
+  (including localhost) run the following command as root
+
+	stap-authorize-server-cert <certfile>
+
+  where <certfile> is the stap-server certificate file from the host running the
+  stap-server service (see section 6.1.3).
+
+  This need only be done once on each client host for each stap-server service
+  to be accessed.
+
+  A client on a compatible host (or the same host) can now access the server
+
+	stap-client -e 'probe begin { printf ("Hello\n"); exit (); }'
+
+  This should print 'Hello', provided the user has the authority to load the
+  resulting module on the client host.
+
+6.1.2 Unprivileged Users (Module Signing)
+  If the user on the client host is a an ordinary unprivileged user or a member
+  of the group stapusr, he will get an error when running the example above,
+  since he does not have authority to load the unsigned module returned by the
+  server. Howeverm if he is a member of the group stapusr and if he can get the
+  module signed by a trusted signer, he will be able to load it.
+
+  The server will sign the module if the --unprivileged option is specified by
+  the client:
+
+	stap-client -e 'probe begin { printf ("Hello\n"); exit (); }' --unprivileged
+
+  The server will now check that the script is safe for use by members of
+  stapusr (i.e. it doesn't do anything "dangerous") and, if so, will compile it
+  and sign it. However we will still get an error saying that the module
+  could not be loaded. This time it is because the server is not a trusted
+  signer.
+
+  In order to authorize the server as a trusted signer, on each host from which
+  a client will access the stap-server service (including localhost), run the
+  following command as root
+
+	stap-authorize-signing-cert <certfile>
+
+  where <certfile> is the stap-server certificate file from the host running the
+  stap-server service (see section 6.1.3).
+
+  This need only be done once on each client host for each stap-server service
+  to be accessed.
+  
+  The example above should now work as expected.   
+
+6.1.3 Ordinary Users
+  Ordinary users are users who are not root and not a member of either of the
+  groups stapdev or stapusr.
+
+  These users can still use the stap-server service to compile their scripts
+  but they can not load the resulting modules, even if the module is signed
+  by a trusted signer (server). The following will ask the server to compile
+  the script and return the resulting unsigned module.
+
+	stap-client -e 'probe begin { printf ("Hello\n"); exit (); }' -p4
+
+  The following will ask the server to check that the script is safe for use by
+  members of stapusr (i.e. it doesn't do anything "dangerous") and, if so, to
+  compile it and sign it.
+
+	stap-client -e 'probe begin { printf ("Hello\n"); exit (); }' -p4 --unprivileged
+
+  In both cases the name of the resulting module will be printed, but it will
+  not be loaded.