1Biboumi(1)                                                          Biboumi(1)
2
3
4
5       depth  2
6

NAME

8       biboumi - XMPP gateway to IRC
9

Description

11       Biboumi  is an XMPP gateway that connects to IRC servers and translates
12       between the two protocols.  It can be used to access IRC channels using
13       any XMPP client as if these channels were XMPP MUCs.
14

Synopsis

16       biboumi [config_filename]
17

Options

19       Available command line options:
20
21   config_filename
22       Specify the file to read for configuration.  See the Configuration sec‐
23       tion for more details on its content.
24

Configuration

26       The configuration file uses a simple format of the form option=value.
27
28       The values from the configuration file can be overridden by environment
29       variables,  with  the name all in upper case and prefixed with "BIBOUMI
30       ()".  For example, if the environment contains “BIBOUMI_PASSWORD=blah",
31       this will override the value of the “password” option in the configura‐
32       tion file.
33
34       Sending SIGUSR1 or SIGUSR2 (see kill(1)) to the process will  force  it
35       to  re-read  the  configuration  and  make it close and re-open the log
36       files.  You can use this to change any configuration option at runtime,
37       or do a log rotation.
38
39       Here is a description of every possible option:
40
41   hostname
42       Mandatory.   The hostname served by the XMPP gateway.  This domain must
43       be configured in the XMPP server as an  external  component.   See  the
44       manual  for  your  XMPP  server for more information.  For prosody, see
45       <http://prosody.im/doc/components#adding_an_external_component>
46
47   password
48       Mandatory.  The password used to authenticate  the  XMPP  component  to
49       your XMPP server.  This password must be configured in the XMPP server,
50       associated with the external component on hostname.
51
52   xmpp_server_ip
53       The IP address to connect to the XMPP server on.  The connection to the
54       XMPP  server  is  unencrypted,  so  the biboumi instance and the server
55       should normally be on the same host.  The default value is 127.0.0.1.
56
57   port
58       The TCP port to use to connect to the local XMPP  component.   The  de‐
59       fault value is 5347.
60
61   db_name
62       The  name  of the database to use.  This option can only be used if bi‐
63       boumi has been compiled with a database support (Sqlite3  and/or  Post‐
64       greSQL).   If  the  value  begins  with  the  postgresql scheme, “post‐
65       gresql://” or “postgres://”, then biboumi will try to  connect  to  the
66       PostgreSQL  database  specified  by  the  URI.   See <https://www.post
67       gresql.org/docs/current/static/libpq-connect.html#idm46428693970032>
68       for  all  possible  values.   For  example  the  value  could be “post‐
69       gresql://user:<secret@localhost>”.  If the value does  not  start  with
70       the postgresql scheme, then it specifies a filename that will be opened
71       with Sqlite3.  For example the value could be  “/var/lib/biboumi/bibou‐
72       mi.sqlite”.
73
74   admin
75       The  bare  JID  of  the gateway administrator.  This JID will have more
76       privileges than other standard users, for example  some  administration
77       ad-hoc commands will only be available to that JID.
78
79       If  you  need  more  than one administrator, separate them with a colon
80       (:).
81
82   fixed_irc_server
83       If this option contains the hostname of  an  IRC  server  (for  example
84       irc.example.org),  then  biboumi will enforce the connexion to that IRC
85       server only.  This means that a JID like #chan@biboumi.example.com must
86       be  used  instead  of #chan%irc.example.org@biboumi.example.com.  The %
87       character loses any meaning in the JIDs.  It can appear in the JID  but
88       will not be interpreted as a separator (thus the JID #channel%hello@bi‐
89       boumi.example.com points to the channel  named  #channel%hello  on  the
90       configured IRC server) This option can for example be used by an admin‐
91       istrator that just wants to let their users join their own  IRC  server
92       using an XMPP client, while forbidding access to any other IRC server.
93
94   persistent_by_default
95       If this option is set to true, all rooms will be persistent by default:
96       the value of the “persistent” option in  the  global  configuration  of
97       each  user  will  be “true”, but the value of each individual room will
98       still default to false.  This means that a user just  needs  to  change
99       the global “persistent” configuration option to false in order to over‐
100       ride this.
101
102       If it is set to false (the default value), all rooms are not persistent
103       by default.
104
105       Each room can be configured individually by each user, to override this
106       default value.  See Ad-hoc commands.
107
108   realname_customization
109       If this option is set to “false” (default is “true”),  the  users  will
110       not  be  able to use the ad-hoc commands that lets them configure their
111       realname and username.
112
113   realname_from_jid
114       If this option is set to “true”, the realname and username of each  bi‐
115       boumi  user  will  be  extracted from their JID.  The realname is their
116       bare JID, and the username is the node-part of their JID.  Note that if
117       realname_customization  is “true”, each user will still be able to cus‐
118       tomize their realname and username, this option just  decides  the  de‐
119       fault realname and username.
120
121       If  this option is set to “false” (the default value), the realname and
122       username of each user will be set to the nick they used to  connect  to
123       the IRC server.
124
125   webirc_password
126       Configure  a  password to be communicated to the IRC server, as part of
127       the WEBIRC message (see  <https://kiwiirc.com/docs/webirc>).   If  this
128       option  is  set,  an  additional DNS resolution of the hostname of each
129       XMPP server will be made when connecting to an IRC server.
130
131   log_file
132       A filename into which logs are written.  If none is provided, the  logs
133       are written on standard output.
134
135   log_level
136       Indicate  what type of log messages to write in the logs.  Value can be
137       from 0 to 3.  0 is debug, 1 is info, 2 is warning, 3 is error.  The de‐
138       fault is 0, but a more practical value for production use is 1.
139
140   ca_file
141       Specifies  which file should be used as the list of trusted CA when ne‐
142       gociating a TLS session.  By default this value is  unset  and  biboumi
143       tries a list of well-known paths.
144
145   outgoing_bind
146       An address (IPv4 or IPv6) to bind the outgoing sockets to.  If no value
147       is specified, it will use the one assigned  by  the  operating  system.
148       You  can for example use outgoing_bind=192.168.1.11 to force biboumi to
149       use the interface with this address.  Note that this is only  used  for
150       connections to IRC servers.
151
152   identd_port
153       The TCP port on which to listen for identd queries.  The default is the
154       standard value: 113.  To be able to listen on this privileged port, bi‐
155       boumi needs to have certain capabilities: on linux, using systemd, this
156       can be achieved by adding  AmbientCapabilities=CAP_NET_BIND_SERVICE  to
157       the  unit file.  On other systems, other solutions exist, like the por‐
158       tacl module on FreeBSD.
159
160       If biboumi's identd server is properly started, it will receive queries
161       from  the  IRC servers asking for the “identity” of each IRC connection
162       made to it.  Biboumi will answer with a hash of the JID that  made  the
163       connection.   This  is  useful for the IRC server to be able to distin‐
164       guish the different users, and be able to deal with the absuses without
165       having to simply ban the IP.  Without this identd server, moderation is
166       a lot harder, because all the different users of a single  biboumi  in‐
167       stance  all  share  the same IP, and they can't be distinguished by the
168       IRC servers.
169
170       To disable the built-in identd, you may set identd_port to 0.
171
172   policy_directory
173       A directory that should contain the policy  files,  used  to  customize
174       Botan's  behaviour  when  negociating  the TLS connections with the IRC
175       servers.  If not specified, the directory is the  one  where  biboumi's
176       configuration file is located: for example if biboumi reads its config‐
177       uration from /etc/biboumi/biboumi.cfg, the policy_directory value  will
178       be /etc/biboumi.
179

TLS configuration

181       Various  settings of the TLS connections can be customized using policy
182       files.  The files should be located in the directory specified  by  the
183       configuration  option  policy_directory.  When attempting to connect to
184       an IRC server using TLS, biboumi will use Botan's default  TLS  policy,
185       and  then  will  try  to  load some policy files to override the values
186       found in these files.  For example, if policy_directory is  /etc/bibou‐
187       mi, when trying to connect to irc.example.com, biboumi will try to read
188       /etc/biboumi/policy.txt, use the values found to override  the  default
189       values,  then  it  will  try to read /etc/biboumi/irc.example.com.poli‐
190       cy.txt and re-override the policy with the values found in this file.
191
192       The policy.txt file applies  to  all  the  connections,  and  irc.exam‐
193       ple.policy.txt  will  only  apply (in addition to policy.txt) when con‐
194       necting to that specific server.
195
196       To see the list of possible options to configure, refer to Botan's  TLS
197       documentation    (https://botan.randombit.net/manual/tls.html#tls-poli‐
198       cies).
199
200       By default, biboumi provides a few policy files, to  work  around  some
201       issues found with a few well-known IRC servers.
202

Usage

204       Biboumi  acts  as  a server, it should be run as a daemon that lives in
205       the background for as long as it is needed.  Note that biboumi does not
206       daemonize  itself,  this  task  should  be  done  by  your  init system
207       (SysVinit, systemd, upstart).
208
209       When started, biboumi connects, without encryption (see  Security),  to
210       the  local XMPP server on the port 5347 and authenticates with the pro‐
211       vided password.  Biboumi then  serves  the  configured  hostname:  this
212       means  that  all  XMPP stanza with a to JID on that domain will be for‐
213       warded to biboumi by the XMPP server, and biboumi will only  send  mes‐
214       sages coming from that hostname.
215
216       When  a  user  joins  an  IRC channel on an IRC server (see Join an IRC
217       channel), biboumi connects to the remote IRC server,  sets  the  user's
218       nick  as  requested,  and then tries to join the specified channel.  If
219       the same user subsequently tries to connect to an other channel on  the
220       same  server,  the  same IRC connection is used.  If, however, an other
221       user wants to join an IRC channel on  that  same  IRC  server,  biboumi
222       opens  a  new connection to that server.  Biboumi connects once to each
223       IRC server, for each user on it.
224
225       Additionally, if one user is using more than one clients (with the same
226       bare  JID), they can join the same IRC channel (on the same server) be‐
227       hind one single nickname.  Biboumi will forward all the  messages  (the
228       channel  ones  and  the  private ones) and the presences to all the re‐
229       sources behind that nick.  There is no need to have multiple  nicknames
230       and  multiple connections to be able to take part in a conversation (or
231       idle) in a channel from a mobile client while  the  desktop  client  is
232       still connected, for example.
233
234       To  cleanly  shutdown the component, send a SIGINT or SIGTERM signal to
235       it.  It will send messages to all connected IRC and XMPP servers to in‐
236       dicate  a  reason  why the users are being disconnected.  Biboumi exits
237       when the end of communication is acknowledged by all IRC  servers.   If
238       one  or  more  IRC servers do not respond, biboumi will only exit if it
239       receives the same signal again or if a 2 seconds delay has passed.
240
241   Addressing
242       IRC entities are represented by XMPP JIDs.  The domain part of the  JID
243       is  the  domain  served by biboumi (the part after the @, biboumi.exam‐
244       ple.com in the examples), and the local part (the part  before  the  @)
245       depends on the concerned entity.
246
247       IRC  channels  and IRC users have a local part formed like this: name %
248       irc_server.
249
250       name can be a channel name or an user nickname.   The  distinction  be‐
251       tween  the two is based on the first character: by default, if the name
252       starts with '#' or '&' (but this can be overridden by the server, using
253       the  ISUPPORT  extension) then it's a channel name, otherwise this is a
254       nickname.
255
256       There is two ways to address an IRC user, using a local part like this:
257       nickname  %  irc_server or by using the in-room address of the partici‐
258       pant, like this: channel_name  %  irc_server  @  biboumi.example.com  /
259       Nickname
260
261       The  second  JID  is  available only to be compatible with XMPP clients
262       when the user wants to send a private message to the participant  Nick‐
263       name in the room channel_name%irc_server@biboumi.example.com.
264
265       On  XMPP, the node part of the JID can only be lowercase.  On the other
266       hand, IRC nicknames are case-insensitive, this means that the nicknames
267       toto,  Toto, tOtO and TOTO all represent the same IRC user.  This means
268       you can talk to the user toto, and this will work.
269
270       Also note that some IRC nicknames or channels  may  contain  characters
271       that  are not allowed in the local part of a JID (for example '@').  If
272       you need to send a message to a nick containing such a  character,  you
273       can   use  a  jid  like  %irc.example.com@biboumi.example.com/Annoying‐
274       Nickn@me, because the JID  AnnoyingNickn@me%irc.example.com@biboumi.ex‐
275       ample.com  would  not  work.  And if you need to address a channel that
276       contains  such  invalid  characters,  you  have  to  use   jid-escaping
277       (http://www.xmpp.org/extensions/xep-0106.html#escaping),   and  replace
278       each of these characters with their escaped  version,  for  example  to
279       join the channel #b@byfoot, you need to use the following JID: #b\40by‐
280       foot%irc.example.com@biboumi.example.com.
281
282       Examples:
283
284       · #foo%irc.example.com@biboumi.example.com is the #foo IRC channel,  on
285         the irc.example.com IRC server, and this is served by the biboumi in‐
286         stance on biboumi.example.com
287
288       · toto%irc.example.com@biboumi.example.com is the IRC user named  toto,
289         or TotO, etc.
290
291       · irc.example.com@biboumi.example.com   is  the  IRC  server  irc.exam‐
292         ple.com.
293
294       Note: Some JIDs are valid but make no sense in the context of biboumi:
295
296       · #test%@biboumi.example.com, or any other JID that does not contain an
297         IRC  server is invalid.  Any message to that kind of JID will trigger
298         an error, or will be ignored.
299
300       If compiled with Libidn, an IRC channel participant has a bare JID rep‐
301       resenting the “hostname” provided by the IRC server.  This JID can only
302       be used to set IRC modes (for example to ban a user based on  its  IP),
303       or  to identify user.  It cannot be used to contact that user using bi‐
304       boumi.
305
306   Join an IRC channel
307       To join an IRC channel #foo on the IRC server irc.example.com, join the
308       XMPP MUC #foo%irc.example.com@biboumi.example.com.
309
310   Connect to an IRC server
311       The  connection  to  the IRC server is automatically made when the user
312       tries to join any channel on that IRC server.  The connection is closed
313       whenever the last channel on that server is left by the user.
314
315   Roster
316       You  can add some JIDs provided by biboumi into your own roster, to re‐
317       ceive presence from them.  Biboumi  will  always  automatically  accept
318       your requests.
319
320   Biboumi's JID
321       By  adding the component JID into your roster, the user will receive an
322       available presence whenever it is started, and an unavailable  presence
323       whenever  it is being shutdown.  This is useful to quickly view if that
324       biboumi instance is started or not.
325
326   IRC server JID
327       These presence will appear online in the user's  roster  whenever  they
328       are connected to that IRC server (see Connect to an IRC server for more
329       details).  This is useful to keep track of which server an user is con‐
330       nected  to: this  is  sometimes  hard  to remember, when they have many
331       clients, or if they are using persistent channels.
332
333   Channel messages
334       On XMPP, unlike on IRC, the displayed order of the messages is the same
335       for  all  participants  of a MUC.  Biboumi can not however provide this
336       feature, as it cannot know whether the IRC server has received and for‐
337       warded  the  messages to other users.  This means that the order of the
338       messages displayed in your XMPP client may not be the same as the order
339       on other IRC users'.
340
341   History
342       Public  channel  messages are saved into archives, inside the database,
343       unless the record_history option is set to  false  by  that  user  (see
344       Ad-hoc commands).  Private messages (messages that are sent directly to
345       a nickname, not a channel) are never stored in the database.
346
347       A channel history can be retrieved by using Message archive  management
348       (MAM)  (https://xmpp.org/extensions/xep-0313.htm)  on  the channel JID.
349       The results can be filtered by start and end dates.
350
351       When a channel is joined, if the client doesn't specify any limit,  bi‐
352       boumi  sends the max_history_length last messages found in the database
353       as the MUC history.  If a client wants to only use MAM for the archives
354       (because  it's  more convenient and powerful), it should request to re‐
355       ceive no history by using an attribute maxchars='0'  or  maxstanzas='0'
356       as defined in XEP 0045, and do a proper MAM request instead.
357
358       Note:  the maxchars attribute is ignored unless its value is exactly 0.
359       Supporting it properly would be very hard and would introduce a lot  of
360       complexity for almost no benefit.
361
362       For a given channel, each user has her or his own archive.  The content
363       of the archives are never shared, and thus a user can not  use  someone
364       else's  archive  to get the messages that they didn't receive when they
365       were offline.  Although this feature would  be  very  convenient,  this
366       would introduce a very important privacy issue: for example if a bibou‐
367       mi gateway is used by two users, by querying the archive one user would
368       be  able to know whether or not the other user was in a room at a given
369       time.
370
371   List channels
372       You can list the IRC channels on a given IRC server by sending an  XMPP
373       disco  items  request on the IRC server JID.  The number of channels on
374       some servers is huge so the result stanza may be very big, unless  your
375       client supports result set management (XEP 0059)
376
377   Nicknames
378       On  IRC,  nicknames are server-wide.  This means that one user only has
379       one single nickname at one given time on all the channels of a  server.
380       This  is  different from XMPP where a user can have a different nick on
381       each MUC, even if these MUCs are on the same server.
382
383       This means that the nick you choose when joining your first IRC channel
384       on  a given IRC server will be your nickname in all other channels that
385       you join on that same IRC server.  If you explicitely change your nick‐
386       name  on  one channel, your nickname will be changed on all channels on
387       the same server as well.  Joining a new channel with a different  nick,
388       however, will not change your nick.  The provided nick will be ignored,
389       in order to avoid changing your nick on the whole  server  by  mistake.
390       If you want to have a different nickname in the channel you're going to
391       join, you need to do it explicitly with the NICK command before joining
392       the channel.
393
394   Private messages
395       Private  messages  are handled differently on IRC and on XMPP.  On IRC,
396       you talk directly to one server-user: toto on the channel #foo  is  the
397       same  user  as  toto on the channel #bar (as long as these two channels
398       are on the same IRC server).  By default you will receive private  mes‐
399       sages from the “global” user (aka <nickname%irc.example.com@biboumi.ex‐
400       ample.com>), unless you previously sent a message to an in-room partic‐
401       ipant  (something like #<test%irc.example.com@biboumi.example.com/nick‐
402       name>), in which case future messages from that same user will  be  re‐
403       ceived from that same “in-room” JID.
404
405   Notices
406       Notices are received exactly like private messages.  It is not possible
407       to send a notice.
408
409   Topic
410       The topic can be set and retrieved seemlessly.  The  unique  difference
411       is  that if an XMPP user tries to set a multiline topic, every line re‐
412       turn (\n) will be replaced by a space, because the IRC server  wouldn't
413       accept it.
414
415   Invitations
416       If  the  invited  JID is a user JID served by this biboumi instance, it
417       will forward the invitation to the target nick, over  IRC.   Otherwise,
418       the  mediated  instance  will directly be sent to the invited JID, over
419       XMPP.
420
421       Example: if the user wishes to invite the  IRC  user  “FooBar”  into  a
422       room, they can invite one of the following “JIDs” (one of them is not a
423       JID, actually):
424
425       · <foobar%anything@biboumi.example.com>
426
427       · <anything@biboumi.example.com/FooBar>
428
429       · FooBar
430
431       (Note that the “anything” parts are simply ignored because  they  carry
432       no  additional meaning for biboumi: we already know which IRC server is
433       targeted using the JID of the target channel.)
434
435       Otherwise, any valid JID can be used, to invite any XMPP user.
436
437   Kicks and bans
438       Kicks are transparently translated from one protocol to another.   How‐
439       ever  banning  an  XMPP  participant has no effect.  To ban an user you
440       need to set a mode +b on that user nick or host  (see  IRC  modes)  and
441       then kick it.
442
443   Encoding
444       On  XMPP,  the encoding is always UTF-8, whereas on IRC the encoding of
445       each message can be anything.
446
447       This means that biboumi has to convert everything coming from IRC  into
448       UTF-8 without knowing the encoding of the received messages.  To do so,
449       it checks if each message is UTF-8 valid, if not it  tries  to  convert
450       from  iso_8859-1  (because  this appears to be the most common case, at
451       least on the channels I visit) to UTF-8.  If that conversion  fails  at
452       some  point,  a  placeholder character '�' is inserted to indicate this
453       decoding error.
454
455       Messages are always sent in UTF-8 over IRC, no conversion  is  done  in
456       that direction.
457
458   IRC modes
459       One  feature  that  doesn't exist on XMPP but does on IRC is the modes.
460       Although some of these modes have a correspondance in  the  XMPP  world
461       (for example the +o mode on a user corresponds to the moderator role in
462       XMPP), it is impossible to map all these modes to an XMPP feature.   To
463       circumvent this problem, biboumi provides a raw notification when modes
464       are changed, and lets the user change the modes directly.
465
466       To change modes, simply send a message starting with  “/mode”  followed
467       by the modes and the arguments you want to send to the IRC server.  For
468       example “/mode +aho louiz”.  Note that your XMPP client may  interprete
469       messages  begining with “/” like a command.  To actually send a message
470       starting with a slash, you may need to start your message with “//mode”
471       or “/say /mode”, depending on your client.
472
473       When  a  mode is changed, the user is notified by a message coming from
474       the MUC bare JID, looking like “Mode #foo [+ov] [toto tutu]”.  In addi‐
475       tion, if the mode change can be translated to an XMPP feature, the user
476       will be notified of this XMPP event as well.  For example if a mode “+o
477       toto”  is received, then toto's role will be changed to moderator.  The
478       mapping between IRC modes and XMPP features is as follow:
479
480       +q     Sets the participant's role to moderator and its affiliation  to
481              owner.
482
483       +a     Sets  the participant's role to moderator and its affiliation to
484              owner.
485
486       +o     Sets the participant's role to moderator and its affiliation  to
487              admin.
488
489       +h     Sets  the participant's role to moderator and its affiliation to
490              member.
491
492       +v     Sets the participant's role to participant and  its  affiliation
493              to member.
494
495       Similarly,  when  a biboumi user changes some participant's affiliation
496       or role, biboumi translates that in an IRC mode change.
497
498       Affiliation set to none
499              Sets mode to -vhoaq
500
501       Affiliation set to member
502              Sets mode to +v-hoaq
503
504       Role set to moderator
505              Sets mode to +h-oaq
506
507       Affiliation set to admin
508              Sets mode to +o-aq
509
510       Affiliation set to owner
511              Sets mode to +a-q
512
513   Ad-hoc commands
514       Biboumi supports a few ad-hoc commands, as described in the  XEP  0050.
515       Different ad-hoc commands are available for each JID type.
516
517   On the gateway itself (e.g on the JID biboumi.example.com):
518       · ping: Just respond “pong”
519
520       · hello:  Provide a form, where the user enters their name, and biboumi
521         responds with a nice greeting.
522
523       · disconnect-user: Only available to the administrator.  The user  pro‐
524         vides a list of JIDs, and a quit message.  All the selected users are
525         disconnected from all the IRC servers to which they  were  connected,
526         using the provided quit message.  Sending SIGINT to biboumi is equiv‐
527         alent to using this command by selecting all the connected  JIDs  and
528         using  the  “Gateway shutdown” quit message, except that biboumi does
529         not exit when using this ad-hoc command.
530
531       · disconnect-from-irc-servers: Disconnect a single  user  from  one  or
532         more IRC server.  The user is immediately disconnected by closing the
533         socket, no message is sent to the IRC server,  but  the  user  is  of
534         course  notified with an XMPP message.  The administrator can discon‐
535         nect any user, while the other users can only disconnect themselves.
536
537       · configure: Lets each user configure some options that applies global‐
538         ly.   The provided configuration form contains these fields: * Record
539         History: whether or not history messages should be saved in the data‐
540         base.   * Max history length: The maximum number of lines in the his‐
541         tory that the server is allowed to send when joining a channel.
542
543                · Persistent: Overrides the value specified in each individual
544                  channel.   If  this  option is set to true, all channels are
545                  persistent, whether or not their specific value is  true  or
546                  false.   This  option is true by default for everyone if the
547                  persistent_by_default configuration option is  true,  other‐
548                  wise  it's false.  See below for more details on what a per‐
549                  sistent channel is.  This value is
550
551   On a server JID (e.g on the JID
552       <chat.freenode.org@biboumi.example.com>)
553
554       · configure: Lets each user configure some options that applies to  the
555         concerned IRC server.  The provided configuration form contains these
556         fields:
557
558                · Address: This address (IPv4, IPv6 or hostname) will be used,
559                  when  biboumi connects to this server.  This is a very handy
560                  way to have a custom name for a network, and be able to edit
561                  the  address to use if one endpoint for that server is dead,
562                  but continue using the same JID.  For example, a user  could
563                  configure  the  server “<freenode@biboumi.example.com>”, set
564                  “chat.freenode.net” in its “Address” field,  and  then  they
565                  would be able to use “freenode” as the network name forever:
566                  if “chat.freenode.net” breaks for some  reason,  it  can  be
567                  changed  to  “irc.freenode.org”  instead, and the user would
568                  not need to change all their bookmarks and settings.
569
570                · Realname: The customized “real name” as it  will  appear  on
571                  the  user's  whois.  This option is not available if biboumi
572                  is configured with realname_customization to false.
573
574                · Username: The “user” part in your user@host.  This option is
575                  not  available  if  biboumi is configured with realname_cus‐
576                  tomization to false.
577
578                · In encoding: The incoming encoding.   Any  received  message
579                  that is not proper UTF-8 will be converted will be converted
580                  from the configured In encoding into UTF-8.  If the  conver‐
581                  sion  fails  at some point, some characters will be replaced
582                  by the placeholders.
583
584                · Out encoding: Currently ignored.
585
586                · After-connection IRC commands: Raw IRC commands that will be
587                  sent  one by one to the server immediately after the connec‐
588                  tion has been successful.  It can for  example  be  used  to
589                  identify  yourself using NickServ, with a command like this:
590                  PRIVMSG NickServ :identify PASSWORD.
591
592                · Ports: The list of TCP ports to use when connecting to  this
593                  IRC  server.  This list will be tried in sequence, until the
594                  connection succeeds for one of them.  The connection made on
595                  these  ports will not use TLS, the communication will be in‐
596                  secure.  The default list contains 6697 and 6670.
597
598                · TLS ports: A second list of ports to try when connecting  to
599                  the  IRC  server.   The  only difference is that TLS will be
600                  used if the connection is established on one of these ports.
601                  All  the  ports  in this list will be tried before using the
602                  other  plain-text  ports  list.   To  entirely  disable  any
603                  non-TLS  connection,  just  remove  all  the values from the
604                  “normal” ports list.  The default list contains 6697.
605
606                · Verify certificate: If set to true (the default value), when
607                  connecting  on a TLS port, the connection will be aborted if
608                  the certificate is not valid (for example if it's not signed
609                  by  a  known authority, or if the domain name doesn't match,
610                  etc).  Set it to false if you want to connect  on  a  server
611                  with a self-signed certificate.
612
613                · SHA-1  fingerprint  of  the TLS certificate to trust: if you
614                  know the hash of the certificate that the server is supposed
615                  to  use, and you only want to accept this one, set its SHA-1
616                  hash in this field.
617
618                · Nickname: A nickname that will be used instead of the  nick‐
619                  name  provided  in the initial presence sent to join a chan‐
620                  nel.  This can be used if the user always wants to have  the
621                  same nickname on a given server, and not have to bother with
622                  setting that nick in all the bookmarks on that server.   The
623                  nickname  can still manually be changed with a standard nick
624                  change presence.
625
626                · Server password: A password that will be sent just after the
627                  connection, in a PASS command.  This is usually used in pri‐
628                  vate servers, where you're only allowed to  connect  if  you
629                  have  the password.  Note that, although this is NOT a pass‐
630                  word that will be sent to NickServ (or some author authenti‐
631                  cation service), some server (notably Freenode) use it as if
632                  it was sent to NickServ to identify your nickname.
633
634       · get-irc-connection-info: Returns some information about the IRC serv‐
635         er,  for  the executing user.  It lets the user know if they are con‐
636         nected to this server, from what port, with or without  TLS,  and  it
637         gives  the  list of joined IRC channel, with a detailed list of which
638         resource is in which channel.
639
640   On a channel JID (e.g on the JID
641       #test%chat.<freenode.org@biboumi.example.com>)
642
643       · configure: Lets each user configure some options that applies to  the
644         concerned  IRC channel.  Some of these options, if not configured for
645         a specific channel, defaults to the value configured at the IRC serv‐
646         er  level.   For  example  the encoding can be specified for both the
647         channel and the server.  If an encoding is not specified for a  chan‐
648         nel,  the  encoding  configured  in the server applies.  The provided
649         configuration form contains these fields: * In encoding: see the  op‐
650         tion  with the same name in the server configuration form.  * Out en‐
651         coding: Currently ignored.  * Persistent: If  set  to  true,  biboumi
652         will  stay in this channel even when all the XMPP resources have left
653         the room.  I.e.  it will not send a PART command, and will stay  idle
654         in  the  channel  until  the connection is forcibly closed.  If a re‐
655         source comes back in the room again, and if the archiving of messages
656         is  enabled  for this room, the client will receive the messages that
657         where sent in this channel.  This option can be used to make  biboumi
658         act as an IRC bouncer.  * Record History: whether or not history mes‐
659         sages should be saved in the database, for this specific channel.  If
660         the value is “unset” (the default), then the value configured global‐
661         ly is used.  This option is there, for example, to be able to  enable
662         history  recording  globally  while  disabling  it for a few specific
663         “private” channels.
664
665   Raw IRC messages
666       Biboumi tries to support as many IRC features as possible, but  doesn't
667       handle everything yet (or ever).  In order to let the user send any ar‐
668       bitrary IRC message, biboumi forwards any XMPP message received  on  an
669       IRC Server JID (see Addressing) as a raw command to that IRC server.
670
671       For example, to WHOIS the user Foo on the server irc.example.com, a us‐
672       er can send the message “WHOIS  Foo”  to  irc.example.com@biboumi.exam‐
673       ple.com.
674
675       The  message  will  be forwarded as is, without any modification appart
676       from adding \r\n at the end (to make it a valid IRC message).  You need
677       to  have  a little bit of understanding of the IRC protocol to use this
678       feature.
679

Security

681       The connection to the XMPP server can only be made on  localhost.   The
682       XMPP server is not supposed to accept non-local connections from compo‐
683       nents.  Thus, encryption is not used to connect to the local XMPP serv‐
684       er because it is useless.
685
686       If  compiled  with the Botan library, biboumi can use TLS when communi‐
687       cating with the IRC servers.  It will first try ports 6697 and 6670 and
688       use  TLS  if  it succeeds, if connection fails on both these ports, the
689       connection is established on port 6667 without any encryption.
690
691       Biboumi does not check if the received JIDs are properly formatted  us‐
692       ing nodeprep.  This must be done by the XMPP server to which biboumi is
693       directly connected.
694
695       Note if you use a biboumi that you have no control  on:  remember  that
696       the  administrator  of the gateway you use is able to view all your IRC
697       conversations, whether you're using encryption or not.  This is exactly
698       as  if you were running your IRC client on someone else's server.  Only
699       use biboumi if you trust its administrator (or, better, if you are  the
700       administrator) or if you don't intend to have any private conversation.
701
702       Biboumi  does not provide a way to ban users from connecting to it, has
703       no protection against flood or any sort of abuse that  your  users  may
704       cause on the IRC servers.  Some XMPP server however offer the possibil‐
705       ity to restrict what JID can access a gateway.  Use that feature if you
706       wish to grant access to your biboumi instance only to a list of trusted
707       users.
708
709
710
711User Manual                       2019-04-22                        Biboumi(1)
Impressum