Updated the Officers for 2019-2020
[wiki.git] / 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!