[[PageOutline]]
+Mostly written by Donald Guy, [[BR]]
+drawn from a variety of sources. [[BR]]
+Credit goes to them, blame goes to him.
+
= What is AFS? =
The '''Andrew File System''' or '''AFS''', is a distributed network file system invented at [http://www.cmu.edu/index.shtml Carnegie Mellon University] as part of Project Andrew (approximately their equivalent of MIT's Project Athena). More importantly, it is the file system used to store most files on Athena today. This includes your personal home directory, your dorm site, and probably some of the software you run, if you ever use clusters. (Though all user directories were migrated from NFS in the summer of 1992, some files probably still remain on NFS and, of course, various file systems are used on personal computers and servers).
= Some MIT/AFS terminology =
'''locker'''::
- For practical purposes, a folder. Probably the what you'll care about most of the time. Technically any directory mountable under /mit, regardless of how its stored. Today, most lockers (possibly all) lockers are stored in AFS.
+ For practical purposes, a folder. Probably the what you'll care about most of the time. Technically any directory mountable under /mit, regardless of how its stored. Today, most lockers lockers are stored in AFS.
'''tokens'''::
Essentially proof to the AFS servers that you are who you say you are, thus allowing you to access files you are supposed to. Analogous to Kerberos tickets.
= The Basics =
== 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
+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
=== 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:
+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.
=== 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.
+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.
+
+== Checking Quota ==
+
+You are only allocated a certain amount of disk space by MIT. To check the quota of the locker you are presently in run {{{fs listquota}}}. You will see output similar to the following:
+
+{{{
+user@host:/mit/chess-club$ fs listquota
+Volume Name Quota Used %Used Partition
+activity.chess-club 1500000 13163 1% 90%
+}}}
+
+
+If this information is good enough for you, then you are done. If not, read on.
= Common Tasks =
user rlidwka
}}}
-This is a list of users or [#MakinganAFSGroup 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
+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) ||
{{{<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$
+}}}
+
+
+See also: {{{man 1 fs}}}, {{{fs help <command>}}}
+
+== 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).
+
+see also: {{{man 1 pts}}}
+
+== 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>
+ }}}
+
+There after the users should be able to get to the folders at {{{http'''s'''://web.mit.edu/<locker>/<path to folder>}}} if they have certificates and no one should be able to reach it via http. Make sure to add yourself if you are going to be accessing it.
+
+see also: http://web.mit.edu/is/web/reference/web-resources/https.html
+
= 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 want {{{aklog athena sipb}}}
+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}}}
+
+=== I'd really prefer that not everyone could list my files, how should I stop this? ===
+What you '''don't''' want to do is take away the l permission from {{{system:anyuser}}} because then no one will be able to get to your `Public` or `www` which you probably don't want. All told, there is no way to stop people on Athena from listing your files (unless you keep everything under `Private` or a similarly restricted directory). It is rather trivial to stop web users, however. A solution I recommend, if you have a website in `www`, is to make a page `redirect.html` (or similar) with the contents like:
+{{{
+<html>
+<head>
+ <meta http-equiv="Refresh" content="0; url=http://www.mit.edu/~<lockername>/">
+</head>
+<body>
+ <p>Please go to my <a href="http://www.mit.edu/~<lockername>/">www</a>!</p>
+</body>
+</html>
+}}}
+
+and then doing a {{{ln -s www/redirect.html index.html}}} in the top level of the locker. Alternatively you can link index.html to a blank file in your `Public` or `www` (you can't simply it in the top level because its not readable there, this will result in a 403 Forbidden error).
+
+=== It was around 6am on a Sunday morning and suddenly I couldn't access my files ===
+Yea, IS&T restarts the AFS servers weekly around 6am.
+
+=== It isn't Sunday and I can't get to my files ===
+There may be a non-scheduled AFS outage. Check [http://3down.mit.edu 3down], hopefully it will be back up soon :-(.
= Advanced Tasks =
+
+
+== Putting Software in a Locker ==
+The Athena environment was designed to allow software to run on several architectures on the same network. On modern Athena, this means 32-bit x86s running Linux, 64-bit x86s running Linux, and SPARCs running Solaris. To accommodate these these various architectures AFS (at least on Athena) has a notion of what systems are compatible with the operating system. You can find these by running {{{fs sysname}}}.
+
+The special variable @sys in a path corresponds to the first of these that matches. When a user runs `add`, {{{/mit/<locker>/arch/@sys/bin}}} is added to their PATH and {{{/mit/<locker>/man}}} or {{{/mit/<locker>/arch/@sys/man}}} is added to their MANPATH.
+
+Primarily because of this fact, a typical locker is set up with the following sort of layout:
+{{{
+user@host:/mit/<some locker>$ tree -dL 2
+.
+|-- arch
+| |-- i386_linux22
+| |-- i386_linux24 -> i386_rhel4/
+| |-- i386_rh9 -> i386_linux24
+| |-- i386_rhel3 -> i386_rhel4
+| |-- i386_rhel4
+| |-- sgi_65
+| |-- sun4x_510
+| |-- sun4x_57
+| |-- sun4x_58 -> sun4x_510/
+| `-- sun4x_59 -> sun4x_58
+|-- bin -> arch/@sys/bin
+|-- include -> arch/@sys/include
+|-- info
+|-- lib -> arch/@sys/lib
+|-- man
+ `-- man1
+}}}
+
+Please note that the @sys variable should really be used ONLY in these convenience in symlinks. To make the folder in arch you usually want to either pick a more general architecture and set it up yourself or simply use the following command in the top level of the locker:
+{{{mkdir -p arch/$ATHENA_SYS/{bin,lib,include}}}}. After making this folder, make the shortcut symlinks with commands similar to {{{ln -s arch/@sys/bin bin}}} (again, this is the ''ONLY'' time you should use @sys yourself). Other than that, its mainly just a matter of making sure to run configure with options like {{{--prefix=/mit/<lockername>}}} and {{{--with-manpath=/mit/<lockername>/man}}}.
+
+See also: {{{man lockers}}}
+
+== Acquiring a new locker ==
+While it is easily possible to make an AFS group for yourself, it is harder to get a new locker. If you want a locker for something official like a student group or a piece of software, send an email to [mailto:accounts@mit.edu] explaining what you need it for and someone at IS&T will let you know. If you feel it is something less official or you would just rather consider it a SIPB project (perhaps get other SIPB people involved) send an email to [mailto:sipb-afsreq@mit.edu] instead. In either case, if a mount point under {{{/mit}}} fails to get set up for you, let [mailto:hesreq@mit.edu] know.
+
+= See Also =
+SIPB's older guide, [http://stuff.mit.edu/afs/sipb.mit.edu/project/doc/afs/html/afs-new.html Inessential AFS] [[BR]]
+OpenAFS documentation at [http://www.openafs.org/]
+
sipb-www / wiki.git / blobdiff