From 6f3dacc40d0f218348329dafa03d3088b768e98c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?louiz=E2=80=99?= Date: Fri, 13 May 2016 01:55:03 +0200 Subject: First rst attempt --- INSTALL.md | 156 ----------------- INSTALL.rst | 161 +++++++++++++++++ README.md | 61 ------- README.rst | 62 +++++++ doc/biboumi.1.md | 493 ---------------------------------------------------- doc/biboumi.1.rst | 507 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 730 insertions(+), 710 deletions(-) delete mode 100644 INSTALL.md create mode 100644 INSTALL.rst delete mode 100644 README.md create mode 100644 README.rst delete mode 100644 doc/biboumi.1.md create mode 100644 doc/biboumi.1.rst diff --git a/INSTALL.md b/INSTALL.md deleted file mode 100644 index 7709fe9..0000000 --- a/INSTALL.md +++ /dev/null @@ -1,156 +0,0 @@ -tl;dr -===== - - cmake . && make && ./biboumi - -If that didn’t work, read on. - -Dependencies -============ - -Build and runtime dependencies: - -Tools: - -- A C++14 compiler (clang >= 3.4 or gcc >= 4.9 for example) -- CMake -- ronn (optional) to build the man page - -Libraries: - -- 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/ - -- libuuid - Generate unique IDs - http://sourceforge.net/projects/libuuid/ - -- libidn (optional, but recommended) - Provides the stringprep functionality. Without it, JIDs for IRC users are - not provided. - http://www.gnu.org/software/libidn/ - -- c-ares (optional, but recommended) - Asynchronously resolve domain names. This offers better reactivity and - performances when connecting to a big number of IRC servers at the same - time. - http://c-ares.haxx.se/ - -- libbotan 1.11 (optional) - Provides TLS support. Without it, IRC connections are all made in - plain-text mode. - Other branches than the 1.11 are not supported. - http://botan.randombit.net/ - -- litesql (optional) - Provides a way to store various options in a (sqlite3) database. Each user - of the gateway can store their own values (for example their prefered port, - or their IRC password). - http://git.louiz.org/litesql - -- systemd (optional) - Provides the support for a systemd service of Type=notify. This is useful only - if you are packaging biboumi in a distribution with Systemd. - - -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. - -The default build type is "Debug", if you want to build a release version, -set the CMAKE_BUILD_TYPE variable to "release", by running this command -instead: - - cmake . -DCMAKE_BUILD_TYPE=release -DCMAKE_INSTALL_PREFIX=/usr - -You can also configure many parameters of the build (like customize CFLAGS, -the install path, choose the compiler, or enabling some options like the -POLLER to use), using the ncurses interface of ccmake: - - 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. - -You can also configure these options using a -D command line flag. - -The list of available options: - -- POLLER: lets you select the poller used by biboumi, at - compile-time. Possible values are: - EPOLL: use the Linux-specific epoll(7). This is the default on Linux. - POLL: use the standard poll(2). This is the default value on all non-Linux - platforms. - -- WITH_BOTAN and WITHOUT_BOTAN: The first force the usage of the Botan library, - if it is not found, the configuration process will fail. The second will - make the build process ignore the Botan library, it will not be used even - if it's available on the system. If none of these option is specified, the - library will be used if available and will be ignored otherwise. - -- WITH_LIBIDN and WITHOUT_LIBIDN: Just like the WITH(OUT)_BOTAN options, but - for the IDN library - -- WITH_SYSTEMD and WITHOUT_SYSTEMD: Just like the other WITH(OUT)_* options, - but for the Systemd library - -Example: - - cmake . -DCMAKE_BUILD_TYPE=release -DCMAKE_INSTALL_PREFIX \ - -DWITH_BOTAN=1 -DWITHOUT_SYSTEMD=1 - -This command will configure the project to build a release, with TLS enabled -(using Botan) but without using Systemd (even if available on the system). - - -Build -===== - -- Once you’ve configured everything using cmake, build the project - - make - - -Install -======= - -- And then, optionaly, Install the software system-wide - - make install - - -Testing -======= - -You can run the test suite with - - make check - -This project uses the Catch unit test framework, it will be automatically -fetched with cmake, by cloning the github repository. - -You can also check the overall code coverage of this test suite by running - - make coverage - -This requires gcov and lcov to be installed. - - -Run -=== - -Run the software using the `biboumi` binary. Read the documentation (the -man page biboumi(1) or the `biboumi.1.md` file) for more information on how -to use biboumi. diff --git a/INSTALL.rst b/INSTALL.rst new file mode 100644 index 0000000..1e5d0f5 --- /dev/null +++ b/INSTALL.rst @@ -0,0 +1,161 @@ +INSTALL +======= + +tl;dr +----- + + cmake . && make && ./biboumi + +If that didn’t work, read on. + +Dependencies +------------ + +Build and runtime dependencies: + +Tools: +~~~~~~ + +- A C++14 compiler (clang >= 3.4 or gcc >= 4.9 for example) +- CMake +- ronn (optional) to build the man page + +Libraries: +~~~~~~~~~~ + +expat_ + Used to parse XML from the XMPP server. + +libiconv_ + Encoding from anything into UTF-8 + +libuuid_ + Generate unique IDs + +libidn_ (optional, but recommended) + Provides the stringprep functionality. Without it, JIDs for IRC users are + not provided. + +c-ares_ (optional, but recommended) + Asynchronously resolve domain names. This offers better reactivity and + performances when connecting to a big number of IRC servers at the same + time. + +libbotan_ 1.11 (optional) + Provides TLS support. Without it, IRC connections are all made in + plain-text mode. + Other branches than the 1.11 are not supported. + +litesql_ (optional) + Provides a way to store various options in a (sqlite3) database. Each user + of the gateway can store their own values (for example their prefered port, + or their IRC password). + +systemd_ (optional) + Provides the support for a systemd service of Type=notify. This is useful only + if you are packaging biboumi in a distribution with Systemd. + + +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. + +The default build type is "Debug", if you want to build a release version, +set the CMAKE_BUILD_TYPE variable to "release", by running this command +instead: + + cmake . -DCMAKE_BUILD_TYPE=release -DCMAKE_INSTALL_PREFIX=/usr + +You can also configure many parameters of the build (like customize CFLAGS, +the install path, choose the compiler, or enabling some options like the +POLLER to use), using the ncurses interface of ccmake: + + 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. + +You can also configure these options using a -D command line flag. + +The list of available options: + +- POLLER: lets you select the poller used by biboumi, at + compile-time. Possible values are: + + - EPOLL: use the Linux-specific epoll(7). This is the default on Linux. + - POLL: use the standard poll(2). This is the default value on all non-Linux + platforms. + +- WITH_BOTAN and WITHOUT_BOTAN: The first force the usage of the Botan library, + if it is not found, the configuration process will fail. The second will + make the build process ignore the Botan library, it will not be used even + if it's available on the system. If none of these option is specified, the + library will be used if available and will be ignored otherwise. + +- WITH_LIBIDN and WITHOUT_LIBIDN: Just like the WITH(OUT)_BOTAN options, but + for the IDN library + +- WITH_SYSTEMD and WITHOUT_SYSTEMD: Just like the other WITH(OUT)_* options, + but for the Systemd library + +Example: + + cmake . -DCMAKE_BUILD_TYPE=release -DCMAKE_INSTALL_PREFIX=/usr + -DWITH_BOTAN=1 -DWITHOUT_SYSTEMD=1 + +This command will configure the project to build a release, with TLS enabled +(using Botan) but without using Systemd (even if available on the system). + + +Build +----- +Once you’ve configured everything using cmake, build the project + + make + + +Install +------- +And then, optionaly, Install the software system-wide + + make install + + +Testing +------- +You can run the test suite with + + make check + +This project uses the Catch unit test framework, it will be automatically +fetched with cmake, by cloning the github repository. + +You can also check the overall code coverage of this test suite by running + + make coverage + +This requires gcov and lcov to be installed. + + +Run +--- +Run the software using the `biboumi` binary. Read the documentation (the +man page biboumi(1) or the `biboumi.1.rst`_ file) for more information on how +to use biboumi. + +.. _expat: http://expat.sourceforge.net/ +.. _libiconv: http://www.gnu.org/software/libiconv/ +.. _libuuid: http://sourceforge.net/projects/libuuid/ +.. _libidn: http://www.gnu.org/software/libidn/ +.. _libbotan: http://botan.randombit.net/ +.. _c-ares: http://c-ares.haxx.se/ +.. _litesql: http://git.louiz.org/litesql +.. _systemd: https://www.freedesktop.org/wiki/Software/systemd/ +.. _biboumi.1.rst: doc/biboumi.1.rst diff --git a/README.md b/README.md deleted file mode 100644 index b8b5124..0000000 --- a/README.md +++ /dev/null @@ -1,61 +0,0 @@ -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++14 and makes 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 them 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-only nickname. An -important goal is to keep the software (and its code) light and simple. - - -Install -======= -Refer to the [INSTALL][] file. - -Usage -===== - -Read [the documentation](doc/biboumi.1.md). - -Authors -======= -Florent Le Coz (louiz’) - - -Contact/Support -=============== -* XMPP ChatRoom: biboumi@muc.poez.io -* Report a bug: https://dev.louiz.org/projects/biboumi/issues/new - -To contribute, the preferred way is to commit your changes on some -publicly-available git repository (your own, or github -(https://github.com/louiz/biboumi), or a fork on https://lab.louiz.org) and -to notify the developers with a ticket on the bug tracker -(https://dev.louiz.org/projects/biboumi/issues/new), a pull request on -github or a merge request on gitlab. - -Optionally you can come discuss your changes on the XMPP chat room, -beforehand. - - -Licence -======= -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. - -[INSTALL]: INSTALL diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..a7f9348 --- /dev/null +++ b/README.rst @@ -0,0 +1,62 @@ +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++14 and makes 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 them 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-only nickname. An +important goal is to keep the software (and its code) light and simple. + + +Install +------- +Refer to the INSTALL_ file. + + +Usage +----- +Read `the documentation`_. + +Authors +------- +Florent Le Coz (louiz’) + + +Contact/Support +--------------- +* XMPP ChatRoom: biboumi@muc.poez.io +* Report a bug: https://dev.louiz.org/projects/biboumi/issues/new + +To contribute, the preferred way is to commit your changes on some +publicly-available git repository (your own, or github +(https://github.com/louiz/biboumi), or a fork on https://lab.louiz.org) and +to notify the developers with a ticket on the bug tracker +(https://dev.louiz.org/projects/biboumi/issues/new), a pull request on +github or a merge request on gitlab. + +Optionally you can come discuss your changes on the XMPP chat room, +beforehand. + + +Licence +------- +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. + +.. _INSTALL: INSTALL.rst +.. _the documentation: doc/biboumi.1.rst diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md deleted file mode 100644 index 3a1fb28..0000000 --- a/doc/biboumi.1.md +++ /dev/null @@ -1,493 +0,0 @@ -BIBOUMI 1 "2014-06-02" -====================== - -NAME ----- - -biboumi - XMPP gateway to IRC - -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. - -SYNOPSIS --------- - -`biboumi` [`config_filename`] - -OPTIONS -------- - -Available command line options: - -`config_filename` - - Specify the file to read for configuration. See *CONFIG* section for more - details on its content. - -CONFIG ------- - -The configuration file uses a simple format of the form -`"option=value"`. Here is a description of each possible option: - -`hostname` (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. - For prosody, see http://prosody.im/doc/components#adding_an_external_component - -`password` (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 *hostname*. - -`xmpp_server_ip` - - The IP address to connect to the XMPP server on. The connection to the XMPP - server is unencrypted, so the biboumi instance and the server should normally - be on the same host. The default value is 127.0.0.1. - -`port` - - The TCP port to use to connect to the local XMPP component. The default - value is 5347. - -`admin` - - The bare JID of the gateway administrator. This JID will have more - privileges than other standard users (the admin thus needs to check their - privileges), for example some administration ad-hoc commands will only be - available to that JID. - -`fixed_irc_server` - - If this option contains the hostname of an IRC server (for example - irc.example.org), then biboumi will enforce the connexion to that IRC - server only. This means that a JID like "#chan@biboumi.example.com" must - be used instead of "#chan%irc.example.org@biboumi.example.com". In that - mode, the virtual channel (see *Connect to an IRC server*) is not - available and you still need to use the ! separator to send message to an - IRC user (for example "foo!@biboumi.example.com" to send a message to - foo), although the in-room JID still work as expected - ("#channel@biboumi.example.com/Nick"). On the other hand, the '%' lose - any meaning. It can appear in the JID but will not be interpreted as a - separator (thus the JID "#channel%hello@biboumi.example.com" points to the - channel named "#channel%hello" on the configured IRC server) This option - can for example be used by an administrator that just wants to let their - users join their own IRC server using an XMPP client, while forbidding - access to any other IRC server. - -`realname_customization` - - If this option is set to “false” (default is “true”), the users will not be - able to use the ad-hoc commands that lets them configure their realname and - username. - -`realname_from_jid` - - If this option is set to “true”, the realname and username of each biboumi - user will be extracted from their JID. The realname is their bare JID, and - the username is the node-part of their JID. Note that if - `realname_customization` is “true”, each user will still be able to - customize their realname and username, this option just decides the default - realname and username. - - If this option is set to “false” (the default value), the realname and - username of each user will be set to the nick they used to connect to the - IRC server. - -`webirc_password` - - Configure a password to be communicated to the IRC server, as part of the - WEBIRC message (see https://kiwiirc.com/docs/webirc). If this option is - set, an additional DNS resolution of the hostname of each XMPP server will - be made when connecting to an IRC server. - -`log_file` - - A filename into which logs are written. If none is provided, the logs are - written on standard output. - -`log_level` - - Indicate what type of log messages to write in the logs. Value can be - from 0 to 3. 0 is debug, 1 is info, 2 is warning, 3 is error. The - default is 0, but a more practical value for production use is 1. - -`ca_file` - - Specifies which file should be use as the list of trusted CA when - negociating a TLS session. By default this value is unset and biboumi - tries a list of well-known paths. - -`outgoing_bind` - - An address (IPv4 or IPv6) to bind the outgoing sockets to. If no value is - specified, it will use the one assigned by the operating system. You can - for example use outgoing_bind=192.168.1.11 to force biboumi to use the - interface with this address. Note that this is only used for connections - to IRC servers. - -The configuration can be re-read at runtime (you can for example change the -log level without having to restart biboumi) by sending SIGUSR1 or SIGUSR2 -(see kill(1)) to the process. - -USAGE ------ - -Biboumi acts as a server, it should be run as a daemon that lives in the -background for as long as it is needed. Note that biboumi does not -daemonize itself, this task should be done by your init system (SysVinit, -systemd, upstart). - -When started, biboumi connects, without encryption (see *SECURITY*), to the -local XMPP server on the port `5347` and authenticates with the provided -password. Biboumi then serves the configured `hostname`: this means that -all XMPP stanza with a `to` JID on that domain will be forwarded to biboumi -by the XMPP server, and biboumi will only send messages coming from that -hostname. - -When a user joins an IRC channel on an IRC server (see *Join an IRC -channel*), 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. - -To cleanly shutdown the component, send a SIGINT or SIGTERM signal to it. -It will send messages to all connected IRC and XMPP servers to indicate a -reason why the users are being disconnected. Biboumi exits when the end of -communication is acknowledged by all IRC servers. If one or more IRC -servers do not respond, biboumi will only exit if it receives the same -signal again or if a 2 seconds delay has passed. - -### Addressing - -IRC entities are represented by XMPP JIDs. The domain part of the JID is -the domain served by biboumi (the part after the `@`, biboumi.example.com in -the examples), and the local part (the part before the `@`) depends on the -concerned entity. - -IRC channels have a local part formed like this: -`channel_name`%`irc_server`. - -If the IRC channel you want to adress starts with the `'#'` character (or an -other character, announced by the IRC server, like `'&'`, `'+'` or `'!'`), -then you must include it in the JID. 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 `'#'` in that case. Biboumi does not do that -because this gets confusing when trying to understand the difference between -the channels *#foo*, and *##foo*. Note that biboumi does not use the -presence of these special characters to identify an IRC channel, only the -presence of the separator `%` is used for that. - -The channel name can also be empty (for example `%irc.example.com`), in that -case this represents the virtual channel provided by biboumi. See *Connect -to an IRC server* for more details. - -There is two ways to address an IRC user, using a local part like this: -`nickname`!`irc_server` -or by using the in-room address of the participant, like this: -`channel_name`%`irc_server`@`biboumi.example.com`/`Nickname` - -The second JID is available only to be compatible with XMPP clients when the -user wants to send a private message to the participant `Nickname` in the -room `channel_name%irc_server@biboumi.example.com`. - -On XMPP, the node part of the JID can only be lowercase. On the other hand, -IRC nicknames are case-insensitive, this means that the nicknames toto, -Toto, tOtO and TOTO all represent the same IRC user. This means you can -talk to the user toto, and this will work. - -Also note that some IRC nicknames may contain characters that are not -allowed in the local part of a JID (for example '@'). If you need to send a -message to a nick containing such a character, you have to use a jid like -`%irc.example.com@biboumi.example.com/AnnoyingNickn@me`, because the JID -`AnnoyingNickn@me!irc.example.com@biboumi.example.com` would not work. - -Examples: - - `#foo%irc.example.com@biboumi.example.com` is the #foo IRC channel, on the - irc.example.com IRC server, and this is served by the biboumi instance on - biboumi.example.com - - `toto!irc.example.com@biboumi.example.com` is the IRC user named toto, or - TotO, etc. - - `irc.example.com@biboumi.example.com` is the IRC server irc.example.com. - - `%irc.example.com@biboumi.example.com` is the virtual channel provided by - biboumi, for the IRC server irc.example.com. - -Note: Some JIDs are valid but make no sense in the context of -biboumi: - - `!irc.example.com@biboumi.example.com` is the empty-string nick on the - irc.example.com server. It makes no sense to try to send messages to it. - - `#test%@biboumi.example.com`, or any other JID that does not contain an - IRC server is invalid. Any message to that kind of JID will trigger an - error, or will be ignored. - -If compiled with Libidn, an IRC channel participant has a bare JID -representing the “hostname” provided by the IRC server. This JID can only -be used to set IRC modes (for example to ban a user based on its IP), or to -identify user. It cannot be used to contact that user using biboumi. - -### Join an IRC channel - -To join an IRC channel `#foo` on the IRC server `irc.example.com`, -join the XMPP MUC `#foo%irc.example.com@hostname`. - -### Connect to an IRC server - -The connection to the IRC server is automatically made when the user tries -to join any channel on that IRC server. The connection is closed whenever -the last channel on that server is left by the user. To be able to stay -connected to an IRC server without having to be in a real IRC channel, -biboumi provides a virtual channel on the jid -`%irc.example.com@biboumi.example.com`. For example if you want to join the -channel `#foo` on the server `irc.example.com`, but you need to authenticate -to a bot of the server before you’re allowed to join it, you can first join -the room `%irc.example.com@biboumi.example.com` (this will effectively -connect you to the IRC server without joining any room), then send your -authentication message to the user `bot!irc.example.com@biboumi.example.com` -and finally join the room `#foo%irc.example.com@biboumi.example.com`. - -### 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 client may not be the same than the order on other -IRC users’. - -### List channels - -You can list the IRC channels on a given IRC server by sending an XMPP disco -items request on the IRC server JID. The number of channels on some servers -is huge, and biboumi does not (yet) support result set management (XEP 0059) -so the result stanza may be very big. - -### 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 a 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. -Joining a new channel with a different nick, however, will not change your -nick. The provided nick will be ignored, in order to avoid changing your -nick on the whole server by mistake. If you want to have a different -nickname in the channel you’re going to join, you need to do it explicitly -with the NICK command before joining the channel. - -### 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 -as toto on the channel #bar (as long as these two channels are on the same -IRC server). By default you will receive private messages from the “global” -user (aka nickname!irc.example.com@biboumi.example.com), unless you -previously sent a message to an in-room participant (something like -\#test%irc.example.com@biboumi.example.com/nickname), in which case future -messages from that same user will be received from that same “in-room” JID. - -### Notices - -Notices are received exactly like private messages. It is not possible to -send a notice. - -### 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 *MODES*) and then kick it. - -### Encoding - -On XMPP, the encoding is always `UTF-8`, 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 -`iso_8859-1` (because this appears to be the most common case, at least -on the channels I visit) to `UTF-8`. If that conversion fails at some -point, a placeholder character `'�'` is inserted to indicate this -decoding error. - -Messages are always sent in UTF-8 over IRC, no conversion is done in that -direction. - -### IRC modes - -One feature that doesn’t exist on XMPP but does on IRC is the `modes`. -Although some of these modes have a correspondance in the XMPP world (for -example the `+o` mode on a user corresponds to the `moderator` 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 “`/mode`” 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 interprete 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: - -`+q` - - Sets the participant’s role to `moderator` and its affiliation to `owner`. - -`+a` - - Sets the participant’s role to `moderator` and its affiliation to `owner`. - -`+o` - - Sets the participant’s role to `moderator` and its affiliation to `admin`. - -`+h` - - Sets the participant’s role to `moderator` and its affiliation to `member`. - -`+v` - - Sets the participant’s role to `participant` and its affiliation to `member`. - -Similarly, when a biboumi user changes some participant's affiliation or role, biboumi translates that in an IRC mode change. - -Affiliation set to `none` - - Sets mode to -vhoaq - -Affiliation set to `member` - - Sets mode to +v-hoaq - -Role set to `moderator` - - Sets mode to +h-oaq - -Affiliation set to `admin` - - Sets mode to +o-aq - -Affiliation set to `owner` - - Sets mode to +a-q - -### Ad-hoc commands - -Biboumi supports a few ad-hoc commands, as described in the XEP 0050. -Different ad-hoc commands are available for each JID type. - -#### On the gateway itself (e.g on the JID biboumi.example.com): - - - ping: Just respond “pong” - - - hello: Provide a form, where the user enters their name, and biboumi - responds with a nice greeting. - - - disconnect-user: Only available to the administrator. The user provides - a list of JIDs, and a quit message. All the selected users are - disconnected from all the IRC servers to which they were connected, - using the provided quit message. Sending SIGINT to biboumi is equivalent - to using this command by selecting all the connected JIDs and using the - “Gateway shutdown” quit message, except that biboumi does not exit when - using this ad-hoc command. - - - disconnect-from-irc-servers: Disconnect a single user from one or more - IRC server. The user is immediately disconnected by closing the socket, - no message is sent to the IRC server, but the user is of course notified - with an XMPP message. The administrator can disconnect any user, while - the other users can only disconnect themselves. - -#### On a server JID (e.g on the JID chat.freenode.org@biboumi.example.com) - - - Configure: Lets each user configure some options that applies to the - concerned IRC server. - -#### On a channel JID (e.g on the JID #test%chat.freenode.org@biboumi.example.com) - - - Configure: Lets each user configure some options that applies to the - concerned IRC channel. Some of these options, if not configured for a - specific channel, defaults to the value configured at the IRC server - level. For example the encoding can be specified for both the channel - and the server. If an encoding is not specified for a channel, the - encoding configured in the server applies. - -### Raw IRC messages - -Biboumi tries to support as many IRC features as possible, but doesn’t -handle everything yet (or ever). In order to let the user send any -arbitrary IRC message, biboumi forwards any XMPP message received on an IRC -Server JID (see *ADDRESSING*) as a raw command to that IRC server. - -For example, to WHOIS the user Foo on the server irc.example.com, a user can -send the message “WHOIS Foo” to “irc.example.com@biboumi.example.com”. - -The message will be forwarded as is, without any modification appart from -adding "\r\n" at the end (to make it a valid IRC message). You need to have -a little bit of understanding of the IRC protocol to use this feature. - -SECURITY --------- - -The connection to the XMPP server can only be made on localhost. The -XMPP server is not supposed to accept non-local connections from components. -Thus, encryption is not used to connect to the local XMPP server because it -is useless. - -If compiled with the Botan library, biboumi can use TLS when communicating -with the IRC serveres. It will first try ports 6697 and 6670 and use TLS if -it succeeds, if connection fails on both these ports, the connection is -established on port 6667 without any encryption. - -Biboumi does not check if the received JIDs are properly formatted using -nodeprep. This must be done by the XMPP server to which biboumi is directly -connected. - -Note if you use a biboumi that you have no control on: remember that the -administrator of the gateway you use is able to view all your IRC -conversations, whether you’re using encryption or not. This is exactly as -if you were running your IRC client on someone else’s server. Only use -biboumi if you trust its administrator (or, better, if you are the -administrator) or if you don’t intend to have any private conversation. - -Biboumi does not provide a way to ban users from connecting to it, has no -protection against flood or any sort of abuse that your users may cause on -the IRC servers. Some XMPP server however offer the possibility to restrict -what JID can access a gateway. Use that feature if you wish to grant access -to your biboumi instance only to a list of trusted users. - -AUTHORS -------- - -This software and man page are both written by Florent Le Coz. - -LICENSE -------- - -Biboumi is released under the zlib license. diff --git a/doc/biboumi.1.rst b/doc/biboumi.1.rst new file mode 100644 index 0000000..6411efe --- /dev/null +++ b/doc/biboumi.1.rst @@ -0,0 +1,507 @@ +======================= +Biboumi(1) User Manual +======================= + +.. contents:: :depth: 2 + + +NAME +==== + +biboumi - XMPP gateway to IRC + +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. + +Synopsis +======== + +biboumi [*config_filename*\ ] + +Options +======= + +Available command line options: + +config_filename +--------------- + +Specify the file to read for configuration. See *CONFIG* section for more +details on its content. + +Configuration +============= + +The configuration file uses a simple format of the form +``option=value``. Here is a description of each possible option: + +The configuration can be re-read at runtime (you can for example change the +log level without having to restart biboumi) by sending SIGUSR1 or SIGUSR2 +(see kill(1)) to the process. + +hostname +-------- + +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. For prosody, see +http://prosody.im/doc/components#adding_an_external_component + +password +-------- + +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 *hostname*. + +xmpp_server_ip +-------------- + +The IP address to connect to the XMPP server on. The connection to the +XMPP server is unencrypted, so the biboumi instance and the server should +normally be on the same host. The default value is 127.0.0.1. + +port +---- + +The TCP port to use to connect to the local XMPP component. The default +value is 5347. + +admin +----- + +The bare JID of the gateway administrator. This JID will have more +privileges than other standard users (the admin thus needs to check their +privileges), for example some administration ad-hoc commands will only be +available to that JID. + +fixed_irc_server +---------------- + +If this option contains the hostname of an IRC server (for example +irc.example.org), then biboumi will enforce the connexion to that IRC +server only. This means that a JID like "#chan@biboumi.example.com" must +be used instead of "#chan%irc.example.org@biboumi.example.com". In that +mode, the virtual channel (see `Connect to an IRC server`_) is not +available and you still need to use the ! separator to send message to an +IRC user (for example "foo!@biboumi.example.com" to send a message to +foo), although the in-room JID still work as expected +("#channel@biboumi.example.com/Nick"). On the other hand, the '%' lose +any meaning. It can appear in the JID but will not be interpreted as a +separator (thus the JID "#channel%hello@biboumi.example.com" points to the +channel named "#channel%hello" on the configured IRC server) This option +can for example be used by an administrator that just wants to let their +users join their own IRC server using an XMPP client, while forbidding +access to any other IRC server. + +realname_customization +---------------------- + +If this option is set to “false” (default is “true”), the users will not be +able to use the ad-hoc commands that lets them configure their realname and +username. + +realname_from_jid +----------------- + +If this option is set to “true”, the realname and username of each biboumi +user will be extracted from their JID. The realname is their bare JID, and +the username is the node-part of their JID. Note that if +``realname_customization`` is “true”, each user will still be able to +customize their realname and username, this option just decides the default +realname and username. + +If this option is set to “false” (the default value), the realname and +username of each user will be set to the nick they used to connect to the +IRC server. + +webirc_password +--------------- + +Configure a password to be communicated to the IRC server, as part of the +WEBIRC message (see https://kiwiirc.com/docs/webirc). If this option is +set, an additional DNS resolution of the hostname of each XMPP server will +be made when connecting to an IRC server. + +log_file +-------- + +A filename into which logs are written. If none is provided, the logs are +written on standard output. + +log_level +--------- + +Indicate what type of log messages to write in the logs. Value can be +from 0 to 3. 0 is debug, 1 is info, 2 is warning, 3 is error. The +default is 0, but a more practical value for production use is 1. + +ca_file +------- + +Specifies which file should be use as the list of trusted CA when +negociating a TLS session. By default this value is unset and biboumi +tries a list of well-known paths. + +outgoing_bind +------------- + +An address (IPv4 or IPv6) to bind the outgoing sockets to. If no value is +specified, it will use the one assigned by the operating system. You can +for example use outgoing_bind=192.168.1.11 to force biboumi to use the +interface with this address. Note that this is only used for connections +to IRC servers. + +Usage +===== + +Biboumi acts as a server, it should be run as a daemon that lives in the +background for as long as it is needed. Note that biboumi does not +daemonize itself, this task should be done by your init system (SysVinit, +systemd, upstart). + +When started, biboumi connects, without encryption (see `Security`_), to the +local XMPP server on the port ``5347`` and authenticates with the provided +password. Biboumi then serves the configured ``hostname``: this means that +all XMPP stanza with a `to` JID on that domain will be forwarded to biboumi +by the XMPP server, and biboumi will only send messages coming from that +hostname. + +When a user joins an IRC channel on an IRC server (see `Join an IRC +channel`_), 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. + +To cleanly shutdown the component, send a SIGINT or SIGTERM signal to it. +It will send messages to all connected IRC and XMPP servers to indicate a +reason why the users are being disconnected. Biboumi exits when the end of +communication is acknowledged by all IRC servers. If one or more IRC +servers do not respond, biboumi will only exit if it receives the same +signal again or if a 2 seconds delay has passed. + +Addressing +---------- + +IRC entities are represented by XMPP JIDs. The domain part of the JID is +the domain served by biboumi (the part after the ``@``, biboumi.example.com in +the examples), and the local part (the part before the ``@``) depends on the +concerned entity. + +IRC channels have a local part formed like this: +``channel_name`` % ``irc_server``. + +If the IRC channel you want to adress starts with the ``'#'`` character (or an +other character, announced by the IRC server, like ``'&'``, ``'+'`` or ``'!'``), +then you must include it in the JID. 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 ``'#'`` in that case. Biboumi does not do that +because this gets confusing when trying to understand the difference between +the channels *#foo*, and *##foo*. Note that biboumi does not use the +presence of these special characters to identify an IRC channel, only the +presence of the separator `%` is used for that. + +The channel name can also be empty (for example ``%irc.example.com``), in that +case this represents the virtual channel provided by biboumi. See *Connect +to an IRC server* for more details. + +There is two ways to address an IRC user, using a local part like this: +``nickname`` ! ``irc_server`` +or by using the in-room address of the participant, like this: +``channel_name`` % ``irc_server`` @ ``biboumi.example.com`` / ``Nickname`` + +The second JID is available only to be compatible with XMPP clients when the +user wants to send a private message to the participant ``Nickname`` in the +room ``channel_name%irc_server@biboumi.example.com``. + +On XMPP, the node part of the JID can only be lowercase. On the other hand, +IRC nicknames are case-insensitive, this means that the nicknames toto, +Toto, tOtO and TOTO all represent the same IRC user. This means you can +talk to the user toto, and this will work. + +Also note that some IRC nicknames may contain characters that are not +allowed in the local part of a JID (for example '@'). If you need to send a +message to a nick containing such a character, you have to use a jid like +``%irc.example.com@biboumi.example.com/AnnoyingNickn@me``, because the JID +``AnnoyingNickn@me!irc.example.com@biboumi.example.com`` would not work. + +Examples: + +* ``#foo%irc.example.com@biboumi.example.com`` is the #foo IRC channel, on the + irc.example.com IRC server, and this is served by the biboumi instance on + biboumi.example.com + +* ``toto!irc.example.com@biboumi.example.com`` is the IRC user named toto, or + TotO, etc. + +* ``irc.example.com@biboumi.example.com`` is the IRC server irc.example.com. + +* ``%irc.example.com@biboumi.example.com`` is the virtual channel provided by + biboumi, for the IRC server irc.example.com. + +Note: Some JIDs are valid but make no sense in the context of +biboumi: + +* ``!irc.example.com@biboumi.example.com`` is the empty-string nick on the + irc.example.com server. It makes no sense to try to send messages to it. + +* ``#test%@biboumi.example.com``, or any other JID that does not contain an + IRC server is invalid. Any message to that kind of JID will trigger an + error, or will be ignored. + +If compiled with Libidn, an IRC channel participant has a bare JID +representing the “hostname” provided by the IRC server. This JID can only +be used to set IRC modes (for example to ban a user based on its IP), or to +identify user. It cannot be used to contact that user using biboumi. + +Join an IRC channel +------------------- + +To join an IRC channel ``#foo`` on the IRC server ``irc.example.com``, +join the XMPP MUC ``#foo%irc.example.com@biboumi.example.com``. + +Connect to an IRC server +------------------------ + +The connection to the IRC server is automatically made when the user tries +to join any channel on that IRC server. The connection is closed whenever +the last channel on that server is left by the user. To be able to stay +connected to an IRC server without having to be in a real IRC channel, +biboumi provides a virtual channel on the jid +``%irc.example.com@biboumi.example.com``. For example if you want to join the +channel ``#foo`` on the server ``irc.example.com``, but you need to authenticate +to a bot of the server before you’re allowed to join it, you can first join +the room ``%irc.example.com@biboumi.example.com`` (this will effectively +connect you to the IRC server without joining any room), then send your +authentication message to the user ``bot!irc.example.com@biboumi.example.com`` +and finally join the room ``#foo%irc.example.com@biboumi.example.com``. + +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 client may not be the same than the order on other +IRC users’. + +List channels +------------- + +You can list the IRC channels on a given IRC server by sending an XMPP disco +items request on the IRC server JID. The number of channels on some servers +is huge, and biboumi does not (yet) support result set management (XEP 0059) +so the result stanza may be very big. + +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 a 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. +Joining a new channel with a different nick, however, will not change your +nick. The provided nick will be ignored, in order to avoid changing your +nick on the whole server by mistake. If you want to have a different +nickname in the channel you’re going to join, you need to do it explicitly +with the NICK command before joining the channel. + +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 +as toto on the channel #bar (as long as these two channels are on the same +IRC server). By default you will receive private messages from the “global” +user (aka nickname!irc.example.com@biboumi.example.com), unless you +previously sent a message to an in-room participant (something like +\#test%irc.example.com@biboumi.example.com/nickname), in which case future +messages from that same user will be received from that same “in-room” JID. + +Notices +------- + +Notices are received exactly like private messages. It is not possible to +send a notice. + +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 `IRC modes`_) and then kick it. + +Encoding +-------- + +On XMPP, the encoding is always ``UTF-8``, 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 +``iso_8859-1`` (because this appears to be the most common case, at least +on the channels I visit) to ``UTF-``. If that conversion fails at some +point, a placeholder character ``'�'`` is inserted to indicate this +decoding error. + +Messages are always sent in UTF-8 over IRC, no conversion is done in that +direction. + +IRC modes +--------- + +One feature that doesn’t exist on XMPP but does on IRC is the ``modes``. +Although some of these modes have a correspondance in the XMPP world (for +example the ``+o`` mode on a user corresponds to the ``moderator`` 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 “``/mode``” 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 interprete 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: + +``+q`` + Sets the participant’s role to ``moderator`` and its affiliation to ``owner``. + +``+a`` + Sets the participant’s role to ``moderator`` and its affiliation to ``owner``. + +``+o`` + Sets the participant’s role to ``moderator`` and its affiliation to ``admin``. + +``+h`` + Sets the participant’s role to ``moderator`` and its affiliation to ``member``. + +``+v`` + Sets the participant’s role to `participant` and its affiliation to ``member``. + +Similarly, when a biboumi user changes some participant's affiliation or role, biboumi translates that in an IRC mode change. + +Affiliation set to ``none`` + Sets mode to -vhoaq + +Affiliation set to ``member`` + Sets mode to +v-hoaq + +Role set to ``moderator`` + Sets mode to +h-oaq + +Affiliation set to ``admin`` + Sets mode to +o-aq + +Affiliation set to ``owner`` + Sets mode to +a-q + +Ad-hoc commands +--------------- + +Biboumi supports a few ad-hoc commands, as described in the XEP 0050. +Different ad-hoc commands are available for each JID type. + +On the gateway itself (e.g on the JID biboumi.example.com): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ping: Just respond “pong” + +- hello: Provide a form, where the user enters their name, and biboumi + responds with a nice greeting. + +- disconnect-user: Only available to the administrator. The user provides + a list of JIDs, and a quit message. All the selected users are + disconnected from all the IRC servers to which they were connected, + using the provided quit message. Sending SIGINT to biboumi is equivalent + to using this command by selecting all the connected JIDs and using the + “Gateway shutdown” quit message, except that biboumi does not exit when + using this ad-hoc command. + +- disconnect-from-irc-servers: Disconnect a single user from one or more + IRC server. The user is immediately disconnected by closing the socket, + no message is sent to the IRC server, but the user is of course notified + with an XMPP message. The administrator can disconnect any user, while + the other users can only disconnect themselves. + +On a server JID (e.g on the JID chat.freenode.org@biboumi.example.com) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Configure: Lets each user configure some options that applies to the + concerned IRC server. + +On a channel JID (e.g on the JID #test%chat.freenode.org@biboumi.example.com) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Configure: Lets each user configure some options that applies to the + concerned IRC channel. Some of these options, if not configured for a + specific channel, defaults to the value configured at the IRC server + level. For example the encoding can be specified for both the channel + and the server. If an encoding is not specified for a channel, the + encoding configured in the server applies. + +Raw IRC messages +---------------- + +Biboumi tries to support as many IRC features as possible, but doesn’t +handle everything yet (or ever). In order to let the user send any +arbitrary IRC message, biboumi forwards any XMPP message received on an IRC +Server JID (see *ADDRESSING*) as a raw command to that IRC server. + +For example, to WHOIS the user Foo on the server irc.example.com, a user can +send the message “WHOIS Foo” to “irc.example.com@biboumi.example.com”. + +The message will be forwarded as is, without any modification appart from +adding "\r\n" at the end (to make it a valid IRC message). You need to have +a little bit of understanding of the IRC protocol to use this feature. + +Security +======== + +The connection to the XMPP server can only be made on localhost. The +XMPP server is not supposed to accept non-local connections from components. +Thus, encryption is not used to connect to the local XMPP server because it +is useless. + +If compiled with the Botan library, biboumi can use TLS when communicating +with the IRC serveres. It will first try ports 6697 and 6670 and use TLS if +it succeeds, if connection fails on both these ports, the connection is +established on port 6667 without any encryption. + +Biboumi does not check if the received JIDs are properly formatted using +nodeprep. This must be done by the XMPP server to which biboumi is directly +connected. + +Note if you use a biboumi that you have no control on: remember that the +administrator of the gateway you use is able to view all your IRC +conversations, whether you’re using encryption or not. This is exactly as +if you were running your IRC client on someone else’s server. Only use +biboumi if you trust its administrator (or, better, if you are the +administrator) or if you don’t intend to have any private conversation. + +Biboumi does not provide a way to ban users from connecting to it, has no +protection against flood or any sort of abuse that your users may cause on +the IRC servers. Some XMPP server however offer the possibility to restrict +what JID can access a gateway. Use that feature if you wish to grant access +to your biboumi instance only to a list of trusted users. -- cgit v1.2.3