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
 * `$USERPATH` to stand for the first letter of the username, a slash, the next two letters of the username, a slash, and the username, concatenated.  For example, a `$USER` of "adamc" would have `$USERPATH` be "a/ad/adamc".
 * `$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/user/$USERPATH`

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`.

= Removing users =

When someone leaves HCoop and you want to squelch all of his domains and DomTool privileges, run:{{{
domtool-rmuser $USER}}}

This does a few things:
 1. Delete `$DOMTOOL/keys/$USER`.
 1. Delete `$DOMTOOL/certs/$USER.pem`.
 1. Run `domtool-admin rmuser $USER`, which:
    1. Removes all DomTool privileges for `$USER`.
    1. Deletes all domains to which only `$USER` has the `domain` permission.  This includes removing all configuration related to those domains in real daemons.

= Querying permissions =

== Listing a user's permissions ==

To list all permission that `$USER` has, run:{{{
domtool-admin perms $USER}}}

== Finding out who has a permission ==

To list all the users that have permission `$CLASS`/`$VALUE`, run:{{{
domtool-admin whohas $CLASS $VALUE}}}

For instance, to see which users are allowed to configure hcoop.net, run:{{{
domtool-admin whohas domain hcoop.net}}}

= Changing permissions =

== Granting a permission ==

To give `$USER` permission `$CLASS`/`$VALUE`, run:{{{
domtool-admin grant $USER $CLASS $VALUE}}}

Such as:
{{{
domtool-admin grant docelic domain spinlocksolutions.com
domtool-admin grant docelic cert /etc/apache2/ssl/apache.pem
domtool-admin grant docelic ip 1.2.3.4
}}}

== Revoking a permission ==

To revoke permission `$CLASS`/`$VALUE` from `$USER` , run:{{{
domtool-admin revoke $USER $CLASS $VALUE}}}

= Updating domtool =

== Reinstalling domtool ==

In the case that you make changes to domtool and want to reinstall it, see [[DomTool/Building]], the ''Reinstalling the standalone tools'' section, for instructions.

== Validating after a major change ==

If something changes in the Domtool standard library, users' configuration might stop working.  If you just run `domtool-admin regen` in such a case, those users' domains will go down, which will probably make them sad.  Instead, run this first:{{{
domtool-admin regen -tc}}}

This just verifies that all configuration type-checks.  You can go through and fix the errors, which show up in `/var/log/domtool.log` on deleuze, one at a time, and only run `domtool-admin regen` (as in the following section) after everything type-checks.

== Regenerating files ==

To effectively erase all published configuration and regenerate it all by running all files found in `.domtool` subdirectories of users' AFS volumes, run:{{{
domtool-admin regen}}}

You might want to do this if there has been some nasty kind of data corruption, or if a security vulnerability has been discovered in DomTool and you want to drop all old, unsafe configuration directives that the buggy DomTool had been letting through.

== Regenerating user-specific files ==

Domtool contains support for generating certain files whenever the set of users changes.  For now, the only file is `/etc/apache2/waklog.conf`, which assigns a Kerberos principal to every user's `/~` URL.

Normally this file is regenerated whenever a user is added or removed.  If you need to trigger a manual regeneration, run:{{{
domtool-admin reusers}}}

= Managing domains =

== Adding a domain ==

To grant a user `$USER` some domain `$DOMAIN`, run:{{{
domtool-admin grant $USER domain $DOMAIN}}}

== Removing a domain ==

To remove all configuration associated with a domain `$DOMAIN`, run:{{{
domtool-admin rmdom $DOMAIN}}}

This clears out DomTool configuration related to `$DOMAIN` and removes any reference to it from the actual configuration files used by real daemons.  However, users' permissions to configure the domain are left untouched.  You can remove those separately with `domtool-admin revoke`.

== Managing admin-run domains ==

Every domain is thought of as owned by a user.  By convention:
 * User `domtool` owns `localhost`, so you should edit `~domtool/.domtool/localhost` for such purposes as adding local e-mail aliases.
 * User `hcoop` owns `hcoop.net` and sub-domains, so you should edit `~hcoop/.domtool/deleuze.hcoop.net`, `~hcoop/.domtool/hcoop.net`, etc., as appropriate.  (`hcoop` also owns the portal, the wiki, and other "informational" services that are relatively low security.)  Don't forget to use '''DOMTOOL_USER=hcoop''' when type-checking and installing your changes.

= Debugging other users' configuration files =

The relevant typing rules for configuration files vary based on which user is processing files.  For instance, the values of `your_domain` depend on which permissions the user has been granted.  You can always use `domtool-admin regen` to reload all config, executed as the appropriate users.  However, reprocessing everything has a significant cost, so you might want to run single files as particular users.  To do this, use this pattern:{{{
DOMTOOL_USER=$SOMEONE domtool $FILENAME}}}

You can also use other ways of setting the UNIX environment variable `DOMTOOL_USER`.  Note that an invocation with `DOMTOOL_USER` set depends on the ability to read that user's private key from AFS, so you will need AFS admin permissions to do this in general.

== Checking users' files ==

You can try type-checking, but not executing, a file as a user with:{{{
DOMTOOL_USER=$SOMEONE domtool -tc $FILENAME}}}

You can also do this assuming that the user has permissions for all domains and IP addresses, in case you want to check something before granting the appropriate permissions:{{{
DOMTOOL_USER=$SOMEONE domtool -tc -fake $FILENAME}}}

= Describing a domain =

To see all "real" configuration generated for a domain, run:{{{
domtool-admin describe $DOMAIN}}}