--- /dev/null
+##Zephyr Quickstart
+
+This is a short and efficient guide for quickly getting on Zephyr. It'll explain everything you need to know to start zephyring as quickly, and reliably, as possible. Zephyr is a fairly old piece of technology, so it can be a little intimidating at first.
+
+This guide assumes only basic understanding of how to use a terminal.
+
+###Get mosh
+
+[Mosh](https://mosh.org) is like `ssh`, which lets you securely log into a
+remote computer, but with the extra functionality of roaming. If
+you computer moves across networks, the connection won't drop. This
+is often useful.
+
+If on Linux, install mosh via package manager; if on macOS, via
+[homebrew](https://brew.sh/) or [macports](https://www.macports.org/);
+if on Windows, install [Mosh for Chrome](https://github.com/rpwoodbu/mosh-chrome/wiki).
+
+If on Linux/macOS, the incantation for logging into athena with mosh is:
+
+`
+mosh --ssh="ssh -K" --server="athrun mosh_project mosh-server" user@hostname
+`
+
+The `-K` part will allow you to use Kerberos tickets on your machine,
+you have them. From here on out we refer to the above incantation as
+`mosh`.
+
+### Pick a dialup
+Log into one of the Athena dialups with the command
+`mosh user@athena.dialup.mit.edu` where `user` is your Athena
+username. Log in with your Athena password. Once on a dialup, run
+`echo $HOST` to learn the name of the machine (for example,
+`mass-toolpike` or `biohazard-cafe`). You can use the Moira command
+`stella $HOST` to learn aliases for the hostname for quicker
+logins. If you were logged into `mass-toolpike.mit.edu`, for example, you
+might log in with `mosh user@i90.mit.edu`. (If you're on campus,
+you can omit the `.mit.edu` part.)
+
+The reason for doing this ceremony of picking one Athena dialup to
+use consistently will become clear in the next step.
+
+### Prepare a screen session
+Log into the dialup you picked above and
+run `athrun sipb pag-screen`. `screen` is a UNIX program that lets
+you run other programs even when you're not logged in, which is
+crucial for being able to receive zephyrgrams. Here are the
+relevant screen commands (`C-a x` means pressing and releasing Ctrl-a,
+then pressing x). You can run `man screen` to learn more commands.
+
+ - `C-a d` - detach the screen (you need to do this to log out without
+ killing your programs)
+ - `C-a c` - create a new window (a single screen session can have
+ several windows, each behaving like a separate terminal)
+ - `C-a n` - cycle to the next window
+ - `C-a p` - cycle to the previous window
+ - `C-a #` - cycle to the `#`th window, indexed from 0
+ - `C-a a` - send a literal `C-a` to the underlying program, required for
+ nested screens.
+
+Screens either be attached or detached (being attached means that
+there's a logged-in user looking at it). To reattach this screen, run
+
+`
+screen -dr pag
+`
+
+The `-dr` flag will detach the screen (in case a hanging session left
+it thinking it was attached) and reattach. `pag` is simply the name
+of the screen; you can list them with `screen -ls`. If you only
+have one screen session, you can omit the name. The important feature
+of this screen is that it will continuously renew your Kerberos
+tickets, as long as they are renewable; this way you only need to
+get new tickets once a week! (This magic is accomplished using the
+script `cont-renew-notify`, which is automatically invoked by
+`pag-screen`. If you don't want this feature, you can kill it).
+
+Now, while logging into different dialups will get you the same files
+(since MIT runs a networked filesystem called AFS), the same is not
+true for programs that run past a logout, like `screen`. In order
+to resume a screen, you must log onto the dialup it was created in.
+This is why we had to go through the trouble of picking a dialup.
+
+###Start a Barnowl
+While attached to your screen, run `athrun
+barnowl`. This will start barnowl, the premiere zephyr
+client. Because of how the zephyr protocol works, you must have
+barnowl running constantly to receive messages; you'll also need
+valid tickets to receive personals. This is why we had to go
+through the process of setting up `pag-screen`. Some useful things
+you can do right off the bat:
+
+* Press `h` to bring up a simple help dialog (`q` to quit).
+* Press `:` to bring up a command prompt (`C-c`, i.e. Ctrl-c,
+ to cancel without running a command).
+
+Zephyr is divided into "classes" and "instances". A class
+corresponds roughly to a chat channel, but they do not belong to
+any one user, and are unmoderated. An instance of a class is like a
+"discussion topic". For example, `-c sipb -i food` is a discussion on
+the class `sipb` about food (probably getting some).
+
+A "personal class" is a class used by one user to discuss things
+about themselves (in the Twitter sense, perhaps). By convention the
+class is the person's username. It is a good idea to subscribe to
+personal classes of people you know, and don't be afraid to take
+part in discussion; however, being loud on someone's personal class
+is considered rude, especially if they don't know you too well.
+
+Other useful classes include `-c sipb`, which is all about SIPB, and
+`out-of-the-loop`, a general ask-question-get-help class.
+
+To receive messages sent to class, you can subscribe using the `sub
+<class>`. To see your subscriptions, run `show subs`.
+
+To actually send a zephyrgram to a class you're subscribed to, run
+the command
+
+`
+zwrite -c <class> -i <instance>
+`
+
+which will then let you type your message. You can send your
+message by pressing return on a line with just a dot, or by sending
+an end-of-file (`C-d`, i.e. Ctrl-d). Pressing `z` will bring a zwrite
+command, so you can avoid having to type `:zwrite` to send a
+command. Pressing `r` will let you reply to a message, by
+pre-running the zwrite command with the appropriate `-c` and `-i`
+flags.
+
+You can also send personal zephyrgrams to any user currently logged
+in, by running `zwrite <user>`. If you want to send a personal to
+several users, you can use cc syntax:
+
+`
+zwrite -C <user1> <user2> ...
+`
+
+This will make it easier for them to reply to everyone in the
+conversation.
+
+Zephyr has been around for much, much longer than most internet
+communities, and has some etiquette that can seem a bit bizarre to
+newcomers. A good description of this (and a more in-depth
+description of how classes/instances work) can be found at
+[here](https://sipb.mit.edu/doc/zephyr/).
+
+To let people know you're using zephyr (and so you get
+subscribers!) send a zephyr to `-c hello -i <your-username>`.
+Don't forget to subscribe to hello first! It's a good idea to
+greet newcomers yourself, too, so they have personal classes to
+join! While subbing (and lurking) on others' personal classes
+is perfectly fine, be mindful of others; not every zephyr user
+wants their classes to become full of people they've never met.
+
+###Get tickets.
+Kerberos is an authentication system developed at MIT,
+which uses "tickets" to prove credentials. Tickets allow you to do privileged
+actions, like receive personal messages. For security reasons,
+tickets expire, so you'll need to get new ones every once in a
+while. The longest MIT allows this period to be is 7 days. Tickets
+also need to be renewed, but pag-screen takes care of that for you.
+
+To get tickets for barnowl, make a new window (`C-a c`) and run the
+command
+
+`
+kinit -l7d
+`
+
+This means "get me Kerberos tickets with a lifetime of 7
+days". You'll have to do this every week; pag-screen will zephyr
+you to remind you the day before. Since your screen will now have
+two windows, use `C-a n` and `C-a p` to navigate between them.
+
+You should now have everything you need to join in on the conversation
+on Zephyr! Happy zephrying!
sipb-www / wiki.git / commitdiff
