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()

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

5.2. Revoking a permission

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

domtool-admin revoke $USER $CLASS $VALUE

6. Regeneration

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.

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

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