BIBOUMI(1)

💖 BIBOUMI(1) 💖

okay bestie, sit down, hydrate, because this is the biboumi manual page and it's a whole journey. this is section 1 of biboumi, lowercase, all cute — and no, i'm not gatekeeping a single flag from you. let's go 🦋

---

✨ NAME ✨

biboumi — biboumi Documentation 💅

(yeah that's literally it, the name section is serving minimalist today)

🌸 SYNOPSIS 🌸

biboumi [-ht] [config_filename]

🎀 COMMAND-LINE OPTIONS 🎀

• -h, --help — prints a help message and dips, exit stage left. that's it, that's the flag 🙈
• -t, --test-config — doesn't actually run anything, it just vibe-checks your configuration file syntax. config valid? exit status is 0, slay. config busted? exit status is non-zero, and honestly, valid of it to tell you 💀

---

👑 ADMINISTRATOR DOCUMENTATION 👑

💜 Usage 💜

so biboumi is a server, right? it's meant to be run as a daemon — a little background gremlin that just lives there, chilling, for as long as you need it. important: biboumi does not daemonize itself. that task is on your init system (SysVinit, systemd, upstart) — it's giving delegated responsibility, and honestly, iconic.

when it starts up, biboumi connects without encryption (see Security, bestie, don't skip that) to the local XMPP server on port 5347 and authenticates with the password you provided. then it serves the configured hostname. what that means in practice: every XMPP stanza with a to JID on that domain gets forwarded to biboumi by the XMPP server, and biboumi will only send messages coming from that hostname. closed loop, no drama 💅

to shut it down cleanly, send a SIGINT or SIGTERM signal to it. it'll send messages to all connected IRC and XMPP servers explaining why the users are getting disconnected (so thoughtful 🫶). biboumi exits when the end of communication is acknowledged by all IRC servers. but if one or more IRC servers just... don't respond? it'll only exit if it receives the same signal again, or if a 2 seconds delay has passed. so yes, you can double-tap the signal. noted 📝

🦋 Configuration 🦋

config happens in different places, for different purposes, and you will keep them straight:

• 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 it's described in the next section.
• A TLS configuration, also admin-only, that can be either global or per-domain. See the TLS configuration section.
• Using the Ad-hoc commands (#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 config file uses a simple format of the form option=value — and note that there are no spaces before or after the equal sign. none. zero. don't do it 🚫

the values from the config 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 config file. sneaky. powerful. lowkey hot 🔥

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. so you can use this to change any configuration option at runtime, or do a log rotation. main character energy, truly 👑

✨ Options ✨

a configuration file can look something like this:

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

and here is a description of all available options, no skips, no shortcuts 💖

⭐ 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 info. for prosody, see <https://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. yes, both sides need it. yes, they have to match. that's the whole bit 🎀

⭐ 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. localhost bestie behavior 💜

⭐ 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 database support (Sqlite3 and/or PostgreSQL) — no database support, no db_name, sorry bb 😭

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. pick your fighter 🥊

⭐ 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. VIP section, no cap 👑

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. locked down, but make it cute 🔒

⭐ 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. plain and simple ✨

⭐ 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. taking away the customization ✂️

⭐ 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. extra work, extra lookup, you've been warned 📡

⭐ log_file ⭐

a filename into which logs are written. if none is provided, the logs are written on standard output. keep it in the terminal if you're nosy, keep it in a file if you're organized 💅

⭐ 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. yes bestie, debug by default, and yes, 1 is the move for prod 🌈

⭐ 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. so you can leave it and let biboumi do the searching 🧚

⭐ 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. IRC only. got it? 🫡

⭐ 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 abuses 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. scary stuff ngl 😭

to disable the built-in identd, you may set identd_port to 0. bye bye identd 👋

⭐ 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. it just follows the config home 🏠

⭐ 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. priority order matters, remember it ⚠️

⭐ persist_user_allowlist ⭐

a list of XMPP XMPP users or domains who are allowed to change the persist ad-hoc option. (yes, it says "XMPP XMPP", i'm just relaying the lore 💀)

⭐ 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. the tiebreaker option 🎯

⭐ archive_expires_after ⭐

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

# 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

so 1d, 1w, 2m, 1y, 1h, or 0 for forever. the 0 is the default and honestly it's giving "i never delete anything" and i respect it 💖

🎀 TLS configuration 🎀

okay so bestie, here's the tea on TLS: you can customize literally ALL the settings for your TLS connections using something called policy files 💅. These files live in whatever directory the config option policy_directory points at.

So when biboumi goes to connect to an IRC server using TLS, here's the little ritual it does 🧚:

1. It starts with Botan's default TLS policy.
2. Then it tries to load some policy files to override the values it found.

For example, if policy_directory is /etc/biboumi, and biboumi is trying to connect to irc.example.com, it will:

• try to read /etc/biboumi/policy.txt, and use whatever values it finds in there to override the defaults ✨
• then try to read /etc/biboumi/irc.example.com.policy.txt and re-override the policy with the values from that file 👑

The way these two play together:

• policy.txt applies to all the connections, no exceptions 🫶
• irc.example.policy.txt only applies when connecting to that specific server — and it stacks on top of policy.txt, not instead of it 💜

Wanna see the full list of options you can configure? Go check out Botan's TLS documentation at https://botan.randombit.net/manual/tls.html#tls-policies. 🌈

On top of all those Botan options, biboumi also implements a few custom ones of its own, listed right here:

• verify_certificate — if you set this to false, biboumi will not check the certificate validity at all 😭 (yes, like, zero checks). The default value is true.

And btw, biboumi ships with a few policy files out of the box by default, to work around some issues found with a few well-known IRC servers 🔥

---

🔒 Security 🔒

Some important facts, no cap:

• The connection to the XMPP server can only be made on localhost. The XMPP server isn't supposed to accept non-local connections from components. So encryption is not used to connect to the local XMPP server, because honestly it would be useless 💀
• If it's compiled with the Botan library, biboumi can use TLS when talking to IRC servers. It will first try ports 6697 and 6670 and use TLS if it succeeds. If the connection fails on both of those ports, the connection gets established on port 6667 with no encryption at all 🙈
• Biboumi does not check if the received JIDs are properly formatted using nodeprep. That's a job that must be done by the XMPP server biboumi is directly connected to 👀
• Biboumi does not provide any way to ban users from connecting to it, and it has no protection against flood or any sort of abuse that your users may cause on the IRC servers. Some XMPP servers do offer the possibility to restrict what JID can access a gateway though, so use that feature if you want to grant access to your biboumi instance only to a list of trusted users 🫶

---

👑 Author

Florent Le Coz

©️ Copyright

2018, Florent Le Coz

---

and that's the whole page, bestie 💖✨ that was version 10.0, dated Jun 12, 2026, filed under BIBOUMI(1) — you ate the whole manual, fr fr, so proud of you 🥹💅🎀