added info about webacls
[wiki.git] / doc / AFSAndYou
index c7fd941ac011614b25929f3219b99822a0f73c21..95ecfa63f94a925636e3af99470450ee396f4633 100644 (file)
@@ -20,8 +20,8 @@ For the most part using AFS, particularly at MIT, is well-hidden and can be used
 
 = The Basics =
 
-== The Layout of an MIT User Locker ==
-Every Athena user has a locker (their home directory) which mounts at {{{/mit/<username>}}} From a technical standpoint, its stored in the volume {{{user.<username>}}} which is located at {{{/afs/athena.mit.edu/user/<first letter>/<second letter>/<user name>}}} For example, the user {{{sipbtest}}} has a home directory that mounts at {{{/mit/sipbtest}}, is volume {{{user.sipbtest}}, and is accessible at {{{/afs/user/s/i/sipbtest}}}.
+== The Layout of a Typical MIT Locker ==
+Every Athena user has a locker (their home directory) which mounts at {{{/mit/<username>}}} From a technical standpoint, its stored in the volume {{{user.<username>}}} which is located at {{{/afs/athena.mit.edu/user/<first letter>/<second letter>/<user name>}}} For example, the user {{{sipbtest}}} has a home directory that mounts at {{{/mit/sipbtest}}}, is volume {{{user.sipbtest}}}, and is accessible at {{{/afs/user/s/i/sipbtest}}}. Projects, Dorms, Classes, etc. are all mounted at {{{/mit/<lockername>}}} and stored at various places in AFS
 
 Within this folder there are 4 special subdirectories you want to care about
 
@@ -32,9 +32,119 @@ Within this folder there are 4 special subdirectories you want to care about
  '''{{{OldFiles}}}'''::
   This folder is a link to a read-only copy of a backup of your files (created nightly at 3 a.m.) This copy can not be edited and does not count towards your quota. (From a technical standpoint, this is a separate volume, user.<username>.backup and is stored only as changes against the current copy). 
  '''{{{www}}}'''::
-  Where you should put a website, if you want one. There is very little special about this directory from an AFS standpoint, but it is world readable (like Public) and is linked directly if someone goes to {{{http://www.mit.edu/~<username>}}} (e.g. http://www.mit.edu/)
+  Where you should put a website, if you want one. There is very little special about this directory from an AFS standpoint, but it is world readable (like Public) and is linked directly if someone goes to {{{http://www.mit.edu/~<username>}}}
+
+
+== Accessing Lockers ==
+
+=== From Athena ===
+
+On Athena you can access a locker either as its full AFS path, if you know it ( e.g. /afs/athena.mit.edu/course/6/6.01 ) or under {{{/mit}}} if it is "attached." Yet a third way is to use tilde expansion and simply {{{ cd ~<locker> }}} (e.g. {{{cd ~6.01}}}) which will take you to the full path. Often, however, you want to attach lockers because it is easier to refer to them outside of the shell (in a script, for example) and software is set-up to run with a path under {{{/mit}}}. There are a few ways to attach a locker: 
+
+ * If you are running on a [http://debathena.mit.edu Debathena] machine, such as [http://linerva.mit.edu linerva.mit.edu], then simply {{{cd /mit/<locker>}}} and it will be auto-attached.
+ * If you are on another Athena machine and don't want to run software out of the locker, than simply type {{{attach <locker>}}} and then `cd` to it.
+ * If, however, you want to use software in the locker, you will be better served by running {{{add <locker>}}} (e.g. {{{add ruby-lang}}}). This will attach the locker at {{{/mit/<locker>}}} and will add the `bin` directory (for your architecture) of that locker to your PATH. What this means is that you should be able to run any software thereafter by simply typing the name of the program at the command line.
+
+
+=== From the Web ===
+
+Generally any locker that you would access on Athena as {{{/mit/<locker>}}} is accessible on the web as {{{{http://web.mit.edu/<locker>}}}. For example, the barnowl locker is at [http://web.mit.edu/barnowl]. As you can see, if there is no index.html (see below), the files in the directory are listed. By default, however, none of the contents are readable except in the `www` and `Public` folders.
+
+Also, you may access something in one of the MIT AFS cells by taking its full AFS path after web.mit.edu ([http://web.mit.edu/afs/athena.mit.edu/activity/c/chess-club]). (That link also shows that if you have a text file named README readable, as a link to Public/README for example, its contents will be displayed below the directory listing).
+
+If these options are good enough for you, then you are done. If not, read on.
 
 = Common Tasks =
 
+== Controlling Who can Access Files ==
+You may be familiar with Unix permissions. Sad to say, but that knowledge is basically useless here. Whereas Unix permissions, are per-file, AFS permissions are controlled by '''Access Control List'''s ('''ACL'''s) on a per-directory basis. 
+
+To view the ACL for a given directory (where you have permission to do so), run {{{fs listacl}}} or {{{fs la}}}, for short. For a typical user locker, the ACL in the top level will look like this 
+{{{
+user@host:~$ fs la
+Access list for . is
+Normal rights:
+  system:expunge ld
+  system:anyuser l
+  user rlidwka
+}}}
+
+This is a list of users or [#CreatinganAFSGroup AFS groups] and their permissions in this directory (and subdirectories that don't have their own ACL modifications). In AFS there are seven permissions as follows
+
+ ||'''r'''||  read   ||   user or members of group can read files in the directory    (i.e. see the contents of files)                  ||
+ ||'''l'''||  list   ||   user or members of group can list files in the directory    (i.e. see the names of files)                     ||
+ ||'''i'''||  insert ||   user or members of group can create files (or subdirectories) in the directory                                ||
+ ||'''d'''||  delete ||   user or members of group can delete files in the directory                                                    ||
+ ||'''w'''||  write  ||   user or members of group can modify files in the directory  (i.e. change the contents of files)               ||
+ ||'''k'''||  lock   ||   user or members of group can lock files in the directory   (you will likely never use this)                   ||
+ ||'''a'''||  admin  ||   user or members of group can see and change permissions. It does '''not''' affect pre-existing subdirectories.||
+
+To add a user or group to the ACL for a given directory simply run {{{fs setacl}}} or {{{fs sa}}} as follows:
+{{{
+fs sa <directory> <user or group> <permissions>
+}}}
+
+ {{{<directory>}}}::
+  can be an absolute or relative path, usually you will want {{{.}}}
+ {{{<user or group>}}}::
+  can be any user or group. Some you probably want to know: system:anyuser means EVERYONE (the entire AFS-using world plus the entire world wide web), system:expunge is the daemon for MIT's delete/lsdel/undelete utilities to work in a given directory.
+ {{{<permissions>}}}::
+ can be a string of the above letters (in any order) or any of the words `read`, `write`, `all` and `none` which are equivalent to `rl`, `rlidwk`, `rlidwka` and the empty string, respectively 
+
+For example, if `user` wants his friends `sipbtest` and `jarandom` to be able to read and write files and anyone to be able to read files in his `awesome_project` directory, he might have a session that looks like this
+
+{{{
+user@host:~$ cd awesome_project/
+user@host:~/awesome_project$ fs sa . system:anyuser read
+user@host:~/awesome_project$ fs sa . jarandom write
+user@host:~/awesome_project$ fs sa . sipbtest write
+user@host:~/awesome_project$ fs la
+Access list for . is
+Normal rights:
+  system:expunge ld
+  system:anyuser rl
+  sipbtest rlidwk
+  jarandom rlidwk
+  user rlidwka
+user@host:~/awesome_project$
+}}}
+
+== Creating an AFS Group ==
+The "normal" way to make an AFS group would be with a command similar to {{{pts creategroup <your user name>:<group name>}}} and then add people with {{{pts adduser <user> <full group name>}}}(e.g. If Donald Guy wanted to created a group for people to edit his www directory (including `sipbtest` and `jflorey`, he might use the following chain of commands {{{pts creategroup fawkes:www ; pts adduser sipbtest fawkes:www; pts adduser jflorey fawkes:www; fs sa ~/www fawkes:www write}}}
+
+This method will work, but at MIT, it is much more common to use moira lists as a group. To create a new list, use the web interface at https://wserv.mit.edu:444/fcgi-bin/lc? to create a moira list, NOT A MAILMAN LIST and be sure to check the box for "Should this list be an AFS Group?" (to make an already existing moira list into an AFS group simply {{{blanche -G <list>}}}). After the servers update (which may take anywhere between 1 second and 10 minutes depending on the number of similar requests), the AFS group system:<list name> will exist in the athena.mit.edu cell. 
+
+This is useful because one often wants the same certain people who can operate on files in a folder to be a mailing list. Thus, for example, it is possible to send mail to gnu@mit.edu and use system:gnu as an AFS group on ACLs. (it is also possible to make moira lists that are AFS groups, but not mailing lists).  
+
+== Controlling Access from the Web ==
+
+If you make a directory listable and readable by system:anyuser then it can be viewed by any user on the web via the urls mentioned [#FromtheWeb above]
+
+Unfortunately, just because you add specific users to an AFS ACL does not mean they can see the folder when the access from the web. IS&T, however, does provide a solution to this. First, make sure that the wanted directory is not readable by system:anyuser. Next {{{fs sa <dir> system:htaccess.mit read }}}. Then create a file named `.htaccess.mit` in that directory. In that file you can do three things, 
+
+ * You can require that the user have valid certificates:
+  {{{
+  <limit GET>
+  require valid-user
+  </limit>
+  }}}
+
+ * You can require the reader be (a) specific user(s), for example:
+  {{{
+  <limit GET>
+  require user fawkes jflorey siptest jarandom
+  </limit>
+  }}}
+ * You can require that the reader be a member of one of certain moira groups (notice these are '''moira''' groups, there is no "system:". For example:
+ {{{
+ <limit GET>
+  require group sipb-staff sipb-prospectives
+ </limit>
+ }}}
+
+
+= Troubleshooting =
+=== I'm trying to access my files, {{{fs la}}} says I should have permissions here, but it still says {{{: Permission denied}}} ===
+There are two likely possibilities. First, its likely that your tokens may have expired. To get new tokens, make sure you have valid kerberos tickets and then run {{{aklog}}}. Another possibility is that you have tokens but not for the correct cell. {{{tokens}}} will tell you what tokens you already have. In all likelihood, if you are reading this, you probably want {{{aklog athena sipb}}}
 
 = Advanced Tasks =