From 3c5cdec1d11fc03899f7068279cf5430d274124c Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Wed, 27 Nov 2013 00:43:37 +0100 Subject: Add some documentation --- COPYING | 20 ++++++ INSTALL | 75 +++++++++++++++++++++++ README | 51 ++++++++++++++++ doc/biboumi.1 | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 338 insertions(+) create mode 100644 COPYING create mode 100644 INSTALL create mode 100644 README create mode 100644 doc/biboumi.1 diff --git a/COPYING b/COPYING new file mode 100644 index 0000000..8806baf --- /dev/null +++ b/COPYING @@ -0,0 +1,20 @@ +Copyright (c) 2013 Florent Le Coz + +This software is provided 'as-is', without any express or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +1. The origin of this software must not be misrepresented; you must not +claim that you wrote the original software. If you use this software +in a product, an acknowledgment in the product documentation would be +appreciated but is not required. + +2. Altered source versions must be plainly marked as such, and must not be +misrepresented as being the original software. + +3. This notice may not be removed or altered from any source +distribution. diff --git a/INSTALL b/INSTALL new file mode 100644 index 0000000..309ecc0 --- /dev/null +++ b/INSTALL @@ -0,0 +1,75 @@ +============== + Dependencies +============== + +Build and runtime dependencies: + +Libraries: +- crypto++ + Sometimes packaged as cryptopp. This library is used to generate MD5 + hashes. + http://www.cryptopp.com/ +- expat + Used to parse XML from the XMPP server. + http://expat.sourceforge.net/ +- libiconv + Encoding from anything into UTF-8 + http://www.gnu.org/software/libiconv/ + +Tools: +- A C++11 compiler. +- CMake + + +============== + Configure +============== + +Configure the build system using cmake, there are many solutions to do + that, the simplest is to just run + +% cmake . + +in the current directory + +You can also configure many parameters of the build (like personnalize +CFLAGS, the install path, choose the compiler, or enabling some options +like the POLLER to use), using: + +% ccmake . + +In ccmake, first use 'c' to configure the build system, edit the values you +need and finaly use 'g' to generate the Makefiles to build the system and +quit ccmake. + +or + +% cmake -i . + +and respond to the questions when you are prompted to. + +You can select the poller used by biboumi, at compile-time, using the POLLER +cmake option. Available values are: + POLL: use the standard poll(2). This is the default value because it works on all supported plateforms + EPOLL: use the Linux-specific epoll(7) + +Example, configure the poller with cmake: +% cmake . -DPOLLER=EPOLL + + +============== + Build +============== + +- Build the project + +% make + + +============= + Install +============= + +- Install the software system-wide + +# make install diff --git a/README b/README new file mode 100644 index 0000000..8a4f3b3 --- /dev/null +++ b/README @@ -0,0 +1,51 @@ + _ _ _ _ +| |__ (_) |__ ___ _ _ _ __ ___ (_) +| '_ \| | '_ \ / _ \| | | | '_ ` _ \| | +| |_) | | |_) | (_) | |_| | | | | | | | +|_.__/|_|_.__/ \___/ \__,_|_| |_| |_|_| + + +Homepage: http://dev.louiz.org/projects/biboumi + +Biboumi is an XMPP gateway that connects to IRC servers and translates +between the two protocols. It can be used to access IRC channels using any +XMPP client as if these channels were XMPP MUCs. + +It is written in modern C++11 and make great efforts to have as little +dependencies and to be as simple as possible. + +The goal is to provide a way to access most of IRC features using any XMPP +client. It doesn’t however try to provide a complete mapping of the +features of both worlds simply because this is not useful and most probably +impossible. For example all IRC modes are not all translatable into an XMPP +features. Some of theme are (like +m (mute) or +o (operator) modes), but +some others are IRC-specific. If IRC is the limiting factor (for example +you cannot have a non-ASCII nickname on IRC) then biboumi doesn’t try to +work around this issue: it just enforces the rules of the IRC server by +telling the user that he/she must choose an ASCII nickname only. An +important goal is to keep the software (and its code) light and simple. + +================ + Install +================ +Refer to the INSTALL file. + +================ + Authors +================ +Florent Le Coz (louiz’) + +================= + Contact/Support +================= +Jabber ChatRoom: biboumi@muc.poezio.eu +Report a bug: http://dev.louiz.org/projects/biboumi/issues/new + +================= + License +================= +Biboumi is Free Software. +(learn more: http://www.gnu.org/philosophy/free-sw.html) + +Biboumi is released under the zlib license. +Please read the COPYING file for details. diff --git a/doc/biboumi.1 b/doc/biboumi.1 new file mode 100644 index 0000000..c874062 --- /dev/null +++ b/doc/biboumi.1 @@ -0,0 +1,192 @@ +.TH biboumi 1 2013-11-21 +. +.SH NAME +. +\fBbiboumi\fR - XMPP gateway to IRC +. +.SH SYNOPSIS +. +\fBbiboumi\fR [\fIconfig_filename\fR] +. +.SH DESCRIPTION +. +Biboumi is an XMPP gateway that connects to IRC servers and translates +between the two protocols. It can be used to access IRC channels using any +XMPP client as if these channels were XMPP MUCs. +. +.SH OPTIONS +. +Available options: +.TP +\fBconfig_filename\fR +Specify the file to read for configuration. See \fBCONFIG\fR section for +more details on its content. +. +.SH CONFIG +. +The configuration file uses a simple format of the form +\fB"option=value"\fR. Here is a description of each possible option: +.TP +\fBhostname\fR (mandatory) +The hostname served by the XMPP gateway. This domain must be configured in +the XMPP server as an external component. See the manual for your XMPP +server for more information. +.TP +\fBpassword\fR (mandatory) +The password used to authenticate the XMPP component to your XMPP server. +This password must be configured in the XMPP server, associated with the +external component on \fBhostname\fR. +. +.SH USAGE +. +When started, biboumi connects, without encryption (see \fBSECURITY\fR), to +the local XMPP server on the port \fI5347\fR and provides the configured +password to authenticate. Biboumi then serves the configured +\fIhostname\fR, this means that all XMPP stanza with a \fIto\fR JID on that +domain will be sent to biboumi, and biboumi will send only send messages +coming from this hostname. +. +When an user joins an IRC channel on an IRC server (see \fBJoin an IRC +channel\fR), biboumi connects to the remote IRC server, sets the user’s nick +as requested, and then tries to join the specified channel. If the same +user subsequently tries to connect to an other channel on the same server, +the same IRC connection is used. If, however, an other user wants to join +an IRC channel on that same IRC server, biboumi opens a new connection to +that server. Biboumi connects once to each IRC server, for each user on it. +. +.SS "Addressing" +. +IRC entities are represented by XMPP JIDs. The domain part of the JID is +the domain served by biboumi, and the local part depends on the concerned +entity. +. +IRC channels and IRC users JIDs have a localpart formed like this: \fIname\fR, +the '\fI%\fR' separator and the \fIirc_server\fR. +. +For an IRC channel, the name starts with '\fI&\fR', '\fI#\fR', '\fI+\fR' +or '\fI!\fR'. Some other gateway implementations, as well as some IRC +clients, do not require them to be started by one of these characters, +adding an implicit '\fI#\fR' in that case. Biboumi does not do that because +this gets confusing when trying to understand the difference between +\fIfoo\fR, \fI#foo\fR, and \fI##foo\fR. +. +If the name starts with any other character, this represents an IRC user. +. +.SS "Join an IRC channel" +. +To join an IRC channel \fI#foo\fR on the IRC server \fIirc.example.com\fR, +join the XMPP MUC \fI#foo%irc.example.com@hostname\fR. +. +.SS "Channel messages" +. +On XMPP, unlike on IRC, the displayed order of the messages is the same for +all participants of a MUC. Biboumi can not however provide this feature, as +it cannot know whether the IRC server has received and forwarded the +messages to other users. This means that the order of the messages +displayed in your XMPP may not be the same than the order on other IRC +users’. +. +.SS "Nicknames" +. +On IRC, nicknames are server-wide. This means that one user only has one +single nickname at one given time on all the channels of a server. This is +different from XMPP where an user can have a different nick on each MUC, +even if these MUCs are on the same server. +. +This means that the nick you choose when joining your first IRC channel on a +given IRC server will be your nickname in all other channels that you join +on that same IRC server. +If you explicitely change your nickname on one channel, your nickname will +be changed on all channels on the same server as well. +. +.SS "Private messages" +. +Private messages are handled differently on IRC and on XMPP. On IRC, you +talk directly to one server-user: toto on the channel #foo is the same user +than toto on the channel #bar (as long as these two channels are on the same +IRC server). Using biboumi, there is no way to receive a message from a +room participant (from a jid like \fI#test%irc.example.com/\fBnickname\fR). +Instead, private messages are received from and sent to the user (using a +jid like \fBnickname\fI%irc.example.com\fR). For conveniance and +compatibility with XMPP clients sending private messages to the MUC +participants, a message sent to +\fB#chan%irc.example.com@irc.example.net/Nickname\fR will be redirected to +\fBNickname%irc.example.com@irc.example.net\fR, although this is not the +prefered way to do it. +. +.SS "Notices" +. +Notices are received exactly like private messages. It is not possible to +send a notice. +. +.SS "Kicks and bans" +. +Kicks are transparently translated from one protocol to another. However +banning an XMPP participant has no effect. To ban an user you need to set a +mode +b on that user nick or host (see \fBMODES\fR) and then kick it. +. +.SS "Encoding" +. +On XMPP, the encoding is always \fIUTF-8\fR, whereas on IRC the encoding of +each message can be anything. +. +This means that biboumi has to convert everything coming from IRC into UTF-8 +without knowing the encoding of the received messages. To do so, it checks +if each message is UTF-8 valid, if not it tries to convert from +\fIiso_8859-1\fR (because this appears to be the most common case, at least +on the channels I visit) to \fIUTF-8\fR. If that conversion fails at some +point, a placeholder character '\f�\fR' is inserted to indicate this +decoding error. +. +Messages are always sent in UTF-8 over IRC, no conversion is done in that +direction. +. +.SS "IRC modes" +. +One feature that doesn’t exist on XMPP but does on IRC is the \fImodes\fR. +Although some of these modes have a correspondance in the XMPP world (for +example the \fI+o\fR mode on an user corresponds to the \fImoderator\fR role +in XMPP), it is impossible to map all these modes to an XMPP feature. To +circumvent this problem, biboumi provides a raw notification when modes are +changed, and lets the user change the modes directly. +. +To change modes, simply send a message starting with “\fB/mode\fR” followed +by the modes and the arguments you want to send to the IRC server. For +example “/mode +aho louiz”. Note that your XMPP client may +inteprete messages begining with “/” like a command. To actually send a +message starting with a slash, you may need to start your message with +“//mode” or “/say /mode”, depending on your client. +. +When a mode is changed, the user is notified by a message coming from the +MUC bare JID, looking like “Mode #foo [+ov] [toto tutu]”. In addition, if +the mode change can be translated to an XMPP feature, the user will be +notified of this XMPP event as well. For example if a mode “+o toto” is +received, then toto’s role will be changed to moderator. The mapping +between IRC modes and XMPP features is as follow: +. +.TP +.B +o +Sets the participant’s role to \fImoderator\fR. +. +.TP +.B +a +Sets the participant’s role to \admin\fR. +. +.TP +.B +v +Sets the participant’s affiliation to \fImember\fR. +. +.SH SECURITY +. +Biboumi does not provide any encryption mechanism: connection to the XMPP +server MUST be made on localhost. The XMPP server is not supposed to accept +non-local connection from components, thus encryption is useless. IRC +SSL/TLS is also not implemented although this could be useful for some +users, this is however not a high priority feature. +. +Biboumi also does not check if JIDs are properly formatted using nodeprep. +This must be done by the XMPP server to which biboumi is directly connected. +. +.SH AUTHORS +. +Written by Florent Le Coz -- cgit v1.2.3