HCoop Git - hcoop/zz_old/ikiwiki/blob - AndrewFileSystem.mdwn

   1 = Basic Architecture =
   2
   3 Using the shared filesystem involves a combination of Kerberos and OpenAFS.
   4
   5 = File conventions =
   6
   7 The `/afs` tree contains shared filesystems.  `/afs/hcoop.net` (symlinked from `/afs/hcoop` as well) is our piece of the AFS-o-sphere.  Subdirectories include:
   8
   9  * `/afs/hcoop.net/user`, the home of home directories
  10  * `/afs/hcoop.net/user/U/US/$USERNAME`, `$USERNAME`'s home directory
  11  * `/afs/hcoop.net/common/etc`, the home of non-platform-specific fun stuff like DomTool
  12
  13 = Connecting to AFS from an HCoop server =
  14
  15 I found this handy summary of the commands that must be run:
  16   http://www.eos.ncsu.edu/remoteaccess/LinuxOpenAfs/kreset_debian/kreset
  17
  18 On our servers, it seems sufficient to run:
  19 {{{kinit
  20 aklog}}}
  21
  22 These should be run automatically if you log in normally, but admins who manually `kinit` to different users (for
  23 the purpose of testing access permissions most often), need to of course run both `kinit; aklog` to completely
  24 switch to a target user.
  25
  26 = The kadmin shell =
  27
  28 All Kerberos administration commands are run from a special shell, called Kadmin. There are two variants of Kadmin:
  29 kadmin is the usual, remote version of the command which can be run on any machine; kadmin.local is the "local"
  30 version which can only be ran on the AFS fileserver (deleuze).
  31
  32 Invoke kadmin.local as `sudo kadmin.local -p YOURUSERNAME_admin`. It is good to include "-p YOURUSERNAME_admin", or
  33 kadmin will "authenticate" as the first user it finds in the ticket cache, which may or may not be the username you
  34 expected. All the administrative commands would work anyway (since you ran kadmin.local), but an incorrect principal
  35 name would make various statistics incorrect (like name of principal who was adding/changing entries in the DB).
  36
  37 To invoke kadmin, use `kadmin -p YOURUSERNAME_admin`. In normal course of action, kadmin asks for a password. This is
  38 impractical for automated scripts. As usual, instead of a password, you can also pass a keytab file. Our keytabs are
  39 saved in /etc/keytabs/ on each system, and they are readable by group 'wheel'. So administrators should be able
  40 to invoke 'kadmin' (use control shell) or kinit/k5start (impersonate any user) by supplying target user's key from
  41 a keytab, such as `kadmin -p domtool/deleuze -k -t /etc/keytabs/domtool.deleuze` .
  42
  43 = Creating a new user =
  44
  45 We follow the convention that Kerberos users for daemons are named `$DAEMON`, where `$DAEMON` is the name of the daemon (for instance, the name of system user it runs as, or the name of its `/etc/init.d` file). ''Some daemons
  46 currently use DAEMON/HOST scheme, but this will be changed later and is not to be used for any new principals
  47 you create''.
  48
  49 To add the Kerberos principal for a daemon, run this in kadmin:{{{
  50 addprinc -randkey -policy service $DAEMON}}}
  51
  52 AFS users exist separately from Kerberos principals.  To add the AFS user for a daemon to which you want to assign UID `$UID`, run:{{{
  53 pts createuser $DAEMON}}}
  54
  55 "keytab" files smooth the way to running daemons that run with AFS privileges. An access-protected local file contains a user's credentials, and daemons read these files on starting up in order to authenticate.
  56
  57 To create a keytab for a daemon, run this in kadmin:{{{
  58 ktadd -k /etc/keytabs/$DAEMON -e "des3-hmac-sha1:normal rc4-hmac:normal" $DAEMON
  59 chown $DAEMON:wheel /etc/keytabs/$DAEMON
  60 chmod 440 /etc/keytabs/$DAEMON
  61 }}}
  62
  63 In the example above, only one key (of 4 or 5 created) is exported for a user. Sometimes it might be desirable to
  64 only export a specific key into a keytab file, but we generally just omit the `-e KEY_TYPE` parameter and export
  65 all keys to the keytab file.
  66
  67 You can view keys stored in a keytab by doing `sudo klist -k /etc/keytabs/KEYTAB_FILE`.
  68
  69 To make daemons properly kinit/aklog as the user you created for them, use ``k5start`` command. Many examples
  70 of how to use it are already found in our /etc/init.d/ scripts. Important options include `-U` (which kinits as
  71 the first principal found in the keytab file, without the need to explicitly name a principal), -f (which specifies
  72 the keytab file to kinit from), and -K MINUTES (which re-news the ticket after MINUTES, so that daemons can run
  73 for long periods of time).
  74
  75 To give $DAEMON the actual permission in AFS space, for most common actions, `fs setacl DIR $DAEMON read` or `write`
  76 are good. All subdirectories that get created within the toplevel directory for which you give permissions, will
  77 inherit all the permissions.
  78
  79 = Listing and setting quotas =
  80
  81 To list volume quota, run{{{
  82 fs lq DIR
  83 }}}
  84
  85
  86 To set volume quota in 1-kilobyte blocks, run{{{
  87 fs sq DIR -max SIZE
  88 }}}