doc/zephyr-quick.mdwn

   1 [[!meta title="Zephyr for the Impatient"]]
   2
   3 ##Zephyr for the Impatient
   4
   5 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.
   6
   7 This guide assumes only basic understanding of how to use a terminal.
   8
   9 ###Get mosh
  10
  11 [Mosh](https://mosh.org) is like `ssh`, which lets you securely log into a
  12 remote computer, but with the extra functionality of roaming. If
  13 you computer moves across networks, the connection won't drop. This
  14 is often useful.
  15
  16 If on Linux, install mosh via package manager; if on macOS, via
  17 [homebrew](https://brew.sh/) or [macports](https://www.macports.org/);
  18 if on Windows or Chrome OS, install [Mosh for Chrome](https://github.com/rpwoodbu/mosh-chrome/wiki).
  19
  20 If on Linux/macOS, the incantation for logging into athena with mosh is:
  21
  22 `
  23 mosh --ssh="ssh -K" --server="athrun mosh_project mosh-server" user@hostname
  24 `
  25
  26 The `-K` part will allow you to use Kerberos tickets on your machine,
  27 you have them. From here on out we refer to the above incantation as
  28 `mosh`.
  29
  30 ### Pick a dialup
  31 Log into one of the Athena dialups with the command
  32 `mosh user@athena.dialup.mit.edu` where `user` is your Athena
  33 username. Log in with your Athena password. Once on a dialup, run
  34 `echo $HOST` to learn the name of the machine (for example,
  35 `mass-toolpike` or `biohazard-cafe`). You can use the Moira command
  36 `stella $HOST` to learn aliases for the hostname for quicker
  37 logins. If you were logged into `mass-toolpike.mit.edu`, for example, you
  38 might log in with `mosh user@i90.mit.edu`. (If you're on campus,
  39 you can omit the `.mit.edu` part.)
  40
  41 The reason for doing this ceremony of picking one Athena dialup to
  42 use consistently will become clear in the next step.
  43
  44 ### Prepare a screen session
  45 Log into the dialup you picked above and
  46 run `athrun sipb pag-screen`. `screen` is a UNIX program that lets
  47 you run other programs even when you're not logged in, which is
  48 crucial for being able to receive zephyrgrams. Here are the
  49 relevant screen commands (`C-a x` means pressing and releasing Ctrl-a,
  50 then pressing x). You can run `man screen` to learn more commands.
  51
  52  - `C-a d` - detach the screen (you need to do this to log out without
  53          killing your programs)
  54  - `C-a c` - create a new window (a single screen session can have
  55          several windows, each behaving like a separate terminal)
  56  - `C-a n` - cycle to the next window
  57  - `C-a p` - cycle to the previous window
  58  - `C-a #` - cycle to the `#`th window, indexed from 0
  59  - `C-a a` - send a literal `C-a` to the underlying program, required for
  60          nested screens.
  61
  62 Screens either be attached or detached (being attached means that
  63 there's a logged-in user looking at it). To reattach this screen, run
  64
  65 `
  66 screen -dr pag
  67 `
  68
  69 The `-dr` flag will detach the screen (in case a hanging session left
  70 it thinking it was attached) and reattach. `pag` is simply the name
  71 of the screen; you can list them with `screen -ls`. If you only
  72 have one screen session, you can omit the name. The important feature
  73 of this screen is that it will continuously renew your Kerberos
  74 tickets, as long as they are renewable; this way you only need to
  75 get new tickets once a week! (This magic is accomplished using the
  76 script `cont-renew-notify`, which is automatically invoked by
  77 `pag-screen`. If you don't want this feature, you can kill it).
  78
  79 Now, while logging into different dialups will get you the same files
  80 (since MIT runs a networked filesystem called AFS), the same is not
  81 true for programs that run past a logout, like `screen`. In order
  82 to resume a screen, you must log onto the dialup it was created in.
  83 This is why we had to go through the trouble of picking a dialup.
  84
  85 ###Start a Barnowl
  86 While attached to your screen, run `athrun
  87 barnowl`. This will start barnowl, the premiere zephyr
  88 client. Because of how the zephyr protocol works, you must have
  89 barnowl running constantly to receive messages; you'll also need
  90 valid tickets to receive personals. This is why we had to go
  91 through the process of setting up `pag-screen`. Some useful things
  92 you can do right off the bat:
  93
  94 * Press `h` to bring up a simple help dialog (`q` to quit).
  95 * Press `:` to bring up a command prompt (`C-c`, i.e. Ctrl-c,
  96  to cancel without running a command).
  97
  98 Zephyr is divided into "classes" and "instances". A class
  99 corresponds roughly to a chat channel, but they do not belong to
 100 any one user, and are unmoderated. An instance of a class is like a
 101 "discussion topic". For example, `-c sipb -i food` is a discussion on
 102 the class `sipb` about food (probably getting some).
 103
 104 A "personal class" is a class used by one user to discuss things
 105 about themselves (in the Twitter sense, perhaps). By convention the
 106 class is the person's username. It is a good idea to subscribe to
 107 personal classes of people you know, and don't be afraid to take
 108 part in discussion; however, being loud on someone's personal class
 109 is considered rude, especially if they don't know you too well.
 110
 111 Other useful classes include `-c sipb`, which is all about SIPB, and
 112 `out-of-the-loop`, a general ask-question-get-help class.
 113
 114 To receive messages sent to class, you can subscribe using the `sub
 115 <class>`. To see your subscriptions, run `show subs`.
 116
 117 To actually send a zephyrgram to a class you're subscribed to, run
 118 the command
 119
 120 `
 121 zwrite -c <class> -i <instance>
 122 `
 123
 124 which will then let you type your message. You can send your
 125 message by pressing return on a line with just a dot, or by sending
 126 an end-of-file (`C-d`, i.e. Ctrl-d). Pressing `z` will bring a zwrite
 127 command, so you can avoid having to type `:zwrite` to send a
 128 command. Pressing `r` will let you reply to a message, by
 129 pre-running the zwrite command with the appropriate `-c` and `-i`
 130 flags.
 131
 132 You can also send personal zephyrgrams to any user currently logged
 133 in, by running `zwrite <user>`. If you want to send a personal to
 134 several users, you can use cc syntax:
 135
 136 `
 137 zwrite -C <user1> <user2> ...
 138 `
 139
 140 This will make it easier for them to reply to everyone in the
 141 conversation.
 142
 143 Zephyr has been around for much, much longer than most internet
 144 communities, and has some etiquette that can seem a bit bizarre to
 145 newcomers. A good description of this (and a more in-depth
 146 description of how classes/instances work) can be found at
 147 [here](https://sipb.mit.edu/doc/zephyr/).
 148
 149 To let people know you're using zephyr (and so you get
 150 subscribers!) send a zephyr to `-c hello -i <your-username>`.
 151 Don't forget to subscribe to hello first! It's a good idea to
 152 greet newcomers yourself, too, so they have personal classes to
 153 join! While subbing (and lurking) on others' personal classes
 154 is perfectly fine, be mindful of others; not every zephyr user
 155 wants their classes to become full of people they've never met.
 156
 157 ###Get tickets.
 158 Kerberos is an authentication system developed at MIT,
 159 which uses "tickets" to prove credentials. Tickets allow you to do privileged
 160 actions, like receive personal messages. For security reasons,
 161 tickets expire, so you'll need to get new ones every once in a
 162 while. The longest MIT allows this period to be is 7 days. Tickets
 163 also need to be renewed, but pag-screen takes care of that for you.
 164
 165 To get tickets for barnowl, make a new window (`C-a c`) and run the
 166 command
 167
 168 `
 169 kinit -l7d
 170 `
 171
 172 This means "get me Kerberos tickets with a lifetime of 7
 173 days". You'll have to do this every week; pag-screen will zephyr
 174 you to remind you the day before. Since your screen will now have
 175 two windows, use `C-a n` and `C-a p` to navigate between them.
 176
 177 You should now have everything you need to join in on the conversation
 178 on Zephyr!  Happy zephrying!