Your IRC, always connected.

#What xBNC is

xBNC is an IRC bouncer: a program that stays connected to your IRC networks around the clock, even when you close your client or switch off your computer. When you come back, it gives you what you missed, exactly once on each device.

You install it on a server of your own (a VPS, a Raspberry Pi, a computer at home), use it with your usual IRC client and configure everything from a web panel, or from IRC with /msg *status. It is a single program written in Rust, with the panel built in.

What it includes

• Bouncer: permanent connections to several networks per user, with verified TLS, SASL PLAIN and EXTERNAL, automatic reconnection with growing delays and flood protection towards the server.
• Several devices at once: what you write on one appears on the others, and each one keeps its own account of what it has read.
• History: channels and private messages with full-text search, filters, TXT and JSON export, general and per-channel retention, and per-user quotas.
• Full IRCv3 with servers and clients (complete list); classic clients see plain old IRC.
• Web chat in the panel, a mentions view and read markers shared between devices.
• Notifications of mentions and private messages by Telegram, Discord, e-mail, a web address of your own or browser and phone push notifications.
• 24 modules (services login, automatic away, auto op, FiSH encryption, detached channels, scheduled tasks…) and 18 plugins already installed (trivia, polls, reminders, weather…).
• Multi-user: five roles, quotas, suspension, audit log, two-step verification, passkeys, OpenID Connect and LDAP.
• Data: SQLite or PostgreSQL, active/standby high availability, backups from the panel or the command line, migration from another bouncer.
• Administration: web panel, REST API with tokens, WebSocket, Prometheus metrics with a Grafana dashboard, alerts in the panel, over IRC and by webhook.
• Security: Argon2id, encrypted credentials, brute-force blocking, CSRF, CSP, an unprivileged service, sandboxed plugins and continuous fuzzing.

#How it works

Your IRC client no longer connects to the network but to xBNC. xBNC keeps one connection per network that is not cut when you close the client, and presents itself to each device as if it were that network's server.

1. You connect with the server password user/network@device:password. The device name (@laptop, @phone) is optional, but it lets each device keep its own account of what it has read.
2. xBNC brings you up to date: it joins your channels for you, sends the topic and the user list, and plays back the messages that arrived since your last connection on that device, without repeating what you already saw.
3. While you are away, xBNC stays in the channels, stores the history, answers CTCP, marks you as away and runs your modules and plugins.
4. All your devices stay in sync: what you write on the phone appears on the laptop, and read markers are shared.

What you get when you connect

1. xBNC's welcome with the parameters (ISUPPORT) of the real network.
2. The network's MOTD (unless you turn on Hide the MOTD), followed by xBNC's name and version.
3. The channels you are in, with their topic and user list.
4. The messages this device has not seen. If the client does not support server-time, each message starts with the date and time in brackets.
5. If you missed private messages or mentions, a summary from *status (module Automatic away).
6. If the network is disconnected, a notice from *status with the reason.
7. This server's message of the day, if a superadministrator has set one (/msg *status setmotd).

History without duplicates

• Each device (the @name of the login, or default if you give none) has a cursor per network: the last message delivered to it. Two connections with the same name share the cursor.
• When it connects it receives the messages after its cursor, up to playback_max (1000 by default). A new device receives the most recent new_client_playback messages (100 by default).
• Cursors are saved on disconnection and every 5 seconds, and never go backwards. If the process stops abruptly, at most a few seconds are repeated.
• Clients with draft/chathistory get no automatic playback: they ask for what they need with CHATHISTORY (up to chathistory_max, 500 by default).

The connection to each network

• States: disconnected, registering and connected. During registration the IRCv3 capabilities, SASL and the nick (with an alternative if it is taken) are negotiated.
• Maximum registration time: 60 seconds. If the server is silent for 90 seconds it is sent a PING, and after 180 the connection is considered lost.
• Automatic reconnection with delays growing from 5 seconds to 5 minutes, with a random ±20 % variation so that thousands of networks do not come back in the same second. If the network says you are reconnecting too fast, xBNC waits at least 2 minutes.
• Output to the server goes through a rate limiter (a burst of 9 lines, then 2 per second) so the network does not throw you out for flooding.
• The server's TLS certificate is always verified against the system's root certificates. For a network with its own or an expired certificate you can trust that particular certificate by its SHA-256 fingerprint (/msg *status addfingerprint); there is no option to turn verification off.
• Each network can have backup servers (/msg *status addserver). If connecting to a server fails, xBNC tries the next one a second later; after going through the whole list it goes back to the growing delays. If a server that was connected drops the connection, xBNC first goes back to that same server.
• The local address used to connect (vhost) can be set per network or per user (/msg *status setbindhost, administrators only).
• If a line is not UTF-8 it is read as Windows-1252, so accented letters from old clients show correctly.

Virtual users

xBNC adds “users” whose names start with *. They do not exist on the network: they are the way to talk to xBNC from any client. *status, *notes, *watch, *crypt, *ignore and one per plugin (*trivia, *remind…). See IRC commands.

#Installation

Requirements

• Linux with systemd: Debian 12, Ubuntu 22.04 or later, Fedora, Rocky or Alma.
• Rust 1.89 or later (rustup.rs) and a C compiler: sudo apt install build-essential or sudo dnf install gcc.
• 1 CPU and 512 MB of RAM for personal use. Measured: 2,000 users with their networks and clients in about 150 MB (see Performance).
• Ports: 6697 (IRC with TLS), 6667 (IRC without TLS, local network only), 8443 (panel). With Let's Encrypt, also 80; with Nginx, 443.

The web panel comes already built inside the source code: Node.js and npm are not needed.

Install

# 1. Install Rust (once, as a normal user)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. Build xBNC (as a normal user)
unzip xbnc-1.0.0.zip && cd xbnc
cargo build --release

# 3. Install the service
sudo ./scripts/install.sh

Run in a terminal without options, the installer asks whether you want to use a domain, the e-mail address for Let's Encrypt and whether you want the panel at https://yourdomain with Nginx. At the end it shows the panel address and the one-time code to create your account:

  Panel:   https://bnc.example.org:8443
  IRC:     bnc.example.org, port 6697 (SSL)
  Code to create your account:  K7QM-2XPA-9DWE

Open the panel, enter the code and create the first administrator (it will be a superadministrator). To see the address and ports again: sudo xbncd info; to see the code again: sudo xbncd setup-code.

What the installer does

1. Checks the system, the built binary and, if you use a domain, that its DNS points to this machine and which ports you must open on your router.
2. Creates the unprivileged system user xbnc and the folders with their permissions.
3. Installs the binary in /usr/local/bin/xbncd and the systemd service with isolation measures (ProtectSystem=strict, NoNewPrivileges, no capabilities, a system call filter).
4. Creates the certificate: self-signed for the IP (or the domain), or from Let's Encrypt with automatic renewal. Renewal reloads xBNC (and Nginx, if used).
5. Writes /etc/xbnc/xbnc.toml with the version in its header, and creates the database and the secret key.
6. With --nginx, installs and configures Nginx: redirection from port 80, the panel on 443, WebSockets and uploads of plugins and backups.
7. Opens the ports in ufw or firewalld and starts the service.

Installer options

Examples

# By IP, with a self-signed certificate
sudo ./scripts/install.sh

# With a domain and Let's Encrypt, panel at https://bnc.example.org:8443
sudo ./scripts/install.sh --domain bnc.example.org --letsencrypt you@example.org

# The same, with the panel at https://bnc.example.org behind Nginx
sudo ./scripts/install.sh --domain bnc.example.org --letsencrypt you@example.org --nginx

# Move an existing installation to a domain
sudo ./scripts/install.sh --reconfigure --domain bnc.example.org --letsencrypt you@example.org

# Change the detected IP
sudo ./scripts/install.sh --reconfigure --ip 192.168.1.50

Where everything goes

The service runs as the unprivileged user xbnc. sudo systemctl status xbnc, sudo systemctl restart xbnc; sudo systemctl reload xbnc makes it re-read networks, channels and users changed from the command line, and the language files. The log: sudo journalctl -u xbnc -f.

Using it away from home

• Forward port 6697 on your router to the xBNC machine and connect to your public IP or to a dynamic DNS name (DuckDNS and the like). Port 6667 need not be opened: xBNC refuses it from outside.
• If you do not want to open the panel (8443) to the internet, manage it through an SSH tunnel: ssh -L 8443:127.0.0.1:8443 user@your-public-ip and open https://localhost:8443.
• With a domain pointing to your home, reinstall with --reconfigure --domain … --letsencrypt … to get rid of the certificate warnings.

Panel behind your own Nginx

If you already run Nginx and prefer to configure it yourself, install with --domain bnc.example.org --behind-proxy and use the included example:

sudo apt install -y nginx
echo 'map $http_upgrade $connection_upgrade { default upgrade; "" close; }' | sudo tee /etc/nginx/conf.d/upgrade.conf
sudo cp packaging/nginx/xbnc.conf /etc/nginx/sites-available/xbnc   # change server_name and certificates
sudo ln -s ../sites-available/xbnc /etc/nginx/sites-enabled/xbnc
sudo nginx -t && sudo systemctl reload nginx

