biboumi/doc/admin.rst

###########################
Administrator documentation
###########################

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 :ref:`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
=============

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 :ref:`ad-hoc commands`, each user can configure various
  settings for themself

Daemon configuration
--------------------

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.

Options
-------

A configuration file can look something like this:

.. code-block:: ini

  hostname=biboumi.example.com
  password=mypassword
  xmpp_server_ip=127.0.0.1
  port=5347
  admin=myself@example.com
  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

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.

db_name
~~~~~~~

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
<https://www.postgresql.org/docs/current/static/libpq-connect.html#idm46428693970032>`_
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”.

admin
~~~~~

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 (:).

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``. 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%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.

persistent_by_default
~~~~~~~~~~~~~~~~~~~~~

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 their global
“persistent” configuration option to "false" in order to override this
and be able to set rooms to not persistent.

If this option is set to "false" (the default value), all rooms are not persistent by
default.

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 used as the list of trusted CA when
negotiating 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.

identd_port
~~~~~~~~~~~

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.

policy_directory
~~~~~~~~~~~~~~~~

A directory that should contain the policy files, used to customize
Botan’s behaviour when negotiating 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.

persist_user_denylist
~~~~~~~~~~~~~~~~~~~~~

A list of XMPP users or domains who are not allowed to change the `persist`
ad-hoc option and who will not be impacted by the `persistent_by_default`
config option. Specific JIDs in this list will take priority over allowed JIDs
or domains.

persist_user_allowlist
~~~~~~~~~~~~~~~~~~~~~~

A list of XMPP XMPP users or domains who are allowed to change the `persist`
ad-hoc option.

default_persistence_allowed
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If a given XMPP user or domain is not in either denylist or allowlist this
option decides if the user is allowed to persist or not.

archive_expires_after
~~~~~~~~~~~~~~~~~~~~~

Messages in the archive can expire after some time, by default never. This
can be changed by this setting

.. code-block:: ini

  # one day
  archive_expires_after=1d
  # one week
  archive_expires_after=1w
  # two months
  archive_expires_after=2m
  # one year
  archive_expires_after=1y
  # 1h
  archive_expires_after=1h
  # keep messages forever, the default
  archive_expires_after=0

sqlite_journal_mode
~~~~~~~~~~~~~~~~~~~

Set the `journal_mode https://sqlite.org/pragma.html#pragma_journal_mode`_ to
be used when connecting to an SQLite database. This option can be one of
`DELETE`, `TRUNCATE`, `PERSIST`, `MEMORY`, `WAL`, `OFF`, or `none` to not set
the journal_mode at all.

By default this option is set to `WAL` to use `Write-Ahead Logging
https://sqlite.org/wal.html`_.

TLS configuration
-----------------

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 <https://botan.randombit.net/manual/tls.html#tls-policies>`_.
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.


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 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.