biboumi - biboumi Documentation
biboumi [
config_filename]
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.
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.
Configuration happens in different places, with different purposes:
- •
- The main and global configuration that specifies vital
settings for the daemon to run, like the hostname, password etc. This is
an admin-only configuration, and this is described in the next
section.
- •
- A TLS configuration, also admin-only, that can be either
global or per-domain. See TLS configuration section.
- •
- Using the Ad-hoc commands, each user can configure
various settings for themself
The configuration file is read by biboumi as it starts. The path is specified as
the only argument to the biboumi binary.
The configuration file uses a simple format of the form
option=value
(note that there are no spaces before or after the equal sign).
The values from the configuration file can be overridden by environment
variables, with the name all in upper case and prefixed with
BIBOUMI_.
For example, if the environment contains “BIBOUMI_PASSWORD=blah",
this will override the value of the “password” option in the
configuration file.
Sending SIGUSR1, SIGUSR2 or SIGHUP (see
kill(1)) to the process will force it to
re-read the configuration and make it close and re-open the log files. You can
use this to change any configuration option at runtime, or do a log rotation.
A configuration file can look something like this:
hostname=biboumi.example.com
password=mypassword
xmpp_server_ip=127.0.0.1
port=5347
[email protected]
db_name=postgresql://biboumi:password@localhost/biboumi
realname_customization=true
realname_from_jid=false
log_file=
ca_file=
outgoing_bind=192.168.0.12
Here is a description of all available options
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
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.
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.
The TCP port to use to connect to the local XMPP component. The default value is
5347.
The name of the database to use. This option can only be used if biboumi has
been compiled with a database support (Sqlite3 and/or PostgreSQL). If the
value begins with the postgresql scheme, “postgresql://” or
“postgres://”, then biboumi will try to connect to the
PostgreSQL database specified by the URI. See
the PostgreSQL doc for
all possible values. For example the value could be
“postgresql://user:secret@localhost”. If the value does not
start with the postgresql scheme, then it specifies a filename that will be
opened with Sqlite3. For example the value could be
“/var/lib/biboumi/biboumi.sqlite”.
The bare JID of the gateway administrator. This JID will have more privileges
than other standard users, for example some administration ad-hoc commands
will only be available to that JID.
If you need more than one administrator, separate them with a colon (:).
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
#[email protected] must be used
instead of
#chan%[email protected]. The
%
character loses any meaning in the JIDs. It can appear in the JID but will not
be interpreted as a separator (thus the JID
#channel%[email protected] 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.
If this option is set to
true, all rooms will be persistent by default:
the value of the “persistent” option in the global configuration
of each user will be “true”, but the value of each individual
room will still default to false. This means that a user just needs to change
the global “persistent” configuration option to false in order
to override this.
If it is set to false (the default value), all rooms are not persistent by
default.
Each room can be configured individually by each user, to override this default
value. See
Ad-hoc commands.
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.
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.
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.
A filename into which logs are written. If none is provided, the logs are
written on standard output.
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.
Specifies which file should be used 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.
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 TCP port on which to listen for identd queries. The default is the standard
value: 113. To be able to listen on this privileged port, biboumi needs to
have certain capabilities: on linux, using systemd, this can be achieved by
adding
AmbientCapabilities=CAP_NET_BIND_SERVICE to the unit file. On
other systems, other solutions exist, like the portacl module on FreeBSD.
If biboumi’s identd server is properly started, it will receive queries
from the IRC servers asking for the “identity” of each IRC
connection made to it. Biboumi will answer with a hash of the JID that made
the connection. This is useful for the IRC server to be able to distinguish
the different users, and be able to deal with the absuses without having to
simply ban the IP. Without this identd server, moderation is a lot harder,
because all the different users of a single biboumi instance all share the
same IP, and they can’t be distinguished by the IRC servers.
To disable the built-in identd, you may set identd_port to 0.
A directory that should contain the policy files, used to customize
Botan’s behaviour when negociating the TLS connections with the IRC
servers. If not specified, the directory is the one where biboumi’s
configuration file is located: for example if biboumi reads its configuration
from /etc/biboumi/biboumi.cfg, the policy_directory value will be
/etc/biboumi.
Various settings of the TLS connections can be customized using policy files.
The files should be located in the directory specified by the configuration
option
policy_directory. When attempting to connect to an IRC server
using TLS, biboumi will use Botan’s default TLS policy, and then will
try to load some policy files to override the values found in these files. For
example, if policy_directory is /etc/biboumi, when trying to connect to
irc.example.com, biboumi will try to read /etc/biboumi/policy.txt, use the
values found to override the default values, then it will try to read
/etc/biboumi/irc.example.com.policy.txt and re-override the policy with the
values found in this file.
The policy.txt file applies to all the connections, and irc.example.policy.txt
will only apply (in addition to policy.txt) when connecting to that specific
server.
To see the list of possible options to configure, refer to
Botan’s
TLS documentation. In addition to these Botan options, biboumi
implements a few custom options listed hereafter: - verify_certificate: if
this value is set to false, biboumi will not check the certificate validity at
all. The default value is true.
By default, biboumi provides a few policy files, to work around some issues
found with a few well-known IRC servers.
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 servers. 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.
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.
Florent Le Coz
2022, Florent Le Coz