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