Contents of packaging/nginx/xbnc.conf:

# Nginx reverse proxy for the xBNC web panel.
# Copy to /etc/nginx/sites-available/xbnc, adjust server_name and the
# certificate paths, then: ln -s ../sites-available/xbnc /etc/nginx/sites-enabled/
# In xbnc.toml: [web] address = "127.0.0.1:8080", public_url = "https://bnc.example.org",
# secure_cookies = true, trust_proxy = true.

server {
    listen 80;
    listen [::]:80;
    server_name bnc.example.org;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name bnc.example.org;

    ssl_certificate     /etc/letsencrypt/live/bnc.example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/bnc.example.org/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    # Plugins are up to 4 MB.
    client_max_body_size 8m;

    # Restoring a backup uploads the whole archive.
    location = /api/v1/backups/restore {
        client_max_body_size 4g;
        proxy_request_buffering off;
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        # WebSockets: live dashboard, web chat, plugin log
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 3600s;
    }
}

# Needed once per Nginx configuration (e.g. in /etc/nginx/conf.d/upgrade.conf):
# map $http_upgrade $connection_upgrade { default upgrade; '' close; }

In xbnc.toml, with the panel behind Nginx: address = "127.0.0.1:8080", public_url = "https://bnc.example.org", secure_cookies = true and trust_proxy = true.

Certificate from another authority

Copy your certificate and key to /etc/xbnc/tls/fullchain.pem and /etc/xbnc/tls/privkey.pem (owner root:xbnc, the key with permissions 0640) and restart with sudo systemctl restart xbnc. The certificate is read at start; reload is not enough.

Docker

mkdir -p tls
cp /path/fullchain.pem /path/privkey.pem tls/
# Edit XBNC_HOSTNAME and XBNC_PUBLIC_URL in docker-compose.yml
docker compose up -d --build
docker compose logs xbnc | grep "setup code"

Open https://bnc.example.org:8443/, enter the code and create your account. The command line: docker compose exec xbnc xbncd user add admin --admin. The data lives in the xbnc-data volume. The container runs as the unprivileged user xbnc (uid 10001), with a read-only file system, no capabilities and no-new-privileges.

Updating

unzip xbnc-new.zip && cd xbnc     # or git pull
cargo build --release
sudo ./scripts/update.sh

update.sh checks the new binary and the configuration, makes a backup, stops the service, swaps the binary and starts it. If it does not start, it goes back to the previous binary and to the database from before the update (a new binary may have upgraded the schema, and an old one refuses to open a newer schema). Nothing is ever updated on its own. With --binary PATH it installs another binary.

If you also want to redo the configuration (for example, to move to a domain), run sudo ./scripts/install.sh --reconfigure afterwards.

Uninstalling

sudo ./scripts/uninstall.sh            # removes the service and the binary; keeps /etc/xbnc and /var/lib/xbnc
sudo ./scripts/uninstall.sh --purge    # also deletes the configuration, the data and the xbnc user

#First steps

1. Create your account in the panel with the one-time code. The first account is a superadministrator.
2. Add a network in Networks → Add network. The wizard has four steps: choose the network (the well-known ones come ready), your nick and name, the identification (SASL, X, Q…) and the channels.
3. Connect your client. The network page has the card “Connect your IRC client” with your exact details and the steps for HexChat, mIRC, WeeChat and irssi, with buttons to copy them.
4. Turn on modules and plugins in Modules. Choose the network at the top; with many networks, “Copy to other networks” repeats the configuration.
5. Choose your time zone and language in Your account: the time zone is used in the log files and in scheduled tasks.
6. Turn on two-step verification and, if you like, a passkey, in Your account.

Networks ready in the wizard

The same from the command line

sudo -u xbnc xbncd user add admin --admin
sudo -u xbnc xbncd network add admin libera --host irc.libera.chat --port 6697 --sasl-user myaccount
sudo -u xbnc xbncd channel add admin libera '#xbnc'
sudo systemctl reload xbnc

The SASL password is asked for at that moment (or read from XBNC_SASL_PASSWORD) and stored encrypted.

#Connecting your IRC client

Any client that lets you set the server, port and server password works. No plugin is needed.

• Server: your domain or IP (sudo xbncd info shows it).
• Port: 6697 with SSL from anywhere; 6667 without SSL only from your local network.
• Password: the same one you use for the panel. You can also put alice/undernet@laptop in the user field (USER) and the password alone in PASS, or sign in with SASL PLAIN from the client.
• One connection is one network: for two networks, create two servers in your client (alice/undernet and alice/libera). Clients with soju.im/bouncer-networks (Goguma, gamja, Halloy) see all your networks in a single connection.
• Device: the @device part is optional but recommended. Each device (@laptop, @phone, @work) gets its own pending history.
• If you installed by IP, the certificate is self-signed: turn on “accept invalid certificates” in your client.

Network List → Add: "xBNC Undernet"
Edit → Server: bnc.example.org/6697
Tick "Use SSL for all the servers on this network"
Login method: Server password (/PASS password)
Password: alice/undernet@hexchat:your-password
With a self-signed certificate: tick "Accept invalid SSL certificates"

The quickest way, in any window:
/server bnc.example.org +6697 alice/undernet@mirc:your-password

The + before the port turns on SSL. With a self-signed certificate, mIRC asks
the first time: click Accept. To save it: File → Select server → Add, with
the same details.

/server add xbnc-undernet bnc.example.org/6697 -tls
/set irc.server.xbnc-undernet.password "alice/undernet@weechat:your-password"
/set irc.server.xbnc-undernet.capabilities "server-time,message-tags,batch,draft/chathistory,echo-message"
/connect xbnc-undernet

With a self-signed certificate: /set irc.server.xbnc-undernet.tls_verify off

/network add -nick alice xbnc-undernet
/server add -tls -network xbnc-undernet -password alice/undernet@irssi:your-password bnc.example.org 6697
/connect xbnc-undernet

With a self-signed certificate, add -notls_verify to /server add

If you get the port or SSL wrong

xBNC spots the usual mistakes and tells you in the client itself:

When the client connects with SSL to a port without SSL it cannot show any message: the service log says so (client sent TLS to a plain-text port).

Networks without SASL (Undernet, QuakeNet)

Some networks do not use SASL: you log in with a services bot, X on Undernet or Q on QuakeNet. xBNC does it for you every time it connects. Turn on the Services login module (in the wizard, the Account step) with your account and password. If you prefer to do it by hand, write the commands in Settings → Commands on connect, one per line, as in your client:

/mode $nick +x
/msg x@channels.undernet.org login YOUR_ACCOUNT YOUR_PASSWORD

They are sent before joining channels, so your IP is already hidden (+x) when you join, and they are stored encrypted.

Client compatibility

The automatic tests use a standard IRC client, a client with every IRCv3 capability and a classic client without any. HexChat, mIRC, WeeChat and irssi have been used by hand with xBNC; the other clients in the list follow the same standards but have not been checked one by one. If something does not work with a particular client, report it with the client's name and version (see Testing the beta).

#Networks

Settings of a network

In the panel, Networks → (your network) → Configuration. Also with the API (PATCH /networks/{id}) or the command line.

Commands on connect

They are written as in your client, one per line (up to 20, of 510 characters each), and stored encrypted because they often contain passwords. $nick is replaced by your current nick. Allowed: /msg (or /privmsg, /query), /notice, /quote (or /raw) and any IRC command with a slash (/mode, /away…). A line without a slash is sent as it is.

/mode $nick +x
/msg x@channels.undernet.org login YOUR_USER YOUR_PASSWORD
AWAY :Connected from xBNC

To identify with X, NickServ, Q or AuthServ the Services login module is better: it waits for the network to confirm the login before joining the channels, and on Undernet it uses Login on Connect.

Undernet

Undernet uses the X service and has neither SASL nor TLS. Turn on Services login with your X account: with Login on Connect the account travels in the server password (+x! account password), so your real IP is never seen and you join the channels already as account.users.undernet.org.

• With Invite and unban, if you cannot join one of your channels, xBNC asks X for INVITE or UNBAN.
• Ignore uses SILENCE: messages from the people you ignore do not even reach xBNC.
• Nicks have at most 12 characters; the away nick is shortened automatically.
• Many Spanish-speaking channels use Latin-1: xBNC always understands it, and with Character encoding you can write to them in Latin-1.
• The connection to Undernet is unencrypted because the network offers no TLS; the X password travels in clear text to the server, as with any client.

Libera.Chat and freenode

Identification by SASL: put your account and password in the network configuration. On Libera you can also use a certificate (Client certificate) with SASL EXTERNAL: generate the certificate in the panel, connect identified, type /msg NickServ CERT ADD and reconnect. If your nick is taken when connecting, Services login with “Recover my nick” sends REGAIN (Libera) or GHOST (freenode).

Rizon

NickServ (Anope), by SASL or with Services login. ChanServ handles invitations and unbans.

