Merge updated git import of Trac content into Markdown.
[wiki.git] / doc / zephyr.mdwn
1 [[!meta title="Using Zephyr (a.k.a. Zephyr For Dummies)"]]
2
3 <!-- For information on the archaic way of using Zephyr, see TraditionalZephyr.-->
4
5 ## Introduction to Zephyr
6
7 Zephyr was a system designed to let system administrators send
8 important messages to users in an easily noticeable format. It was
9 meant to have a low volume of traffic and be used only for official
10 notices. This is obviously not what Zephyr is today. It can still be
11 used in the way it was intended: notice that you get official
12 zephyrgrams as you log in, with important information about Athena
13 services and planned outages. However, the most common usage is by
14 average users exchanging information about classes, how their days are
15 going, and talking on Zephyr classes and instances about everything
16 from the latest episode of Battlestar Galactica to the next 18.03
17 problem set. The usage of Zephyr has far exceeded original
18 expectations. Over time, people have also created programs that give
19 Zephyr a graphical interface, and programs that give zephyr a purely
20 textual interface, that can be used entirely within a ssh
21 terminal. Some of these zephyr clients have become so widely used that
22 there are users who do not know that there are other ways to send (and
23 receive) zephyrgrams. This wiki will cover the traditional commands,
24 typed at the athena% prompt, as well as the more common modern zephyr
25 client Barnowl.
26
27 The information in this wiki about Barnowl just barely touches the
28 surface.  More for in-depth functionality, visit the [Barnowl
29 wiki](https://barnowl.scripts.mit.edu:444/wiki).
30
31 ## Modern Zephyr
32
33 Today the majority of Zephyr users use the barnowl client.  There are
34 other clients as well (for example, Pidgin supports Zephyr).  The
35 following sections will go into detail about how to install, use, and
36 customize barnowl.
37
38 ### Other Clients
39
40 There are other clients besides Barnowl, however their use is not
41 nearly as widespread.  Some of these include:
42
43 * Owl (unmaintained, Barnowl evolved from this)
44 * vt / jervt
45 * zwgc (see TraditionalZephyr)
46 * Pidgin
47 * zephyr-mode for emacs
48
49 Using Barnowl is recommended, as it is better supported and more
50 documentation exists for it.
51
52 ### Using Barnowl
53 You will need access to an Athena machine to run barnowl.  The easiest
54 way to do this would be to SSH into linerva.mit.edu.
55
56 On a Debian-based linux distro, open up a terminal and type `ssh
57 <username>@linerva.mit.edu`.
58
59 On Windows, download a SSH client (such as
60 [PuTTY](http://chiark.greenend.org.uk/~sgtatham/putty/download.html))
61 and install it.  Once you've opened it, type `<username>@linerva.mit.edu`
62 into the prompt and hit enter.
63
64 On a Mac, open Terminal from the Utilities Folder in Applications. Type
65 `kinit <username>@ATHENA.MIT.EDU && ssh -K
66 <username>@linerva.mit.edu` If this command fails (saying -K is
67 invalid), then just do `ssh <username>@linerva.mit.edu`.
68
69 (In all these cases, don't include the angle brackets, just replace
70 <username> with your MIT username).  You will then be prompted for your
71 password.  Enter it, and then carry on with running barnowl!
72
73 To start barnowl, run the command `add barnowl; barnowl` at the prompt
74 on any Athena machine or dialup, such as linerva.mit.edu.
75
76 The simplest use of Zephyr is to send personal zephyrs to other
77 users. To send a zephyr, type `:` to bring up a command line, and run
78 the command `zwrite USERNAME`. You can also start a `zwrite` command
79 by simply typing z.
80
81 You can then enter your message, and then enter a `.` on a line by
82 itself to finish the zephyr. By convention, zephyrs are usually
83 word-wrapped to 70 characters or so per line; barnowl will wrap at about
84 10 characters less than the width of your terminal window, so if you
85 have a large window, you may need to press M-q (Alt-q, or Escape then q)
86 to word-wrap the current paragraph to a smaller width.
87
88 Once you've sent and received zephyrs, you can navigate the message
89 list with the arrow keys. Press `d` to mark a message as deleted, `u`
90 to undelete it, and `x` to expunge all messages that have been marked
91 as deleted.
92
93 Instead of entering a `zwrite` command manually, you can also select a
94 message in the message list with the arrow keys, and reply to it using
95 `r`, which will automatically set up an appropriate `zwrite` command.
96
97 For more documentation on the built-in commands and keybindings, you
98 can press h to bring up barnowl's built-in help screen. For help with
99 a specific command, bring up a command line with `:` and then type
100 `help COMMAND`.
101
102 ### Classes and Instances
103
104 Generally the most interesting discussion on Zephyr, however, happens
105 on so-called Zephyr <em>classes</em>. A class is a bit like a chat
106 room in other IM systems. Anyone can send a zephyr to a class, and
107 anyone who is subscribed to that class will receive it. There is no
108 security on classes -- anyone who knows the name of a class can
109 subscribe, and there is no way to determine who is subscribed to a
110 given class.
111
112 To subscribe to a class, use the subscribe command:
113
114     :subscribe CLASSNAME * *
115
116 To send a zephyr to a class, use the zwrite command with the -c option:
117
118     :zwrite -c CLASSNAME
119
120 Zephyrs to classes usually have an instance attached. An instance is a
121 short &ldquo;topic&rdquo; or &ldquo;subject&rdquo; that indicates the
122 context of a zephyr.  Different instances are often used to multiplex
123 multiple conversations on a high-traffic class. You can specify an
124 instance with the -i option to zwrite:
125
126     :zwrite -c CLASSNAME -i INSTANCE
127
128 A message without an instance specified will default to the instance
129 &ldquo;personal&rdquo;.
130
131 Some common classes include:
132
133 <strong>help</strong>:
134 > -c help is a class for asking (and answering) questions on virtually
135 > any topic imaginable. Be sure to use an instance (such as
136 > &ldquo;linux&rdquo;, &ldquo;barnowl&rdquo;, &ldquo;campus&rdquo;, or
137 > so on) when asking questions, since it's a fairly high-traffic
138 > class.
139
140 <strong>sipb</strong>:
141 > -c sipb is where most SIPB members hang out. It's a place for
142 > technical discussion, questions, support, and organizing SIPB events
143 > or projects. You should also always use an instance when sending to
144 > -c sipb.
145
146 <strong>Personal Classes</strong>:
147 > By convention, nearly every Zephyr user has a "personal" class that
148 > is the same as their username. How this class is used varies from
149 > person to person, but it's often a sort of mini-blog, a place to
150 > report what one is working on or up to, or ask friends questions, or
151 > just rant about something.
152
153 ### Zephyr Slang
154
155 If you spend enough time on Zephyr, you'll begin noticing some strange
156 phrases and words being thrown around.  Some of these include:
157
158 <strong>i,i foo</strong>:
159 > picked up from CMU zephyrland and means "I have no point here, I
160 > just like saying:".  Sometimes people simply use quotes: `"foo"`.
161
162 <strong>mix</strong>:
163 > If somebody accidentally sends a Zephyr to the wrong class or
164 > person, they will send another Zephyr to that wrong/class person
165 > simply saying "mix".  This basically just means, "oops, sorry, I
166 > didn't mean to send that Zephyr here".  You might also see "-i mix",
167 > which is the same thing, only with instances.
168
169 <strong>.d</strong>:
170 > You may see an instance change from `-i foo` to `-i foo.d`.  This
171 > indicates a deviation or tangent from the the original topic.
172
173 <strong>starking</strong>:
174 > Answering a question or replying to a topic to a topic several hours
175 > (or days, occasionally) later. The term originates from Greg Stark,
176 > who would often reply to zephyrs hours or occasionally days later
177 > without seeing if anyone had answered yet, or worse, if the instance
178 > had moved on to an entirely different topic.
179
180 <strong>ttants</strong>:
181 >  Literally, "Things That Are Not The Same".
182
183 <strong>prnf</strong>:
184 >  Literally, "Pseudo-Random Neuron Firings".
185
186 There are many other acronyms that are used; if you don't know what it
187 means, try using the `whats foo` command at an Athena terminal. If you
188 don't have the command, run `add sipb` first.
189
190 ### Zephyr Etiquette
191
192 There are rules that people tend to use on Zephyr.  These include:
193
194 Good grammar, spelling, and punctuation.  Not everybody uses
195 capitalization, but they will still use good English.  Please do not say
196 things such as "hey wut r u up to???".  It makes you look like an idiot.
197 Really.
198
199 You don't need multiple question marks or exclamation points.  Usually.
200
201 There are a few abbreviations people use, such as YMMV (Your Mileage May
202 Vary) or IIRC (If I Remember Correctly), as well as some nerdier ones
203 like DTRT (Do The Right Thing, in reference to
204 [http://www.jwz.org/doc/worse-is-better.html The Rise of "Worse Is
205 Better"]).  Try running `add outland; whats dtrt` to look up an
206 abbreviation.  Common abbreviations that you might find on AIM, however,
207 are not often used.  People tend to look down upon "lol", "rofl", and
208 such.
209
210 Personal classes are by convention considered a little more private than
211 non-personal (public) classes. Although most people don't mind people
212 they've met subscribing to their personal class and lurking, it's poor
213 form to talk loudly on the personal class of someone you don't know.
214
215 ### Startup
216
217 There might be some options that you want to be consistent from
218 session to session; you don't want to have to set the same variables
219 each time.  You can fix this by adding the commands to your "startup"
220 file, for example, `.owl/startup`.  This can be done from within
221 Barnowl, by using the `startup` command:
222
223     :startup set foo bar
224
225 Where `foo` is the variable you want to set, and `bar` is the value.
226 You do not necessarily have to use the `set` command, either, any
227 command you can type in Barnowl can be added to the startup file.
228
229 ### Logging
230
231 It is handy to be able to log your conversations so you can refer back
232 to them later.  To log classes, for example:
233
234     :set classlogging on
235
236 And to log personals:
237
238     :set logging on
239
240 This will log to the "zlog" directory in your locker. You probably
241 don't want people to see what classes you're on or what people you
242 talk to, so you can run the Athena commands
243
244     mkdir -p ~/zlog
245     fs sa ~/zlog system:anyuser none
246     mkdir -p ~/zlog/people
247     mkdir -p ~/zlog/class
248
249 to create the necessary directories and make them completely hidden.
250
251 ### Colors
252
253 By default, there are seven colors you may use in the terminal: red,
254 green, yellow, blue, magenta, cyan, and white.  In order to use color
255 in Zephyr, you can use the following notation: `@(@color(red)This is
256 some red text))`
257
258 Colors may vary from machine to machine, as different terminal
259 profiles may have different shades of the seven colors.
260
261 ### Filters
262
263 Some people like to customize their Barnowl by color-coding classes.
264 This makes it easier to tell different classes apart (and minimize
265 mixing).  Barnowl has some already existing filters, for example,
266 `personal` (for incoming personals), `out` (for outgoing personals),
267 and `ping` (for pings).  To assign a color to a filter, add the
268 following to your startup file:
269
270     filter personal -c green
271
272 What if you want to color-code your class, or a friends class?  You
273 can create and color filters with:
274
275     filter johndoe class johndoe
276     filter johndoe -c blue
277
278 You can update your settings and filters without restarting your
279 Barnowl session by:
280
281     :source ~/path/to/config/file
282
283 You can see all the filters by using `:show filters`, and narrow to a
284 particular filter with, e.g., `:view personal`. You can use `:view
285 all` or the keyboard shortcut `V` to see all messages again.
286
287 For more detailed information on filters, visit
288 https://barnowl.scripts.mit.edu:444/wiki/Filters.
289
290 ## Running Barnowl in Screen
291
292 It can be very annoying to have to close Barnowl when you turn off
293 your computer.  During the time your computer is off, you're missing
294 many (possibly important) zephyrs.  It can be aggravating to be using
295 zephyr via an unreliable network connection.  It can also be
296 frustrating if you leave your computer on with Zephyr up, but go to a
297 different computer and want to check your zephyrs - how do you do
298 this?  These problems can be solved with the magic of screen.
299
300 A more detailed and extensive explanation of this can be found at
301 http://web.mit.edu/kchen/bin/owl-screen.txt.
302
303 ### Screen
304
305 You should find a computer or server on which to run your screen
306 session(s) that is up all the time, for example, linerva.mit.edu.
307 Screen allows you to run programs inside of it on one computer, and to
308 access those same programs from other computers via ssh.
309
310 ### Quickstart
311
312 1.  Pick a machine to host your screen session on.
313     If you don't know of any options, linux.mit.edu (Linerva) is a good choice.
314 2.  ssh to that machine.
315 3.  Run "add kchen".  You may want to add this to your `~/.environment` file.
316 4.  Run "owl-screen"
317
318 Your screen session is now ready.  Once you start the screen session,
319 you'll need to get renewable Kerberos tickets in order to run it for
320 any extended period of time.  Press C-a C-c to open a new screen
321 window, and run
322
323     kinit -l7d -54
324
325 (length 7 days, both Kerberos 5 and Kerberos 4). Press C-a 0 to return
326 back to your Barnowl window.
327
328 When you're ready to log out, press C-a d to "detach" your screen, and
329 then type `exit` or `logout` to log out.  Later, when you want to
330 "reattach" your screen, ssh to the machine again, and run `screen -r`.
331
332 ### Kerberos Tickets and AFS Tokens
333
334 In order to keep your screen session authenticated, you'll need to
335 keep your Kerberos tickets and AFS tokens up-to-date.  There is a
336 script that will do this for you, located in the `kchen` locker.
337 After you ssh into the machine that hosts your screen sessions, run
338 the following commands:
339
340     add kchen
341     owl-screen
342     C-a C-c
343     kinit -l1d -r7d -54
344
345 ### Attaching and Detaching Sessions
346
347 To detach a screen session (for example, if you want to log out),
348 press C-a d (Control-A, then D).  Screen continues to run, but is no
349 longer active.
350
351 To reattach a screen session, possibly detaching from wherever it's
352 currently attached, run:
353
354     screen -dr
355
356 `screen` can do a whole lot more.  To find out about it, see
357 [UsingScreen](https://sipb-www.scripts.mit.edu:444/doc/wiki/UsingScreen).
358
359 ### Interaction with Traditional Zephyr
360
361 The default athena startup scripts launch zwgc on login. If you are
362 subscribed to many classes and use Zephyr as many do today, zwgc's
363 behavior is not very desirable. To disable zwgc startup, add:
364
365     setenv ZEPHYR_CLIENT false
366
367 to your `~/.environment` file if you use `tcsh` or
368
369     ZEPHYR_CLIENT=false
370
371 to your `~/.bash_environment` if you use `bash`. This will cause your
372 shell to launch the `false` executable instead of zwgc which does
373 nothing.