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.

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

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

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

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

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

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

2. Delete $DOMTOOL/certs/$USER.pem.

3. Run domtool-admin rmuser $USER, which:

   1. Removes all DomTool privileges for $USER.

   2. Deletes all domains to which only $USER has the domain permission. This includes removing all configuration related to those domains in real daemons.

4. Querying permissions

4.1. Listing a user's permissions

To list all permission that $USER has, run:

domtool-admin perms $USER

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

5. Changing permissions

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

5.2. Revoking a permission

To revoke permission $CLASS/$VALUE from $USER , run:

domtool-admin revoke $USER $CLASS $VALUE

6. Updating domtool

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

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

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

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

7. Managing domains

7.1. Adding a domain

To grant a user $USER some domain $DOMAIN, run:

domtool-admin grant $USER domain $DOMAIN

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

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

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

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

9. Describing a domain

To see all "real" configuration generated for a domain, run:

domtool-admin describe $DOMAIN