EvilNet

X3 services: you identify with AuthServ (AUTH account password) and mode +x hides your host (numeric 396). Choose AuthServ in Services login, or “Automatic”.

QuakeNet

The Q service (AUTH to Q@CServe.quakenet.org) and +x. Services login does it for you; invite and unban use INVITE and UNBANME.

IRCnet and EFnet

They have no NickServ: anyone could take that nick. That is why, in “Automatic”, xBNC never sends your services password on these networks and says so in *status and in the log. IRCnet offers optional SASL with accounts from sasl.ircnet.com. To keep op without services, use Get op back when left alone.

OFTC and other networks with NickServ

Services login with NickServ, or commands on connect. For the client certificate, OFTC uses the SHA-1 fingerprint and Libera the SHA-512 one: the panel shows all three fingerprints (SHA-1, SHA-256 and SHA-512).

#IRC commands

You type them in your client as /msg *service command. The answers come in your language.

*status

It is the main service: everything you can do with a network in the panel can also be done here. /msg *status help lists the commands grouped and with their names in bold, only those your account may use; /msg *status help <command> explains one with an example, and /msg *status help <word> searches (for example help channel). Names are not case-sensitive, and the names used by other bouncers are accepted too (ListChans, ListMods, AddTrustedServerFingerprint…), listed under each command as “Also accepted”.

Unless stated otherwise, any account may use a command. The others say who may: accounts allowed to make changes (every role except “limited”), administrators (administrator and superadministrator) or superadministrators. Administrative actions are recorded in the audit log.

General

Networks and connection

Servers, certificates and addresses

Channels

History (buffers)

Modules and plugins

Administration

Notes on these commands

• Backup servers. If connecting to a server fails, xBNC tries the next one on the list a second later, and after going through the whole list it waits as usual again (5 s, 10 s, 20 s… up to 5 min). If a server that was connected drops the connection, xBNC first goes back to that same server. Passwords of backup servers are stored encrypted. jump alone moves to the next one; jump server or jump server:port, to a particular one.
• Trusted certificates. For networks with a self-signed or expired certificate, or one with another name. xBNC still checks everything else about TLS and accepts only that particular certificate (its SHA-256 fingerprint). To see a server's fingerprint: openssl s_client -connect irc.example.org:6697 </dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha256
• Local address (vhost). Administrators only, because it uses the server's IP addresses. xBNC checks that the address belongs to the machine before saving it. The network's address takes priority over the user's. It applies on the next connection.
• Disabled channels. They stay saved with their key and settings, but xBNC does not join them when connecting. The panel marks them as “Disabled”. enablechan joins them straight away.
• Channel order. It is the order in which xBNC joins when connecting and in which channels and the panel list them. New channels go at the end.
• Wildcards. enablechan, disablechan, attach, detach and clearbuffer accept several names separated by spaces or commas, and the wildcards * and ?: disablechan #xbnc* #xbnc-dev.
• Message of the day. A superadministrator sets it and every user receives it, as a notice from *status, each time a client connects. Up to 20 lines of 400 characters. Shown with showmotd.
• Notices to everyone. broadcast sends “[Administrator notice] text” to every running network; every connected client receives it. restart and shutdown with a message send it first.
• Restarting and stopping. restart restarts xBNC inside the same process (the networks reconnect). shutdown stops it completely and systemd does not start it again: it has to be started with sudo systemctl start xbnc.
• Ports and xbnc.toml. Ports and the rest of xbnc.toml are not changed from IRC: listports shows them and rehash re-reads users, networks, channels and languages (the same as sudo systemctl reload xbnc). saveconfig exists out of habit: xBNC saves every change at once.

*notes

They are the same notes as in Your account → Notes.

*watch

Matches of the Watch words module arrive here. /msg *watch help reminds you how to configure it.

*crypt

Type +p before a message to send it unencrypted. See Message encryption.

*ignore

One service per plugin

Each active plugin answers on *id (*trivia, *remind, *poll…). With help or any text it does not understand, it explains how it is used. If a plugin has nothing to say, xBNC answers with its name, version, description and usage.

Client commands

#Web panel

Live settings

What you change in Settings is stored in the database, applies without restarting and takes priority over xbnc.toml. The ↺ icon next to a field goes back to the value of xbnc.toml.

What is read at start (ports, certificates, database, secret key, the panel itself and the log level) is changed in xbnc.toml and needs sudo systemctl restart xbnc. The page says so. Superadministrators also have a button to restart the service.

Accessibility and use on the phone

• Keyboard navigation with visible focus; dialogs close with Escape.
• Respects the system's “reduce motion”.
• On narrow screens the side bar opens with the menu button.
• The theme (light, or dark in black, yellow and grey) follows the system the first time; the moon or sun button changes it and remembers it in that browser.
• It can be installed as an app (PWA) to get push notifications.
• In English and Spanish, and in any language installed as a translation file (see Translating xBNC). The language is changed on the sign-in page, in Your account or (the server default) in Settings, and applies at once to the panel and to xBNC's messages on IRC, also with the client connected. From IRC it is changed with /msg *status language en.

#History and search

xBNC stores the messages of channels and private conversations (and, with the Events module, joins, parts, kicks, nick changes, topics and modes). Each message carries the server's time if the network sends it.

Searching

In Networks → (network) → History, or with the API. The search uses a full-text index:

• It finds whole words and word beginnings: deplo finds “deployment”.
• It ignores case and accents: cafe finds “Café”.
• Several words must all appear, in any order. In quotes, the exact phrase is searched: "out of service".
• If nothing matches by word, it also looks for pieces in the middle of a word: ployment finds “deployment”.
• It combines with the conversation, sender and date filters.

Export and delete

It exports to TXT or JSON (everything, or one conversation). A conversation or the whole history of the network is deleted from the panel, with /msg *status clearbuffer (or clearallbuffers, clearallchannelbuffers, clearallquerybuffers) or with the API.

Retention and quotas

• General: Settings → History, days of retention (30 by default; 0, forever).
• Per channel: in the channels of each network, or with /msg *status setbuffer: the server setting, store nothing, forever or N days.
• Per user: an administrator can set a history space quota (max_history_mb) in Users; usage shows on each user's page.
• Space: about 150 bytes per stored message, including the search index.

Log files

Besides the history, the Log files module writes daily text files in the classic IRC format to /var/lib/xbnc/logs/user/network/#channel/YYYY-MM-DD.log, with times in your time zone.

#Notifications

In Your account → Notifications, xBNC tells you about mentions and private messages.

“Send a test notification” sends one to every configured channel. So as not to flood you, xBNC groups notifications: if many arrive in a row, those not sent are counted and the next notification says how many were skipped.

Format of the notification at your own web address

{
  "network": "undernet",
  "network_id": 1,
  "conversation": "#xbnc",
  "from": "bob",
  "text": "y2k, what time is the meeting tomorrow?",
  "private": false,
  "ts": 1762851240000,
  "skipped": 0
}

With push, tapping the notification opens the panel chat in that conversation.

#Modules

Modules are native xBNC features, built into the program, that are turned on and configured per network: in the panel (Modules), with the API or from IRC with /msg *status. Changes apply at once, without reconnecting. Every setting is validated (types, ranges, lengths, no control characters). Passwords and keys are stored encrypted and the panel never shows them again: to change them, type them again.

/msg *status modules                         list and state
/msg *status enable keepnick                 turn on (disable to turn off)
/msg *status get away                        show settings
/msg *status set away delay 60               change a setting
/msg *status addline watch patterns *xbnc*   add a line to a list
/msg *status dellines watch patterns         empty a list
/msg *status availmods                       every module and plugin, with what it does

Setting types: yes/no (in *status, true, on or 1 for yes and false, off or 0 for no), number (with a minimum and maximum), text, list (one entry per line), choice (one of the values given) and secret (stored encrypted).

Connection and account

Channels

#xbnc
#xbnc-dev

If you type /part #xbnc, xBNC does not leave the channel.

o *!*@home.example.org #xbnc
v friend!*@* *
o bob!*@* #xbnc shared-key

/quote DETACH #xbnc     detaches the channel (it keeps recording)
/quote ATTACH #xbnc     or /join #xbnc: shows it again

If someone writes your nick in #xbnc, the channel comes back with the latest messages.

Messages: 25
…in how many seconds: 10
Quiet seconds before showing it again: 60

Messages

Away message: Back soon
Nick while away: {nick}|away

When you return, *status sums up: “While you were away: 3 private messages (bob, carol) and 2 mentions in #xbnc”.

*deploy*
*xbnc* #xbnc
*urgent* bob

Matches arrive in the *watch conversation.

ghost /msg NickServ GHOST $1
op /mode $1 +o $nick
greet /msg $1 hi, $1, how are you?

In your client: /ghost y2k   (or /quote ghost y2k if your client does not send it)

/msg *ignore add pest
/msg *ignore add *!*@spam.example
/msg *ignore list
/msg *ignore del pest

Only in these channels:
#xbnc

Before: \x0304,01red\x03 \x02bold\x02   After: red bold

