welcome: please sign in

The following 398 words could not be found in the dictionary of 7 words (including 7 LocalSpellingWords) and are highlighted below:
ability   access   actions   actual   ad   adamc   addacl   addcert   added   Adding   adding   address   addresses   adduser   admin   admins   afs   after   aliases   all   All   allowed   already   also   always   an   and   any   apache   apache2   appropriate   are   argument   as   assigns   associated   assuming   at   authority   based   be   been   before   bother   buggy   Building   but   By   by   ca   can   case   cases   cert   certain   certificate   certs   change   changes   Changing   check   Checking   checking   checks   clear   clears   com   commands   Common   common   concatenated   conf   config   configuration   configure   consequence   contains   Contents   context   convention   Conventions   Coop   corruption   cost   count   Creates   daemons   data   Debugging   Delete   Deletes   deleuze   depend   depends   describe   Describing   direct   directives   directory   discovered   do   docelic   document   does   doesn   Dom   domain   domains   Domtool   domtool   Don   down   drop   each   edit   effectively   environment   erase   errors   etc   every   Every   everything   example   executed   executing   exist   failed   fake   few   fields   file   files   Finding   fine   first   fix   following   For   for   forget   found   from   general   generate   generated   generating   give   given   global   go   Grant   grant   granted   granting   Granting   group   Guide   had   halfway   has   have   hcoop   his   However   idempotent   If   if   in   In   includes   incrementing   informational   inherited   installing   instance   Instead   instructions   interactions   interest   invocation   ip   is   issue   it   It   its   just   Kerberos   key   keys   kind   leaves   left   letter   letters   letting   library   list   Listing   ll   local   localhost   log   low   mail   major   make   Managing   manual   members   might   Most   name   nasty   need   net   new   next   Normally   not   Note   now   number   Of   of   old   on   one   only   openssl   or   other   our   out   owned   ownership   owns   page   particular   path   pattern   peeking   pem   people   perfectionists   permission   permissions   perms   portal   prevent   previous   principal   private   privileges   probably   processing   published   purposes   Querying   re   read   real   reference   regen   regenerate   regenerated   Regenerating   regeneration   reinstall   Reinstalling   related   relatively   relevant   reload   remove   removed   Removes   removes   Removing   removing   repeatedly   reprocessing   req   result   reusers   revoke   Revoking   rmdom   rmuser   root   rules   Run   run   running   sad   safe   same   saved   section   security   see   separately   serial   servers   services   Set   set   setting   should   show   sign   significant   single   slash   so   some   someone   something   Sometimes   specific   spinlocksolutions   squelch   ssl   stand   standalone   standard   start   stop   stored   sub   subdirectories   such   Such   support   Table   tc   that   That   The   the   them   there   these   things   this   This   those   thought   through   time   to   To   Tool   tools   trigger   try   two   type   typing   unsafe   untouched   up   Updating   use   Use   used   user   User   username   users   Validating   values   var   variable   vary   verifies   volumes   vulnerability   waklog   want   ways   We   When   when   whenever   which   who   whohas   wiki   will   with   work   working   would   You   you   your  

Clear message
Edit

DomTool / AdminProcedures

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.

Contents

  1. Conventions for this document
  2. Adding users
  3. Removing users
  4. Querying permissions
    1. Listing a user's permissions
    2. Finding out who has a permission
  5. Changing permissions
    1. Granting a permission
    2. Revoking a permission
  6. Updating domtool
    1. Reinstalling domtool
    2. Validating after a major change
    3. Regenerating files
    4. Regenerating user-specific files
  7. Managing domains
    1. Adding a domain
    2. Removing a domain
    3. Managing admin-run domains
  8. Debugging other users' configuration files
    1. Checking users' files
  9. Describing a domain

1. Conventions for this document

We'll use:

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:

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)