HCoop Git - hcoop/zz_old/ikiwiki/blob - DomTool/AdminProcedures.mdwn

   1 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.
   2
   3 [[TableOfContents()]]
   4
   5 = Conventions for this document =
   6
   7 We'll use:
   8  * `$USER` to stand for the UNIX username that should be clear from context
   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".
  10  * `$DOMTOOL` to stand for `/afs/hcoop.net/common/etc/domtool`, the root of global DomTool data
  11
  12 = Adding users =
  13
  14 When a new UNIX user is added who should have DomTool access, run:{{{
  15 domtool-adduser $USER}}}
  16
  17 This does a few things:
  18  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.
  19  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:
  20     * Common name: Set to `$USER`
  21     * E-mail address: Set to `$USER@hcoop.net`
  22  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`.
  23  1. Grant some standard DomTool permissions to the user:
  24     * `user $USER`
  25     * `group $USER`
  26     * `path /afs/hcoop.net/user/$USERPATH`
  27
  28 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.
  29
  30 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`.
  31
  32 = Removing users =
  33
  34 When someone leaves HCoop and you want to squelch all of his domains and DomTool privileges, run:{{{
  35 domtool-rmuser $USER}}}
  36
  37 This does a few things:
  38  1. Delete `$DOMTOOL/keys/$USER`.
  39  1. Delete `$DOMTOOL/certs/$USER.pem`.
  40  1. Run `domtool-admin rmuser $USER`, which:
  41     1. Removes all DomTool privileges for `$USER`.
  42     1. Deletes all domains to which only `$USER` has the `domain` permission.  This includes removing all configuration related to those domains in real daemons.
  43
  44 = Querying permissions =
  45
  46 == Listing a user's permissions ==
  47
  48 To list all permission that `$USER` has, run:{{{
  49 domtool-admin perms $USER}}}
  50
  51 == Finding out who has a permission ==
  52
  53 To list all the users that have permission `$CLASS`/`$VALUE`, run:{{{
  54 domtool-admin whohas $CLASS $VALUE}}}
  55
  56 For instance, to see which users are allowed to configure hcoop.net, run:{{{
  57 domtool-admin whohas domain hcoop.net}}}
  58
  59 = Changing permissions =
  60
  61 == Granting a permission ==
  62
  63 To give `$USER` permission `$CLASS`/`$VALUE`, run:{{{
  64 domtool-admin grant $USER $CLASS $VALUE}}}
  65
  66 Such as:
  67 {{{
  68 domtool-admin grant docelic domain spinlocksolutions.com
  69 domtool-admin grant docelic cert /etc/apache2/ssl/apache.pem
  70 }}}
  71
  72 == Revoking a permission ==
  73
  74 To revoke permission `$CLASS`/`$VALUE` from `$USER` , run:{{{
  75 domtool-admin revoke $USER $CLASS $VALUE}}}
  76
  77 = Updating domtool =
  78
  79 == Reinstalling domtool ==
  80
  81 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.
  82
  83 == Validating after a major change ==
  84
  85 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:{{{
  86 domtool-admin regen -tc}}}
  87
  88 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.
  89
  90 == Regenerating files ==
  91
  92 To effectively erase all published configuration and regenerate it all by running all files found in `.domtool` subdirectories of users' AFS volumes, run:{{{
  93 domtool-admin regen}}}
  94
  95 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.
  96
  97 = Managing domains =
  98
  99 == Adding a domain ==
 100
 101 To grant a user `$USER` some domain `$DOMAIN`, run:{{{
 102 domtool-admin grant $USER domain $DOMAIN}}}
 103
 104 == Removing a domain ==
 105
 106 To remove all configuration associated with a domain `$DOMAIN`, run:{{{
 107 domtool-admin rmdom $DOMAIN}}}
 108
 109 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`.
 110
 111 == Managing admin-run domains ==
 112
 113 Every domain is thought of as owned by a user.  By convention:
 114  * User `domtool` owns `localhost`, so you should edit `~domtool/domtool/localhost` for such purposes as adding local e-mail aliases.
 115  * 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.)
 116
 117 = Debugging other users' configuration files =
 118
 119 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:{{{
 120 DOMTOOL_USER=$SOMEONE domtool $FILENAME}}}
 121
 122 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.