Legacy encoding: Windows-1252
Send in that encoding to:
#xbnc
grandpa

/msg *crypt setkey #xbnc cbc:a-long-key
/msg *crypt keyx bob          agree on a key in private (DH1080)
/msg *crypt list
/msg *crypt delkey #xbnc
+p hello                      sends this message unencrypted

mon-fri 08:00 /away Working
mon-fri 15:00 /away
weekend 10:30 /msg #xbnc Good morning!
every 2h /msg #xbnc-dev still here

CTCP requests allowed every 10 seconds: 5
Reply to VERSION: mIRC v7.77
CTCP to ignore:
FINGER
TIME

No settings. When on, your clients do not receive the server's message of the day.

History and DCC

With “Store kicks, nick changes, topics and modes” on, when the history is played back
you also see: “bob changed the topic to: Meeting at 20:00”.

/var/lib/xbnc/logs/y2k/undernet/#xbnc/2026-11-11.log

[18:30:12] <bob> hello everyone
[18:30:20] * carol has joined

If you run /whois bob from your phone, the answer reaches only the phone,
not the laptop that is also connected.

# xbnc.toml, only if the server is behind a router (NAT):
[dcc]
public_ip = "203.0.113.10"
ports = "50000-50100"

Always on

Core features that need no turning on.

#Plugins

Plugins add features for the whole channel. They run in sandboxed WebAssembly: they cannot read files or see other networks, they have CPU and memory limits, and they only do what their permissions allow, which are shown before installing them. Those that go out to the internet can only connect to approved sites.

1. The 18 official plugins come installed: xBNC installs the missing ones on the first start and after each update, and updates those with an old version. They stay off on every network. One that a superadministrator uninstalls on purpose does not come back until the next version of xBNC (or until it is installed again from Plugins → Catalogue).
2. A superadministrator can install others from the remote catalogue or by uploading a .wasm file, and approves the websites of plugins that go out to the internet (“Sites it may connect to”): link titles, weather and news.
3. Each user turns them on in their networks from Modules, in the Plugins section, and adjusts their settings.
4. They answer in your xBNC language (or the one of their “Language” setting) and also work with your own messages. The official plugins speak English and Spanish; in another language they answer in English.

#Users, roles and security

Roles

What each role can do

An administrator only manages roles below their own; nobody can change their own role or promote themselves, and there is always at least one superadministrator. Users do not see other people's networks (the API answers 404).

Accounts

• User names: 1 to 32 characters A-Z a-z 0-9 . _ -, not case-sensitive. Passwords: at least 10 characters.
• Per-user quotas: networks (max_networks), devices (max_clients) and history space in MB (max_history_mb). Empty: the server's general value.
• Suspending an account closes its access and disconnects its networks. Deleting it also removes its networks and history.
• Changing or resetting the password closes the account's other panel sessions.

Ways to sign in to the panel

• User and password, with optional two-step verification (TOTP, RFC 6238, with a QR code) using Google Authenticator, Aegis, 1Password or another compatible app. The secret is stored encrypted; a wrong code counts as a failed attempt. IRC clients still sign in with the password only: the protocol has no second step.
• Passkeys (WebAuthn): sign in with the device's fingerprint, face or PIN. They are added and removed in Your account.
• OpenID Connect (Google, Microsoft, Keycloak, Authentik…) and LDAP, if the administrator configures them in xbnc.toml (see Configuration). An external account is linked and unlinked in Your account.

Security measures

Recommendations

