ee25310d |
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 |