diff options
Diffstat (limited to 'doc/admin.rst')
| -rw-r--r-- | doc/admin.rst | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/doc/admin.rst b/doc/admin.rst new file mode 100644 index 0000000..a5850a7 --- /dev/null +++ b/doc/admin.rst @@ -0,0 +1,305 @@ +########################### +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 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 :ref:`Ad-hoc commands`. + +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 +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. + +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 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. + + +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. + + + |