xBNC Wiki — The Next Generation of IRC Bouncers Wiki v1.0.0

Wiki Reference

Reference

IRCv3, the test report, the architecture, the threat model, performance and the test environment.

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

CapabilityWhat for
server-timeReal time of each message.
message-tagsTags on messages.
multi-prefixEvery rank of a user (@+), not only the highest.
extended-joinJoins carry the account and the real name.
away-notifyNotices when someone goes away or comes back.
account-notifyNotices when someone identifies or stops being identified.
account-tagEach message says the account of whoever sent it.
chghostChanges of user or host without leaving and joining.
userhost-in-namesThe user list with nick!user@host.
invite-notifyInvitations of other people to your channels.
setnameReal name changes.
cap-notifyThe server adds or removes capabilities on the fly.
saslSASL identification (PLAIN and EXTERNAL towards the server; PLAIN from the clients).

With the clients

CapabilityWhat for
server-timeReal time of each message.
message-tagsTags on messages.
echo-messageYour own messages come back confirmed by the server.
batchGroups of messages (history, playback).
saslSASL identification (PLAIN and EXTERNAL towards the server; PLAIN from the clients).
draft/chathistoryThe client asks for the history it needs (CHATHISTORY).
draft/event-playbackThe history includes joins, parts, kicks and nick changes as real events.
draft/read-markerRead markers shared between devices.
soju.im/bouncer-networksAll your networks in a single connection.
soju.im/bouncer-networks-notifyNotices of changes in your networks.
extended-joinJoins carry the account and the real name.
away-notifyNotices when someone goes away or comes back.
account-notifyNotices when someone identifies or stops being identified.
account-tagEach message says the account of whoever sent it.
chghostChanges of user or host without leaving and joining.
multi-prefixEvery rank of a user (@+), not only the highest.
userhost-in-namesThe user list with nick!user@host.
invite-notifyInvitations of other people to your channels.
setnameReal name changes.
cap-notifyThe server adds or removes capabilities on the fly.

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.

FieldContents
report, formatxbnc-diagnostics, format version 1.
version, brandxBNC version and “xBNC v1.0.0 - https://xbnc.org”.
os, arch, databaseSystem, architecture and database (sqlite or postgresql).
started_at, generated_atWhen xBNC started and when the report was generated.
timezone, languageYour time zone and language.
countersServer counters (traffic, messages, reconnections, logins).
networks[]Per network: name, host, port, tls, enabled, whether it has SASL or a server password, saved_channels, active modules and plugins, and live.
networks[].livestate, server, network_name, connected_since, last_error, caps_offered, caps_acked, isupport, services_logged_in, host_hidden, channels_joined and clients (device and capabilities of each one).

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

Module (crates/xbncd/src)What it does
main.rsThe xbncd command: running the service and the command line (users, networks, backups, import, languages, releases, updates).
configReading and validating xbnc.toml.
db, sqlStorage: versioned migrations, users, networks, channels, messages, cursors, audit log and backups; sql gives SQLite (rusqlite) and PostgreSQL the same interface.
cryptoArgon2id, XChaCha20-Poly1305 encryption of the stored credentials and a Secret type that is never printed.
authThe login format, password checks, the brute-force limiter and the masking of lines in the logs.
utilIRC line codec (length limit, lossy UTF-8, protection against CR/LF injection) and time helpers.
network/The task of each network of each user: connection to the IRC server, state, history and attached clients. mods.rs and extra.rs hold the behaviour of the modules, status.rs and status_more.rs the *status, *notes and *watch commands, plugins.rs delivers events to plugins, dcc.rs decides which DCC offers go through xBNC and readmark.rs keeps the read markers.
downstream, bouncer, eventsClient connections: registration, CAP, SASL, PASS and relaying to the network task; soju.im/bouncer-networks; notices to clients when a network changes.
modulesCatalogue of the modules, schema and validation of their settings and the typed configuration per network.
performTurns client-style commands (/msg, /mode…) into IRC, for the commands on connect, aliases and scheduled tasks.
logsLog files, written in a separate thread.
certsClient certificates (generation, validation and fingerprints) and trusted server certificates.
fishFiSH encryption: Blowfish ECB and CBC and the DH1080 key exchange.
i18nLanguages: the built-in English and Spanish and the files of locales_dir.
netinfoLocal network addresses and the address shown for 0.0.0.0.
server, haShared context, the registry of network tasks, TLS listeners, maintenance and reloading; active/standby high availability with PostgreSQL.
rbac, settingsThe five roles and their permissions; history settings and limits editable live (database over xbnc.toml).
totp, webauthn, ssoTwo-step verification (RFC 6238), passkeys, OpenID Connect and LDAP.
tzTime zones with daylight saving time, with the database built in.
metrics, alertsTraffic and message counters, process memory and CPU; alert rules checked every 30 s, with notices in the panel, over IRC and by webhook.
notify, pushNotifications by Telegram, Discord, e-mail, your own web address and Web Push.
plugins, plugin_dev, catalogWebAssembly plugins: manifest, validation, the Wasmi engine with limits, instances and actions; development mode; the built-in catalogue and the signed remote one.
dccReading and rewriting DCC offers and the one-use relays.
httpA minimal HTTP/1.1 client (verified TLS, bounded size and time) for webhooks, notifications, plugins with web access and update checks.
updates, releaseNew version notices, downloading and checking packages, the xbncd apply-update helper and Ed25519 signatures.
backupBackups from the panel and restoring them.
importMigration from another bouncer: reading its configuration, module data, plan, applying it in one transaction and importing logs.
web/HTTP server (axum): the /api/v1 API, WebSocket, sessions, CSRF, headers and the panel files built into the binary.

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

