--- /dev/null
- require user fawkes jflorey siptest jarandom
+[[!meta title="AFS and You"]]
+
+<div style="float: right; font-size: 0.8em; background-color: #D0D0D0; margin: 1em;">
+ <ol>
+ <li><a href="#WhatisAFS">What is AFS?</a></li>
+ <li><a href="#SomeMITAFSterminology">Some MIT/AFS terminology</a></li>
+ <li><a href="#TheBasics">The Basics</a>
+ <ol><li><a href="#TheLayoutofaTypicalMITLocker">The Layout of a Typical MIT Locker</a></li>
+ <li><a href="#AccessingLockers">Accessing Lockers</a>
+ <ol><li><a href="#FromAthena">From Athena</a></li>
+ <li><a href="#FromtheWeb">From the Web</a></li>
+ </ol>
+ <li><a href="#CheckingQuota">Checking Quota</a></li>
+ </ol>
+ <li><a href="#CommonTasks">Common Tasks</a>
+ <ol><li><a href="#ControllingWhocanAccessFiles">Controlling Who can Access Files</a></li>
+ <li><a href="#CreatinganAFSGroup">Creating an AFS Group</a></li>
+ <li><a href="#ControllingAccessfromtheWeb">Controlling Access from the Web</a></li>
+ </ol>
+ <li><a href="#Troubleshooting">Troubleshooting</a>
+ <ol>
+ <li><a href="#ImtryingtoaccessmyfilesfslasaysIshouldhavepermissionsherebutitstillsays:Permissiondenied">I'm trying to access my files, <tt>fs la</tt> says I should have permissions …</a></li>
+ <li><a href="#IdreallypreferthatnoteveryonecouldlistmyfileshowshouldIstopthis">I'd really prefer that not everyone could list my files, how should I stop …</a></li>
+ <li><a href="#Itwasaround6amonaSundaymorningandsuddenlyIcouldntaccessmyfiles">It was around 6am on a Sunday morning and suddenly I couldn't access my …</a></li>
+ <li><a href="#ItisntSundayandIcantgettomyfiles">It isn't Sunday and I can't get to my files</a></li>
+ </ol>
+ <li><a href="#AdvancedTasks">Advanced Tasks</a>
+ <ol>
+ <li><a href="#PuttingSoftwareinaLocker">Putting Software in a Locker</a></li>
+ <li><a href="#Acquiringanewlocker">Acquiring a new locker</a></li>
+ </ol>
+ <li><a href="#SeeAlso">See Also</a></li>
+ </ol>
+</div>
+
+
+<p>
+Mostly written by Donald Guy, <br />
+drawn from a variety of sources. <br />
+Credit goes to them, blame goes to him.
+</p>
+<h2 id="WhatisAFS">What is AFS?</h2>
+<p>
+The <strong>Andrew File System</strong> or <strong>AFS</strong> is a distributed network file system invented at <a href="http://www.cmu.edu/index.shtml">Carnegie Mellon University</a> 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, the data and websites of many living groups and student groups on campus, and probably some of the software you run (if you ever use Athena 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.)
+
+</p>
+<p>
+<strong><i>In Short: AFS is probably where some of the files you care about live</i></strong>
+</p>
+<p>
+For the most part, using AFS, particularly at MIT, is well-hidden and can be used like any other UNIX file system. For some things, you will need to know a bit more. Let's start by defining some terms.
+</p>
+<h2 id="SomeMITAFSterminology">Some MIT/AFS terminology</h2>
+<dl><dt><strong>locker</strong></dt><dd>
+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.
+</dd></dl>
+<dl><dt><strong>tokens</strong></dt><dd>
+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.
+
+</dd></dl>
+<dl><dt><strong>cell</strong></dt><dd>
+AFS concept of an "administrative domain of authority." Each cell has its own set of users, groups, and administrators. Analogous to a Kerberos realm. Each top-level directory in /afs corresponds to a cell. The cells you are most likely to care about are <tt>athena.mit.edu</tt> and <tt>sipb.mit.edu</tt>.
+</dd></dl>
+<h2 id="TheBasics">The Basics</h2>
+<h2 id="TheLayoutofaTypicalMITLocker">The Layout of a Typical MIT Locker</h2>
+<p>
+Every Athena user has a locker (their home directory), which mounts at <tt>/mit/<username></tt>. From a technical standpoint, it is stored in the volume <tt>user.<username></tt> which is located at <tt>/afs/athena.mit.edu/user/<first letter>/<second letter>/<user name></tt>. For example, the user <tt>joeuser</tt> has a home directory that mounts at <tt>/mit/joeuser</tt>, is volume <tt>user.joeuser</tt>, and is accessible at <tt>/afs/user/j/o/joeuser</tt>. Lockers for projects, software, classes, living groups, and student groups are all mounted at <tt>/mit/<lockername></tt> and stored at various places in AFS.
+
+</p>
+<p>
+Within each locker, there are (by default) 4 special subdirectories you want to care about.
+</p>
+<dl><dt><strong><tt>Public</tt></strong></dt><dd>
+By default, this directory can be read by everyone (and I do mean EVERYONE!), so put files here you want to share with the entire world.
+</dd><dt><strong><tt>Private</tt></strong></dt><dd>
+By default, this directory can only be read and can only be <i>listed</i> by you (from AFS, not from web) whereas the files in other directories can (by default) only be read by you, but can be listed by anyone. This means that other people can't see the contents of your files, but they can see what files you have outside of <tt>Private</tt>
+</dd><dt><strong><tt>OldFiles</tt></strong></dt><dd>
+
+This folder is a link to a read-only copy of a backup of your files (created nightly at 3 a.m.). This copy cannot be edited and does not count towards the locker's quota. (From a technical standpoint, this is a separate volume, user.<username>.backup and is stored only as changes against the current copy.)
+</dd><dt><strong><tt>www</tt></strong></dt><dd>
+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 to <tt>http://www.mit.edu/~<lockername></tt> as well as <tt>http://web.mit.edu/<lockername></tt>.
+</dd></dl>
+<h2 id="AccessingLockers">Accessing Lockers</h2>
+<h3 id="FromAthena">From Athena</h3>
+
+<p>
+On Athena, you can access a locker either as its full AFS path, if you know it (e.g. <tt>/afs/athena.mit.edu/course/6/6.01</tt>), or under <tt>/mit</tt> if it is "attached." Yet a third way is to use tilde expansion and simply <tt> cd ~~<locker> </tt> (e.g. <tt>cd ~~6.01</tt>) 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 <tt>/mit</tt>. There are a few ways to attach a locker:
+
+</p>
+<ul><li>If you are running on a <a href="http://debathena.mit.edu">Debathena</a> machine, such as <a href="http://linerva.mit.edu">linerva.mit.edu</a>, then simply <tt>cd /mit/<locker></tt> and it will be auto-attached.
+</li><li>If you are on another Athena machine and don't want to run software out of the locker, than simply type <tt>attach <locker></tt> and then <tt>cd</tt> to it.
+
+</li><li>If, however, you want to use software in the locker, you will be better served by running <tt>add <locker></tt> (e.g. <tt>add ruby-lang</tt>). This will attach the locker at <tt>/mit/<locker></tt> and will add the <tt>bin</tt> directory (for your architecture) of that locker to your PATH. What this means is that you should be able to run any program located in that locker by simply typing the name of the program at the command line.
+<ul><li>If you frequently use the same locker, it may be helpful for you to add the <tt>add <locker></tt> command to your <tt>.environment</tt> file. To do this simply from the Athena command line, type <tt>echo "add lockername" > ~/.environment</tt> or <tt>echo "add lockername >> ~/.environment</tt>.
+
+</li></ul></li></ul><h3 id="FromtheWeb">From the Web</h3>
+<p>
+Generally any locker that you would access on Athena as <tt>/mit/<locker></tt> is accessible on the web as <tt>http://web.mit.edu/<locker></tt>. For example, the barnowl locker is at <a href="http://web.mit.edu/barnowl">http://web.mit.edu/barnowl</a>. 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 <tt>www</tt> and <tt>Public</tt> folders.
+
+</p>
+<p>
+Also, you may access something in one of the MIT AFS cells by taking its full AFS path after web.mit.edu (<a href="http://web.mit.edu/afs/athena.mit.edu/activity/c/chess-club">http://web.mit.edu/afs/athena.mit.edu/activity/c/chess-club</a>). (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).
+</p>
+<h2 id="CheckingQuota">Checking Quota</h2>
+<p>
+You are only allocated a certain amount of disk space by MIT. To check the quota of the locker you are presently in run <tt>fs listquota</tt>. You will see output similar to the following:
+</p>
+<pre>user@host:/mit/chess-club$ fs listquota
+Volume Name Quota Used %Used Partition
+activity.chess-club 1500000 13163 1% 90%
+</pre><p>
+If this information is good enough for you, then you are done. If not, read on.
+</p>
+
+<h2 id="CommonTasks">Common Tasks</h2>
+<h2 id="ControllingWhocanAccessFiles">Controlling Who can Access Files</h2>
+<p>
+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 <strong>Access Control List</strong>s (<strong>ACL</strong>s) on a per-directory basis.
+</p>
+<p>
+To view the ACL for a given directory (where you have permission to do so), run <tt>fs listacl</tt> or <tt>fs la</tt>, for short. For a typical user locker, the ACL in the top level will look like this
+
+</p>
+<pre>user@host:~$ fs la
+Access list for . is
+Normal rights:
+ system:expunge ld
+ system:anyuser l
+ user rlidwka
+</pre><p>
+This is a list of users or <a href="#CreatinganAFSGroup">AFS groups</a> and their permissions in this directory (and subdirectories that don't have their own ACL modifications). In AFS there are seven permissions as follows
+</p>
+<blockquote>
+<table>
+<tr><td><strong>r</strong></td><td> read </td><td> user or members of group can read files in the directory (i.e. see the contents of files)
+</td></tr><tr><td><strong>l</strong></td><td> list </td><td> user or members of group can list files in the directory (i.e. see the names of files)
+
+</td></tr><tr><td><strong>i</strong></td><td> insert </td><td> user or members of group can create files (or subdirectories) in the directory
+</td></tr><tr><td><strong>d</strong></td><td> delete </td><td> user or members of group can delete files in the directory
+</td></tr><tr><td><strong>w</strong></td><td> write </td><td> user or members of group can modify files in the directory (i.e. change the contents of files)
+</td></tr><tr><td><strong>k</strong></td><td> lock </td><td> user or members of group can lock files in the directory (you will likely never use this)
+
+</td></tr><tr><td><strong>a</strong></td><td> admin </td><td> user or members of group can see and change permissions. It does <strong>not</strong> affect pre-existing subdirectories.
+</td></tr></table>
+</blockquote>
+<p>
+To add a user or group to the ACL for a given directory simply run <tt>fs setacl</tt> or <tt>fs sa</tt> as follows:
+
+</p>
+<pre>fs sa <directory> <user or group> <permissions>
+</pre><dl><dt><tt><directory></tt></dt><dd>
+can be an absolute or relative path, usually you will want <tt>.</tt>
+</dd><dt><tt><user or group></tt></dt><dd>
+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.
+</dd><dt><tt><permissions></tt></dt><dd>
+
+can be a string of the above letters (in any order) or any of the words <tt>read</tt>, <tt>write</tt>, <tt>all</tt> and <tt>none</tt> which are equivalent to <tt>rl</tt>, <tt>rlidwk</tt>, <tt>rlidwka</tt> and the empty string, respectively
+
+</dd></dl>
+<p>
+For example, if <tt>user</tt> wants his friends <tt>sipbtest</tt> and <tt>jarandom</tt> to be able to read and write files and anyone to be able to read files in his <tt>awesome_project</tt> directory, he might have a session that looks like this
+</p>
+<pre>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$
+
+</pre><p>
+See also: <tt>man 1 fs</tt>, <tt>fs help <command></tt>
+</p>
+<h2 id="CreatinganAFSGroup">Creating an AFS Group</h2>
+<p>
+The "normal" way to make an AFS group would be with a command similar to <tt>pts creategroup <your user name>:<group name></tt> and then add people with <tt>pts adduser <user> <full group name></tt>(e.g. If Donald Guy wanted to created a group for people to edit his www directory (including <tt>sipbtest</tt> and <tt>jflorey</tt>, he might use the following chain of commands <tt>pts creategroup fawkes:www ; pts adduser sipbtest fawkes:www; pts adduser jflorey fawkes:www; fs sa ~/www fawkes:www write</tt>
+
+</p>
+<p>
+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 <a href="https://wserv.mit.edu:444/fcgi-bin/lc">https://wserv.mit.edu:444/fcgi-bin/lc</a>? 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 <tt>blanche -G <list></tt>). 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.
+</p>
+<p>
+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).
+</p>
+<p>
+see also: <tt>man 1 pts</tt>
+
+</p>
+<h2 id="ControllingAccessfromtheWeb">Controlling Access from the Web</h2>
+<p>
+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 <a href="#FromtheWeb">above</a>
+</p>
+<p>
+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 <tt>fs sa <dir> system:htaccess.mit read </tt>. Then create a file named <tt>.htaccess.mit</tt> in that directory. In that file you can do three things,
+
+</p>
+<ul><li>You can require that the user have valid certificates:
+<pre> <limit GET>
+ require valid-user
+ </limit>
+</pre></li></ul><ul><li>You can require the reader be (a) specific user(s), for example:
+<pre> <limit GET>
++ require user fawkes jflorey sipbtest jarandom
+ </limit>
+
+</pre></li><li>You can require that the reader be a member of one of certain moira groups (notice these are <strong>moira</strong> groups, there is no "system:". For example:
+<pre> <limit GET>
+ require group sipb-staff sipb-prospectives
+ </limit>
+</pre></li></ul><p>
+There after the users should be able to get to the folders at <tt>http<b>s</b>://web.mit.edu/<locker>/<path to folder></tt> 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.
+
+</p>
+<p>
+see also: <a href="http://web.mit.edu/is/web/reference/web-resources/https.html">http://web.mit.edu/is/web/reference/web-resources/https.html</a>
+</p>
+<h2 id="Troubleshooting">Troubleshooting</h2>
+<h3 id="ImtryingtoaccessmyfilesfslasaysIshouldhavepermissionsherebutitstillsays:Permissiondenied">I'm trying to access my files, <tt>fs la</tt> says I should have permissions here, but it still says <tt>: Permission denied</tt></h3>
+<p>
+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 <tt>aklog</tt>. Another possibility is that you have tokens but not for the correct cell. <tt>tokens</tt> will tell you what tokens you already have. In all likelihood, if you are reading this, you probably want <tt>aklog athena sipb</tt>. Finally, a third possibility is that your group membership has changed since you acquired tokens. Try running <tt>aklog -force</tt>
+
+</p>
+<h3 id="IdreallypreferthatnoteveryonecouldlistmyfileshowshouldIstopthis">I'd really prefer that not everyone could list my files, how should I stop this?</h3>
+<p>
+What you <strong>don't</strong> want to do is take away the l permission from <tt>system:anyuser</tt> because then no one will be able to get to your <tt>Public</tt> or <tt>www</tt> 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 <tt>Private</tt> or a similarly restricted directory). It is rather trivial to stop web users, however. A solution I recommend, if you have a website in <tt>www</tt>, is to make a page <tt>redirect.html</tt> (or similar) with the contents like:
+
+</p>
+<pre><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>
+</pre><p>
+and then doing a <tt>ln -s www/redirect.html index.html</tt> in the top level of the locker. Alternatively you can link index.html to a blank file in your <tt>Public</tt> or <tt>www</tt> (you can't simply it in the top level because its not readable there, this will result in a 403 Forbidden error).
+</p>
+<h3 id="Itwasaround6amonaSundaymorningandsuddenlyIcouldntaccessmyfiles">It was around 6am on a Sunday morning and suddenly I couldn't access my files</h3>
+
+<p>
+Yeah, most AFS servers restart weekly at 6 AM on Sunday.
+</p>
+<h3 id="ItisntSundayandIcantgettomyfiles">It isn't Sunday and I can't get to my files</h3>
+<p>
+There may be a non-scheduled AFS outage. Check <a href="http://3down.mit.edu">3down</a>, hopefully it will be back up soon :-(.
+</p>
+<h2 id="AdvancedTasks">Advanced Tasks</h2>
+<h2 id="PuttingSoftwareinaLocker">Putting Software in a Locker</h2>
+<p>
+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 <tt>fs sysname</tt>.
+
+</p>
+<p>
+The special variable @sys in a path corresponds to the first of these that matches. When a user runs <tt>add</tt>, <tt>/mit/<locker>/arch/@sys/bin</tt> is added to their PATH and <tt>/mit/<locker>/man</tt> or <tt>/mit/<locker>/arch/@sys/man</tt> is added to their MANPATH.
+
+</p>
+<p>
+Primarily because of this fact, a typical locker is set up with the following sort of layout:
+</p>
+<pre>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
+
+</pre><p>
+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:
+<tt>mkdir -p arch/$ATHENA_SYS/{bin,lib,include</tt>}. After making this folder, make the shortcut symlinks with commands similar to <tt>ln -s arch/@sys/bin bin</tt> (again, this is the <i>ONLY</i> time you should use @sys yourself). Other than that, its mainly just a matter of making sure to run configure with options like <tt>--prefix=/mit/<lockername></tt> and <tt>--with-manpath=/mit/<lockername>/man</tt>.
+
+</p>
+<p>
+See also: <tt>man lockers</tt>
+</p>
+
+<h2 id="Acquiringanewlocker">Acquiring a new locker</h2>
+<p>
+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 <a href="mailto:accounts@mit.edu">accounts@mit.edu</a> 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 <a href="mailto:sipb-afsreq@mit.edu">sipb-afsreq@mit.edu</a> instead. In either case, if a mount point under <tt>/mit</tt> fails to get set up for you, let <a href="mailto:hesreq@mit.edu">hesreq@mit.edu</a> know.
+</p>
+
+
+<h2 id="SeeAlso">See Also</h2>
+<p>SIPB's older guide, <a href="http://stuff.mit.edu/afs/sipb.mit.edu/project/doc/afs/html/afs-new.html">Inessential AFS</a> <br /> OpenAFS documentation at <a href="http://www.openafs.org/">http://www.openafs.org/</a>
+</p>
+
--- /dev/null
- word-wrapped to 70-character lines or so; Pressing M-q (Alt-q, or
- Escape then q) will word-wrap the text you've entered for you.
+[[!meta title="Using Zephyr (a.k.a. Zephyr For Dummies)"]]
+
+<!-- For information on the archaic way of using Zephyr, see TraditionalZephyr.-->
+
+## Introduction to Zephyr
+
+Zephyr was a system designed to let system administrators send
+important messages to users in an easily noticeable format. It was
+meant to have a low volume of traffic and be used only for official
+notices. This is obviously not what Zephyr is today. It can still be
+used in the way it was intended: notice that you get official
+zephyrgrams as you log in, with important information about Athena
+services and planned outages. However, the most common usage is by
+average users exchanging information about classes, how their days are
+going, and talking on Zephyr classes and instances about everything
+from the latest episode of Battlestar Galactica to the next 18.03
+problem set. The usage of Zephyr has far exceeded original
+expectations. Over time, people have also created programs that give
+Zephyr a graphical interface, and programs that give zephyr a purely
+textual interface, that can be used entirely within a ssh
+terminal. Some of these zephyr clients have become so widely used that
+there are users who do not know that there are other ways to send (and
+receive) zephyrgrams. This wiki will cover the traditional commands,
+typed at the athena% prompt, as well as the more common modern zephyr
+client Barnowl.
+
+The information in this wiki about Barnowl just barely touches the
+surface. More for in-depth functionality, visit the [Barnowl
+wiki](https://barnowl.scripts.mit.edu:444/wiki).
+
+## Modern Zephyr
+
+Today the majority of Zephyr users use the barnowl client. There are
+other clients as well (for example, Pidgin supports Zephyr). The
+following sections will go into detail about how to install, use, and
+customize barnowl.
+
+### Other Clients
+
+There are other clients besides Barnowl, however their use is not
+nearly as widespread. Some of these include:
+
+* Owl (unmaintained, Barnowl evolved from this)
+* vt / jervt
+* zwgc (see TraditionalZephyr)
+* Pidgin
+* zephyr-mode for emacs
+
+Using Barnowl is recommended, as it is better supported and more
+documentation exists for it.
+
+### Using Barnowl
++You will need access to an Athena machine to run barnowl. The easiest
++way to do this would be to SSH into linerva.mit.edu.
++
++On a Debian-based linux distro, open up a terminal and type `ssh
++<username>@linerva.mit.edu`.
++
++On Windows, download a SSH client (such as
++[PuTTY](http://chiark.greenend.org.uk/~sgtatham/putty/download.html))
++and install it. Once you've opened it, type `<username>@linerva.mit.edu`
++into the prompt and hit enter.
++
++On a Mac, open Terminal from the Utilities Folder in Applications. Type
++`kinit <username>@ATHENA.MIT.EDU && ssh -K
++<username>@linerva.mit.edu` If this command fails (saying -K is
++invalid), then just do `ssh <username>@linerva.mit.edu`.
++
++(In all these cases, don't include the angle brackets, just replace
++<username> with your MIT username). You will then be prompted for your
++password. Enter it, and then carry on with running barnowl!
+
+To start barnowl, run the command `add barnowl; barnowl` at the prompt
+on any Athena machine or dialup, such as linerva.mit.edu.
+
+The simplest use of Zephyr is to send personal zephyrs to other
+users. To send a zephyr, type `:` to bring up a command line, and run
+the command `zwrite USERNAME`. You can also start a `zwrite` command
+by simply typing z.
+
+You can then enter your message, and then enter a `.` on a line by
+itself to finish the zephyr. By convention, zephyrs are usually
- <strong>"un" Classes</strong>:
- > Many people use "un" classes in addition to their personal class,
- > for example `johndoe` might use `-c unjohndoe`. Sometimes there are
- > nested un-classes as well, such as `-c ununjohndoe` or `-c
- > unununjohndoe`. It is extremely rare to see anything more than
- > three "un"s. Un-classes are generally used for snarking about a
- > conversation going on in the next class up (`-c unjohndoe` snarking
- > about `-c johndoe`), or for more intense ranting. The more "un"s,
- > the more intense the snarking/ranting generally becomes.
-
++word-wrapped to 70 characters or so per line; barnowl will wrap at about
++10 characters less than the width of your terminal window, so if you
++have a large window, you may need to press M-q (Alt-q, or Escape then q)
++to word-wrap the current paragraph to a smaller width.
+
+Once you've sent and received zephyrs, you can navigate the message
+list with the arrow keys. Press `d` to mark a message as deleted, `u`
+to undelete it, and `x` to expunge all messages that have been marked
+as deleted.
+
+Instead of entering a `zwrite` command manually, you can also select a
+message in the message list with the arrow keys, and reply to it using
+`r`, which will automatically set up an appropriate `zwrite` command.
+
+For more documentation on the built-in commands and keybindings, you
+can press h to bring up barnowl's built-in help screen. For help with
+a specific command, bring up a command line with `:` and then type
+`help COMMAND`.
+
+### Classes and Instances
+
+Generally the most interesting discussion on Zephyr, however, happens
+on so-called Zephyr <em>classes</em>. A class is a bit like a chat
+room in other IM systems. Anyone can send a zephyr to a class, and
+anyone who is subscribed to that class will receive it. There is no
+security on classes -- anyone who knows the name of a class can
+subscribe, and there is no way to determine who is subscribed to a
+given class.
+
+To subscribe to a class, use the subscribe command:
+
+ :subscribe CLASSNAME * *
+
+To send a zephyr to a class, use the zwrite command with the -c option:
+
+ :zwrite -c CLASSNAME
+
+Zephyrs to classes usually have an instance attached. An instance is a
+short “topic” or “subject” that indicates the
+context of a zephyr. Different instances are often used to multiplex
+multiple conversations on a high-traffic class. You can specify an
+instance with the -i option to zwrite:
+
+ :zwrite -c CLASSNAME -i INSTANCE
+
+A message without an instance specified will default to the instance
+“personal”.
+
+Some common classes include:
+
+<strong>help</strong>:
+> -c help is a class for asking (and answering) questions on virtually
+> any topic imaginable. Be sure to use an instance (such as
+> “linux”, “barnowl”, “campus”, or
+> so on) when asking questions, since it's a fairly high-traffic
+> class.
+
+<strong>sipb</strong>:
+> -c sipb is where most SIPB members hang out. It's a place for
+> technical discussion, questions, support, and organizing SIPB events
+> or projects. You should also always use an instance when sending to
+> -c sipb.
+
+<strong>Personal Classes</strong>:
+> By convention, nearly every Zephyr user has a "personal" class that
+> is the same as their username. How this class is used varies from
+> person to person, but it's often a sort of mini-blog, a place to
+> report what one is working on or up to, or ask friends questions, or
+> just rant about something.
+
- talk to, so you can run the Athena command
+### Zephyr Slang
+
+If you spend enough time on Zephyr, you'll begin noticing some strange
+phrases and words being thrown around. Some of these include:
+
+<strong>i,i foo</strong>:
+> picked up from CMU zephyrland and means "I have no point here, I
+> just like saying:". Sometimes people simply use quotes: `"foo"`.
+
+<strong>mix</strong>:
+> If somebody accidentally sends a Zephyr to the wrong class or
+> person, they will send another Zephyr to that wrong/class person
+> simply saying "mix". This basically just means, "oops, sorry, I
+> didn't mean to send that Zephyr here". You might also see "-i mix",
+> which is the same thing, only with instances.
+
+<strong>.d</strong>:
+> You may see an instance change from `-i foo` to `-i foo.d`. This
+> indicates a deviation or tangent from the the original topic.
+
+<strong>starking</strong>:
+> Answering a question or replying to a topic to a topic several hours
+> (or days, occasionally) later. The term originates from Greg Stark,
+> who would often reply to zephyrs hours or occasionally days later
+> without seeing if anyone had answered yet, or worse, if the instance
+> had moved on to an entirely different topic.
+
+<strong>ttants</strong>:
+> Literally, "Things That Are Not The Same".
+
+<strong>prnf</strong>:
+> Literally, "Pseudo-Random Neuron Firings".
+
+There are many other acronyms that are used; if you don't know what it
+means, try using the `whats foo` command at an Athena terminal. If you
+don't have the command, run `add sipb` first.
+
++### Zephyr Etiquette
++
++There are rules that people tend to use on Zephyr. These include:
++
++Good grammar, spelling, and punctuation. Not everybody uses
++capitalization, but they will still use good English. Please do not say
++things such as "hey wut r u up to???". It makes you look like an idiot.
++Really.
++
++You don't need multiple question marks or exclamation points. Usually.
++
++There are a few abbreviations people use, such as YMMV (Your Mileage May
++Vary) or IIRC (If I Remember Correctly), as well as some nerdier ones
++like DTRT (Do The Right Thing, in reference to
++[http://www.jwz.org/doc/worse-is-better.html The Rise of "Worse Is
++Better"]). Try running `add outland; whats dtrt` to look up an
++abbreviation. Common abbreviations that you might find on AIM, however,
++are not often used. People tend to look down upon "lol", "rofl", and
++such.
++
++Personal classes are by convention considered a little more private than
++non-personal (public) classes. Although most people don't mind people
++they've met subscribing to their personal class and lurking, it's poor
++form to talk loudly on the personal class of someone you don't know.
++
+### Startup
+
+There might be some options that you want to be consistent from
+session to session; you don't want to have to set the same variables
+each time. You can fix this by adding the commands to your "startup"
+file, for example, `.owl/startup`. This can be done from within
+Barnowl, by using the `startup` command:
+
+ :startup set foo bar
+
+Where `foo` is the variable you want to set, and `bar` is the value.
+You do not necessarily have to use the `set` command, either, any
+command you can type in Barnowl can be added to the startup file.
+
+### Logging
+
+It is handy to be able to log your conversations so you can refer back
+to them later. To log classes, for example:
+
+ :set classlogging on
+
+And to log personals:
+
+ :set logging on
+
+This will log to the "zlog" directory in your locker. You probably
+don't want people to see what classes you're on or what people you
- to make this directory completely hidden.
++talk to, so you can run the Athena commands
+
+ mkdir -p ~/zlog
+ fs sa ~/zlog system:anyuser none
++ mkdir -p ~/zlog/people
++ mkdir -p ~/zlog/class
+
++to create the necessary directories and make them completely hidden.
+
+### Colors
+
+By default, there are seven colors you may use in the terminal: red,
+green, yellow, blue, magenta, cyan, and white. In order to use color
+in Zephyr, you can use the following notation: `@(@color(red)This is
+some red text))`
+
+Colors may vary from machine to machine, as different terminal
+profiles may have different shades of the seven colors.
+
+### Filters
+
+Some people like to customize their Barnowl by color-coding classes.
+This makes it easier to tell different classes apart (and minimize
+mixing). Barnowl has some already existing filters, for example,
+`personal` (for incoming personals), `out` (for outgoing personals),
+and `ping` (for pings). To assign a color to a filter, add the
+following to your startup file:
+
+ filter personal -c green
+
+What if you want to color-code your class, or a friends class? You
+can create and color filters with:
+
+ filter johndoe class johndoe
+ filter johndoe -c blue
+
+You can update your settings and filters without restarting your
+Barnowl session by:
+
+ :source ~/path/to/config/file
+
+You can see all the filters by using `:show filters`, and narrow to a
+particular filter with, e.g., `:view personal`. You can use `:view
+all` or the keyboard shortcut `V` to see all messages again.
+
+For more detailed information on filters, visit
+https://barnowl.scripts.mit.edu:444/wiki/Filters.
+
+## Running Barnowl in Screen
+
+It can be very annoying to have to close Barnowl when you turn off
+your computer. During the time your computer is off, you're missing
+many (possibly important) zephyrs. It can be aggravating to be using
+zephyr via an unreliable network connection. It can also be
+frustrating if you leave your computer on with Zephyr up, but go to a
+different computer and want to check your zephyrs - how do you do
+this? These problems can be solved with the magic of screen.
+
+A more detailed and extensive explanation of this can be found at
+http://web.mit.edu/kchen/bin/owl-screen.txt.
+
+### Screen
+
+You should find a computer or server on which to run your screen
+session(s) that is up all the time, for example, linerva.mit.edu.
+Screen allows you to run programs inside of it on one computer, and to
+access those same programs from other computers via ssh.
+
+### Quickstart
+
+1. Pick a machine to host your screen session on.
+ If you don't know of any options, linux.mit.edu (Linerva) is a good choice.
+2. ssh to that machine.
+3. Run "add kchen". You may want to add this to your `~/.environment` file.
+4. Run "owl-screen"
+
+Your screen session is now ready. Once you start the screen session,
+you'll need to get renewable Kerberos tickets in order to run it for
+any extended period of time. Press C-a C-c to open a new screen
+window, and run
+
+ kinit -l7d -54
+
+(length 7 days, both Kerberos 5 and Kerberos 4). Press C-a 0 to return
+back to your Barnowl window.
+
+When you're ready to log out, press C-a d to "detach" your screen, and
+then type `exit` or `logout` to log out. Later, when you want to
+"reattach" your screen, ssh to the machine again, and run `screen -r`.
+
+### Kerberos Tickets and AFS Tokens
+
+In order to keep your screen session authenticated, you'll need to
+keep your Kerberos tickets and AFS tokens up-to-date. There is a
+script that will do this for you, located in the `kchen` locker.
+After you ssh into the machine that hosts your screen sessions, run
+the following commands:
+
+ add kchen
+ owl-screen
+ C-a C-c
+ kinit -l1d -r7d -54
+
+### Attaching and Detaching Sessions
+
+To detach a screen session (for example, if you want to log out),
+press C-a d (Control-A, then D). Screen continues to run, but is no
+longer active.
+
+To reattach a screen session, possibly detaching from wherever it's
+currently attached, run:
+
+ screen -dr
+
+`screen` can do a whole lot more. To find out about it, see
+[UsingScreen](https://sipb-www.scripts.mit.edu:444/doc/wiki/UsingScreen).
++
++### Interaction with Traditional Zephyr
++
++The default athena startup scripts launch zwgc on login. If you are
++subscribed to many classes and use Zephyr as many do today, zwgc's
++behavior is not very desirable. To disable zwgc startup, add:
++
++ setenv ZEPHYR_CLIENT false
++
++to your `~/.environment` file if you use `tcsh` or
++
++ ZEPHYR_CLIENT=false
++
++to your `~/.bash_environment` if you use `bash`. This will cause your
++shell to launch the `false` executable instead of zwgc which does
++nothing.
sipb-www / wiki.git / commitdiff
