Add some documentation
This commit is contained in:
Florent Le Coz
@@ -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.
|
||||||
@@ -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
|
||||||
@@ -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’) <louiz@louiz.org>
|
||||||
|
|
||||||
|
=================
|
||||||
|
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.
|
||||||
+192
@@ -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
|
||||||
Reference in New Issue
Block a user