From 3c5cdec1d11fc03899f7068279cf5430d274124c Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Wed, 27 Nov 2013 00:43:37 +0100 Subject: Add some documentation --- doc/biboumi.1 | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 doc/biboumi.1 (limited to 'doc') diff --git a/doc/biboumi.1 b/doc/biboumi.1 new file mode 100644 index 0000000..c874062 --- /dev/null +++ b/doc/biboumi.1 @@ -0,0 +1,192 @@ +.TH biboumi 1 2013-11-21 +. +.SH NAME +. +\fBbiboumi\fR - XMPP gateway to IRC +. +.SH SYNOPSIS +. +\fBbiboumi\fR [\fIconfig_filename\fR] +. +.SH DESCRIPTION +. +Biboumi is an XMPP gateway that connects to IRC servers and translates +between the two protocols. It can be used to access IRC channels using any +XMPP client as if these channels were XMPP MUCs. +. +.SH OPTIONS +. +Available options: +.TP +\fBconfig_filename\fR +Specify the file to read for configuration. See \fBCONFIG\fR section for +more details on its content. +. +.SH CONFIG +. +The configuration file uses a simple format of the form +\fB"option=value"\fR. Here is a description of each possible option: +.TP +\fBhostname\fR (mandatory) +The hostname served by the XMPP gateway. This domain must be configured in +the XMPP server as an external component. See the manual for your XMPP +server for more information. +.TP +\fBpassword\fR (mandatory) +The password used to authenticate the XMPP component to your XMPP server. +This password must be configured in the XMPP server, associated with the +external component on \fBhostname\fR. +. +.SH USAGE +. +When started, biboumi connects, without encryption (see \fBSECURITY\fR), to +the local XMPP server on the port \fI5347\fR and provides the configured +password to authenticate. Biboumi then serves the configured +\fIhostname\fR, this means that all XMPP stanza with a \fIto\fR JID on that +domain will be sent to biboumi, and biboumi will send only send messages +coming from this hostname. +. +When an user joins an IRC channel on an IRC server (see \fBJoin an IRC +channel\fR), biboumi connects to the remote IRC server, sets the user’s nick +as requested, and then tries to join the specified channel. If the same +user subsequently tries to connect to an other channel on the same server, +the same IRC connection is used. If, however, an other user wants to join +an IRC channel on that same IRC server, biboumi opens a new connection to +that server. Biboumi connects once to each IRC server, for each user on it. +. +.SS "Addressing" +. +IRC entities are represented by XMPP JIDs. The domain part of the JID is +the domain served by biboumi, and the local part depends on the concerned +entity. +. +IRC channels and IRC users JIDs have a localpart formed like this: \fIname\fR, +the '\fI%\fR' separator and the \fIirc_server\fR. +. +For an IRC channel, the name starts with '\fI&\fR', '\fI#\fR', '\fI+\fR' +or '\fI!\fR'. Some other gateway implementations, as well as some IRC +clients, do not require them to be started by one of these characters, +adding an implicit '\fI#\fR' in that case. Biboumi does not do that because +this gets confusing when trying to understand the difference between +\fIfoo\fR, \fI#foo\fR, and \fI##foo\fR. +. +If the name starts with any other character, this represents an IRC user. +. +.SS "Join an IRC channel" +. +To join an IRC channel \fI#foo\fR on the IRC server \fIirc.example.com\fR, +join the XMPP MUC \fI#foo%irc.example.com@hostname\fR. +. +.SS "Channel messages" +. +On XMPP, unlike on IRC, the displayed order of the messages is the same for +all participants of a MUC. Biboumi can not however provide this feature, as +it cannot know whether the IRC server has received and forwarded the +messages to other users. This means that the order of the messages +displayed in your XMPP may not be the same than the order on other IRC +users’. +. +.SS "Nicknames" +. +On IRC, nicknames are server-wide. This means that one user only has one +single nickname at one given time on all the channels of a server. This is +different from XMPP where an user can have a different nick on each MUC, +even if these MUCs are on the same server. +. +This means that the nick you choose when joining your first IRC channel on a +given IRC server will be your nickname in all other channels that you join +on that same IRC server. +If you explicitely change your nickname on one channel, your nickname will +be changed on all channels on the same server as well. +. +.SS "Private messages" +. +Private messages are handled differently on IRC and on XMPP. On IRC, you +talk directly to one server-user: toto on the channel #foo is the same user +than toto on the channel #bar (as long as these two channels are on the same +IRC server). Using biboumi, there is no way to receive a message from a +room participant (from a jid like \fI#test%irc.example.com/\fBnickname\fR). +Instead, private messages are received from and sent to the user (using a +jid like \fBnickname\fI%irc.example.com\fR). For conveniance and +compatibility with XMPP clients sending private messages to the MUC +participants, a message sent to +\fB#chan%irc.example.com@irc.example.net/Nickname\fR will be redirected to +\fBNickname%irc.example.com@irc.example.net\fR, although this is not the +prefered way to do it. +. +.SS "Notices" +. +Notices are received exactly like private messages. It is not possible to +send a notice. +. +.SS "Kicks and bans" +. +Kicks are transparently translated from one protocol to another. However +banning an XMPP participant has no effect. To ban an user you need to set a +mode +b on that user nick or host (see \fBMODES\fR) and then kick it. +. +.SS "Encoding" +. +On XMPP, the encoding is always \fIUTF-8\fR, whereas on IRC the encoding of +each message can be anything. +. +This means that biboumi has to convert everything coming from IRC into UTF-8 +without knowing the encoding of the received messages. To do so, it checks +if each message is UTF-8 valid, if not it tries to convert from +\fIiso_8859-1\fR (because this appears to be the most common case, at least +on the channels I visit) to \fIUTF-8\fR. If that conversion fails at some +point, a placeholder character '\f�\fR' is inserted to indicate this +decoding error. +. +Messages are always sent in UTF-8 over IRC, no conversion is done in that +direction. +. +.SS "IRC modes" +. +One feature that doesn’t exist on XMPP but does on IRC is the \fImodes\fR. +Although some of these modes have a correspondance in the XMPP world (for +example the \fI+o\fR mode on an user corresponds to the \fImoderator\fR role +in XMPP), it is impossible to map all these modes to an XMPP feature. To +circumvent this problem, biboumi provides a raw notification when modes are +changed, and lets the user change the modes directly. +. +To change modes, simply send a message starting with “\fB/mode\fR” followed +by the modes and the arguments you want to send to the IRC server. For +example “/mode +aho louiz”. Note that your XMPP client may +inteprete messages begining with “/” like a command. To actually send a +message starting with a slash, you may need to start your message with +“//mode” or “/say /mode”, depending on your client. +. +When a mode is changed, the user is notified by a message coming from the +MUC bare JID, looking like “Mode #foo [+ov] [toto tutu]”. In addition, if +the mode change can be translated to an XMPP feature, the user will be +notified of this XMPP event as well. For example if a mode “+o toto” is +received, then toto’s role will be changed to moderator. The mapping +between IRC modes and XMPP features is as follow: +. +.TP +.B +o +Sets the participant’s role to \fImoderator\fR. +. +.TP +.B +a +Sets the participant’s role to \admin\fR. +. +.TP +.B +v +Sets the participant’s affiliation to \fImember\fR. +. +.SH SECURITY +. +Biboumi does not provide any encryption mechanism: connection to the XMPP +server MUST be made on localhost. The XMPP server is not supposed to accept +non-local connection from components, thus encryption is useless. IRC +SSL/TLS is also not implemented although this could be useful for some +users, this is however not a high priority feature. +. +Biboumi also does not check if JIDs are properly formatted using nodeprep. +This must be done by the XMPP server to which biboumi is directly connected. +. +.SH AUTHORS +. +Written by Florent Le Coz -- cgit v1.2.3 From 8e2dd573bb01f1caa66674a58c2917592256b41f Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sun, 8 Dec 2013 20:23:35 +0100 Subject: Provide the doc in markdown format The included man page is now generated from this markdown file, using ronn --- doc/biboumi.1 | 219 +++++++++++++++++++-------------------------------------- doc/biboumi.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 276 insertions(+), 145 deletions(-) create mode 100644 doc/biboumi.md (limited to 'doc') diff --git a/doc/biboumi.1 b/doc/biboumi.1 index c874062..5f88a16 100644 --- a/doc/biboumi.1 +++ b/doc/biboumi.1 @@ -1,192 +1,121 @@ -.TH biboumi 1 2013-11-21 +.\" generated with Ronn/v0.7.3 +.\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.SH NAME +.TH "BIBOUMI" "" "December 2013" "" "" . -\fBbiboumi\fR - XMPP gateway to IRC +.SH "NAME" +Bbiboumi \- XMPP gateway to IRC . -.SH SYNOPSIS +.SH "SYNOPSIS" +\fBbiboumi\fR [\fBconfig_file\fR] . -\fBbiboumi\fR [\fIconfig_filename\fR] -. -.SH DESCRIPTION -. -Biboumi is an XMPP gateway that connects to IRC servers and translates -between the two protocols. It can be used to access IRC channels using any -XMPP client as if these channels were XMPP MUCs. -. -.SH OPTIONS +.SH "DESCRIPTION" +Biboumi is an XMPP gateway that connects to IRC servers and translates between the two protocols\. It can be used to access IRC channels using any XMPP client as if these channels were XMPP MUCs\. . +.SH "OPTIONS" Available options: -.TP +. +.P \fBconfig_filename\fR -Specify the file to read for configuration. See \fBCONFIG\fR section for -more details on its content. . -.SH CONFIG +.P +Specify the file to read for configuration\. See \fICONFIG\fR section for more details on its content\. +. +.SH "CONFIG" +The configuration file uses a simple format of the form \fB"option=value"\fR\. Here is a description of each possible option: . -The configuration file uses a simple format of the form -\fB"option=value"\fR. Here is a description of each possible option: -.TP +.P \fBhostname\fR (mandatory) -The hostname served by the XMPP gateway. This domain must be configured in -the XMPP server as an external component. See the manual for your XMPP -server for more information. -.TP +. +.P +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\. +. +.P \fBpassword\fR (mandatory) -The password used to authenticate the XMPP component to your XMPP server. -This password must be configured in the XMPP server, associated with the -external component on \fBhostname\fR. -. -.SH USAGE -. -When started, biboumi connects, without encryption (see \fBSECURITY\fR), to -the local XMPP server on the port \fI5347\fR and provides the configured -password to authenticate. Biboumi then serves the configured -\fIhostname\fR, this means that all XMPP stanza with a \fIto\fR JID on that -domain will be sent to biboumi, and biboumi will send only send messages -coming from this hostname. -. -When an user joins an IRC channel on an IRC server (see \fBJoin an IRC -channel\fR), biboumi connects to the remote IRC server, sets the user’s nick -as requested, and then tries to join the specified channel. If the same -user subsequently tries to connect to an other channel on the same server, -the same IRC connection is used. If, however, an other user wants to join -an IRC channel on that same IRC server, biboumi opens a new connection to -that server. Biboumi connects once to each IRC server, for each user on it. . -.SS "Addressing" +.P +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 \fIhostname\fR\. +. +.SH "USAGE" +When started, biboumi connects, without encryption (see \fISECURITY\fR), to the local XMPP server on the port \fB5347\fR and provides the configured password to authenticate\. Biboumi then serves the configured \fBhostname\fR, this means that all XMPP stanza with a \fBto\fR JID on that domain will be sent to biboumi, and biboumi will send only send messages coming from this hostname\. . -IRC entities are represented by XMPP JIDs. The domain part of the JID is -the domain served by biboumi, and the local part depends on the concerned -entity. +.P +When an user joins an IRC channel on an IRC server (see \fIJoin an IRC channel\fR), biboumi connects to the remote IRC server, sets the user’s nick as requested, and then tries to join the specified channel\. If the same user subsequently tries to connect to an other channel on the same server, the same IRC connection is used\. If, however, an other user wants to join an IRC channel on that same IRC server, biboumi opens a new connection to that server\. Biboumi connects once to each IRC server, for each user on it\. . -IRC channels and IRC users JIDs have a localpart formed like this: \fIname\fR, -the '\fI%\fR' separator and the \fIirc_server\fR. +.SS "Addressing" +IRC entities are represented by XMPP JIDs\. The domain part of the JID is the domain served by biboumi, and the local part depends on the concerned entity\. . -For an IRC channel, the name starts with '\fI&\fR', '\fI#\fR', '\fI+\fR' -or '\fI!\fR'. Some other gateway implementations, as well as some IRC -clients, do not require them to be started by one of these characters, -adding an implicit '\fI#\fR' in that case. Biboumi does not do that because -this gets confusing when trying to understand the difference between -\fIfoo\fR, \fI#foo\fR, and \fI##foo\fR. +.P +IRC channels and IRC users JIDs have a localpart formed like this: \fBname\fR, the \fB\'%\'\fR separator and the \fBirc_server\fR\. . -If the name starts with any other character, this represents an IRC user. +.P +For an IRC channel, the name starts with \fB\'&\'\fR, \fB\'#\'\fR, \fB\'+\'\fR or \fB\'!\'\fR\. Some other gateway implementations, as well as some IRC clients, do not require them to be started by one of these characters, adding an implicit \fB\'#\'\fR in that case\. Biboumi does not do that because this gets confusing when trying to understand the difference between \fIfoo\fR, \fI#foo\fR, and \fI##foo\fR\. . -.SS "Join an IRC channel" +.P +If the name starts with any other character, this represents an IRC user\. . -To join an IRC channel \fI#foo\fR on the IRC server \fIirc.example.com\fR, -join the XMPP MUC \fI#foo%irc.example.com@hostname\fR. +.SS "Join an IRC channel" +To join an IRC channel \fB#foo\fR on the IRC server \fBirc\.example\.com\fR, join the XMPP MUC \fB#foo%irc\.example\.com@hostname\fR\. . .SS "Channel messages" -. -On XMPP, unlike on IRC, the displayed order of the messages is the same for -all participants of a MUC. Biboumi can not however provide this feature, as -it cannot know whether the IRC server has received and forwarded the -messages to other users. This means that the order of the messages -displayed in your XMPP may not be the same than the order on other IRC -users’. +On XMPP, unlike on IRC, the displayed order of the messages is the same for all participants of a MUC\. Biboumi can not however provide this feature, as it cannot know whether the IRC server has received and forwarded the messages to other users\. This means that the order of the messages displayed in your XMPP may not be the same than the order on other IRC users’\. . .SS "Nicknames" +On IRC, nicknames are server\-wide\. This means that one user only has one single nickname at one given time on all the channels of a server\. This is different from XMPP where an user can have a different nick on each MUC, even if these MUCs are on the same server\. . -On IRC, nicknames are server-wide. This means that one user only has one -single nickname at one given time on all the channels of a server. This is -different from XMPP where an user can have a different nick on each MUC, -even if these MUCs are on the same server. -. -This means that the nick you choose when joining your first IRC channel on a -given IRC server will be your nickname in all other channels that you join -on that same IRC server. -If you explicitely change your nickname on one channel, your nickname will -be changed on all channels on the same server as well. +.P +This means that the nick you choose when joining your first IRC channel on a given IRC server will be your nickname in all other channels that you join on that same IRC server\. If you explicitely change your nickname on one channel, your nickname will be changed on all channels on the same server as well\. . .SS "Private messages" -. -Private messages are handled differently on IRC and on XMPP. On IRC, you -talk directly to one server-user: toto on the channel #foo is the same user -than toto on the channel #bar (as long as these two channels are on the same -IRC server). Using biboumi, there is no way to receive a message from a -room participant (from a jid like \fI#test%irc.example.com/\fBnickname\fR). -Instead, private messages are received from and sent to the user (using a -jid like \fBnickname\fI%irc.example.com\fR). For conveniance and -compatibility with XMPP clients sending private messages to the MUC -participants, a message sent to -\fB#chan%irc.example.com@irc.example.net/Nickname\fR will be redirected to -\fBNickname%irc.example.com@irc.example.net\fR, although this is not the -prefered way to do it. +Private messages are handled differently on IRC and on XMPP\. On IRC, you talk directly to one server\-user: toto on the channel #foo is the same user than toto on the channel #bar (as long as these two channels are on the same IRC server)\. Using biboumi, there is no way to receive a message from a room participant (from a jid like #test%irc\.example\.com/nickname)\. Instead, private messages are received from and sent to the user (using a jid like nickname%irc\.example\.com)\. For conveniance and compatibility with XMPP clients sending private messages to the MUC participants, a message sent toNickname%irc\.example\.com@irc\.example\.net, although this is not the prefered way to do it\. . .SS "Notices" -. -Notices are received exactly like private messages. It is not possible to -send a notice. +Notices are received exactly like private messages\. It is not possible to send a notice\. . .SS "Kicks and bans" -. -Kicks are transparently translated from one protocol to another. However -banning an XMPP participant has no effect. To ban an user you need to set a -mode +b on that user nick or host (see \fBMODES\fR) and then kick it. +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 \fIMODES\fR) and then kick it\. . .SS "Encoding" +On XMPP, the encoding is always \fBUTF\-8\fR, whereas on IRC the encoding of each message can be anything\. . -On XMPP, the encoding is always \fIUTF-8\fR, whereas on IRC the encoding of -each message can be anything. -. -This means that biboumi has to convert everything coming from IRC into UTF-8 -without knowing the encoding of the received messages. To do so, it checks -if each message is UTF-8 valid, if not it tries to convert from -\fIiso_8859-1\fR (because this appears to be the most common case, at least -on the channels I visit) to \fIUTF-8\fR. If that conversion fails at some -point, a placeholder character '\f�\fR' is inserted to indicate this -decoding error. +.P +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 \fBiso_8859\-1\fR (because this appears to be the most common case, at least on the channels I visit) to \fBUTF\-8\fR\. If that conversion fails at some point, a placeholder character \fB\'�\'\fR is inserted to indicate this decoding error\. . -Messages are always sent in UTF-8 over IRC, no conversion is done in that -direction. +.P +Messages are always sent in UTF\-8 over IRC, no conversion is done in that direction\. . .SS "IRC modes" +One feature that doesn’t exist on XMPP but does on IRC is the \fBmodes\fR\. Although some of these modes have a correspondance in the XMPP world (for example the \fB+o\fR mode on an user corresponds to the \fBmoderator\fR role in XMPP), it is impossible to map all these modes to an XMPP feature\. To circumvent this problem, biboumi provides a raw notification when modes are changed, and lets the user change the modes directly\. . -One feature that doesn’t exist on XMPP but does on IRC is the \fImodes\fR. -Although some of these modes have a correspondance in the XMPP world (for -example the \fI+o\fR mode on an user corresponds to the \fImoderator\fR role -in XMPP), it is impossible to map all these modes to an XMPP feature. To -circumvent this problem, biboumi provides a raw notification when modes are -changed, and lets the user change the modes directly. +.P +To change modes, simply send a message starting with “\fB/mode\fR” followed by the modes and the arguments you want to send to the IRC server\. For example “/mode +aho louiz”\. Note that your XMPP client may inteprete messages begining with “/” like a command\. To actually send a message starting with a slash, you may need to start your message with “//mode” or “/say /mode”, depending on your client\. . -To change modes, simply send a message starting with “\fB/mode\fR” followed -by the modes and the arguments you want to send to the IRC server. For -example “/mode +aho louiz”. Note that your XMPP client may -inteprete messages begining with “/” like a command. To actually send a -message starting with a slash, you may need to start your message with -“//mode” or “/say /mode”, depending on your client. +.P +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: . -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: +.P +\fB+o\fR . -.TP -.B +o -Sets the participant’s role to \fImoderator\fR. +.P +Sets the participant’s role to \fBmoderator\fR\. . -.TP -.B +a -Sets the participant’s role to \admin\fR. +.P +\fB+a\fR . -.TP -.B +v -Sets the participant’s affiliation to \fImember\fR. +.P +Sets the participant’s role to \fBadmin\fR\. . -.SH SECURITY +.P +\fB+v\fR . -Biboumi does not provide any encryption mechanism: connection to the XMPP -server MUST be made on localhost. The XMPP server is not supposed to accept -non-local connection from components, thus encryption is useless. IRC -SSL/TLS is also not implemented although this could be useful for some -users, this is however not a high priority feature. +.P +Sets the participant’s affiliation to \fBmember\fR\. . -Biboumi also does not check if JIDs are properly formatted using nodeprep. -This must be done by the XMPP server to which biboumi is directly connected. +.SH "SECURITY" +Biboumi does not provide any encryption mechanism: connection to the XMPP server MUST be made on localhost\. The XMPP server is not supposed to accept non\-local connection from components, thus encryption is useless\. IRC SSL/TLS is also not implemented although this could be useful for some users, this is however not a high priority feature\. . -.SH AUTHORS +.P +Biboumi also does not check if JIDs are properly formatted using nodeprep\. This must be done by the XMPP server to which biboumi is directly connected\. . +.SH "AUTHORS" Written by Florent Le Coz diff --git a/doc/biboumi.md b/doc/biboumi.md new file mode 100644 index 0000000..a251801 --- /dev/null +++ b/doc/biboumi.md @@ -0,0 +1,202 @@ +BIBOUMI 1 "2013-11-21" +====================== + +NAME +---- + +Bbiboumi - XMPP gateway to IRC + +SYNOPSIS +-------- + +`biboumi` [`config_file`] + +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. + +OPTIONS +------- + +Available 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. + +`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*. + +USAGE +----- + +When started, biboumi connects, without encryption (see *SECURITY*), to the +local XMPP server on the port `5347` and provides the configured password to +authenticate. Biboumi then serves the configured `hostname`, this means +that all XMPP stanza with a `to` JID on that domain will be sent to biboumi, +and biboumi will send only send messages coming from this hostname. + +When an user joins an IRC channel on an IRC server (see *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. + +### Addressing + +IRC entities are represented by XMPP JIDs. The domain part of the JID is +the domain served by biboumi, and the local part depends on the concerned +entity. + +IRC channels and IRC users JIDs have a localpart formed like this: +`name`, the `'%'` separator and the `irc_server`. + +For an IRC channel, the name starts with `'&'`, `'#'`, `'+'` +or `'!'`. 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 +*foo*, *#foo*, and *##foo*. + +If the name starts with any other character, this represents an IRC user. + +### 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`. + +### Channel messages + +On XMPP, unlike on IRC, the displayed order of the messages is the same for +all participants of a MUC. Biboumi can not however provide this feature, as +it cannot know whether the IRC server has received and forwarded the +messages to other users. This means that the order of the messages +displayed in your XMPP may not be the same than the order on other IRC +users’. + +### Nicknames + +On IRC, nicknames are server-wide. This means that one user only has one +single nickname at one given time on all the channels of a server. This is +different from XMPP where an user can have a different nick on each MUC, +even if these MUCs are on the same server. + +This means that the nick you choose when joining your first IRC channel on a +given IRC server will be your nickname in all other channels that you join +on that same IRC server. +If you explicitely change your nickname on one channel, your nickname will +be changed on all channels on the same server as well. + +### Private messages + +Private messages are handled differently on IRC and on XMPP. On IRC, you +talk directly to one server-user: toto on the channel #foo is the same user +than toto on the channel #bar (as long as these two channels are on the same +IRC server). Using biboumi, there is no way to receive a message from a +room participant (from a jid like #test%irc.example.com/nickname). Instead, +private messages are received from and sent to the user (using a jid like +nickname%irc.example.com). For conveniance and compatibility with XMPP +clients sending private messages to the MUC participants, a message sent to +#chan%irc.example.com@irc.example.net/Nickname will be redirected to +Nickname%irc.example.com@irc.example.net, although this is not the prefered +way to do it. + +### 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 an 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 +inteprete messages begining with “/” like a command. To actually send a +message starting with a slash, you may need to start your message with +“//mode” or “/say /mode”, depending on your client. + +When a mode is changed, the user is notified by a message coming from the +MUC bare JID, looking like “Mode #foo [+ov] [toto tutu]”. In addition, if +the mode change can be translated to an XMPP feature, the user will be +notified of this XMPP event as well. For example if a mode “+o toto” is +received, then toto’s role will be changed to moderator. The mapping +between IRC modes and XMPP features is as follow: + +`+o` + + Sets the participant’s role to `moderator`. + +`+a` + + Sets the participant’s role to `admin`. + +`+v` + + Sets the participant’s affiliation to `member`. + +SECURITY +-------- + +Biboumi does not provide any encryption mechanism: connection to the XMPP +server MUST be made on localhost. The XMPP server is not supposed to accept +non-local connection from components, thus encryption is useless. IRC +SSL/TLS is also not implemented although this could be useful for some +users, this is however not a high priority feature. + +Biboumi also does not check if JIDs are properly formatted using nodeprep. +This must be done by the XMPP server to which biboumi is directly connected. + +AUTHORS +------- + +Written by Florent Le Coz -- cgit v1.2.3 From 2aa868c7cc3a11b66f3326519f8d67b67b33b986 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sun, 8 Dec 2013 20:28:57 +0100 Subject: Document the bare-JID-for-IRC-users feature --- doc/biboumi.1 | 2 +- doc/biboumi.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/biboumi.1 b/doc/biboumi.1 index 5f88a16..013ab77 100644 --- a/doc/biboumi.1 +++ b/doc/biboumi.1 @@ -52,7 +52,7 @@ IRC channels and IRC users JIDs have a localpart formed like this: \fBname\fR, t For an IRC channel, the name starts with \fB\'&\'\fR, \fB\'#\'\fR, \fB\'+\'\fR or \fB\'!\'\fR\. Some other gateway implementations, as well as some IRC clients, do not require them to be started by one of these characters, adding an implicit \fB\'#\'\fR in that case\. Biboumi does not do that because this gets confusing when trying to understand the difference between \fIfoo\fR, \fI#foo\fR, and \fI##foo\fR\. . .P -If the name starts with any other character, this represents an IRC user\. +If the name starts with any other character, this represents an IRC user\. If compiled with Libidn, an IRC user has a bare JID representing the “hostname” provided by the IRC server\. . .SS "Join an IRC channel" To join an IRC channel \fB#foo\fR on the IRC server \fBirc\.example\.com\fR, join the XMPP MUC \fB#foo%irc\.example\.com@hostname\fR\. diff --git a/doc/biboumi.md b/doc/biboumi.md index a251801..355445e 100644 --- a/doc/biboumi.md +++ b/doc/biboumi.md @@ -80,6 +80,8 @@ this gets confusing when trying to understand the difference between *foo*, *#foo*, and *##foo*. If the name starts with any other character, this represents an IRC user. +If compiled with Libidn, an IRC user has a bare JID representing the +“hostname” provided by the IRC server. ### Join an IRC channel -- cgit v1.2.3 From bb094e5058f0ee4b22e73b10166d0ca90fab559b Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sun, 8 Dec 2013 20:33:36 +0100 Subject: Document the log_file and log_level configuration options --- doc/biboumi.1 | 12 ++++++++++++ doc/biboumi.md | 10 ++++++++++ 2 files changed, 22 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1 b/doc/biboumi.1 index 013ab77..3e472c8 100644 --- a/doc/biboumi.1 +++ b/doc/biboumi.1 @@ -36,6 +36,18 @@ The hostname served by the XMPP gateway\. This domain must be configured in th .P 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 \fIhostname\fR\. . +.P +\fBlog_file\fR +. +.P +A filename into which logs are written\. If none is provided, the logs are written on standard output +. +.P +\fBlog_level\fR +. +.P +Indicate what type of log messages to write in the logs\. Values can be from 0 to 3\. 0 is debug, 1 is info, 2 is warnig, 3 is error\. +. .SH "USAGE" When started, biboumi connects, without encryption (see \fISECURITY\fR), to the local XMPP server on the port \fB5347\fR and provides the configured password to authenticate\. Biboumi then serves the configured \fBhostname\fR, this means that all XMPP stanza with a \fBto\fR JID on that domain will be sent to biboumi, and biboumi will send only send messages coming from this hostname\. . diff --git a/doc/biboumi.md b/doc/biboumi.md index 355445e..811b5c0 100644 --- a/doc/biboumi.md +++ b/doc/biboumi.md @@ -46,6 +46,16 @@ The configuration file uses a simple format of the form This password must be configured in the XMPP server, associated with the external component on *hostname*. +`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. Values can be from 0 to 3. + 0 is debug, 1 is info, 2 is warnig, 3 is error. + USAGE ----- -- cgit v1.2.3 From e840704b58a984351971e8034e74f5e9fdfaf114 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sat, 4 Jan 2014 01:30:03 +0100 Subject: Convert received modes into roles and affiliations --- doc/biboumi.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/biboumi.md b/doc/biboumi.md index 811b5c0..35755ef 100644 --- a/doc/biboumi.md +++ b/doc/biboumi.md @@ -184,17 +184,21 @@ 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: +`+a` + + Sets the participant’s role to `moderator` and its affiliation to `owner`. + `+o` - Sets the participant’s role to `moderator`. + Sets the participant’s role to `moderator` and its affiliation to `admin`. -`+a` +`+h` - Sets the participant’s role to `admin`. + Sets the participant’s role to `moderator` and its affiliation to `member`. `+v` - Sets the participant’s affiliation to `member`. + Sets the participant’s role to `participant` and its affiliation to `member`. SECURITY -------- -- cgit v1.2.3 From b51368304140ea227dbbb71357a2fe9d7fd9057a Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sat, 4 Jan 2014 02:04:38 +0100 Subject: Document the shutdown procedure --- doc/biboumi.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.md b/doc/biboumi.md index 35755ef..4bbbcf7 100644 --- a/doc/biboumi.md +++ b/doc/biboumi.md @@ -73,6 +73,14 @@ 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 the SIGINT or SIGTERM signals 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 all +connections are closed because the remote aknowledged the end of +communication. If the remote server does not respond, biboumi does not +exit, unless SIGINT or SIGTERM is received again, in which case biboumi +closes the TCP connections and exits immediately. + ### Addressing IRC entities are represented by XMPP JIDs. The domain part of the JID is -- cgit v1.2.3 From c5b4be0e17a21449d226ebcc3a9313a020c0c8b4 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Mon, 17 Feb 2014 02:31:14 +0100 Subject: Little man page update --- doc/biboumi.md | 46 ++++++++++++++++++++++++++++------------------ 1 file changed, 28 insertions(+), 18 deletions(-) (limited to 'doc') diff --git a/doc/biboumi.md b/doc/biboumi.md index 4bbbcf7..334e65e 100644 --- a/doc/biboumi.md +++ b/doc/biboumi.md @@ -1,15 +1,15 @@ -BIBOUMI 1 "2013-11-21" +BIBOUMI 1 "2014-02-17" ====================== NAME ---- -Bbiboumi - XMPP gateway to IRC +biboumi - XMPP gateway to IRC SYNOPSIS -------- -`biboumi` [`config_file`] +`biboumi` [`config_filename`] DESCRIPTION ----------- @@ -53,8 +53,9 @@ The configuration file uses a simple format of the form `log_level` - Indicate what type of log messages to write in the logs. Values can be from 0 to 3. - 0 is debug, 1 is info, 2 is warnig, 3 is error. + Indicate what type of log messages to write in the logs. Values 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. USAGE ----- @@ -76,7 +77,7 @@ that server. Biboumi connects once to each IRC server, for each user on it. To cleanly shutdown the component, send the SIGINT or SIGTERM signals 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 all -connections are closed because the remote aknowledged the end of +connections are closed because the remote acknowledged the end of communication. If the remote server does not respond, biboumi does not exit, unless SIGINT or SIGTERM is received again, in which case biboumi closes the TCP connections and exits immediately. @@ -132,7 +133,7 @@ be changed on all channels on the same server as well. Private messages are handled differently on IRC and on XMPP. On IRC, you talk directly to one server-user: toto on the channel #foo is the same user -than toto on the channel #bar (as long as these two channels are on the same +as toto on the channel #bar (as long as these two channels are on the same IRC server). Using biboumi, there is no way to receive a message from a room participant (from a jid like #test%irc.example.com/nickname). Instead, private messages are received from and sent to the user (using a jid like @@ -178,12 +179,12 @@ 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 -inteprete messages begining with “/” like a command. To actually send a -message starting with a slash, you may need to start your message with -“//mode” or “/say /mode”, depending on your client. +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 @@ -192,6 +193,10 @@ 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`. @@ -214,13 +219,18 @@ SECURITY Biboumi does not provide any encryption mechanism: connection to the XMPP server MUST be made on localhost. The XMPP server is not supposed to accept non-local connection from components, thus encryption is useless. IRC -SSL/TLS is also not implemented although this could be useful for some -users, this is however not a high priority feature. +SSL/TLS is also not yet implemented. -Biboumi also does not check if JIDs are properly formatted using nodeprep. -This must be done by the XMPP server to which biboumi is directly connected. +Biboumi also does not check if received JIDs are properly formatted using +nodeprep. This must be done by the XMPP server to which biboumi is directly +connected. AUTHORS ------- -Written by Florent Le Coz +This software and man page are both written by Florent Le Coz. + +LICENSE +------- + +Biboumi is released under the zlib license. -- cgit v1.2.3 From e43de640e9158ef396c9dc71a13bdcbfef740e7d Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Mon, 17 Feb 2014 03:07:27 +0100 Subject: Build the man page as part of the build process, if ronn is found --- doc/biboumi.1 | 133 ------------------------------- doc/biboumi.1.md | 236 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/biboumi.md | 236 ------------------------------------------------------- 3 files changed, 236 insertions(+), 369 deletions(-) delete mode 100644 doc/biboumi.1 create mode 100644 doc/biboumi.1.md delete mode 100644 doc/biboumi.md (limited to 'doc') diff --git a/doc/biboumi.1 b/doc/biboumi.1 deleted file mode 100644 index 3e472c8..0000000 --- a/doc/biboumi.1 +++ /dev/null @@ -1,133 +0,0 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "BIBOUMI" "" "December 2013" "" "" -. -.SH "NAME" -Bbiboumi \- XMPP gateway to IRC -. -.SH "SYNOPSIS" -\fBbiboumi\fR [\fBconfig_file\fR] -. -.SH "DESCRIPTION" -Biboumi is an XMPP gateway that connects to IRC servers and translates between the two protocols\. It can be used to access IRC channels using any XMPP client as if these channels were XMPP MUCs\. -. -.SH "OPTIONS" -Available options: -. -.P -\fBconfig_filename\fR -. -.P -Specify the file to read for configuration\. See \fICONFIG\fR section for more details on its content\. -. -.SH "CONFIG" -The configuration file uses a simple format of the form \fB"option=value"\fR\. Here is a description of each possible option: -. -.P -\fBhostname\fR (mandatory) -. -.P -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\. -. -.P -\fBpassword\fR (mandatory) -. -.P -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 \fIhostname\fR\. -. -.P -\fBlog_file\fR -. -.P -A filename into which logs are written\. If none is provided, the logs are written on standard output -. -.P -\fBlog_level\fR -. -.P -Indicate what type of log messages to write in the logs\. Values can be from 0 to 3\. 0 is debug, 1 is info, 2 is warnig, 3 is error\. -. -.SH "USAGE" -When started, biboumi connects, without encryption (see \fISECURITY\fR), to the local XMPP server on the port \fB5347\fR and provides the configured password to authenticate\. Biboumi then serves the configured \fBhostname\fR, this means that all XMPP stanza with a \fBto\fR JID on that domain will be sent to biboumi, and biboumi will send only send messages coming from this hostname\. -. -.P -When an user joins an IRC channel on an IRC server (see \fIJoin an IRC channel\fR), biboumi connects to the remote IRC server, sets the user’s nick as requested, and then tries to join the specified channel\. If the same user subsequently tries to connect to an other channel on the same server, the same IRC connection is used\. If, however, an other user wants to join an IRC channel on that same IRC server, biboumi opens a new connection to that server\. Biboumi connects once to each IRC server, for each user on it\. -. -.SS "Addressing" -IRC entities are represented by XMPP JIDs\. The domain part of the JID is the domain served by biboumi, and the local part depends on the concerned entity\. -. -.P -IRC channels and IRC users JIDs have a localpart formed like this: \fBname\fR, the \fB\'%\'\fR separator and the \fBirc_server\fR\. -. -.P -For an IRC channel, the name starts with \fB\'&\'\fR, \fB\'#\'\fR, \fB\'+\'\fR or \fB\'!\'\fR\. Some other gateway implementations, as well as some IRC clients, do not require them to be started by one of these characters, adding an implicit \fB\'#\'\fR in that case\. Biboumi does not do that because this gets confusing when trying to understand the difference between \fIfoo\fR, \fI#foo\fR, and \fI##foo\fR\. -. -.P -If the name starts with any other character, this represents an IRC user\. If compiled with Libidn, an IRC user has a bare JID representing the “hostname” provided by the IRC server\. -. -.SS "Join an IRC channel" -To join an IRC channel \fB#foo\fR on the IRC server \fBirc\.example\.com\fR, join the XMPP MUC \fB#foo%irc\.example\.com@hostname\fR\. -. -.SS "Channel messages" -On XMPP, unlike on IRC, the displayed order of the messages is the same for all participants of a MUC\. Biboumi can not however provide this feature, as it cannot know whether the IRC server has received and forwarded the messages to other users\. This means that the order of the messages displayed in your XMPP may not be the same than the order on other IRC users’\. -. -.SS "Nicknames" -On IRC, nicknames are server\-wide\. This means that one user only has one single nickname at one given time on all the channels of a server\. This is different from XMPP where an user can have a different nick on each MUC, even if these MUCs are on the same server\. -. -.P -This means that the nick you choose when joining your first IRC channel on a given IRC server will be your nickname in all other channels that you join on that same IRC server\. If you explicitely change your nickname on one channel, your nickname will be changed on all channels on the same server as well\. -. -.SS "Private messages" -Private messages are handled differently on IRC and on XMPP\. On IRC, you talk directly to one server\-user: toto on the channel #foo is the same user than toto on the channel #bar (as long as these two channels are on the same IRC server)\. Using biboumi, there is no way to receive a message from a room participant (from a jid like #test%irc\.example\.com/nickname)\. Instead, private messages are received from and sent to the user (using a jid like nickname%irc\.example\.com)\. For conveniance and compatibility with XMPP clients sending private messages to the MUC participants, a message sent toNickname%irc\.example\.com@irc\.example\.net, although this is not the prefered way to do it\. -. -.SS "Notices" -Notices are received exactly like private messages\. It is not possible to send a notice\. -. -.SS "Kicks and bans" -Kicks are transparently translated from one protocol to another\. However banning an XMPP participant has no effect\. To ban an user you need to set a mode +b on that user nick or host (see \fIMODES\fR) and then kick it\. -. -.SS "Encoding" -On XMPP, the encoding is always \fBUTF\-8\fR, whereas on IRC the encoding of each message can be anything\. -. -.P -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 \fBiso_8859\-1\fR (because this appears to be the most common case, at least on the channels I visit) to \fBUTF\-8\fR\. If that conversion fails at some point, a placeholder character \fB\'�\'\fR is inserted to indicate this decoding error\. -. -.P -Messages are always sent in UTF\-8 over IRC, no conversion is done in that direction\. -. -.SS "IRC modes" -One feature that doesn’t exist on XMPP but does on IRC is the \fBmodes\fR\. Although some of these modes have a correspondance in the XMPP world (for example the \fB+o\fR mode on an user corresponds to the \fBmoderator\fR role in XMPP), it is impossible to map all these modes to an XMPP feature\. To circumvent this problem, biboumi provides a raw notification when modes are changed, and lets the user change the modes directly\. -. -.P -To change modes, simply send a message starting with “\fB/mode\fR” followed by the modes and the arguments you want to send to the IRC server\. For example “/mode +aho louiz”\. Note that your XMPP client may inteprete messages begining with “/” like a command\. To actually send a message starting with a slash, you may need to start your message with “//mode” or “/say /mode”, depending on your client\. -. -.P -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: -. -.P -\fB+o\fR -. -.P -Sets the participant’s role to \fBmoderator\fR\. -. -.P -\fB+a\fR -. -.P -Sets the participant’s role to \fBadmin\fR\. -. -.P -\fB+v\fR -. -.P -Sets the participant’s affiliation to \fBmember\fR\. -. -.SH "SECURITY" -Biboumi does not provide any encryption mechanism: connection to the XMPP server MUST be made on localhost\. The XMPP server is not supposed to accept non\-local connection from components, thus encryption is useless\. IRC SSL/TLS is also not implemented although this could be useful for some users, this is however not a high priority feature\. -. -.P -Biboumi also does not check if JIDs are properly formatted using nodeprep\. This must be done by the XMPP server to which biboumi is directly connected\. -. -.SH "AUTHORS" -Written by Florent Le Coz diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md new file mode 100644 index 0000000..334e65e --- /dev/null +++ b/doc/biboumi.1.md @@ -0,0 +1,236 @@ +BIBOUMI 1 "2014-02-17" +====================== + +NAME +---- + +biboumi - XMPP gateway to IRC + +SYNOPSIS +-------- + +`biboumi` [`config_filename`] + +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. + +OPTIONS +------- + +Available 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. + +`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*. + +`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. Values 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. + +USAGE +----- + +When started, biboumi connects, without encryption (see *SECURITY*), to the +local XMPP server on the port `5347` and provides the configured password to +authenticate. Biboumi then serves the configured `hostname`, this means +that all XMPP stanza with a `to` JID on that domain will be sent to biboumi, +and biboumi will send only send messages coming from this hostname. + +When an user joins an IRC channel on an IRC server (see *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 the SIGINT or SIGTERM signals 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 all +connections are closed because the remote acknowledged the end of +communication. If the remote server does not respond, biboumi does not +exit, unless SIGINT or SIGTERM is received again, in which case biboumi +closes the TCP connections and exits immediately. + +### Addressing + +IRC entities are represented by XMPP JIDs. The domain part of the JID is +the domain served by biboumi, and the local part depends on the concerned +entity. + +IRC channels and IRC users JIDs have a localpart formed like this: +`name`, the `'%'` separator and the `irc_server`. + +For an IRC channel, the name starts with `'&'`, `'#'`, `'+'` +or `'!'`. 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 +*foo*, *#foo*, and *##foo*. + +If the name starts with any other character, this represents an IRC user. +If compiled with Libidn, an IRC user has a bare JID representing the +“hostname” provided by the IRC server. + +### 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`. + +### Channel messages + +On XMPP, unlike on IRC, the displayed order of the messages is the same for +all participants of a MUC. Biboumi can not however provide this feature, as +it cannot know whether the IRC server has received and forwarded the +messages to other users. This means that the order of the messages +displayed in your XMPP may not be the same than the order on other IRC +users’. + +### Nicknames + +On IRC, nicknames are server-wide. This means that one user only has one +single nickname at one given time on all the channels of a server. This is +different from XMPP where an user can have a different nick on each MUC, +even if these MUCs are on the same server. + +This means that the nick you choose when joining your first IRC channel on a +given IRC server will be your nickname in all other channels that you join +on that same IRC server. +If you explicitely change your nickname on one channel, your nickname will +be changed on all channels on the same server as well. + +### 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). Using biboumi, there is no way to receive a message from a +room participant (from a jid like #test%irc.example.com/nickname). Instead, +private messages are received from and sent to the user (using a jid like +nickname%irc.example.com). For conveniance and compatibility with XMPP +clients sending private messages to the MUC participants, a message sent to +#chan%irc.example.com@irc.example.net/Nickname will be redirected to +Nickname%irc.example.com@irc.example.net, although this is not the prefered +way to do it. + +### 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 an 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`. + +SECURITY +-------- + +Biboumi does not provide any encryption mechanism: connection to the XMPP +server MUST be made on localhost. The XMPP server is not supposed to accept +non-local connection from components, thus encryption is useless. IRC +SSL/TLS is also not yet implemented. + +Biboumi also does not check if received JIDs are properly formatted using +nodeprep. This must be done by the XMPP server to which biboumi is directly +connected. + +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.md b/doc/biboumi.md deleted file mode 100644 index 334e65e..0000000 --- a/doc/biboumi.md +++ /dev/null @@ -1,236 +0,0 @@ -BIBOUMI 1 "2014-02-17" -====================== - -NAME ----- - -biboumi - XMPP gateway to IRC - -SYNOPSIS --------- - -`biboumi` [`config_filename`] - -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. - -OPTIONS -------- - -Available 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. - -`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*. - -`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. Values 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. - -USAGE ------ - -When started, biboumi connects, without encryption (see *SECURITY*), to the -local XMPP server on the port `5347` and provides the configured password to -authenticate. Biboumi then serves the configured `hostname`, this means -that all XMPP stanza with a `to` JID on that domain will be sent to biboumi, -and biboumi will send only send messages coming from this hostname. - -When an user joins an IRC channel on an IRC server (see *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 the SIGINT or SIGTERM signals 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 all -connections are closed because the remote acknowledged the end of -communication. If the remote server does not respond, biboumi does not -exit, unless SIGINT or SIGTERM is received again, in which case biboumi -closes the TCP connections and exits immediately. - -### Addressing - -IRC entities are represented by XMPP JIDs. The domain part of the JID is -the domain served by biboumi, and the local part depends on the concerned -entity. - -IRC channels and IRC users JIDs have a localpart formed like this: -`name`, the `'%'` separator and the `irc_server`. - -For an IRC channel, the name starts with `'&'`, `'#'`, `'+'` -or `'!'`. 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 -*foo*, *#foo*, and *##foo*. - -If the name starts with any other character, this represents an IRC user. -If compiled with Libidn, an IRC user has a bare JID representing the -“hostname” provided by the IRC server. - -### 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`. - -### Channel messages - -On XMPP, unlike on IRC, the displayed order of the messages is the same for -all participants of a MUC. Biboumi can not however provide this feature, as -it cannot know whether the IRC server has received and forwarded the -messages to other users. This means that the order of the messages -displayed in your XMPP may not be the same than the order on other IRC -users’. - -### Nicknames - -On IRC, nicknames are server-wide. This means that one user only has one -single nickname at one given time on all the channels of a server. This is -different from XMPP where an user can have a different nick on each MUC, -even if these MUCs are on the same server. - -This means that the nick you choose when joining your first IRC channel on a -given IRC server will be your nickname in all other channels that you join -on that same IRC server. -If you explicitely change your nickname on one channel, your nickname will -be changed on all channels on the same server as well. - -### 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). Using biboumi, there is no way to receive a message from a -room participant (from a jid like #test%irc.example.com/nickname). Instead, -private messages are received from and sent to the user (using a jid like -nickname%irc.example.com). For conveniance and compatibility with XMPP -clients sending private messages to the MUC participants, a message sent to -#chan%irc.example.com@irc.example.net/Nickname will be redirected to -Nickname%irc.example.com@irc.example.net, although this is not the prefered -way to do it. - -### 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 an 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`. - -SECURITY --------- - -Biboumi does not provide any encryption mechanism: connection to the XMPP -server MUST be made on localhost. The XMPP server is not supposed to accept -non-local connection from components, thus encryption is useless. IRC -SSL/TLS is also not yet implemented. - -Biboumi also does not check if received JIDs are properly formatted using -nodeprep. This must be done by the XMPP server to which biboumi is directly -connected. - -AUTHORS -------- - -This software and man page are both written by Florent Le Coz. - -LICENSE -------- - -Biboumi is released under the zlib license. -- cgit v1.2.3 From 8fd2746696d32262b2e6900879a9a315e56f76f2 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Wed, 19 Feb 2014 02:24:00 +0100 Subject: Reload the conf on SIGUSR1/2 --- doc/biboumi.1.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 334e65e..18482fb 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -57,6 +57,10 @@ The configuration file uses a simple format of the form 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. +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 ----- -- cgit v1.2.3 From fbcce3c1123c144a3b395ee6415465f61a8e0ac1 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Tue, 15 Apr 2014 05:41:17 +0200 Subject: Fix a wrong description of how addressing works in biboumi --- doc/biboumi.1.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 18482fb..bd6463d 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -95,14 +95,14 @@ entity. IRC channels and IRC users JIDs have a localpart formed like this: `name`, the `'%'` separator and the `irc_server`. -For an IRC channel, the name starts with `'&'`, `'#'`, `'+'` -or `'!'`. 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 -*foo*, *#foo*, and *##foo*. - -If the name starts with any other character, this represents an IRC user. +If the IRC channel you want to adress starts with the `'#'` character (or +less frequently, but still valid, one of `'&'`, `'+'` 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*, *#foo*, and *##foo*. + If compiled with Libidn, an IRC user has a bare JID representing the “hostname” provided by the IRC server. -- cgit v1.2.3 From 996a827a5231464eb4d31d78b56ed4054ab0f4a8 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Tue, 15 Apr 2014 05:42:12 +0200 Subject: Document the new dummy channel, and how biboumi creates and closes connections --- doc/biboumi.1.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index bd6463d..c985de7 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -111,6 +111,21 @@ If compiled with Libidn, an IRC user has a bare JID representing the 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_serve@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 can join it, you can first join the room +`%irc.example.com@biboumi.example.net` (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.net" and finally +join the room `#foo%irc.example.com@biboumi.example.net`. + ### Channel messages On XMPP, unlike on IRC, the displayed order of the messages is the same for -- cgit v1.2.3 From a593d806dde970519b997c619e9e690e0aa1bcfc Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sat, 31 May 2014 17:08:49 +0200 Subject: Document the `admin` configuration option --- doc/biboumi.1.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index c985de7..5197d8f 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -46,6 +46,12 @@ The configuration file uses a simple format of the form This password must be configured in the XMPP server, associated with the external component on *hostname*. +`admin` + + The bare JID of the gateway admin. This JID will have more privileges than + other standard users, for example some administration ad-hoc commands will + only be available to that JID. + `log_file` A filename into which logs are written. If none is provided, the logs are -- cgit v1.2.3 From 1706a92f0c67058591ac8ebb378cf46a6bdbad5a Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Tue, 3 Jun 2014 02:11:29 +0200 Subject: Update the documentation --- doc/biboumi.1.md | 117 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 78 insertions(+), 39 deletions(-) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 5197d8f..241e5c2 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -1,4 +1,4 @@ -BIBOUMI 1 "2014-02-17" +BIBOUMI 1 "2014-06-02" ====================== NAME @@ -48,18 +48,19 @@ The configuration file uses a simple format of the form `admin` - The bare JID of the gateway admin. This JID will have more privileges than - other standard users, for example some administration ad-hoc commands will - only be available to that JID. + 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. `log_file` A filename into which logs are written. If none is provided, the logs are - written on standard output + written on standard output. `log_level` - Indicate what type of log messages to write in the logs. Values can be + 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. @@ -71,12 +72,13 @@ USAGE ----- When started, biboumi connects, without encryption (see *SECURITY*), to the -local XMPP server on the port `5347` and provides the configured password to -authenticate. Biboumi then serves the configured `hostname`, this means -that all XMPP stanza with a `to` JID on that domain will be sent to biboumi, -and biboumi will send only send messages coming from this hostname. +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 an user joins an IRC channel on an IRC server (see *Join an IRC +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, @@ -84,13 +86,12 @@ 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 the SIGINT or SIGTERM signals to 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 all -connections are closed because the remote acknowledged the end of -communication. If the remote server does not respond, biboumi does not -exit, unless SIGINT or SIGTERM is received again, in which case biboumi -closes the TCP connections and exits immediately. +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 @@ -109,8 +110,22 @@ 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*, *#foo*, and *##foo*. +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. + +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.example.com@biboumi.example.com` is the IRC user named toto, or TotO, etc. + If compiled with Libidn, an IRC user has a bare JID representing the -“hostname” provided by the IRC server. +“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. ### Join an IRC channel @@ -124,13 +139,13 @@ 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_serve@biboumi.example.com`. For example if you want to join the +`%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 can join it, you can first join the room -`%irc.example.com@biboumi.example.net` (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.net" and finally -join the room `#foo%irc.example.com@biboumi.example.net`. +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 @@ -138,14 +153,14 @@ On XMPP, unlike on IRC, the displayed order of the messages is the same for all participants of a MUC. Biboumi can not however provide this feature, as it cannot know whether the IRC server has received and forwarded the messages to other users. This means that the order of the messages -displayed in your XMPP may not be the same than the order on other IRC -users’. +displayed in your XMPP client may not be the same than the order on other +IRC users’. ### Nicknames On IRC, nicknames are server-wide. This means that one user only has one single nickname at one given time on all the channels of a server. This is -different from XMPP where an user can have a different nick on each MUC, +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 @@ -160,13 +175,10 @@ 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). Using biboumi, there is no way to receive a message from a -room participant (from a jid like #test%irc.example.com/nickname). Instead, -private messages are received from and sent to the user (using a jid like -nickname%irc.example.com). For conveniance and compatibility with XMPP -clients sending private messages to the MUC participants, a message sent to -#chan%irc.example.com@irc.example.net/Nickname will be redirected to -Nickname%irc.example.com@irc.example.net, although this is not the prefered -way to do it. +room participant (from a jid like +#test%irc.example.com@biboumi.example.com/nickname). Instead, private +messages are received from and sent to the user (using a jid like +nickname%irc.example.com@biboumi.example.com). ### Notices @@ -199,8 +211,8 @@ direction. 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 an user corresponds to the `moderator` role -in XMPP), it is impossible to map all these modes to an XMPP feature. To +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. @@ -238,6 +250,23 @@ between IRC modes and XMPP features is as follow: Sets the participant’s role to `participant` and its affiliation to `member`. +### Ad-hoc commands + +Biboumi supports a few ad-hoc commands, as described in the XEP 0050. + + - ping: Just respond “pong” + + - hello: Provide a form, where the user enters their name, and biboumi + responds with a nice greeting. + + - disconnect-user: Available to the administrator only. The user provides + a list of JIDs, and a quit message. All these 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. + SECURITY -------- @@ -246,9 +275,19 @@ server MUST be made on localhost. The XMPP server is not supposed to accept non-local connection from components, thus encryption is useless. IRC SSL/TLS is also not yet implemented. -Biboumi also does not check if received JIDs are properly formatted using -nodeprep. This must be done by the XMPP server to which biboumi is directly -connected. +Biboumi also 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. + +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. + +Biboumi does not yet 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 users. AUTHORS ------- -- cgit v1.2.3 From fa071309917252cd76d1334eedc6703057d1f29f Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Fri, 6 Jun 2014 02:15:35 +0200 Subject: Little doc fix --- doc/biboumi.1.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 241e5c2..6b04802 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -102,13 +102,18 @@ entity. IRC channels and IRC users JIDs have a localpart formed like this: `name`, the `'%'` separator and the `irc_server`. -If the IRC channel you want to adress starts with the `'#'` character (or -less frequently, but still valid, one of `'&'`, `'+'` 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 +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*, *#foo*, and *##foo*. +the channels *#foo*, and *##foo*. + +The name part 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. + 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, @@ -121,7 +126,13 @@ Examples: irc.example.com IRC server, and this is served by the biboumi instance on biboumi.example.com - `toto.example.com@biboumi.example.com` is the IRC user named toto, or TotO, etc. + `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. If compiled with Libidn, an IRC user has a bare JID representing the “hostname” provided by the IRC server. This JID can only be used to set IRC -- cgit v1.2.3 From 1604320a2398901aa7662ece857e9bd217e8b06a Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sun, 8 Jun 2014 23:30:17 +0200 Subject: Make the XMPP component port configurable fix #2541 --- doc/biboumi.1.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 6b04802..605fb96 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -46,6 +46,11 @@ The configuration file uses a simple format of the form This password must be configured in the XMPP server, associated with the external component on *hostname*. +`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 -- cgit v1.2.3 From 7c1a38999c2eebfbd0939c9f8f8f864f10d9bc9a Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Wed, 11 Jun 2014 02:37:11 +0200 Subject: Rewrite the whole IID usage IRC users and channels are now distinguished by the separator used in the IID (% or !). ref #2468 --- doc/biboumi.1.md | 36 ++++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 605fb96..38a4718 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -101,11 +101,12 @@ 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, and the local part depends on the concerned -entity. +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 and IRC users JIDs have a localpart formed like this: -`name`, the `'%'` separator and the `irc_server`. +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 `'!'`), @@ -113,12 +114,16 @@ 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*. +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 name part can also be empty (for example `%irc.example.com`), in 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. +IRC users have a local part formed like this: +`user_name`!`irc_server`. 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, @@ -131,7 +136,7 @@ Examples: 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!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. @@ -139,9 +144,20 @@ Examples: `%irc.example.com@biboumi.example.com` is the virtual channel provided by biboumi, for the IRC server irc.example.com. -If compiled with Libidn, an IRC user 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. +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 -- cgit v1.2.3 From 6cbaa2c669ab572009eb560c4be8ff2e47542d55 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Fri, 13 Jun 2014 01:46:12 +0200 Subject: Document the encryption, and a few documentation issues are fixed --- doc/biboumi.1.md | 79 ++++++++++++++++++++++++++++++-------------------------- 1 file changed, 43 insertions(+), 36 deletions(-) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 38a4718..1de6f81 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -6,11 +6,6 @@ NAME biboumi - XMPP gateway to IRC -SYNOPSIS --------- - -`biboumi` [`config_filename`] - DESCRIPTION ----------- @@ -18,10 +13,15 @@ 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 options: +Available command line options: `config_filename` @@ -176,7 +176,7 @@ 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" +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 @@ -207,10 +207,9 @@ 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). Using biboumi, there is no way to receive a message from a -room participant (from a jid like -#test%irc.example.com@biboumi.example.com/nickname). Instead, private -messages are received from and sent to the user (using a jid like -nickname%irc.example.com@biboumi.example.com). +room participant (from a jid like #test%irc.example.com@biboumi.example.com/nickname). +Instead, private messages are received from and sent to the user (using a +jid like `nickname!irc.example.com@biboumi.example.com`). ### Notices @@ -291,35 +290,43 @@ Biboumi supports a few ad-hoc commands, as described in the XEP 0050. - hello: Provide a form, where the user enters their name, and biboumi responds with a nice greeting. - - disconnect-user: Available to the administrator only. The user provides - a list of JIDs, and a quit message. All these 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-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. SECURITY -------- -Biboumi does not provide any encryption mechanism: connection to the XMPP -server MUST be made on localhost. The XMPP server is not supposed to accept -non-local connection from components, thus encryption is useless. IRC -SSL/TLS is also not yet implemented. - -Biboumi also 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. - -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. - -Biboumi does not yet 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 users. +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 ------- -- cgit v1.2.3 From 386ac4186a750feee12b7d9b89ca37c3d16ebff4 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Wed, 18 Jun 2014 22:55:18 +0200 Subject: Document the new way to send private messages --- doc/biboumi.1.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 1de6f81..f3f1677 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -122,8 +122,14 @@ 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. -IRC users have a local part formed like this: -`user_name`!`irc_server`. +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, @@ -206,10 +212,11 @@ be changed on all channels on the same server as well. 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). Using biboumi, there is no way to receive a message from a -room participant (from a jid like #test%irc.example.com@biboumi.example.com/nickname). -Instead, private messages are received from and sent to the user (using a -jid like `nickname!irc.example.com@biboumi.example.com`). +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 -- cgit v1.2.3 From 39175e1ad6fe6507bbe2874c6ce413cbe9c3366e Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Tue, 24 Jun 2014 20:47:07 +0200 Subject: Little documentation update --- doc/biboumi.1.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index f3f1677..fb48d4b 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -39,6 +39,7 @@ The configuration file uses a simple format of the form 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) @@ -76,6 +77,11 @@ log level without having to restart biboumi) by sending SIGUSR1 or SIGUSR2 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 -- cgit v1.2.3 From 546f3536ee1ea7ce8922fa32b6fdf600adc133cb Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Mon, 18 Aug 2014 02:23:15 +0200 Subject: Escape a # in biboumi.1.md --- doc/biboumi.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index fb48d4b..a35d4fc 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -221,7 +221,7 @@ 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 +\#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 -- cgit v1.2.3 From fd0a3225be09990e8d2e0e7f441440de9879f7eb Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sat, 24 Jan 2015 18:03:00 +0100 Subject: Document the new affiliation/role stuff, and update changelog --- doc/biboumi.1.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index a35d4fc..18df220 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -294,6 +294,28 @@ between IRC modes and XMPP features is as follow: 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. -- cgit v1.2.3 From 2df0ebf2dfed1dcbf80c92bff8361e2a04581bec Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Wed, 25 Feb 2015 18:35:30 +0100 Subject: Add support for a fixed_irc_server configuration This option lets the administrator choose a specific IRC server, and only that server can be used with this biboumi instance. In this mode, JIDs to use are changed like this: - #chan%irc.example.com@biboumi.example.com -> #chan@biboumi.example.com - user!irc.example.com@biboumi.example.com -> user!@biboumi.example.com - #chan%irc.example.com@biboumi.example.com/Nick -> #chan@biboumi.example.com/Nick - %irc.example.com@biboumi.example.com -> no equivalent - irc.example.com@biboumi.example.com -> no equivalent --- doc/biboumi.1.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 18df220..9e95139 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -59,6 +59,20 @@ The configuration file uses a simple format of the form 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@irc.biboumi.org" must be + used instead of "#chan%irc.example.org@irc.biboumi.org". 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"). + 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, but + without letting them join any other IRC servers on the internet. + `log_file` A filename into which logs are written. If none is provided, the logs are -- cgit v1.2.3 From c307df85c8e7d9bcd4570269bf13c3e92c3f5954 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Wed, 25 Feb 2015 19:05:04 +0100 Subject: Do not handle the "%" char in a special way, in the fixed_server mode Also fix some doc --- doc/biboumi.1.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 9e95139..3fd5a25 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -63,15 +63,19 @@ The configuration file uses a simple format of the form 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@irc.biboumi.org" must be - used instead of "#chan%irc.example.org@irc.biboumi.org". 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"). - 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, but - without letting them join any other IRC servers on the internet. + 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. `log_file` -- cgit v1.2.3 From d79850f984cb5aa9579ebc5f5e53696fc7872eb8 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Tue, 21 Apr 2015 02:54:47 +0200 Subject: Document how to address a nick with @ character fix #3047 --- doc/biboumi.1.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 3fd5a25..b69dede 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -160,6 +160,12 @@ 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 -- cgit v1.2.3 From 0a6b673b14efc4f623ea445045e6fc60e9842a25 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Thu, 7 May 2015 17:01:17 +0200 Subject: Support raw IRC messages Messages received on an IRC server JID are forwarded as raw IRC messages. fix #2486 --- doc/biboumi.1.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index b69dede..faa9618 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -357,6 +357,20 @@ Biboumi supports a few ad-hoc commands, as described in the XEP 0050. “Gateway shutdown” quit message, except that biboumi does not exit when using this ad-hoc command. +### 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 -------- -- cgit v1.2.3 From a2b0f21a96a3c9ba217937d4762799e038fd5e9a Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Tue, 19 May 2015 06:21:08 +0200 Subject: Document the listing of channels fix #2472 --- doc/biboumi.1.md | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index faa9618..836b99d 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -224,6 +224,13 @@ 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 -- cgit v1.2.3 From 84aafab6040f8fd126e6c4941631d44f122c4b9a Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Mon, 12 Oct 2015 16:47:27 +0200 Subject: =?UTF-8?q?Provide=20the=20=E2=80=9Crealname=5Fcustomization?= =?UTF-8?q?=E2=80=9D=20option?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ref #3136 --- doc/biboumi.1.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 836b99d..d28c3a3 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -77,6 +77,12 @@ The configuration file uses a simple format of the form 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. + `log_file` A filename into which logs are written. If none is provided, the logs are -- cgit v1.2.3 From 1aa2c2d857037f3274297527ca3971a75203d39c Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Mon, 12 Oct 2015 17:14:29 +0200 Subject: Introduce the realname_from_jid option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When set to true, the realname and username are extracted (by default) from the user’s JID fix #3136 --- doc/biboumi.1.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index d28c3a3..763be56 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -83,6 +83,19 @@ The configuration file uses a simple format of the form 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. + `log_file` A filename into which logs are written. If none is provided, the logs are -- cgit v1.2.3 From 34fc1d4010d23be947c00fc956f2bdded2374cee Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sat, 31 Oct 2015 06:17:35 +0100 Subject: Implement a basic webirc support See https://kiwiirc.com/docs/webirc fix #3135 --- doc/biboumi.1.md | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 763be56..1631ebd 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -96,6 +96,13 @@ The configuration file uses a simple format of the form 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 -- cgit v1.2.3 From 5ce9d3f1429228746fcee724a44860f16ad166f5 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Thu, 5 Nov 2015 02:16:21 +0100 Subject: Make the CA file configurable --- doc/biboumi.1.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 1631ebd..8a234fc 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -114,6 +114,12 @@ The configuration file uses a simple format of the form 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. + 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. -- cgit v1.2.3 From 6dcb21a032d47cd3a1f6f2d5d795a1c0f67b382e Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Mon, 30 Nov 2015 21:28:35 +0100 Subject: Document the fact that the joining-nick is ignored fix #2695 --- doc/biboumi.1.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 8a234fc..4aded1e 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -275,6 +275,11 @@ 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 -- cgit v1.2.3 From 241768836ddfb9e3609f987224cd821058fcc948 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Tue, 1 Dec 2015 16:08:40 +0100 Subject: Add the outgoing_bind option Lets the admin choose a local address to bind each outgoing (IRC) socket. --- doc/biboumi.1.md | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 4aded1e..7a33f4f 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -120,6 +120,15 @@ The configuration file uses a simple format of the form 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 connection to the XMPP server is always done locally + on 127.0.0.1. + 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. -- cgit v1.2.3 From 1f6eea62f46789c0d3ebe7da133ccad2e59c89c8 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Thu, 3 Dec 2015 21:14:24 +0100 Subject: Add an ad-hoc command to disconnect a user from one or more IRC server fix #3077 --- doc/biboumi.1.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 7a33f4f..cf7b893 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -410,6 +410,12 @@ Biboumi supports a few ad-hoc commands, as described in the XEP 0050. “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. + ### Raw IRC messages Biboumi tries to support as many IRC features as possible, but doesn’t -- cgit v1.2.3 From 8ddbe8d3e6a5a5001537379aa4f1a418c6cb6d23 Mon Sep 17 00:00:00 2001 From: Stuart Mumford Date: Fri, 11 Dec 2015 15:19:40 +0000 Subject: Make the XMPP server address configurable. fix #3145 --- doc/biboumi.1.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index cf7b893..bb18475 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -47,6 +47,12 @@ The configuration file uses a simple format of the form 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 -- cgit v1.2.3 From dfcb0a6e0e975b7a4fd3b9ca3cb340fc1859d7f9 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Tue, 29 Dec 2015 10:05:40 +0100 Subject: This is no longer true, with the recent xmpp_server_ip configuration option --- doc/biboumi.1.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index bb18475..085a754 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -132,8 +132,7 @@ The configuration file uses a simple format of the form 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 connection to the XMPP server is always done locally - on 127.0.0.1. + 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 -- cgit v1.2.3 From 8ca818f8abab5fba668dfd54268de72cdfa3d95d Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Wed, 30 Dec 2015 20:04:21 +0100 Subject: Document the Configure ad-hoc commands --- doc/biboumi.1.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.md b/doc/biboumi.1.md index 085a754..3a1fb28 100644 --- a/doc/biboumi.1.md +++ b/doc/biboumi.1.md @@ -401,6 +401,9 @@ Affiliation set to `owner` ### 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” @@ -421,6 +424,20 @@ Biboumi supports a few ad-hoc commands, as described in the XEP 0050. 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 -- cgit v1.2.3 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 From 38202e5f6e16d8fc1e07811049851bfa417fb9c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?louiz=E2=80=99?= Date: Mon, 23 May 2016 11:51:03 +0200 Subject: Update the build process to take into account the rst files --- doc/biboumi.1.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'doc') diff --git a/doc/biboumi.1.rst b/doc/biboumi.1.rst index 6411efe..2a6dae3 100644 --- a/doc/biboumi.1.rst +++ b/doc/biboumi.1.rst @@ -4,7 +4,6 @@ Biboumi(1) User Manual .. contents:: :depth: 2 - NAME ==== -- cgit v1.2.3 From 4661f7fe5bd05fa669586789b46561ebdbd53e69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?louiz=E2=80=99?= Date: Tue, 14 Jun 2016 14:52:04 +0200 Subject: Fix a doc typo --- doc/biboumi.1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/biboumi.1.rst b/doc/biboumi.1.rst index 2a6dae3..b8bf794 100644 --- a/doc/biboumi.1.rst +++ b/doc/biboumi.1.rst @@ -353,7 +353,7 @@ 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 +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. -- cgit v1.2.3 From 4463e9f5e3169d41a423982a35d9ca3cd4a9562c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?louiz=E2=80=99?= Date: Thu, 28 Jul 2016 16:05:36 +0200 Subject: Document the multi-nick session thing --- doc/biboumi.1.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'doc') diff --git a/doc/biboumi.1.rst b/doc/biboumi.1.rst index b8bf794..6d4c35a 100644 --- a/doc/biboumi.1.rst +++ b/doc/biboumi.1.rst @@ -178,6 +178,14 @@ 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. +Additionally, if one user is using more than one clients (with the same bare +JID), they can join the same IRC channel (on the same server) behind one +single nickname. Biboumi will forward all the messages (the channel ones and +the private ones) and the presences to all the resources behind that nick. +There is no need to have multiple nicknames and multiple connections to be +able to take part in a conversation (or idle) in a channel from a mobile client +while the desktop client is still connected, for example. + 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 -- cgit v1.2.3 From b66c006a4bc63030c25134550c6f27aca677830a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?louiz=E2=80=99?= Date: Fri, 29 Jul 2016 10:40:00 +0200 Subject: Trivial micro fix --- doc/biboumi.1.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/biboumi.1.rst b/doc/biboumi.1.rst index 6d4c35a..dd365f0 100644 --- a/doc/biboumi.1.rst +++ b/doc/biboumi.1.rst @@ -1,6 +1,6 @@ -======================= +====================== Biboumi(1) User Manual -======================= +====================== .. contents:: :depth: 2 -- cgit v1.2.3