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