# HG changeset patch # User Mikael Berthe # Date 1223715390 -7200 # Node ID 0674abda9a8f288834e0052bf5220a56b1148793 # Parent 3df441efb7c25224062596953f768b0da16bccf8 Add Franky's mcabber user guide diff -r 3df441efb7c2 -r 0674abda9a8f mcabber/configure.ac --- a/mcabber/configure.ac Fri Oct 10 20:29:15 2008 +0200 +++ b/mcabber/configure.ac Sat Oct 11 10:56:30 2008 +0200 @@ -258,6 +258,7 @@ libjabber/Makefile src/Makefile doc/Makefile + doc/guide/Makefile doc/help/Makefile Makefile]) AC_OUTPUT diff -r 3df441efb7c2 -r 0674abda9a8f mcabber/doc/guide/Makefile.am --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mcabber/doc/guide/Makefile.am Sat Oct 11 10:56:30 2008 +0200 @@ -0,0 +1,8 @@ +guide: + pdflatex guide + bibtex guide + pdflatex guide + pdflatex guide + +clean-guide: + rm -f *.aux *.blg *.dvi *.toc *.out *.bbl *.log *.pdf diff -r 3df441efb7c2 -r 0674abda9a8f mcabber/doc/guide/guide.bib --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mcabber/doc/guide/guide.bib Sat Oct 11 10:56:30 2008 +0200 @@ -0,0 +1,67 @@ +@inproceedings{otr, + author = "Nikita Borisov and Ian Goldberg and Eric Brewer", + title = "Off-the-Record Communication, or, Why Not To Use PGP", + booktitle = "Proceedings of the 2004 ACM Workshop on Privacy in the Electronic Society.", + year = "2004", + publisher = "ACM", + note = "\url{http://www.cypherpunks.ca/otr/otr-wpes.pdf}" +} + +@manual{xep27, + author = "Thomas Muldowney", + title = "XEP-0027: Current Jabber OpenPGP Usage", + organization = "XMPP Standards Foundation", + year = "1999-2006", + note = "\url{http://www.xmpp.org/extensions/xep-0027.html}" +} + +@manual{xep45, + author = "Peter Saint-Andre", + title = "XEP-0045: Multi-User Chat", + organization = "XMPP Standards Foundation", + year = "1999-2008", + note = "\url{http://www.xmpp.org/extensions/xep-0045.html}" +} + +@misc{libotr, + title ="Off-the-Record Messaging", + author = "Ian Goldberg and Chris Alexander and Nikita Borisov", + note ="\url{http://www.cypherpunks.ca/otr/}" +} + +@misc{samplerc, + title = "Sample configuration file for mcabber", + note = "\url{http://www.lilotux.net/~mikael/mcabber/hg/?raw-file/tip/mcabber/mcabberrc.example}" +} + +@misc{mcabber, + title = "Mcabber", + author = "Mikael Berthe", + note = "\url{http://www.lilotux.net/~mikael/mcabber/}" +} + +@misc{jabber, + title = "Jabber/XMPP Protocols", + author = "XMPP Standards Foundation", + note = "\url{http://www.xmpp.org/protocols/}" +} + +@inproceedings{smp, + author = "Chris Alexander and Ian Goldberg", + title = "Improved User Authentication in Off-The-Record Messaging", + booktitle = "Proceedings of the 2007 ACM workshop on Privacy in electronic society", + year = "2007", + publisher = "ACM", + note = "\url{http://www.cypherpunks.ca/~iang/pubs/impauth.pdf}" +} + +@misc{centericq, + title = "CenterICQ", + author = "Konstantin Klyagin", + note = "\url{http://thekonst.net/en/centericq}" +} + +@misc{centerim, + title = "CenterIM", + note = "\url{http://www.centerim.org}" +} diff -r 3df441efb7c2 -r 0674abda9a8f mcabber/doc/guide/guide.png Binary file mcabber/doc/guide/guide.png has changed diff -r 3df441efb7c2 -r 0674abda9a8f mcabber/doc/guide/guide.tex --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mcabber/doc/guide/guide.tex Sat Oct 11 10:56:30 2008 +0200 @@ -0,0 +1,283 @@ +\documentclass[12pt,oneside,a4]{book} +\usepackage{hyperref} +\usepackage{float} +\usepackage{listings} +\usepackage{graphicx} +\usepackage{multirow} +\title{Mcabber User Guide} +\author{franky} +\begin{document} +\maketitle +\tableofcontents +\chapter*{Introduction} +This guide was written for users who are new to mcabber\cite{mcabber} which is a small +command line client for the Jabber protocol\cite{jabber} as an introduction. This introduction may +become a comprehensive guide to every aspect of mcabber later, but the first versions should only be +regarded as an overview of all features. Feel free to bug me with corrections of spelling errors or +with contributions to the content. +\paragraph{Conventions used in this guide:\\} +\begin{tabular}{ c p{10cm} } + \verb+/command+ & This is a command for mcabber which can only be executed during runtime.\\ + \verb+command+ & A command for mcabber which can be given in the configuration file, too.\\ + \verb+$command+ & The \$-sign precedes shell commands.\\ + \textit{variable} & This is a variable which can be set in the configuration file or during runtime. \\ +\end{tabular} +\chapter{Basic Usage} +After installing mcabber, you should create a configuration file first. The easiest way of doing this +is to copy the sample configuration file\cite{samplerc} to \~{}/.mcabber/mcabberrc. Then, you only have to change the variables +\textit{username} and \textit{server} before you can, finally, start mcabber. When the Login was successful, +mcabber might look similar to the following screenshot:\\ +\begin{figure}[h!] + \centering + \includegraphics[scale=0.8]{guide} + \caption{screenshot of mcabber} + \label{fig:screenshot} +\end{figure} +The screen is divided into 4 regions: The roster(sometimes called buddy list) in the upper left, +the chat window/buffer in the upper right, the input line at the bottom and the log window above the +input line. Those two blue lines which are below and above the log window are status lines. The lower one +displays the general mcabber status and the upper line the status of the selected contact. +The screenshot shows mcabber in "chat mode" which can be entered by pressing enter or sending a message +when a contact is selected. Leaving chatmode is done by pressing Esc. To move between your contacts, you +can use the buttons Pg Up/Pg Down. If you look at the roster of the screenshot, you will notice that the +contact "loic" is marked red. That's the default for the "unread" color, so "loic" sent a message to +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 +\verb+/roster unread_next+ to quickly jump to the next unread buffer. Which brings us to the interface of mcabber. +Since mcabber has only one input line, there has to be some way of distinguishing mcabber commands from normal text +messages. As you might have guessed already, all mcabber commands start with a slash, while any other line which you +have entered will be sent as a message to the selected buddy. You won't find a complete list of all commands here, +since mcabber has already got a great help system. It's at your fingertips when you enter \verb+/help+. +Furthermore, you can choose the language of the help system by setting \textit{lang} to de, en, fr, it, nl, pl, ru or uk. +\section{Multi-user Chat} +Jabber offers more than other one-on-one chats. There is an extension\cite{xep45} which adds many-to-many chat, +very similar to systems like IRC. Mcabber can participate through the command \verb+/room+. If you happen to +find big rooms, you should play a bit with \verb+/color muc+ to make the conversation more readable. +Last but not least, you might be interested in the channel mcabber@conf.lilotux.net as a new mcabber user. +Feel free to drop by and tell us about your experiences with mcabber or this guide! +\section{Transports} +Transports, also known as Gateways, are Jabber server components which are used for translating your Jabber messages +for proprietary networks like ICQ, AIM or MSN. At the time of writing, mcabber can't register transports, but, +if you've registered a transport with another client, you'll be able to use them within mcabber. +Transports are, basically, just another contact on your roster. Thus, using transports is done by sending your status, +maybe explicitly with \verb+/status_to+. +\section{Symbols} +Most users may be puzzled when they see all those different characters in the roster, the status bar and +in the chat window for the first time. Some of those symbols might be obvious, but others aren't descriptive at all. +So, here is a list of all characters and their meanings, structured per window where they were taken from. \\ +\begin{tabular}{c c} + \begin{tabular}{|c | l|} + \hline + \multicolumn{2}{|c|}{Roster}\\ + \hline + Symbols & Rosteritem \\ \hline + \verb+---+ & unfolded Group \\ + \verb-+++- & folded Group \\ \hline + \verb+[ ]+ & buddy or chat room(MUC) \\ + \verb+{ }+ & buddy who can't see your status \\ + \verb- + - & buddy is typing \\ + \verb+ . + & buddy stopped typing \\ + \verb+ _ + & buddy status: offline \\ + \verb+ o + & buddy status: online \\ + \verb+ a + & buddy status: away \\ + \verb+ d + & buddy status: do not disturb \\ + \verb+ n + & buddy status: not available\\ + \verb+ f + & buddy status: free for chat \\ + \verb+ ? + & buddy status unknown \\ + \verb+ x + & muc status: not connected \\ + \verb+ C + & muc status: connected \\ + \hline + \end{tabular} + & + \begin{tabular}{|c | l|} + \hline + \multicolumn{2}{|c|}{Chat Window} \\ \hline + Symbols & Meaning \\ \hline + \verb+-->+ & sent message \\ + \verb+<==+ & received message \\ + \verb+~+ & message was encrypted with GPG\\ + \verb+O+ & message was encrypted with OTR\\ + \verb+***+ & info message \\ + \verb+#<#+ & error message \\ + \hline + %\end{tabular} + %\begin{tabular}{|c | l|} + % \hline + \multicolumn{2}{|c|}{Upper Status Line} \\ \hline + Symbols & Meaning \\ \hline + \verb+~+ & chat mode enabled \\ + \verb+*+ & buffer is scroll-locked \\ + \verb+[C]+ & chatstate: composing \\ + \verb+[A]+ & chatstate: active \\ + \verb+[I]+ & chatstate: inactive \\ + \verb+[P]+ & chatstate: paused \\ + \verb+[G]+ & chatstate: gone \\ + \hline + \end{tabular} +\end{tabular} +\chapter{Logging} +Some people write their diaries to remember special moments. Others merely save their chat logs, +which are often full of personal details, too. Of course, mcabber can keep your chat history +and fortunately, the format of these logs is easy enough to read with your +favourite text editor. Moreover, searching is possible with standard unix tools like \verb+$grep+. +\section{Enable Logging} +To enable logging, you'll have to add some lines to your configuration file: +\begin{lstlisting} +set logging = 1 +set load_logs = 1 +\end{lstlisting} +Those variables tell mcabber to log the chat history and to load old logs when you restart it. +Please note that there are a lot of other variables affecting logging. You can e.g. choose whether +you want to log Multi-user Chats(\textit{log\_muc\_conf}) or whether you want to log status changes(\textit{logging\_ignore\_status}). +You'll find them all in the sample configuration file\cite{samplerc} if you search for "History Logging". +\section{Grouping logs} +If you know other instant messengers, you might be used to a concept called "metacontacts". +They can be used to group users, which have multiple representations in your +roster (e.g. because they have work and home accounts). Unfortunately, mcabber doesn't support +metacontacts yet, but at least you can group the history of different contacts together. +This basically works by merging those histories and then creating a symlink frome one to the other. +Here's an example with the histories of foo\_work@jabber.org ond foo\_home@jabber.org: +\begin{lstlisting} +$ cd ~/.mcabber/histo/ +$ merge_history.py foo_work@jabber.org foo_home@jabber.org > foo +$ mv foo foo_home@jabber.org +$ rm foo_work@jabber.org +$ ln -sf foo_home@jabber.org foo_work@jabber.org +\end{lstlisting} +The script merge\_history.py is included in the mcabber tarball. +\section{Converting centerim logs} +You've got old centericq\cite{centericq} or centerim\cite{centerim} logs and want to keep +them in mcabber? There's a script called cicq2mcabber.pl in the contrib directory of the mcabber +tarball which can be used to do that. Now you only have to figure out where exactly +centerim saves the history of a particular contact(somewhere under \~{}/.centerim/), +convert this file to the mcabber history format and save it to \~{}/.mcabber/histo/ with the +Jabber ID as the filename. +\chapter{Scripting} +This chapter will introduce you to the scripting facilities of mcabber. +\section{Aliases} +Aliases are used to map complex commands to a word. \verb+/roster search+ is one of the commands worth remapping +because it will be used every day. If you want to remap it to \verb+/rs+, +issue the command \verb+alias rs = roster search+. +\section{Internal Hooks} +Internal Hooks can be used to let mcabber execute commands when a special event occurs. +At the time of this writing, only 2 hooks were defined: +\begin{itemize} + \item \textit{hook-post-connect} + \item \textit{hook-pre-disconnect} +\end{itemize} +The time of the execution is self-explaining, just set those variables to the command you want +to execute. +\section{External scripts} +Mcabber will execute the external script specified in the variable \textit{events\_command} whenever a new +message is received. It will be called at least with 3 parameters: +\begin{enumerate} + \item MSG or STATUS + \item IN, OUT or MUC if the first argument was MSG or one character of "\_OFDNAI" if the first argument was STATUS + \item The JID which triggered the event + \item (optional) filename of the file which contains the message body +\end{enumerate} +If you need the message body for your event script, you'll have to set the option \textit{event\_log\_files} to 1. +The script has to delete that file after it processed it. To execute mcabber commands, +you'll have to compile mcabber with FIFO support(\verb+$./configure --enable-fifo+). Then activate it by setting the +variable \textit{fifo\_name} to the filename of the fifo in your config file. There will be some verbose debug +output in the logging window if you don't set the variable \textit{fifo\_hide\_output} to 1.\\ +There is another variable which might be interesting for the developer of external scripts. +If \textit{statefile} is set to a filename, mcabber saves the JIDs of all unread buffers to that file, one per line. +\chapter{Encryption} +Encryption is one of the greatest advantages of Jabber compared to similar +"legacy" networks like ICQ, MSN, AIM, etc. With encryption, you'll be able +to communicate in hostile network environments with a clear conscience, +because almost nobody will be able to spy on you. Practically, every connection +which is established when using the Jabber protocol could be encrypted. +First of all, you can connect to your Jabber server via ssl, which will +prevent anyone between you and the server from sniffing your plaintext +messages or your password. In mcabber you could enable this feature by adding +\begin{lstlisting} +set ssl = 1 +set ssl_verify = -1 +\end{lstlisting} +to your configuration file. +The next step is server to server encryption, which you can't control, +unless you're the admin of your server. So, theoretically it would be possible +to spy between Jabber servers, or maybe your buddy doesn't use an ssl +connection. Of course, if you are truly paranoid, you won't trust the +server admins but only your buddy. So, to encrypt messages between you and your +buddy, end-to-end encryption can be used. There are two protocols for +accomplishing this: The first one is OpenPGP/GnuPG, which is a semi standard\cite{xep27} +in the Jabber world. The other protocol is Off-the-Record(OTR) Messaging, which was +designed by cryptographers Ian Goldberg and Nikita Borisov\cite{otr}. Although OTR +isn't a standard, a lot of developers have implemented it for their instant +messaging clients. The main reason might be the availability of libotr\cite{libotr}, +an open-source library from the authors of OTR which does all the hard work. +GnuPG is considered to be more mature, but it also has a major drawback: +You can't encrypt messages between Jabber and legacy networks. Because +naturally, the clients of other networks won't support Jabber extensions. +OTR can fill that gap, because it only uses the message body as an envelope +for the whole protocol. + +I will now describe in detail how to use both protocols with mcabber. +\section{OpenPGP} +First of all, I'm assuming that you've already generated a gnupg key +which you want to use to encrypt Jabber messages. If you haven't done +this before, go to \url{http://gnupg.org/documentation/} first. + +Using PGP encryption with mcabber should be straight-forward, but you have to +restart mcabber for configuring it. To enable PGP for mcabber, you must +add two lines to your configuration file: +\begin{lstlisting} +set pgp = 1 +set pgp_private_key = 23DEADBEEFDEAD42 +\end{lstlisting} +The first one enables OpenPGP and the second line tells mcabber which PGP key it +should use. If you didn't notice: This hexadecimal number is the last +characters of your PGP key fingerprint, get it with +\verb+gpg --fingerprint+\verb+ --list-secret-keys+. +If you have no problems writing your passphrase to your hard disk, you could +also set the variable \textit{pgp\_passphrase} in your config file. Otherwise mcabber will +ask you for your passphrase at every start-up. +From now on, mcabber will magically use PGP encryption whenever it can. +Basically this works because presence messages of users using PGP are signed +with their key. If you happen to have a contact whose Jabber client doesn't +conform to that part of the standard, you can manually give mcabber their key +fingerprint: +\begin{lstlisting} +pgp setkey foo@bar.net D9940C9BB1B92310 +\end{lstlisting} +\section{OTR} +Enabling OTR in mcabber works in almost the same manner as PGP. But instead of +generating your encryption key by hand, mcabber will create one for you when +it starts. This might take some time and you can speed it up by generating +randomness by typing, moving the mouse, writing to hard disk etc. +But first of all, you must add the following lines to your configuration file +and restart mcabber: +\begin{lstlisting} +set otr = 1 +otrpolicy default manual +\end{lstlisting} +The first line is analogous to PGP. The second one gives the OTR subsystem +the hint that you want to be able to start encrypted OTR channels +manually(by issuing \verb+/otr start+). If you want that they are also "magically" started, you should +change \verb+manual+ to \verb+opportunistic+. The opportunistic mode adds some whitespace +characters to the first message sent to a buddy. So, his client can find those +characters and establish an OTR channel. Please note that "establishing" the +channel could take some time, depending on the delay of exchanging messages +between both ends. (For the technically inclined: Four messages have to be sent +before the channel is fully established. The whole protocol is described in +detail at \url{http://www.cypherpunks.ca/otr/Protocol-v2-3.1.0.html}) + +Keep in mind that an established channel with a buddy isn't per se secure. It +could be possible that you become a victim of a Man-in-the-middle attack. To +make it secure, you'll have to exchange the fingerprints of the keys through +a trusted medium (telephone, in person, etc). You can see your own fingerprint +by using the command \verb+/otr key+ and the fingerprint of your chat buddy by +\verb+/otr fingerprint+. Check \verb+/help otr+ to find out how to trust the fingerprint now. +There is even another way for exchanging fingerprints: The Socialist Millionaires' +Protocol\cite{smp}. It's basically a cryptographic secure way for two parties with the +secret information x and y to check whether x==y without revealing any +information about the secrets. Unfortunately there aren't many clients +supporting that feature yet. In mcabber it is mapped to the commands +\verb+/otr smpq bob@foo.net your_secret+ for the initiating party and +\verb+/otr smpr alice@foo.net your_secret+ for the answering party. If both parties supply +the same secret, the fingerprints can be marked trusted. +\bibliographystyle{plain} +\bibliography{guide} +\end{document}