TableContentsSince migration
usersUser, Argon2id hash, role, limits and quotas, encrypted TOTP secret, language, time zone, bind host, last login and last connection.1 (2, 4, 8, 9, 10)
networksServer, port, TLS, nick, SASL, commands on connect, client certificate, backup servers and trusted certificates; passwords and keys encrypted.1 (3, 4, 10)
channelsSaved channels per network, with an encrypted key, retention, disabled and position.1 (8, 10)
messagesHistory: network, conversation, time, sender, command, text, outgoing and mention.1 (8)
client_cursorsLast message delivered per network and device.1
audit_logAdministrative actions.1
web_sessionsPanel sessions (token hash, CSRF, IP, browser, expiry).2
settingsSettings changed from the panel.2
login_eventsLogin attempts over IRC and in the panel (10,000 at most).2
module_configModules per network: enabled and validated JSON settings.4
notesEach user's notes.4
messages_ftsFull-text index of messages.text, kept in sync by triggers (SQLite; PostgreSQL uses its own text search).5
api_tokensAPI tokens: SHA-256 hash, prefix, scope, expiry, last use and IP.6
pluginsInstalled plugins: manifest, SHA-256, size, enabled on the server, approved web domains and the module itself.7 (8)
plugin_configPlugins per network: enabled, settings and saved state.7
plugin_kvEach plugin's key-value store per network.8
notify_settingsNotification settings of each user.8
push_subscriptionsWeb Push subscriptions of each user's browsers.8
read_markersLast message read in each conversation.8
passkeysPasskeys: credential, public key, counter, name and last use.8
user_identitiesOutside identities (OpenID Connect, LDAP) linked to local users.8

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

AssetWhy it matters
Passwords of the xBNC accountsThey give access to the networks, the history and, for administrators, the whole server.
Network credentials (SASL, server password, channel keys, commands on connect, services passwords, FiSH keys, certificates)They allow impersonating the user on the networks.
History and logsPrivate conversations and channels: personal information.
Panel sessions and API tokensAs good as the password while valid.
The secret key (secret.key)Decrypts every stored credential.
The availability of the serviceIf it goes down, users lose messages and presence.
The reputation of the server's IPEvery connection leaves from it.

Who may attack

ActorWhat they controlWhat they try
Anyone on the internetConnections to the IRC, panel and DCC portsGuess passwords, exhaust resources, exploit the parser.
Someone on an IRC networkMessages, CTCP, DCC, channel names and nicksInject commands, make xBNC connect to internal networks, flood the history.
A malicious IRC serverEverything coming through a network's connectionThe above, plus malformed answers, huge lines and disconnection loops.
An xBNC userTheir account, networks, modules and pluginsRead other people's data, escalate to administrator, abuse the server.
An administratorOther people's users and networksEscalate to superadministrator, change global settings.
The author of a pluginThe code a superadministrator installsEscape the sandbox, read data, act without permission.
The author of a language fileA file an administrator copies to locales_dirInject IRC commands or HTML through the texts (refused: they are validated and treated as plain text).
A malicious websiteThe browser of a signed-in userCSRF, session theft, WebSocket hijacking.
Whoever gets the backupsThe .tar.gz filesCredentials and conversations.

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)

ThreatMeasure
Password brute forcePer-IP blocking shared with the panel and tokens; Argon2id; the same cost for users that do not exist.
Exhausting connections or memoryGlobal connection limit, 16 unauthenticated per IP, clients per user, registration time and bounded queues.
Huge or binary lines8703-byte limit per line and lossy UTF-8.
Command injection with CR/LFAny CR or LF cuts the line; texts of modules, plugins and language files are validated without control characters.
Plain text on the internetPorts without TLS only accept the local network or require insecure = true.
Credentials in the logsMasking of PASS, AUTHENTICATE, OPER and messages to services at every level.

