This page is only of direct interest to HCoop admins; that is, people with root privileges on our servers.  Most members should probably start at DomTool/UserGuide.

[[TableOfContents()]]

= Conventions for this document =

We'll use:
 * `$USER` to stand for the UNIX username that should be clear from context
 * `$DOMTOOL` to stand for `/afs/hcoop.net/common/etc/domtool`, the root of global DomTool data

= Adding users =

When a new UNIX user is added who should have DomTool access, run:{{{
domtool-adduser $USER}}}

This does a few things:
 1. Creates a `$DOMTOOL/keys/$USER` directory if it doesn't already exist, setting its ownership to `domtool.domtool` and granting `$USER` read permissions on it.  The AFS permissions inherited from `$DOMTOOL/keys` already prevent other users from peeking at keys stored in this directory.
 1. Use `openssl req` to generate (to file `$DOMTOOL/keys/$USER/key.pem`) a new RSA key for purposes of `$USER`'s interactions with DomTool.  The only fields given values on this key are:
    * Common name: Set to `$USER`
    * E-mail address: Set to `$USER@hcoop.net`
 1. Use `openssl ca` to sign the key with the DomTool certificate authority.  The result is a certificate file in `$DOMTOOL/certs/$USER.pem`, owned by `domtool.domtool`.
 1. Grant some standard DomTool permissions to the user:
    * `user $USER`
    * `group $USER`
    * `path /afs/hcoop.net/usr/$USER`

All of these actions should be idempotent.  That is, running `domtool-adduser` repeatedly with the same argument should work just fine.  The only consequence that might bother perfectionists is that our certificate authority will issue a new certificate each time with a new serial number, incrementing the saved serial number count.  It should also be safe to re-run `domtool-adduser` after a previous invocation failed halfway through.

Sometimes you only want to run the SSL-related commands or the DomTool permission-related commands.  For those cases, run `domtool-addcert $USER` or `domtool-addacl $USER`.