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 --- doc/biboumi.1.md | 493 ---------------------------------------------------- doc/biboumi.1.rst | 507 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 507 insertions(+), 493 deletions(-) delete mode 100644 doc/biboumi.1.md create mode 100644 doc/biboumi.1.rst (limited to 'doc') 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