Connections to the IRC networks

ThreatMeasure
Server impersonationTLS verified with the system store, with no option to turn it off; a trusted certificate only accepts its exact SHA-256 fingerprint.
Malformed answersOwn parser without unsafe, with tests and fuzzing.
History floodingConfigurable retention, optional events, bounded queues; the log module drops lines if the disk cannot keep up; hide flooding channels.
Disconnection loopsGrowing delays with random variation and a minimum wait after throttling notices.
Being thrown out for floodingRate limiting on the output.
Theft of the services passwordOn networks without NickServ it is never sent in automatic mode.

DCC

ThreatMeasure
Using the bouncer to reach internal networks (SSRF)Offers to internal addresses or ports below 1024 refused unless the user allows them.
Making xBNC connect to a third partyFor your own sends it only connects back to your device's IP.
Ports open indefinitelyOne port per offer, a single connection, a timeout, closing when idle and a size limit.
Hijacking the transferWhen receiving, the port only accepts the client's IP.

Web panel and API

ThreatMeasure
CSRFCSRF token in a header, SameSite=Strict cookie and Origin check.
XSSReact escapes all content; CSP without external or inline scripts; IRC texts are never interpreted as HTML; translations are plain text.
Session theftHttpOnly and Secure cookie; only the token's SHA-256 in the database; sliding expiry; changing the password closes the other sessions.
WebSocket hijackingOrigin check, the session revalidated every 30 s and no API tokens.
Privilege escalationPermissions checked on the server in every route; nobody changes their own role; there is always a superadministrator.
Seeing other users' dataOther people's networks answer 404, not 403.
API abuse and slowloris20 requests/s per IP, bounded bodies, 64 connections per IP and 4,096 in total, closing after 2 minutes without traffic, 10 s for the TLS handshake.
Leaked tokensScope, expiry, last use and IP visible, immediate revocation, only their SHA-256 stored.
Stolen first accessOne-time code, only in the service log.
Webhook to internal sitesOnly a superadministrator configures it; no redirects, no credentials in the URL, 10 s at most.

Plugins

ThreatMeasure
Escaping the sandboxWasmi interpreter without JIT, module validated when loaded, no WASI nor imports other than xbnc's, advanced WebAssembly features turned off.
Blocking or crashing the serverFuel per event, limited memory, execution that never grows the native stack, calls in separate threads, stopping after five failures.
Acting without permissionDeclarative actions checked against the permissions; dangerous commands always forbidden; maximum messages per event; web access only to approved domains and with limits.
Reading other people's dataEach instance only receives the events of its network; state and store separated per network.
File changed after installationIts SHA-256 is stored and it is not loaded if it does not match; files 0600.
Malicious plugin installedOnly a superadministrator installs, seeing permissions and fingerprint; recorded in the audit log; signed remote catalogue.

Import from another bouncer

ThreatMeasure
File crafted to create a superadministratorThe import never grants that role.
Weak inherited passwordsSalted SHA-256 compared in constant time and replaced by Argon2id; formats that cannot be checked get a random password.
Abusive paths or sizesFile up to 4 MB, limited nesting, validated names; logs are only read from the folders given.
Leaks in the previewThe preview includes no secrets.

Updates from the panel

ThreatMeasure
Fake package (compromised download server, DNS or network)Ed25519 signature over the package name and its SHA-256; the public key is only in xbnc.toml, owned by root.
Going back to a version with known flawsEqual or older versions than the installed one are refused.
A compromised xbnc process trying to install something as rootThe helper (xbnc-update.service) trusts nothing in the service's folder: it copies the package to /run (0700), checks the signature and the version on that copy, never follows symbolic links, validates the file name and uses each request only once.
Fake update requestOnly superadministrators, from a panel session (not with API tokens) and with CSRF; recorded in the audit log.
Endless downloads or redirects to plain text200 MB and 10 minutes at most; https:// only, 5 redirects at most.

Data at rest and backups

ThreatMeasure
Theft of the databaseNetwork credentials encrypted with XChaCha20-Poly1305; the key outside the database, with 0600 permissions checked at start.
Theft of a backup0600 file; it includes the key, so it must be stored encrypted.
Access from other users of the systemService run as the unprivileged xbnc user, 0700 folders and systemd hardening.

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

Users and networksClientsMessages/s deliveredCPU (of one core)MemoryLatency p50 / p95 / p99Every network back after an outage
5005004925 %52 MB21 / 43 / 46 ms6.2 s
5005004,84743 %56 MB46 / 64 / 72 ms6.2 s
1,0001,0001,95117 %88 MB50 / 80 / 95 ms6.2 s
1,0002,0001,96811 %114 MB44 / 66 / 78 ms6.2 s
2,0002,0001,96819 %153 MB75 / 141 / 155 ms6.3 s
  • 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

