Mercurial > hg
comparison mcabber/doc/guide/guide.tex @ 1559:0674abda9a8f
Add Franky's mcabber user guide
author | Mikael Berthe <mikael@lilotux.net> |
---|---|
date | Sat, 11 Oct 2008 10:56:30 +0200 |
parents | |
children | 921429804e20 |
comparison
equal
deleted
inserted
replaced
1558:3df441efb7c2 | 1559:0674abda9a8f |
---|---|
1 \documentclass[12pt,oneside,a4]{book} | |
2 \usepackage{hyperref} | |
3 \usepackage{float} | |
4 \usepackage{listings} | |
5 \usepackage{graphicx} | |
6 \usepackage{multirow} | |
7 \title{Mcabber User Guide} | |
8 \author{franky} | |
9 \begin{document} | |
10 \maketitle | |
11 \tableofcontents | |
12 \chapter*{Introduction} | |
13 This guide was written for users who are new to mcabber\cite{mcabber} which is a small | |
14 command line client for the Jabber protocol\cite{jabber} as an introduction. This introduction may | |
15 become a comprehensive guide to every aspect of mcabber later, but the first versions should only be | |
16 regarded as an overview of all features. Feel free to bug me with corrections of spelling errors or | |
17 with contributions to the content. | |
18 \paragraph{Conventions used in this guide:\\} | |
19 \begin{tabular}{ c p{10cm} } | |
20 \verb+/command+ & This is a command for mcabber which can only be executed during runtime.\\ | |
21 \verb+command+ & A command for mcabber which can be given in the configuration file, too.\\ | |
22 \verb+$command+ & The \$-sign precedes shell commands.\\ | |
23 \textit{variable} & This is a variable which can be set in the configuration file or during runtime. \\ | |
24 \end{tabular} | |
25 \chapter{Basic Usage} | |
26 After installing mcabber, you should create a configuration file first. The easiest way of doing this | |
27 is to copy the sample configuration file\cite{samplerc} to \~{}/.mcabber/mcabberrc. Then, you only have to change the variables | |
28 \textit{username} and \textit{server} before you can, finally, start mcabber. When the Login was successful, | |
29 mcabber might look similar to the following screenshot:\\ | |
30 \begin{figure}[h!] | |
31 \centering | |
32 \includegraphics[scale=0.8]{guide} | |
33 \caption{screenshot of mcabber} | |
34 \label{fig:screenshot} | |
35 \end{figure} | |
36 The screen is divided into 4 regions: The roster(sometimes called buddy list) in the upper left, | |
37 the chat window/buffer in the upper right, the input line at the bottom and the log window above the | |
38 input line. Those two blue lines which are below and above the log window are status lines. The lower one | |
39 displays the general mcabber status and the upper line the status of the selected contact. | |
40 The screenshot shows mcabber in "chat mode" which can be entered by pressing enter or sending a message | |
41 when a contact is selected. Leaving chatmode is done by pressing Esc. To move between your contacts, you | |
42 can use the buttons Pg Up/Pg Down. If you look at the roster of the screenshot, you will notice that the | |
43 contact "loic" is marked red. That's the default for the "unread" color, so "loic" sent a message to | |
44 you, but you have not read it, yet. Moving by pressing Pg Down would need 6 key presses, so it might be faster to use | |
45 \verb+/roster unread_next+ to quickly jump to the next unread buffer. Which brings us to the interface of mcabber. | |
46 Since mcabber has only one input line, there has to be some way of distinguishing mcabber commands from normal text | |
47 messages. As you might have guessed already, all mcabber commands start with a slash, while any other line which you | |
48 have entered will be sent as a message to the selected buddy. You won't find a complete list of all commands here, | |
49 since mcabber has already got a great help system. It's at your fingertips when you enter \verb+/help+. | |
50 Furthermore, you can choose the language of the help system by setting \textit{lang} to de, en, fr, it, nl, pl, ru or uk. | |
51 \section{Multi-user Chat} | |
52 Jabber offers more than other one-on-one chats. There is an extension\cite{xep45} which adds many-to-many chat, | |
53 very similar to systems like IRC. Mcabber can participate through the command \verb+/room+. If you happen to | |
54 find big rooms, you should play a bit with \verb+/color muc+ to make the conversation more readable. | |
55 Last but not least, you might be interested in the channel mcabber@conf.lilotux.net as a new mcabber user. | |
56 Feel free to drop by and tell us about your experiences with mcabber or this guide! | |
57 \section{Transports} | |
58 Transports, also known as Gateways, are Jabber server components which are used for translating your Jabber messages | |
59 for proprietary networks like ICQ, AIM or MSN. At the time of writing, mcabber can't register transports, but, | |
60 if you've registered a transport with another client, you'll be able to use them within mcabber. | |
61 Transports are, basically, just another contact on your roster. Thus, using transports is done by sending your status, | |
62 maybe explicitly with \verb+/status_to+. | |
63 \section{Symbols} | |
64 Most users may be puzzled when they see all those different characters in the roster, the status bar and | |
65 in the chat window for the first time. Some of those symbols might be obvious, but others aren't descriptive at all. | |
66 So, here is a list of all characters and their meanings, structured per window where they were taken from. \\ | |
67 \begin{tabular}{c c} | |
68 \begin{tabular}{|c | l|} | |
69 \hline | |
70 \multicolumn{2}{|c|}{Roster}\\ | |
71 \hline | |
72 Symbols & Rosteritem \\ \hline | |
73 \verb+---+ & unfolded Group \\ | |
74 \verb-+++- & folded Group \\ \hline | |
75 \verb+[ ]+ & buddy or chat room(MUC) \\ | |
76 \verb+{ }+ & buddy who can't see your status \\ | |
77 \verb- + - & buddy is typing \\ | |
78 \verb+ . + & buddy stopped typing \\ | |
79 \verb+ _ + & buddy status: offline \\ | |
80 \verb+ o + & buddy status: online \\ | |
81 \verb+ a + & buddy status: away \\ | |
82 \verb+ d + & buddy status: do not disturb \\ | |
83 \verb+ n + & buddy status: not available\\ | |
84 \verb+ f + & buddy status: free for chat \\ | |
85 \verb+ ? + & buddy status unknown \\ | |
86 \verb+ x + & muc status: not connected \\ | |
87 \verb+ C + & muc status: connected \\ | |
88 \hline | |
89 \end{tabular} | |
90 & | |
91 \begin{tabular}{|c | l|} | |
92 \hline | |
93 \multicolumn{2}{|c|}{Chat Window} \\ \hline | |
94 Symbols & Meaning \\ \hline | |
95 \verb+-->+ & sent message \\ | |
96 \verb+<==+ & received message \\ | |
97 \verb+~+ & message was encrypted with GPG\\ | |
98 \verb+O+ & message was encrypted with OTR\\ | |
99 \verb+***+ & info message \\ | |
100 \verb+#<#+ & error message \\ | |
101 \hline | |
102 %\end{tabular} | |
103 %\begin{tabular}{|c | l|} | |
104 % \hline | |
105 \multicolumn{2}{|c|}{Upper Status Line} \\ \hline | |
106 Symbols & Meaning \\ \hline | |
107 \verb+~+ & chat mode enabled \\ | |
108 \verb+*+ & buffer is scroll-locked \\ | |
109 \verb+[C]+ & chatstate: composing \\ | |
110 \verb+[A]+ & chatstate: active \\ | |
111 \verb+[I]+ & chatstate: inactive \\ | |
112 \verb+[P]+ & chatstate: paused \\ | |
113 \verb+[G]+ & chatstate: gone \\ | |
114 \hline | |
115 \end{tabular} | |
116 \end{tabular} | |
117 \chapter{Logging} | |
118 Some people write their diaries to remember special moments. Others merely save their chat logs, | |
119 which are often full of personal details, too. Of course, mcabber can keep your chat history | |
120 and fortunately, the format of these logs is easy enough to read with your | |
121 favourite text editor. Moreover, searching is possible with standard unix tools like \verb+$grep+. | |
122 \section{Enable Logging} | |
123 To enable logging, you'll have to add some lines to your configuration file: | |
124 \begin{lstlisting} | |
125 set logging = 1 | |
126 set load_logs = 1 | |
127 \end{lstlisting} | |
128 Those variables tell mcabber to log the chat history and to load old logs when you restart it. | |
129 Please note that there are a lot of other variables affecting logging. You can e.g. choose whether | |
130 you want to log Multi-user Chats(\textit{log\_muc\_conf}) or whether you want to log status changes(\textit{logging\_ignore\_status}). | |
131 You'll find them all in the sample configuration file\cite{samplerc} if you search for "History Logging". | |
132 \section{Grouping logs} | |
133 If you know other instant messengers, you might be used to a concept called "metacontacts". | |
134 They can be used to group users, which have multiple representations in your | |
135 roster (e.g. because they have work and home accounts). Unfortunately, mcabber doesn't support | |
136 metacontacts yet, but at least you can group the history of different contacts together. | |
137 This basically works by merging those histories and then creating a symlink frome one to the other. | |
138 Here's an example with the histories of foo\_work@jabber.org ond foo\_home@jabber.org: | |
139 \begin{lstlisting} | |
140 $ cd ~/.mcabber/histo/ | |
141 $ merge_history.py foo_work@jabber.org foo_home@jabber.org > foo | |
142 $ mv foo foo_home@jabber.org | |
143 $ rm foo_work@jabber.org | |
144 $ ln -sf foo_home@jabber.org foo_work@jabber.org | |
145 \end{lstlisting} | |
146 The script merge\_history.py is included in the mcabber tarball. | |
147 \section{Converting centerim logs} | |
148 You've got old centericq\cite{centericq} or centerim\cite{centerim} logs and want to keep | |
149 them in mcabber? There's a script called cicq2mcabber.pl in the contrib directory of the mcabber | |
150 tarball which can be used to do that. Now you only have to figure out where exactly | |
151 centerim saves the history of a particular contact(somewhere under \~{}/.centerim/), | |
152 convert this file to the mcabber history format and save it to \~{}/.mcabber/histo/ with the | |
153 Jabber ID as the filename. | |
154 \chapter{Scripting} | |
155 This chapter will introduce you to the scripting facilities of mcabber. | |
156 \section{Aliases} | |
157 Aliases are used to map complex commands to a word. \verb+/roster search+ is one of the commands worth remapping | |
158 because it will be used every day. If you want to remap it to \verb+/rs+, | |
159 issue the command \verb+alias rs = roster search+. | |
160 \section{Internal Hooks} | |
161 Internal Hooks can be used to let mcabber execute commands when a special event occurs. | |
162 At the time of this writing, only 2 hooks were defined: | |
163 \begin{itemize} | |
164 \item \textit{hook-post-connect} | |
165 \item \textit{hook-pre-disconnect} | |
166 \end{itemize} | |
167 The time of the execution is self-explaining, just set those variables to the command you want | |
168 to execute. | |
169 \section{External scripts} | |
170 Mcabber will execute the external script specified in the variable \textit{events\_command} whenever a new | |
171 message is received. It will be called at least with 3 parameters: | |
172 \begin{enumerate} | |
173 \item MSG or STATUS | |
174 \item IN, OUT or MUC if the first argument was MSG or one character of "\_OFDNAI" if the first argument was STATUS | |
175 \item The JID which triggered the event | |
176 \item (optional) filename of the file which contains the message body | |
177 \end{enumerate} | |
178 If you need the message body for your event script, you'll have to set the option \textit{event\_log\_files} to 1. | |
179 The script has to delete that file after it processed it. To execute mcabber commands, | |
180 you'll have to compile mcabber with FIFO support(\verb+$./configure --enable-fifo+). Then activate it by setting the | |
181 variable \textit{fifo\_name} to the filename of the fifo in your config file. There will be some verbose debug | |
182 output in the logging window if you don't set the variable \textit{fifo\_hide\_output} to 1.\\ | |
183 There is another variable which might be interesting for the developer of external scripts. | |
184 If \textit{statefile} is set to a filename, mcabber saves the JIDs of all unread buffers to that file, one per line. | |
185 \chapter{Encryption} | |
186 Encryption is one of the greatest advantages of Jabber compared to similar | |
187 "legacy" networks like ICQ, MSN, AIM, etc. With encryption, you'll be able | |
188 to communicate in hostile network environments with a clear conscience, | |
189 because almost nobody will be able to spy on you. Practically, every connection | |
190 which is established when using the Jabber protocol could be encrypted. | |
191 First of all, you can connect to your Jabber server via ssl, which will | |
192 prevent anyone between you and the server from sniffing your plaintext | |
193 messages or your password. In mcabber you could enable this feature by adding | |
194 \begin{lstlisting} | |
195 set ssl = 1 | |
196 set ssl_verify = -1 | |
197 \end{lstlisting} | |
198 to your configuration file. | |
199 The next step is server to server encryption, which you can't control, | |
200 unless you're the admin of your server. So, theoretically it would be possible | |
201 to spy between Jabber servers, or maybe your buddy doesn't use an ssl | |
202 connection. Of course, if you are truly paranoid, you won't trust the | |
203 server admins but only your buddy. So, to encrypt messages between you and your | |
204 buddy, end-to-end encryption can be used. There are two protocols for | |
205 accomplishing this: The first one is OpenPGP/GnuPG, which is a semi standard\cite{xep27} | |
206 in the Jabber world. The other protocol is Off-the-Record(OTR) Messaging, which was | |
207 designed by cryptographers Ian Goldberg and Nikita Borisov\cite{otr}. Although OTR | |
208 isn't a standard, a lot of developers have implemented it for their instant | |
209 messaging clients. The main reason might be the availability of libotr\cite{libotr}, | |
210 an open-source library from the authors of OTR which does all the hard work. | |
211 GnuPG is considered to be more mature, but it also has a major drawback: | |
212 You can't encrypt messages between Jabber and legacy networks. Because | |
213 naturally, the clients of other networks won't support Jabber extensions. | |
214 OTR can fill that gap, because it only uses the message body as an envelope | |
215 for the whole protocol. | |
216 | |
217 I will now describe in detail how to use both protocols with mcabber. | |
218 \section{OpenPGP} | |
219 First of all, I'm assuming that you've already generated a gnupg key | |
220 which you want to use to encrypt Jabber messages. If you haven't done | |
221 this before, go to \url{http://gnupg.org/documentation/} first. | |
222 | |
223 Using PGP encryption with mcabber should be straight-forward, but you have to | |
224 restart mcabber for configuring it. To enable PGP for mcabber, you must | |
225 add two lines to your configuration file: | |
226 \begin{lstlisting} | |
227 set pgp = 1 | |
228 set pgp_private_key = 23DEADBEEFDEAD42 | |
229 \end{lstlisting} | |
230 The first one enables OpenPGP and the second line tells mcabber which PGP key it | |
231 should use. If you didn't notice: This hexadecimal number is the last | |
232 characters of your PGP key fingerprint, get it with | |
233 \verb+gpg --fingerprint+\verb+ --list-secret-keys+. | |
234 If you have no problems writing your passphrase to your hard disk, you could | |
235 also set the variable \textit{pgp\_passphrase} in your config file. Otherwise mcabber will | |
236 ask you for your passphrase at every start-up. | |
237 From now on, mcabber will magically use PGP encryption whenever it can. | |
238 Basically this works because presence messages of users using PGP are signed | |
239 with their key. If you happen to have a contact whose Jabber client doesn't | |
240 conform to that part of the standard, you can manually give mcabber their key | |
241 fingerprint: | |
242 \begin{lstlisting} | |
243 pgp setkey foo@bar.net D9940C9BB1B92310 | |
244 \end{lstlisting} | |
245 \section{OTR} | |
246 Enabling OTR in mcabber works in almost the same manner as PGP. But instead of | |
247 generating your encryption key by hand, mcabber will create one for you when | |
248 it starts. This might take some time and you can speed it up by generating | |
249 randomness by typing, moving the mouse, writing to hard disk etc. | |
250 But first of all, you must add the following lines to your configuration file | |
251 and restart mcabber: | |
252 \begin{lstlisting} | |
253 set otr = 1 | |
254 otrpolicy default manual | |
255 \end{lstlisting} | |
256 The first line is analogous to PGP. The second one gives the OTR subsystem | |
257 the hint that you want to be able to start encrypted OTR channels | |
258 manually(by issuing \verb+/otr start+). If you want that they are also "magically" started, you should | |
259 change \verb+manual+ to \verb+opportunistic+. The opportunistic mode adds some whitespace | |
260 characters to the first message sent to a buddy. So, his client can find those | |
261 characters and establish an OTR channel. Please note that "establishing" the | |
262 channel could take some time, depending on the delay of exchanging messages | |
263 between both ends. (For the technically inclined: Four messages have to be sent | |
264 before the channel is fully established. The whole protocol is described in | |
265 detail at \url{http://www.cypherpunks.ca/otr/Protocol-v2-3.1.0.html}) | |
266 | |
267 Keep in mind that an established channel with a buddy isn't per se secure. It | |
268 could be possible that you become a victim of a Man-in-the-middle attack. To | |
269 make it secure, you'll have to exchange the fingerprints of the keys through | |
270 a trusted medium (telephone, in person, etc). You can see your own fingerprint | |
271 by using the command \verb+/otr key+ and the fingerprint of your chat buddy by | |
272 \verb+/otr fingerprint+. Check \verb+/help otr+ to find out how to trust the fingerprint now. | |
273 There is even another way for exchanging fingerprints: The Socialist Millionaires' | |
274 Protocol\cite{smp}. It's basically a cryptographic secure way for two parties with the | |
275 secret information x and y to check whether x==y without revealing any | |
276 information about the secrets. Unfortunately there aren't many clients | |
277 supporting that feature yet. In mcabber it is mapped to the commands | |
278 \verb+/otr smpq bob@foo.net your_secret+ for the initiating party and | |
279 \verb+/otr smpr alice@foo.net your_secret+ for the answering party. If both parties supply | |
280 the same secret, the fingerprints can be marked trusted. | |
281 \bibliographystyle{plain} | |
282 \bibliography{guide} | |
283 \end{document} |