welcome: please sign in

Diff for "DomTool/AdminProcedures"

Differences between revisions 1 and 15 (spanning 14 versions)
Revision 1 as of 2006-12-16 20:53:25
Size: 2051
Editor: AdamChlipala
Comment:
Revision 15 as of 2008-07-15 15:01:59
Size: 7432
Editor: AdamChlipala
Comment: -fake
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
[[TableOfContents()]] <<TableOfContents>>
Line 9: Line 9:
 * `$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".
Line 25: Line 26:
    * `path /afs/hcoop.net/usr/$USER`     * `path /afs/hcoop.net/user/$USERPATH`
Line 30: Line 31:

= 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
}}}

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

= 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}}}

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

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.

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

DomTool/AdminProcedures (last edited 2009-02-17 16:44:21 by AdamChlipala)