ProblemBeforeAfter
Memory after many simultaneous logins: glibc kept in each thread the 19 MB of every Argon2id calculation.1,680 MB with 500 clients55 MB (util::tune_allocator, a fixed mmap threshold)
Hundreds of Argon2id calculations at once (also useful against floods of login attempts).No limitOne per CPU (crypto::with_hash_slot)
One SQLite transaction per stored message.p50 70 ms and 13 % CPU with 500 networksp50 21 ms and 5 % CPU: a single writer thread stores everything waiting in one transaction (Db::insert_message)

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

SetWhereWhat it covers
Protocol (16)crates/xbnc-protoParser and serialiser, tag escaping, prefixes, casemapping, ISUPPORT, CTCP.
Units of the service (159)crates/xbncd/srcConfiguration, Argon2id, encryption and key permissions, database and migrations (SQLite and PostgreSQL, and upgrading an old schema), history and search, cursors, sessions, backups, login, brute-force limiter, log masking, codec, CAP, roles, settings, TOTP (RFC 6238 vectors), metrics, tokens, cookies, origin, IP behind a proxy, OpenAPI coverage, HTTP→HTTPS redirect, module catalogue and validation, globs, mentions, aliases, logs, client and trusted certificates (with a real TLS handshake), FiSH, time zones, languages (every key used exists, Spanish complete, files checked and loaded), plugins (permissions, limits, fuzzing regressions), DCC, HTTP client, release signatures, the update helper and connection limits, which names a TLS certificate is valid for, and the panel address shown after installing, and the texts of the installer (complete in English and Spanish, checked in any language file, and every key the scripts use exists).
API (13)tests/api.rsFirst run with a one-time code, login, sessions, CSRF, origin, headers, brute force, networks, channels, history, export, isolation between users, roles, live settings, 2FA, panel, OpenAPI, modules, certificates, notes, language, tokens, metrics, alerts, import and plugins.
End to end (16)tests/e2e.rsThe whole bouncer against a simulated IRC server (scenarios below).
Modules (18 + 12)tests/modules.rs, tests/modules_v1.rsEach module against the simulated server: away and summary, keep nick, replies to the device that asked, events, CTCP, sticky channels, aliases, auto op, rejoin after a kick, watch words, MOTD and logs; and the modules of 1.0: IRCv3 extras only for clients that asked, services login (X with the hidden host and Login on Connect), invite, ignore and remove colours, FiSH in both directions and DH1080, detached channels, flooding channels, autocycle, Latin-1 and scheduled tasks.
*status commands (12)tests/status_commands.rsGrouped help, other bouncers' command names, backup servers (added, jumped to, promoted and automatic switch), trusted fingerprints, bind hosts, disabled and ordered channels, buffers, MOTD and broadcast, permissions, networks from IRC and a language added as a file.
Plugins (2 + 5 + 7)tests/plugins.rs, tests/plugins_v1.rs, tests/official_plugins.rsPlugins answering on the network and to the user, and each official plugin: seen, trivia, greet, factoids, karma, quotes, games, badwords, web access only to approved sites, reminders, tell, polls, channel stats, anti-flood, dice and autoresponder.
Shared port (2)tests/shared_port.rsThe panel and IRC on one TLS port: a browser gets the panel, an IRC client the bouncer, plain http:// is sent to https:// and an IRC client without SSL is told to turn it on.
Panel (3)tests/panel.rsChat in the panel, mentions and channel history, plugin development mode and the one-click catalogue.
SSO (3)tests/sso.rsPasskeys, OpenID Connect and LDAP.
Command line (2)tests/cli.rsxbncd info run as a real process: the panel at the address given at installation, and no error when its output goes into head.
PostgreSQL (1)tests/postgres.rsMoving an SQLite database to PostgreSQL (with XBNC_TEST_POSTGRES).
Real IRC server (1)tests/real_ircd.rsA real xBNC against a real IRC server (see below).
Rust SDK (3)sdk/rustEvents and answers of the SDK.

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.
  13. With /mode $nick +x in the commands on connect, no JOIN reaches the server (saved channels, those in the commands, a client's own) until the server hides the host (396).
  14. /msg *status joinnow joins the held channels.
  15. A wrong password gets the right format, and the address is blocked after the failures with the minutes left and where to unblock it.
  16. The example password (“YOUR_PASSWORD”) is explained and does not block the address.

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:

TargetWhat it receives
irc_messageArbitrary IRC lines: parser, serialiser and the round trip.
dccDCC offers.
import_configConfiguration files of another bouncer.
search_querySearch queries against the full-text index.
plugin_manifestWebAssembly files with arbitrary manifests.
plugin_runtimeArbitrary WebAssembly modules loaded and run as plugins.
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.