• Use a real certificate (Let's Encrypt) and do not publish plain-text ports.
• Keep backups encrypted: they contain the secret key.
• Every connection to the networks leaves from the server's IP: if a user misbehaves on a network, the server's IP may end up banned.
• Turn on two-step verification or a passkey on administration accounts.

To report a vulnerability, follow SECURITY.md: do not publish it; use the repository's private advisory. Answer within 3 days at most, assessment within 7 and a fix within 90 at most. The complete threat model is in Threat model.

#Configuration (xbnc.toml)

/etc/xbnc/xbnc.toml only holds process settings: users, networks and channels are in the database. The installer creates it for you. After editing it: sudo xbncd check-config and sudo systemctl restart xbnc. An unknown key is an error, so that a typo does not go unnoticed. What you set in Settings in the panel takes priority over [history] and [limits].

General

[database]

[[listen]] (one per port)

[web]

[history]

[limits]

[log]

[dcc]

[smtp] (e-mail notifications)

[oidc] (OpenID Connect)

[ldap]

[updates]

[catalog] (remote plugin catalogue)

Complete example

hostname = "bnc.example.org"
language = "en"
secret_key_file = "/var/lib/xbnc/secret.key"
# locales_dir = "/etc/xbnc/locales"

[database]
path = "/var/lib/xbnc/xbnc.db"
# url = "postgres://xbnc:password@127.0.0.1/xbnc?sslmode=require"
# ha = true

[[listen]]
address = "0.0.0.0:6697"
tls_cert = "/etc/xbnc/tls/fullchain.pem"
tls_key = "/etc/xbnc/tls/privkey.pem"

[[listen]]
address = "0.0.0.0:6667"
lan_only = true

[web]
address = "0.0.0.0:8443"
tls_cert = "/etc/xbnc/tls/fullchain.pem"
tls_key = "/etc/xbnc/tls/privkey.pem"
public_url = "https://bnc.example.org:8443"
session_hours = 12

[history]
retention_days = 30
playback_max = 1000
new_client_playback = 100
chathistory_max = 500

[limits]
max_connections = 1000
max_clients_per_user = 10
max_networks_per_user = 10
login_max_failures = 5
login_window_seconds = 600
login_block_seconds = 900
registration_timeout_seconds = 30
client_queue = 4096

[log]
level = "info"

[dcc]
public_ip = "203.0.113.10"
ports = "50000-50100"

[smtp]
host = "smtp.example.org"
port = 587
security = "starttls"
username = "xbnc@example.org"
password = "..."
from = "xBNC <xbnc@example.org>"

[oidc]
name = "Keycloak"
issuer = "https://sso.example.org/realms/home"
client_id = "xbnc"
client_secret = "..."
auto_create = true
default_role = "user"
allowed_groups = ["irc"]

[ldap]
url = "ldaps://ldap.example.org:636"
bind_dn = "uid={username},ou=people,dc=example,dc=org"

[updates]
repository = "owner/xbnc"

[catalog]
url = "https://plugins.example.org/index.json"
public_key = "BASE64..."

#Command line

Every command accepts -c PATH (or the XBNC_CONFIG variable; /etc/xbnc/xbnc.toml by default), -h for help and -V for the version. Those that write to the database are run as the service user: sudo -u xbnc xbncd … (in Docker, docker compose exec xbnc xbncd …). Afterwards, sudo systemctl reload xbnc so the service applies the changes to users, networks and channels. Every action is recorded in the audit log.

Examples

sudo xbncd info
sudo xbncd setup-code
sudo -u xbnc xbncd user add alice
sudo -u xbnc xbncd user add carla --role moderator
echo 'a-long-password' | sudo -u xbnc xbncd user add bob --password-stdin
sudo -u xbnc xbncd user role carla admin
sudo -u xbnc xbncd user reset-2fa alice
sudo -u xbnc xbncd network add alice libera --host irc.libera.chat --sasl-user alice
sudo -u xbnc xbncd network add alice undernet --host irc.undernet.org --port 6667 --no-tls
sudo -u xbnc xbncd channel add alice libera '#xbnc' --key
sudo -u xbnc xbncd backup /var/lib/xbnc/copy.db
sudo -u xbnc xbncd import /home/old/.bouncer --logs --utc-offset Europe/London             # preview
sudo -u xbnc xbncd import /home/old/.bouncer --logs --utc-offset Europe/London --apply     # import
xbncd locales check pt.json --missing
sudo systemctl reload xbnc

Scripts

#Backups, databases and migration

Backups from the panel

In Settings → Backups (superadministrators): make a backup now, download it, delete it, restore it and schedule automatic backups (every N hours, keeping the last M). Each backup is a .tar.gz with the database (a live copy with an integrity check), the secret key and the installed plugins, stored in /var/lib/xbnc/backups/.

Restoring leaves the backup staged (one can also be uploaded from your computer) and it is applied when xBNC restarts; until then it can be cancelled. Backups contain the secret key: keep them encrypted.

Backups from the command line

sudo ./scripts/backup.sh                       # in /var/backups/xbnc, keeps 14
sudo ./scripts/backup.sh /mnt/backups --keep 30

# Every night at 3:30
echo '30 3 * * * root /path/to/xbnc/scripts/backup.sh >/dev/null' | sudo tee /etc/cron.d/xbnc-backup

# Restore (stops the service, keeps the current files as *.pre-restore-DATE, restores and starts)
sudo ./scripts/restore.sh /var/backups/xbnc/xbnc-20261108T033000Z.tar.gz
sudo ./scripts/restore.sh ARCHIVE --with-config    # also /etc/xbnc

# Only the database
sudo -u xbnc xbncd backup /var/lib/xbnc/copy.db

PostgreSQL

sudo systemctl stop xbnc
sudo -u xbnc xbncd migrate-to-postgres postgres://xbnc:password@127.0.0.1/xbnc
# in /etc/xbnc/xbnc.toml:
#   [database]
#   url = "postgres://xbnc:password@127.0.0.1/xbnc"
sudo systemctl start xbnc

The target database must be empty. With ?sslmode=require the connection is encrypted. Full-text search works the same with SQLite and PostgreSQL.

High availability

With ha = true, several servers run xBNC against the same PostgreSQL database. The one holding a PostgreSQL lock works and the others wait. If the active one goes down, its connection closes, the lock is released and another takes over within seconds. An active node that loses the database stops at once, so there are never two at the same time. Clients must be able to reach the active node (a floating IP or a DNS name that changes).

Migrating from another bouncer

xBNC brings over what you had in your previous bouncer if it uses the classic block configuration format (<User name>, <Network name>, <Chan #channel>).

From the panel (Users → Import from another bouncer, superadministrators): choose the .conf file or paste its contents, click “See what will be imported” (nothing is written) and then “Import”. From the panel only the configuration is read; SASL, NickServ, commands on connect, certificates and logs are in the data folder and are imported on the server.

# Preview: changes nothing
sudo -u xbnc xbncd import /path/to/the/folder
# Import, with the logs (which were in London time)
sudo -u xbnc xbncd import /path/to/the/folder --apply --logs --utc-offset Europe/London
sudo systemctl reload xbnc

# Logs of one particular network, separately
sudo -u xbnc xbncd import-logs alice libera /path/to/logs/libera --utc-offset America/New_York

The logs folder has one sub-folder per channel or conversation (#xbnc/, bob/) with YYYY-MM-DD.log files. Messages, actions (* nick …), notices (-nick- …) and joins, parts, quits, kicks, nick changes, topics and modes are recognised. With a named time zone (Europe/London) each day's daylight saving time is applied.

Any other module shows in the preview as “no equivalent”. After importing: networks with several servers use only the first; networks without TLS are flagged; if you used the same ports, stop the previous bouncer before starting xBNC; and configure your clients with the user/network format.

#Alerts and monitoring

Alerts

xBNC checks these conditions every 30 seconds. They are adjusted in Settings → Alerts (0 turns each one off):

When an alert starts and when it is resolved:

• It appears (or disappears) on the panel's Home page for administrators.
• It is recorded in the audit log (action alert).
• With “Notify administrators over IRC” (on by default), every connected administrator and superadministrator gets a notice from *status in their language.
• With a webhook (only a superadministrator configures it), xBNC sends a POST with JSON. It has 10 seconds to answer with 2xx; if it fails, it is noted in the service log.

{
  "source": "xbnc",
  "server": "bnc.example.org",
  "state": "firing",
  "alert": "network_down",
  "subject": "alice/libera",
  "message": "Network alice/libera has been disconnected for more than 15 minutes",
  "since": 1762600000000,
  "text": "[xBNC bnc.example.org] firing: Network alice/libera ...",
  "content": "[xBNC bnc.example.org] firing: Network alice/libera ..."
}

state is firing or resolved. The text and content fields make it work as it is with the incoming webhooks of Slack and Mattermost (text) and Discord (content).

Prometheus metrics

GET /api/v1/metrics in Prometheus format, with an administrator's session or a token with the “metrics” scope:

scrape_configs:
  - job_name: xbnc
    scheme: https
    metrics_path: /api/v1/metrics
    authorization:
      credentials: xbnc_...
    static_configs:
      - targets: ["bnc.example.org:8443"]

The same counters are shown on IRC with /msg *status traffic (administrators).

Grafana and Prometheus rules

In packaging/monitoring/:

• grafana-dashboard.json: a dashboard ready to import with connected and disconnected networks, IRC clients, users, memory, uptime, messages per second, traffic, networks by state, logins, reconnections, storage, history and active alerts.
• prometheus-rules.yml: alerts XbncDown, XbncNetworksDisconnected, XbncManyReconnects, XbncFailedLogins, XbncBlockedAddresses, XbncMemoryHigh, XbncDatabaseLarge, XbncLogLinesDropped and XbncInternalAlert.

Health check

GET /api/v1/health answers without a session; it is meant for load balancers and external monitors.

#REST API

Everything the panel does is in the API. Base: /api/v1, at the same address as the panel. JSON format; errors are {"error": "code", "message": "text"} with the right HTTP status. The OpenAPI 3.1 specification is at GET /api/v1/openapi.json (and in docs/openapi.json); a test checks that it documents every route.

API tokens

Create them in Your account → API tokens. The full token (xbnc_ and 43 characters) is only shown when created: xBNC stores its SHA-256. Send it in the header Authorization: Bearer xbnc_…; with a token no CSRF is needed.

They expire after 30, 90 or 365 days, or never; at most 50 per user. The list shows the prefix, the last use and the last IP. A wrong token counts as a failed attempt (the same blocks as IRC and the panel). Creating and revoking is recorded in the audit log.

Panel session

1. POST /auth/login with {"username", "password"} (and totp_code if the account has two-step verification). The answer brings the xbnc_session cookie and, in the body, csrf.
2. Send the cookie with every request, and with POST, PUT, PATCH and DELETE the header X-CSRF-Token with that value (GET /auth/me returns it again).
3. Requests with an Origin header from another site are refused; curl and scripts do not send it.

Examples

B=https://bnc.example.org:8443/api/v1
T="Authorization: Bearer xbnc_..."

# Networks and their state
curl -s -H "$T" $B/networks

# Search the history of network 1
curl -s -H "$T" "$B/networks/1/history?target=%23xbnc&q=meeting&limit=20"

# Reconnect a network (write token)
curl -s -X POST -H "$T" -H 'Content-Type: application/json' -d '{"action":"jump"}' $B/networks/1/control

# Turn on a module
curl -s -X PUT -H "$T" -H 'Content-Type: application/json' \
  -d '{"enabled":true,"config":{"delay":60,"summary":true}}' $B/networks/1/modules/away

# Languages and the Spanish panel texts (no session needed)
curl -s $B/i18n
curl -s $B/i18n/es

# With a session instead of a token: create a user and give them a network
curl -s -c jar -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"your-password"}' $B/auth/login > login.json
CSRF=$(python3 -c 'import json;print(json.load(open("login.json"))["csrf"])')
curl -s -b jar -H "X-CSRF-Token: $CSRF" -H 'Content-Type: application/json' \
  -d '{"username":"bruno","password":"a-long-password","role":"user","max_networks":3}' $B/users
curl -s -b jar -H "X-CSRF-Token: $CSRF" -H 'Content-Type: application/json' \
  -d '{"user_id":2,"name":"libera","host":"irc.libera.chat","port":6697,"tls":true,"nick":"bruno",
       "sasl_username":"bruno","sasl_password":"secret","channels":["#xbnc","#xbnc-dev"]}' $B/networks

All routes

“owner or admin”: the owner of the network or an administrator. “session only”: not accepted with a token. Passwords are never returned: networks say has_sasl_password and has_server_password.

#Versions and updates

New version notices

With [updates] repository (or url) in xbnc.toml, xBNC checks the latest published version once a day and says so on the Home page and in Settings → Updates. On its own it downloads and installs nothing.

Updating

In this beta, xBNC is installed from the source code: it is updated with scripts/update.sh (see Installation).

Updating from the panel (package installations)

xBNC also includes one-click updates for when it is installed from signed .deb or .rpm packages. With [updates] public_key, Settings → Updates shows “Update now” to superadministrators. xBNC downloads the package and its .sig signature, checks the Ed25519 signature and leaves it in /var/lib/xbnc/updates/. The system service xbnc-update checks everything again as root without trusting that folder (it verifies with the key in /etc/xbnc/xbnc.toml, which xBNC cannot change, and refuses equal or older versions), installs it with dpkg or rpm and xBNC restarts. A package without a signature, signed with another key or modified is never installed. Without public_key, or without a package installation, the panel explains how to update by hand.

Publishing signed releases

# Once: create the key (the private one is secret; the public one goes in [updates] public_key)
xbncd release keygen --out xbnc-release.key

# For each release: sign the packages (writes FILE.sig)
XBNC_RELEASE_KEY="$(cat xbnc-release.key)" xbncd release sign xbnc_1.0.0_amd64.deb xbnc-1.0.0-1.x86_64.rpm

# Check
xbncd release verify --public-key "BASE64..." xbnc_1.0.0_amd64.deb

The repository includes a workflow that builds and signs .deb and .rpm packages and a container image (.github/workflows/release.yml). It needs the key as a repository secret (XBNC_RELEASE_KEY) and the public key as a variable (XBNC_RELEASE_PUBLIC_KEY). During the beta xBNC is published only as a source .zip, so the workflow only runs when it is started by hand from the Actions tab.

Publishing on GitHub

scripts/publish-github.sh publishes the source code, a release with the .zip and its checksum, and the wiki as a website of its own (GitHub Pages), from the maintainer's computer and with the maintainer's GitHub account. The complete guide is docs/PUBLISHING.md.

#Writing plugins

A plugin is a WebAssembly file with a JSON manifest inside. There are SDKs for C (sdk/c, with the 18 official plugins as examples and the xbnc_util.h helper) and for Rust (sdk/rust). Any language that compiles to WebAssembly without WASI works if it follows the interface.

Manifest

{
  "id": "hello",
  "name": "Hello",
  "version": "1.0.0",
  "description": "Answers !hello.",
  "usage": "In a channel: !hello",
  "author": "your-name",
  "permissions": ["send"],
  "settings": [
    { "key": "greeting", "type": "text", "label": "Greeting", "default": "Hello!" },
    { "key": "lang", "type": "text", "label": "Language", "help": "Empty: your xBNC language.", "default": "" }
  ],
  "translations": {
    "es": {
      "name": "Hola",
      "description": "Responde a !hello.",
      "usage": "En un canal: !hello",
      "settings": { "greeting": { "label": "Saludo" } }
    }
  }
}

Interface (ABI 1)

The module exports:

And it can only import from the xbnc module (neither WASI nor anything else):

Events

{
  "event": "message",
  "network": "undernet", "nick": "y2k", "connected": true, "clients": 1, "lang": "en",
  "config": { "trigger": "!roll" },
  "state": null,
  "command": "PRIVMSG", "conversation": "#xbnc", "channel": true,
  "from": "bob", "from_mask": "bob!b@host", "text": "!roll 2d6",
  "action": false, "outgoing": false
}

Common fields: network, nick (your current nick), connected, clients (connected clients), lang (your language code: en, es or any installed language), config (its settings) and state (what it saved).

Answer

{
  "actions": [
    { "reply": "text in the same conversation" },
    { "tell": "text for you only, as *id" },
    { "privmsg": { "target": "#channel", "text": "..." } },
    { "notice": { "target": "nick", "text": "..." } },
    { "raw": "MODE #channel +o bob" },
    { "http": { "id": "weather", "method": "GET", "url": "https://api.open-meteo.com/..." } }
  ],
  "state": { "whatever you want to keep": 1 }
}

• Single-line texts. Actions without permission or badly formed are dropped and noted in the log.
• state replaces the plugin's saved state on that network; it comes with every event and survives restarts. The instance is kept between events while the network is running.
• raw can never send QUIT, PASS, USER, NICK, CAP, AUTHENTICATE, OPER, SERVER or SQUIT.
• http: ('id', 'url', 'method', 'body'). https only, to approved domains; methods GET, POST, PUT and DELETE; body up to 16 KB (text or JSON); up to 3 requests at a time and 30 per minute per plugin and network. The answer arrives as an http event with id, status, body (up to 256 KB) and, if it failed, error.

Limits

C SDK

sdk/c/xbnc_plugin.h takes care of the interface. Main functions:

sdk/c/xbnc_util.h adds what the official plugins use: language of the answer (u_lang), reading commands with aliases (u_command), walking the store (u_next_key), dates, time zones with European daylight saving time and text building.

#include "xbnc_plugin.h"

void on_event(const xbnc_event *ev) {
    static char kind[16], text[256], greeting[128];
    xbnc_get(ev, "event", kind, sizeof kind);
    if (!xbnc_streq(kind, xbnc_strlen(kind), "message")) return;
    xbnc_get(ev, "text", text, sizeof text);
    if (!xbnc_streq(text, xbnc_strlen(text), "!hello")) return;
    xbnc_config(ev, "greeting", greeting, sizeof greeting);
    xbnc_reply(greeting[0] ? greeting : "Hello!");
}

cd sdk/c
clang --target=wasm32 -O2 -nostdlib -fno-builtin -I. \
  -Wl,--no-entry -Wl,--export-dynamic -Wl,--strip-debug -Wl,-z,stack-size=65536 \
  -o hello.raw.wasm hello.c
xbncd plugin pack hello.raw.wasm hello.json -o hello.wasm
xbncd plugin check hello.wasm
sudo -u xbnc xbncd plugin install hello.wasm

# The official examples: make (or make bundle to copy them to the catalogue)

It needs clang and wasm-ld (LLVM 15 or later) and llvm-objcopy (or xbncd plugin pack).

Rust SDK

The xbnc-plugin crate (sdk/rust) provides the Plugin trait, the Event type (with kind(), text(), conversation(), is_channel(), outgoing(), config_str(), state()…), Response (with reply(), tell(), state()…) and the plugin! macro. Included example (sdk/rust/examples/stats.rs):

//! Example plugin: counts messages per channel and answers "!stats".
//! The counts survive restarts thanks to the persisted state.
//!
//! Build: cargo build -p xbnc-plugin --release --target wasm32-unknown-unknown --example stats
//! then: xbncd plugin pack target/wasm32-unknown-unknown/release/examples/stats.wasm \
//!         sdk/rust/examples/stats.json -o stats.wasm

use xbnc_plugin::{plugin, Event, Plugin, Response};

#[derive(Default)]
struct Stats;

impl Plugin for Stats {
    fn on_event(&mut self, ev: &Event) -> Response {
        let mut r = Response::new();
        let mut counts = ev.state().as_object().cloned().unwrap_or_default();
        match ev.kind() {
            "message" if ev.is_channel() && !ev.outgoing() => {
                let chan = ev.conversation().to_lowercase();
                let n = counts.get(&chan).and_then(|v| v.as_u64()).unwrap_or(0) + 1;
                counts.insert(chan, n.into());
                if ev.text().trim() == ev.config_str("trigger") {
                    r.reply(format!("{} messages counted in {}", n, ev.conversation()));
                }
                r.state(counts.into());
            }
            "command" => {
                if counts.is_empty() {
                    r.tell("Nothing counted yet.");
                }
                let mut v: Vec<_> = counts.iter().collect();
                v.sort_by_key(|e| std::cmp::Reverse(e.1.as_u64()));
                for (chan, n) in v.into_iter().take(10) {
                    r.tell(format!("{chan}: {n}"));
                }
            }
            _ => {}
        }
        r
    }
}

plugin!(Stats);

Development mode

In Plugins → Development (superadministrators): with the mode on, xBNC watches /var/lib/xbnc/plugins/dev/. A .wasm saved there is checked and installed as soon as it changes and every network reloads it. If you put name.json next to name.wasm, it packs it for you (no need for xbncd plugin pack). A new plugin is turned on in the networks of whoever turned the mode on. The results and what the plugin writes are shown in the page's live log.

sudo cp hello.wasm hello.json /var/lib/xbnc/plugins/dev/

Publishing your own catalogue

Besides the official ones, xBNC can offer the plugins of a signed remote catalogue ([catalog] in xbnc.toml). The index is a JSON {"plugins": [{"id", "version", "url", "sha256", "size", "manifest"}]} and its Ed25519 signature in base64 is published in index.sig. Each plugin is checked against the signed SHA-256 before it is installed.

xbncd plugin catalog-keygen -o catalogue.key        # once; the public key goes in [catalog] public_key
xbncd plugin catalog-entry hello.wasm https://plugins.example.org/hello.wasm   # entry for the index
xbncd plugin catalog-sign --key catalogue.key index.json                       # writes index.json.sig

#Translating xBNC

xBNC can speak any language. Every text it shows lives in one file per language: the web panel, the sign-in page and everything it says over IRC (*status, its help, notices and module messages). You translate one file and the language appears in every language selector of xBNC, without programming or compiling anything.

The files

English and Spanish are built into the program. Other languages, and corrections, go in /etc/xbnc/locales/ (locales_dir in xbnc.toml, or the XBNC_LOCALES_DIR variable). xBNC reads them at start and on reload (sudo systemctl reload xbnc or /msg *status rehash).

{
  "language": {
    "code": "pt",
    "name": "Português",
    "english_name": "Portuguese",
    "locale": "pt-PT",
    "translators": ["Your name or nick"]
  },
  "irc": {
    "connected_to": "Ligado a {0} como {1}.",
    "help.group.channels": "Canais"
  },
  "panel": {
    "Joined": "Dentro",
    "Delete {username}": "Apagar {username}"
  }
}

Step by step

1. Copy en.json as <code>.json (for example pt.json).
2. Change the language part: code, name, English name, locale and your name.
3. Translate the texts on the right. Never change the keys on the left.
4. Check the file: xbncd locales check pt.json (add --missing to see what is left).
5. Try it: copy it to /etc/xbnc/locales/ and reload xBNC. It appears straight away on the sign-in page, in Your account, in Settings and with /msg *status language pt.
6. Send it to the project so it is included in the next version.

Rules for the texts

A text that breaks these rules is ignored and shown in English; xbncd locales check reports it as a problem. This also makes it impossible for a language file to inject IRC commands (line breaks are forbidden).

Correcting a built-in language

A file for a language that already exists (for example es.json in /etc/xbnc/locales/) only needs the texts you want to change: the rest stays as it is.

What a file does not translate

• Plugin replies. Their name, description and settings are translated in their manifest (translations). What a plugin answers in a channel is written in the plugin itself; in a language it does not include, it answers in English. The official plugins speak English and Spanish.
• The installer speaks English and Spanish.
• The server log is in English.

Translating this wiki

The wiki is a project of its own, separate from the app (xbnc-wiki), so that anyone can read it without installing xBNC. It is generated with build.py from one content file per language (content/en.py is the base) and the xBNC source code. To translate it, copy en.py as <code>.py and translate the texts between quotes without touching the HTML tags or calls such as code(…). The tables of modules, plugins and commands translate themselves with xBNC's language files. When the wiki is built, each language appears in the selector at the top.

For developers

• In the panel, texts are written in English inside t("…"), tk("…") or tx("…"). npm run i18n:check (in web/) lists what is missing from en.json, and node scripts/i18n-check.mjs --sync adds it.
• In the server, the text is added to the irc section of locales/en.json and used with self.t("key", &[]), tr!(self, "key", arg1, arg2) or i18n::tr(lang, "key", &[…]). The tests check that every key used exists and that es.json translates all of them with the same placeholders.

The complete guide is in TRANSLATING.md, in the source code.

#IRCv3

xBNC negotiates with each server the capabilities it offers and xBNC wants, and offers each client its own. Each client only gets what it asked for: a classic client receives the usual messages (for example, the short JOIN and only the highest rank in the user list).

With the servers

With the clients

With CAP LS 302, sasl=PLAIN is announced. If the server does not support a capability a client asks for, xBNC still offers it when it can build it itself (for example, the extended JOIN with the data it knows). The test report records, per network, what the server offers (caps_offered), what xBNC turned on (caps_acked) and what each client asked for.

#Test report

In Your account → Test report → Download report (or GET /api/v1/diagnostics) you download a JSON file with what is needed to diagnose a problem with a network, without passwords, messages, other people's nicks or the IPs of your devices.

#Architecture

xBNC is a single program (xbncd) with the panel built in. The code is split into crates/xbnc-proto (IRC protocol without I/O: parser and serialiser with IRCv3 tags, prefixes, casemapping, ISUPPORT and CTCP) and crates/xbncd (service, CLI, API and panel), plus the plugin SDKs in sdk/, the panel (React and TypeScript) in web/ and the translations in locales/.

How it works inside

• Each network of each user is an independent task that exclusively owns its connection to the server, the state of the network and the list of clients. Nobody else touches that state: there are no locks on the path of the messages.
• Each client is a reading task and a writing task, with a bounded queue. If a client does not read, it is disconnected instead of piling up memory; when it comes back it gets what was pending.
• The panel, the API and the command line never touch the IRC connections: they write to the database and send orders to the network tasks (state, control, join, part, reload, disconnect a client, alert, broadcast).
• Every database access goes through a separate thread pool. The messages of every network go through a single writer thread that stores everything waiting (up to 512) in one transaction, keeping each network's order.
• Modules are code of the program itself, called at specific points (server line, client command, timer, connection, client joining or leaving). Plugins receive their events from the network task and run in the blocking thread pool.
• When a message arrives: it is parsed, the state is updated (nick, channels, members, modes, topic), it is stored with the server's time and an identifier, and it is sent to each client adapted to its capabilities.
• Texts are looked up in the loaded languages (built in, plus the files of locales_dir) by key, with English as the fallback.

Modules of the code

The panel (web/) is a React and TypeScript application built with Vite. web/dist is built into the binary, so xBNC stays a single file. The official plugins are built into the binary too (crates/xbncd/catalog/).

State machines

They are kept separate:

1. Connection to the network: Disconnected → Registering → Connected. While registering, xBNC negotiates the IRCv3 capabilities, SASL and the nick (with an alternative if it is taken). Times: 30 s to connect, 60 s to register, a PING after 90 s of silence and disconnection at 180 s. Reconnection with growing delays from 5 s to 5 minutes with ±20 % random variation, and at least 2 minutes after a throttling notice. If a server fails and the network has backup servers, the next one is tried after 1 second.
2. Client session: registration (CAP, PASS or SASL, NICK, USER) with a time limit, and then a session attached to a network.
3. User and bouncer: which network tasks exist and how many clients each user has.

The path of a message

1. The network task reads a line from the server and parses it.
2. It updates the state (nick, channels, members, modes, topic).
3. If it is a PRIVMSG, NOTICE or ACTION from someone (or an event, with the Events module), it stores it in messages with the server's time (server-time) or the local one, and gives it the identifier msgid = x<id>.
4. It sends it to each attached client adapted to its capabilities (removing the tags the client did not ask for) and moves each client's cursor forward.

What a client sends goes to the server, is stored as outgoing and is relayed to the user's other clients (and to the sender itself if it asked for echo-message).

History without duplicates

• Each device (@device in the login, default if it is not given) has a cursor per network in client_cursors: the identifier of the last message delivered.
• When it connects, it gets the messages after its cursor (up to playback_max, 1,000 by default). A new device gets the most recent new_client_playback (100 by default).
• Cursors are saved when the device disconnects and every 5 seconds; they never go back.
• Clients with draft/chathistory get no automatic playback: they ask for what they need with CHATHISTORY. Messages already read on another device (draft/read-marker) are not played back again.

Database schema

PostgreSQL has the same schema; it is supported from version 8 of the schema (PG_MIGRATIONS), and every new migration is added to both lists. Channel events (JOIN, PART…) are stored in messages with their command. Passwords imported from another bouncer with SHA-256 are kept as legacy-sha256$<hash>$<salt> until the first correct login, when they are replaced by Argon2id. Migrations are applied at start inside a transaction, and a binary refuses to open a newer schema than it knows.

#Threat model

What xBNC protects, from whom and with which measure at each point. It is the guide for the external audit and for reviewing each change.

What is protected

Who may attack

Out of scope: someone who is already root on the machine, the server provider and failures of the operating system or of the IRC networks.

IRC client connections (6697/6667)

Connections to the IRC networks

DCC

Web panel and API

Plugins

Import from another bouncer

Updates from the panel

Data at rest and backups

Accepted risks

• The history is stored unencrypted in the database: encrypting it would prevent search and playback. It is protected by the system's permissions.
• IRC clients have no second factor: the bouncer password is their only protection (hence per-IP blocking and Argon2id).
• A superadministrator can install a plugin with permission to send messages on behalf of whoever turns it on: it is a decision of trust that the panel shows before installing.
• Every connection to the networks leaves from the server's IP.
• FiSH is old cryptography (Blowfish, without integrity); decrypted messages are stored in the history like the rest.

Review

Each version reviews these tables: a new feature that opens a surface not listed here is added to them. The tests behind each measure are in crates/xbncd/tests/ and in the unit tests of each module; fuzzing covers the IRC parser, DCC, the imported configuration file, search, and the manifests and execution of plugins (see Test environment).

Internal review of version 0.7. The whole code was reviewed with these tables as a guide (it does not replace the external audit):

• SQL queries: all with bound parameters; the parts built with format! are only fixed column lists and clauses.
• API authorisation: every route checks the session or token and the permission; network routes check the owner. Fixed: PATCH /users/{id} answered 404 or 403 to accounts without permission depending on whether the user existed.
• External processes: the only one is dpkg or rpm in the update helper, with fixed arguments and the package already checked.
• File paths: logs, plugins and updates build paths only from validated names; the update helper never follows symbolic links.
• Denial of service: added the limit of unauthenticated IRC connections per IP, the panel's connection limits and idle time, and the limit of simultaneous Argon2id calculations.
• Plugins: the interpreter moved to the loop execution mode after fuzzing found that the chained-call mode could exhaust the native stack in unoptimised builds.
• unsafe code: only one call to mallopt at start (memory allocator setting).
• Dependencies: cargo-deny in CI (licences and security advisories).

Internal review of version 1.0. The new code of 1.0 was reviewed and three points were fixed before publishing: on networks without services the password is never sent to whoever uses the nick “NickServ”; the FiSH key exchange has a limit of requests and stored keys; decrypted text cannot break lines. Language files are validated (placeholders, tags, no control characters or line breaks) and a text that fails is shown in English.

#Performance

Load test (cargo run --release --example loadtest -- --users 1000 --clients 1 --rate 2 --seconds 60): a simulated IRC server sends messages to every network at once (the worst case) and each client measures how long it takes to receive them, going through the history, modules and plugins. Machine: 2 vCPU Xeon at 2.1 GHz, 7 GB of RAM, network disk, default configuration (SQLite).

• No message was lost in any test.
• Latency grows with the size of the burst: with 2,000 networks receiving the same message at once, the last one is delivered about 150 ms after the first. With real traffic, spread over time, it is a few milliseconds.
• Memory: about 45 KB per connected network and about 30 KB more per client, not counting the history (on disk).
• Client logins (Argon2id) go one at a time per CPU: 2,000 clients signing in together take about 27 s on 2 cores, without a memory spike.
• Disk: about 150 bytes per stored message, including the search index.

Sizing: a small server (1–2 vCPU, 1 GB of RAM) serves hundreds of users with several networks and thousands of messages per second. With many users, check limits.max_connections, the service's LimitNOFILE (65,536 by default) and the history retention.

How it is measured

The test (crates/xbncd/examples/loadtest.rs) starts, in a single process:

• a simulated IRC server with a channel #xbnc;
• xBNC with N users, each one with its network connected to that server and joined to #xbnc;
• one or more IRC clients per user connected to xBNC.

The server sends --rate messages per second to the channel, to every network at the same time (the worst case: simultaneous bursts). Each message carries the time it was sent, and each client measures how long it takes to arrive: IRC server → xBNC (stored in the history, modules, plugins) → client. At the end the server cuts every connection and the test measures how long it takes for every network to come back.

Memory and CPU are those of the whole process, so they include the simulated server and the test clients (xBNC alone uses a little less). The build is --release with the default configuration (history in SQLite with WAL).

Problems found and fixed with this test

Still to do

• Repeat the test on dedicated hardware and with several networks per user.
• Measure with real IRC servers far away (the test uses a local one, without network latency).

To repeat it: cargo run --release --example loadtest -- --users 2000 --clients 1 --rate 1 --seconds 60. The options are --users, --clients (per user), --rate (messages per second to the channel) and --seconds.

#Test environment

With Docker

testenv/ brings up xBNC with two different IRC servers (Ergo and InspIRCd) on an isolated network, all in plain text on purpose:

cd testenv
docker compose up -d --build
./setup.sh
# IRC: localhost:6667, password test/ergo@laptop:testpassword1
# Panel: http://localhost:8080 (user test, password testpassword1)

Do not publish those ports on a public interface.

Automatic tests

cargo test --workspace                                   # every test
XBNC_TEST_POSTGRES=postgres://postgres@127.0.0.1/postgres cargo test --workspace   # also with PostgreSQL
cargo clippy --workspace --all-targets -- -D warnings
cd web && npm run build && npm run i18n:check            # panel and translations
xbncd locales check locales/*.json                       # language files
python3 ../xbnc-wiki/build.py --app .                   # the wiki (a separate project)

They cover the protocol, the units, the API against a real bouncer, IRC end to end, every *status command, the switch to a backup server, the trusted certificate with a real TLS handshake, a language added as a file, modules and plugins against a simulated IRC server, the panel, SSO and real IRC servers in CI (Ergo, InspIRCd, UnrealIRCd, Solanum and miniircd). Fuzzing (fuzz/) runs every week. testenv/ui/language_check.py checks in a real browser that every way of changing the language works.

Tests on real networks

The test plan per network, module and plugin is in testenv/real/PLAN.md. See Testing the beta.

The test sets

End-to-end scenarios

1. On connecting, the client gets the welcome, the network's ISUPPORT, its channels, the topic and the list of users.
2. A message received with the client closed is played back on reconnecting, with its time; your own messages are not played back to the same device and a third connection gets no duplicates.
3. Two devices connected at once stay in sync; a new device gets the recent history.
4. CHATHISTORY LATEST, AFTER and errors, batch, the server's server-time kept, msgid and echo-message; capabilities that are not implemented are not announced.
5. Login with SASL PLAIN.
6. A wrong password is refused and the IP is blocked after three failures, even with the right password.
7. Unknown network: the error lists the networks available.
8. Server outage: the bouncer says so, reconnects with growing delays and joins the channels again.
9. *status, and PART and JOIN with a key saved (the key is stored encrypted).
10. Commands on connect are sent before joining channels.
11. Read markers are shared between devices.
12. soju.im/bouncer-networks for modern clients.

Real IRC servers

tests/real_ircd.rs connects a real xBNC to a real IRC server (variable XBNC_IRCD=host:port) and checks the list of users, messages in both directions, sync between two devices, playback without duplicates with the client closed, a nick change, leaving a channel and staying connected to the network:

XBNC_IRCD=127.0.0.1:6667 cargo test -p xbncd --test real_ircd -- --ignored

CI runs it against Ergo, InspIRCd, UnrealIRCd, Solanum and miniircd (testenv/ci/start-ircd.sh builds or installs each one with a minimal configuration).

Fuzzing

fuzz/ has six libFuzzer targets:

cargo install cargo-fuzz          # needs Rust nightly
cd fuzz && mkdir -p corpus/irc_message && cp seeds/irc_message/* corpus/irc_message/
cargo +nightly fuzz run irc_message corpus/irc_message -- -max_total_time=600

CI (.github/workflows/fuzz.yml) runs each target for 20 minutes every week, keeps the corpus between runs and first checks that the failures already found (fuzz/regressions/) are still fixed. The failures found so far, all fixed and with their test:

1. The parser accepted CR, LF or NUL inside a line.
2. The parser accepted commands that are not alphanumeric (@ @).
3. DCC offers accepted control characters.
4. Embedding a manifest overflowed with sections of impossible size.
5. A plugin with a long loop exhausted the process's native stack in builds where the compiler does not turn the interpreter's calls into jumps: the interpreter now uses the loop execution mode, which never grows the stack.

Load tests

cargo run --release --example loadtest -- --users 2000 --rate 1 --seconds 60. Results and method in Performance.

The panel in a browser

The panel has been gone through in Chrome with Playwright against a real bouncer with a real IRC client connected: first run, network wizard, channels, history and search, users, security, settings, 2FA, modules, plugins (installation with the permissions preview, per-network settings), import from another bouncer, alerts, updates, backups, chat, the sign-in page, the light and dark themes and the phone, in English and in Spanish, with no errors in the console apart from the expected 401 before signing in. testenv/ui/language_check.py URL USER PASSWORD repeats in a real browser every way of changing the language (sign-in page, Your account, Settings, a language added as a file) and checks that no text is left in another language.

Manual checklist

Use it with testenv/ or with a real installation:

• The service starts and stops cleanly (systemctl start and stop xbnc; the log shows xBNC stopped).
• An administrator and several users are created with the command line.
• A user with two networks is connected to both at once.
• A classic client (HexChat, WeeChat, irssi or mIRC) connects with user/network@device:password.
• With the client closed, someone else writes in the channel and in private; on reconnecting those messages arrive exactly once.
• Two clients of the same user see what the other one writes.
• docker compose restart ergo (or cutting the network): xBNC says so, reconnects and joins the channels again.
• /msg *status status shows the right state.
• Five wrong passwords block the IP for 15 minutes.
• scripts/backup.sh and scripts/restore.sh bring back users, networks and history.
• journalctl -u xbnc contains no passwords after logging in, SASL and /msg NickServ IDENTIFY.
• From the panel: create a user, add a network with the wizard, join a channel and see the history.
• An ordinary user does not see Users, Security or Settings, nor other people's networks.
• Turn on two-step verification and sign in with the code.
• Change the retention in Settings and check in System that it applies without restarting.
• Memory use with 1 user and 2 networks (systemctl status xbnc): note it down to compare in future versions.

#Common problems

Always start with the log and with *status: sudo journalctl -u xbnc -n 100 --no-pager and, from your client, /msg *status status.

You cannot connect

Problems with a network

Modules and plugins

Panel and service

More detail in the log

# In /etc/xbnc/xbnc.toml:  [log] level = "info,xbncd=debug"
sudo systemctl restart xbnc
sudo journalctl -u xbnc -f
sudo journalctl -u xbnc --since "1 hour ago" -p warning

With trace every IRC line is logged (with credentials masked). Go back to info when done: with debug, nicks and channels appear.

#Testing the beta

Version 1.0.0 is being tested on real networks (Undernet, Libera.Chat, freenode, Rizon, EvilNet, IRCnet and others) before it is declared stable.

1. Install it and add your networks.
2. Follow the test plan in testenv/real/PLAN.md: one section per network, module and plugin.
3. If something fails, download the test report from Your account.
4. Send it with what you did, what you expected, what happened, the network, the client, the approximate time, the version (/msg *status version) and the warnings of the log (sudo journalctl -u xbnc --since "1 hour ago" | grep -E "WARN|ERROR"; review it before sending it).

If the project is on GitHub, use the “Test report” issue template. Security flaws are not made public: follow SECURITY.md.

Known limits

• Undernet and QuakeNet do not offer TLS: the connection to those networks is unencrypted.
• FiSH is old cryptography (Blowfish, without integrity): it protects from the network's servers, it is no replacement for end-to-end encryption. Decrypted messages are stored in your history like the rest.
• Some clients do not send commands they do not know: aliases need /quote.
• DCC between an IPv6-only client and an IPv4-only one is not translated.
• Search by pieces of words is only used when there are no whole-word matches.
• If the process stops abruptly, a few seconds of history may be repeated.
• In a language added as a file, the replies of the official plugins come in English (they speak English and Spanish).
• In this beta installation is from the source code; no .deb or .rpm packages are published.
• Still to be checked on real networks: login with X, NickServ, Q and AuthServ; invite and unban; plugins with web access; FiSH with real clients; installer with real systemd and Let's Encrypt; DCC between networks; SASL EXTERNAL; importer with real installations.