From: Miguel C Young de la Sota Date: Mon, 4 Sep 2017 02:40:42 +0000 (-0400) Subject: (no commit message) X-Git-Url: https://sipb.mit.edu/gitweb.cgi/wiki.git/commitdiff_plain/55f343a3c05527a2826a6f3b467ab3d93db2dcf5 --- diff --git a/doc/zephyr-quick.mdwn b/doc/zephyr-quick.mdwn new file mode 100644 index 0000000..7f29066 --- /dev/null +++ b/doc/zephyr-quick.mdwn @@ -0,0 +1,176 @@ +##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 +`. To see your subscriptions, run `show subs`. + +To actually send a zephyrgram to a class you're subscribed to, run +the command + +` +zwrite -c -i +` + +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 `. If you want to send a personal to +several users, you can use cc syntax: + +` +zwrite -C ... +` + +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 `. +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!