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

Wiki Administration

Administration

Users and security, the configuration file, the command line, backups, monitoring, the REST API and updates.

Users, roles and security

Roles

RoleWho it is for
superadminEverything, including system settings, plugins, backups, updates, import and managing other administrators.
adminManages users (except administrators and superadministrators), every network and security; sees the system.
moderatorSees users and the audit log, and can suspend and reactivate normal and limited users.
userManages their own networks, channels and history. It is the default role.
limitedUses networks an administrator prepares for them; manages channels and history, but does not add, edit or delete networks.

What each role can do

Permissionsuperadminadminmoderatoruserlimited
Edit system settings, install plugins, backups, import, updateyes————
See the system, manage users, security and every networkyesyes———
See users and the audit log, suspend usersyesyesyes——
Manage their own networksyesyesyesyes—
Use their networks, channels, history, chat, modules and pluginsyesyesyesyesyes

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

AreaMeasure
PasswordsArgon2id (m = 19 MiB, t = 2, p = 1). A user that does not exist costs the same to check, so as not to reveal which accounts exist. At most one computation per CPU at a time, so a flood of attempts cannot exhaust the memory.
Stored credentialsSASL and server passwords, channel keys, commands on connect, services passwords, FiSH keys, TOTP secrets and certificate keys, encrypted with XChaCha20-Poly1305. The key lives outside the database (secret.key, permissions 0600 checked at start).
TLSrustls, TLS 1.2 and 1.3 only. Towards the networks the certificate is verified with the system store, with no option to turn it off. A trusted certificate (addfingerprint) accepts only that exact SHA-256 fingerprint, and the signatures of the TLS handshake are still checked.
Plain textForbidden on public addresses unless insecure = true is set explicitly. The default port without TLS only accepts the local network.
Brute forceIP blocked after 5 failures in 10 minutes for 15 minutes (configurable), shared between IRC (PASS and SASL), the panel and API tokens. At most 16 unauthenticated IRC connections per IP.
LogsPasswords, AUTHENTICATE, OPER and messages to services (NickServ IDENTIFY, X LOGIN, Q AUTH…) are never logged, at any level.
InputLines limited to 8703 bytes; any CR or LF inside a line cuts it, to prevent command injection; nicks, names and texts of modules and plugins validated.
ResourcesLimits on total connections and on clients and networks per user; bounded queues per client and towards the server; maximum registration time.
SQLEvery query uses bound parameters.
PrivilegesThe service runs as the unprivileged xbnc user, with systemd isolation. In Docker: unprivileged user, read-only, no capabilities.
Panel: sessionsA random 256-bit token in an HttpOnly, SameSite=Strict and Secure cookie; the database only holds its SHA-256. Sliding expiry (12 h by default).
Panel: CSRF and originCSRF token required on every request that changes something; requests and WebSockets with another site's Origin are refused.
Panel: headersStrict CSP without external or inline scripts, X-Frame-Options: DENY, nosniff, Referrer-Policy: no-referrer, HSTS with TLS and Cache-Control: no-store on the API.
Panel: abuse20 requests per second per IP, bodies up to 256 KB (4 MB for plugins), 64 connections per IP and 4,096 in total, closing after 2 minutes without traffic and 10 s for the TLS handshake. With trust_proxy the real IP behind Nginx is used.
First accessThe first account can only be created with a one-time code that the service writes to its log.
Secrets in the APIPasswords are never returned; only whether they exist.
API tokens256 bits with the xbnc_ prefix; only their SHA-256 is stored. Scope, expiry, last use and IP visible, immediate revocation.
ModulesBuilt into the program: no external code is loaded. Auto op: *!*@* is refused; with a key, a random challenge answered with HMAC-SHA256 and compared in constant time.
Log filesPaths built only from sanitised names (a channel cannot leave its folder), folders 0700 and files 0600.
PluginsWebAssembly in the Wasmi interpreter, with fuel (CPU) per event, 16 MB of memory, no access to files or a network of their own. Actions checked against the permissions. Only a superadministrator installs, seeing the SHA-256 fingerprint; a file that changes after installation is not loaded. Five failures in a row stop it.
DCCOffers from IRC cannot make xBNC connect to internal networks or to ports below 1024 (unless allowed). For your own sends it only connects back to your device's IP. Each port accepts a single connection, with a timeout, a size limit and closing when idle.
Services loginOn networks without NickServ (IRCnet, EFnet) automatic mode never sends the password.
TranslationsLanguage files are data, not code: an IRC text with line breaks or control characters, or with placeholders different from the English ones, is ignored. Files of 2 MB at most and 100 languages.
FiSHKey exchange accepts 5 requests per minute and 100 keys per session; decrypted text cannot break lines.
Webhookshttp(s) only, no user in the URL or control characters, certificate verified, no redirects followed, 10 s at most.
ImportSuperadministrators only; it never grants that role; the preview returns no secrets.
Audit logEvery action of the panel, of IRC and of the command line is recorded with date, author and detail (Security → Audit, or xbncd audit).
FuzzingIRC parser, DCC, importer, search, manifests and plugin execution, every week in CI with earlier failures as regressions.

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

KeyDefaultWhat it does
hostnamexbncServer name the clients see.
languageenDefault language of the IRC messages and of the panel: en, es or any language installed in locales_dir. Each user can choose their own. The installer sets the one you choose.
locales_dir/etc/xbnc/localesFolder of extra languages and corrections (one <code>.json file per language, see Translating xBNC). Read at start and on reload. The XBNC_LOCALES_DIR environment variable takes priority.
secret_key_filerequiredPath of the 32-byte key that encrypts the credentials. Created by xbncd init with permissions 0600. Back it up: without it they cannot be decrypted.

[database]

KeyDefaultWhat it does
pathrequiredSQLite file. Its folder is also the data folder (plugins, log files, backups).
url—PostgreSQL instead of SQLite: postgres://user:password@host/db. Add ?sslmode=require to encrypt the connection.
hafalseHigh availability (needs url): several nodes share the database; one works and the others wait to take over.

[[listen]] (one per port)

KeyDefaultWhat it does
addressrequiredAddress and port: 0.0.0.0:6697 or [::]:6697.
tls_cert—Certificate chain (PEM). Required unless insecure, lan_only or a loopback address.
tls_key—Private key (PEM).
insecurefalseAllow plain text on a public address (not recommended).
lan_onlyfalseLocal network clients only (loopback, private, link-local, CGNAT/Tailscale, IPv6 ULA). The rest get an explanatory ERROR. May go without TLS.

[web]

KeyDefaultWhat it does
addressrequiredAddress of the panel and the API, for example 0.0.0.0:8443 or 127.0.0.1:8080. Without [web], there is no panel.
tls_cert, tls_key—Certificate of the panel.
insecurefalseUnencrypted HTTP on a public address (only behind a TLS proxy on a trusted network).
secure_cookiestrue with TLSMarks the session cookie as Secure. Set it to true behind a TLS proxy.
public_url—Public URL of the panel (https://bnc.example.org). Used to check the Origin of requests and as the base for OpenID Connect.
session_hours12Session length in hours (sliding).
trust_proxyfalseTrust X-Forwarded-For and X-Real-IP from a proxy on loopback, so blocking uses the real IP.
sharedfalseServe the panel on the IRC port of address (one of the [[listen]] entries, with TLS): browsers get the panel and IRC clients the bouncer, on the same port, with the listener's certificate (leave tls_cert and tls_key out here).

[history]

KeyDefaultWhat it does
retention_days30Delete messages older than N days. 0, forever.
playback_max1000Maximum messages played back on reconnection.
new_client_playback100Messages for a device that had never connected.
chathistory_max500Maximum limit accepted in CHATHISTORY.

[limits]

KeyDefaultWhat it does
max_connections1000IRC client connections in total.
max_clients_per_user10Devices connected per user.
max_networks_per_user10Networks per user.
login_max_failures5Failures before an IP is blocked.
login_window_seconds600Window in which failures are counted.
login_block_seconds900Length of the block.
registration_timeout_seconds30Time for a client to complete its login.
client_queue4096Lines queued per client before disconnecting it as slow (when it comes back it gets what was pending).

[log]

KeyDefaultWhat it does
levelinfoFilter: error, warn, info, debug, trace, or per module (info,xbncd=debug). The RUST_LOG variable takes priority. Credentials are masked at every level.

[dcc]

KeyDefaultWhat it does
public_ipthe one xBNC uses towards the networkAddress announced on IRC. Needed behind NAT. If the connection to the network is IPv6, the public IPv4 is announced.
portsany free oneRange for the tunnels, for example 50000-50100 (open it in the firewall and the router). The installer writes 50000-50100 and opens it.

[smtp] (e-mail notifications)

KeyDefaultWhat it does
hostrequiredMail server.
port587Port.
securitystarttlsstarttls, tls (port 465) or none (local relays only).
username, password—Credentials.
fromrequiredSender, for example xBNC <xbnc@example.org>.

[oidc] (OpenID Connect)

KeyDefaultWhat it does
name—Text of the button (Google, Keycloak…).
issuerrequiredURL of the issuer; its /.well-known/openid-configuration is read.
client_id, client_secretrequiredDetails of the application registered with the provider. The return address is https://YOUR-PANEL/api/v1/auth/oidc/callback (uses public_url).
scopesopenid profile emailScopes requested.
username_claimpreferred_usernameClaim used as the name of automatically created accounts.
auto_createfalseCreate the xBNC account the first time someone signs in.
link_existingfalseLink with a local account of the same name (only with providers you control).
default_roleuserRole of the accounts created.
allowed_groups[] (everyone)If given, only members of one of these groups may sign in.
groups_claimgroupsClaim with the groups.

[ldap]

KeyDefaultWhat it does
urlrequiredldaps://host:636, or ldap://host:389 with starttls = true.
starttlsfalseUse STARTTLS.
bind_dnrequiredDN used to bind; {{username}} is replaced by the name typed.
ca_filesystem certificatesPEM file with the authority of the LDAP server.
auto_create, link_existing, default_rolefalse, false, userAs in [oidc].

[updates]

KeyDefaultWhat it does
checktrueCheck once a day whether there is a new version (and when an administrator asks). Downloads nothing.
repository—GitHub repository with the releases (owner/name).
url—Or any https URL answering {{"version", "url", "notes", "packages"}}.
public_key—Ed25519 public key of the releases. With it, and xBNC installed from a package, a superadministrator can update from the panel.

[catalog] (remote plugin catalogue)

KeyDefaultWhat it does
url—https:// address of the JSON index.
public_key—Ed25519 public key (base64) that signs the index.

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.

CommandWhat it doesOptions
xbncd runRuns the bouncer in the foreground (the service does this). SIGHUP (systemctl reload) re-reads networks, channels, users and languages.—
xbncd initCreates the database and the secret key.—
xbncd check-configChecks the configuration file and exits.—
xbncd infoShows the panel address and how clients connect.—
xbncd setup-codeShows the one-time code to create the first administrator.—
xbncd user add NAMECreates a user. The password is asked twice, read from standard input with --password-stdin or from XBNC_PASSWORD.--role superadmin|admin|moderator|user|limited (user by default); --admin (shortcut for --role superadmin); --password-stdin
xbncd user listLists the users.—
xbncd user passwd NAMEChanges the password.--password-stdin
xbncd user role NAME ROLEChanges the role.—
xbncd user enable|disable NAMEReactivates or suspends an account (after a reload, its networks disconnect).—
xbncd user reset-2fa NAMERemoves two-step verification (lost phone).—
xbncd user delete NAME --yesDeletes the user, their networks and their history.--yes (confirm)
xbncd network add USER NAME --host SERVERAdds a network. SASL and server passwords are asked for or read from XBNC_SASL_PASSWORD and XBNC_SERVER_PASSWORD.--port (6697); --no-tls; --nick; --username; --realname; --server-password; --sasl-user ACCOUNT
xbncd network list USERLists a user's networks.—
xbncd network enable|disable USER NAMEEnables or disables a network.—
xbncd network delete USER NAME --yesDeletes a network.--yes
xbncd channel add USER NETWORK CHANNELSaves a channel to join automatically.--key (asks for the channel key)
xbncd channel list USER NETWORKLists the saved channels.—
xbncd channel delete USER NETWORK CHANNELRemoves a saved channel.—
xbncd plugin install FILE.wasmInstalls or updates a plugin; each user turns it on in their networks.--yes (accept the permissions it asks for)
xbncd plugin listLists the installed plugins.—
xbncd plugin remove IDUninstalls a plugin and deletes its settings on every network.—
xbncd plugin check FILE.wasmChecks a plugin and shows its manifest.—
xbncd plugin pack PLUGIN.wasm MANIFEST.json -o OUTPUT.wasmPuts the manifest (JSON) inside a compiled plugin.-o, --output (required)
xbncd plugin catalog-keygen -o KEYTo publish a catalogue: creates the signing key (keep it safe).-o, --output
xbncd plugin catalog-entry FILE.wasm URLTo publish a catalogue: prints the index entry of a plugin published at URL (https://).—
xbncd plugin catalog-sign --key KEY INDEXTo publish a catalogue: signs the index (writes INDEX.sig).-k, --key
xbncd backup DESTINATIONConsistent copy of the database, with xBNC running.—
xbncd migrate-to-postgres URLCopies the SQLite database to a new, empty PostgreSQL one. Stop xBNC first; then set database.url.—
xbncd import PATHBrings users, networks, channels and modules from another bouncer (its data folder, with configs/ and users/, or its configuration file). Without --apply nothing is written.--apply; --logs (also the log files); --utc-offset ZONE (+02:00 or Europe/Madrid; +00:00 by default)
xbncd import-logs USER NETWORK FOLDERImports text logs (one folder per channel with YYYY-MM-DD.log files) into a network's history. Can be repeated without duplicating.--utc-offset ZONE
xbncd auditLatest administrative actions.--limit N (50)
xbncd release keygenTo publish releases: creates the signing key pair. The public key goes in [updates] public_key.--out FILE (xbnc-release.key)
xbncd release sign FILES…Writes FILE.sig next to each package. The private key is read from XBNC_RELEASE_KEY or from --key.--key
xbncd release verify --public-key KEY FILES…Checks the .sig signatures.—
xbncd apply-updateInstalls an update requested from the panel (run as root by the xbnc-update service; checks the signature again).—
xbncd locales check FILES…Checks language files against English: missing texts, texts xBNC does not use, broken {0} or <b> tags. Does not need the configuration.--missing (also lists what is missing)
xbncd locales listLanguages this server offers, with the share translated of each.—

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 other --host irc.example.net --sasl-user alice
sudo -u xbnc xbncd network add alice example --host irc.example.org --port 6667 --no-tls
sudo -u xbnc xbncd channel add alice other '#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

ScriptUse
scripts/install.shInstalls or reconfigures the service (see Installation).
scripts/update.sh [--binary PATH] [--build]Updates the binary with a backup first and automatic rollback.
scripts/prereqs.sh [--check]Installs what is needed to build xBNC (build tools and Rust), or with --check only says what is missing.
scripts/backup.sh [FOLDER] [--keep N]Live backup: database, secret key and /etc/xbnc in a 0600 .tar.gz (in /var/backups/xbnc, keeps 14).
scripts/restore.sh ARCHIVE [--with-config] [--yes]Restores a backup.sh copy. Keeps the current files as *.pre-restore-DATE.
scripts/uninstall.sh [--purge]Removes the service and the binary; with --purge, also configuration, data and the xbnc user.

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

WhatHow it ends up in xBNC
UsersWith their name. Administrators become admin (never superadmin). Users that already exist in xBNC are not touched.
PasswordsThose stored with salted SHA-256 keep working and move to Argon2id the first time each user signs in. Those in another format (MD5) get a new random password, shown only once.
NetworksServer, port, TLS, server password, nick, ident and real name. Disabled networks stay disabled. If there were several servers, the first is used (add the others afterwards as backup servers with /msg *status addserver). IPv6 servers are supported.
ChannelsWith their keys (encrypted). Disabled ones are not imported.
SASL, NickServ and commands on connectSASL goes to the network; the NickServ password and the commands on connect go to “Commands on connect” (encrypted). They need the data folder.
Client certificateImported if it is in the data folder and its key matches.
ModulesThe xBNC equivalent is turned on (table below).
LogsThe daily text files go into each network's history, with search. Can be repeated without duplicating.

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 example /path/to/logs/example --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.

Module of the previous bouncerIn xBNC
keepnickKeep nick
simple_away, away, autoaway, awaynickAutomatic away (with the delay and message of simple_away)
autoopAutomatic op and voice (add the entries again: the syntax is different)
kickrejoinRejoin after a kick (with its delay)
stickychanSticky channels (with the list)
buffextrasEvents in the history
logLog files
route_repliesReplies to whoever asked
certClient certificate
alias, watchAliases and Watch words (add the entries again)
block_motdHide the MOTD
ctcprepliesCTCP replies (with the reply to VERSION)
perform, nickserv, saslCommands on connect and the network's SASL
chansaver, savebuff, playback, clientbuffer, webadmin, controlpanel, fail2ban, lastseen, notes, clearbufferonmsg, simple_disconnect, missingmotd, certauth, listsockets, identfile, partylineAlready included in xBNC, always on

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

AlertFires whenDefault
network_downA network has been trying to connect for more than N minutes without success (those you disconnect do not count). Up to 10,080 (a week).15 minutes
failed_loginsThere are N or more failed sign-ins (IRC, panel and tokens) in the last 10 minutes.30
memoryThe process memory goes over N MB.off
databaseThe database goes over N MB.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/other",
  "message": "Network alice/other has been disconnected for more than 15 minutes",
  "since": 1762600000000,
  "text": "[xBNC bnc.example.org] firing: Network alice/other ...",
  "content": "[xBNC bnc.example.org] firing: Network alice/other ..."
}

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"]
MetricTypeWhat it measures
xbnc_infogaugeServer version (label version).
xbnc_uptime_secondsgaugeSeconds since it started.
xbnc_usersgaugeAccounts.
xbnc_networksgaugeConfigured networks.
xbnc_networks_running{state}gaugeConnections by state: connected, connecting, disconnected, reconnecting.
xbnc_irc_clientsgaugeConnected IRC clients.
xbnc_connectionsgaugeIRC connections open to the bouncer, also unauthenticated ones.
xbnc_blocked_ipsgaugeAddresses blocked after failures.
xbnc_server_bytes_received_total, xbnc_server_bytes_sent_totalcounterBytes received from and sent to the IRC servers.
xbnc_client_bytes_received_total, xbnc_client_bytes_sent_totalcounterBytes received from and sent to the clients.
xbnc_server_lines_totalcounterLines received from the servers.
xbnc_messages_stored_totalcounterMessages stored in the history.
xbnc_reconnects_totalcounterReconnections to IRC servers.
xbnc_client_logins_totalcounterSuccessful IRC client logins.
xbnc_failed_logins_totalcounterFailed logins (IRC and panel).
xbnc_history_messagesgaugeMessages stored in the history.
xbnc_database_bytesgaugeSize of the database.
xbnc_resident_memory_bytesgaugeProcess memory.
xbnc_log_lines_dropped_totalcounterLines of the log module dropped because the disk could not keep up.
xbnc_dcc_relays_totalcounterDCC sends and chats relayed by xBNC.
xbnc_dcc_bytes_totalcounterDCC bytes relayed by xBNC.
xbnc_alerts_firing{alert}gaugeActive alerts by type.

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.

ScopeCan
readGET requests only.
writeEverything your account can do, except signing out, changing the password, two-step verification, passkeys and creating or revoking tokens (those need a panel session and answer 403 session_required).
metricsGET /metrics only.

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":"example","host":"irc.example.org","port":6697,"tls":true,"nick":"bruno",
       "sasl_username":"bruno","sasl_password":"secret","channels":["#xbnc","#xbnc-dev"]}' $B/networks

All routes

MethodRouteWhat it doesWho
GET/healthHealth check.no session
GET/i18nInstalled languages (code, name, share translated, translators) and the server's default language.no session
GET/i18n/{code}Panel texts in one language: English text → translation.no session
GET, POST/setupFirst setup with the one-time code.no session
POST/auth/loginSign in: {username, password, totp_code}. Returns the xbnc_session cookie and the csrf field.no session
POST/auth/logoutClose the session.session
GET/auth/meYour account, your permissions and the CSRF token.session or token
GET/auth/methodsWays of signing in the server offers (passkeys, OpenID Connect, LDAP).no session
GET/auth/oidc/startRedirects to the OpenID Connect provider.no session
GET/auth/oidc/callbackReturn from the OpenID Connect provider.no session
POST/auth/passkey/optionsStarts signing in with a passkey (WebAuthn challenge).no session
POST/auth/passkeySigns in with the passkey's answer.no session
GET/dashboardSummary of the Home page (global for administrators).session or token
GET/presetsWell-known networks for the wizard.session or token
GET, POST/networksList (?all=true: every network, administrators) and create networks: {user_id, name, host, port, tls, nick, username, realname, server_password, sasl_username, sasl_password, channels, on_connect}.create: user or above
GET, PATCH, DELETE/networks/{id}Show with live state, edit (an omitted secret is kept, "" deletes it) and delete.owner or admin
POST/networks/{id}/control{action: connect | disconnect | jump}.owner or admin
GET, POST/networks/{id}/channelsChannels, with disabled and position (joining order); add {name, key}.owner or admin
DELETE/networks/{id}/channels/{name}Remove a channel (encode # as %23).owner or admin
PUT/networks/{id}/channels/{name}/historyRetention of the channel: {retention_days: null (server setting) | -1 (do not store) | 0 (forever) | N days}.owner or admin
DELETE/networks/{id}/clients/{client}Disconnect a device.owner or admin
GET/networks/{id}/conversationsConversations with their number of messages.owner or admin
GET, DELETE/networks/{id}/historySearch: target, q, sender, before_id, from, to, limit (up to 500), newest first. DELETE deletes (?target= one conversation).owner or admin
GET/networks/{id}/history/exportDownload: ?format=txt|json and ?target=.owner or admin
GET/networks/{id}/chatWebSocket of the panel chat: the panel as one more IRC client. Messages {line: "PRIVMSG #xbnc :hello"} in both directions.owner only, session
GET, PUT/networks/{id}/on-connectCommands on connect: {commands: "/msg X login …"}; empty deletes them.owner or admin
GET, PUT, DELETE/networks/{id}/certClient certificate: SHA-1/256/512 fingerprints; upload {certificate, private_key} in PEM; delete. The key is never returned.owner or admin
POST/networks/{id}/cert/generateGenerate a new certificate.owner or admin
GET/modulesModule catalogue: ids, settings with type and limits.session or token
GET/networks/{id}/modulesState of a network's modules (secrets empty, plus secrets_set).owner or admin
PUT/networks/{id}/modules/{module}{enabled, config}: validated and applied at once. An empty secret keeps the stored one; null deletes it.owner or admin
GET/networks/{id}/pluginsPlugins of a network.owner or admin
PUT/networks/{id}/plugins/{plugin}{enabled, config}.owner or admin
GET/mentionsMessages that mention you, newest first (?before=ms&limit=).session or token
GET/notesYour notes.session or token
PUT, DELETE/notes/{key}Save {text} (up to 400 characters) or delete a note.session or token
PUT/me/language{language: code of an installed language (en, es…) | ""} (empty: the server's).session or token
PUT/me/timezone{timezone: "Europe/London"} (IANA name; empty: UTC).session or token
PUT/me/passwordChange your password (closes your other sessions).session only
PUT/me/avatarProfile photo: the image bytes with Content-Type image/png, image/jpeg or image/webp (at most 256 KB and 1024×1024 pixels; the real format is checked).session or token
DELETE/me/avatarRemove your profile photo.session or token
GET/users/{id}/avatarA user's photo: yours, or anyone's with view_users. The address with ?v= is in the avatar field of users and /auth/me.session or token
DELETE/users/{id}/avatarRemove a user's photo (manage_users, on roles below yours).session or token
POST/me/totp/setupStart turning on two-step verification (secret and QR code).session only
POST/me/totp/enableTurn it on with a code.session only
POST/me/totp/disableTurn it off.session only
GET, POST/me/passkeysYour passkeys; register one.session only
POST/me/passkeys/optionsStart registering a passkey.session only
DELETE/me/passkeys/{id}Remove a passkey.session only
GET, DELETE/me/identitiesLinked external accounts (OpenID Connect, LDAP); unlink.session only
POST/me/identities/oidcStart linking your OpenID Connect account.session only
GET, PUT/me/notificationsNotification settings (the Telegram token comes back hidden).session or token
POST/me/notifications/testSend a test notification to every channel.session or token
GET, POST, DELETE/me/pushDevices with push; subscribe {endpoint, keys: {p256dh, auth}, label}; remove {endpoint}.session or token
GET/push/keyVAPID public key for Web Push.session or token
GET/diagnosticsTest report: what each of your networks supports and how xBNC handled it (no secrets or messages).session or token
GET, POST/tokensYour tokens; create {name, scope: read | write | metrics, expires_days: 0–3650} (0: never expires). The token only comes in the answer.session only
DELETE/tokens/{id}Revoke a token.session only
GET/sessionsPanel sessions (?all=true: all of them, administrators).session
DELETE/sessions/{id}Close a session.session
GET, POST/usersList and create {username, password, role, max_networks, max_clients}.see: moderator; create: admin
GET, PATCH, DELETE/users/{id}Show, change {role, enabled, max_networks, max_clients, max_history_mb} (null removes the limit) and delete.depends on the role
POST/users/{id}/passwordReset the password (closes their sessions).admin
GET/users/{id}/usageNetworks, clients and history space used against their quotas.moderator
GET/securitySign-ins and blocked IPs.moderator
DELETE/security/blocked/{ip}Unblock an IP.admin
GET/auditAudit log.moderator
GET, PUT/settingsLive settings.see: admin; edit: superadmin
GET/systemVersion, database, listeners and counters.admin
POST/system/restartRestart xBNC (the service starts it again).superadmin
GET/alertsActive alerts.admin
GET/metricsMetrics in Prometheus format.admin or metrics token
GET/wsWebSocket of the Home page: a {type: "stats"} message every 2 seconds with the state of the networks and, for administrators, memory, CPU, clients, connections, blocked IPs and counters; {type: "logout"} when the session ends.session only
GET, POST/backupsBackups, staged restore and settings of the automatic ones; make a backup now.superadmin
GET, DELETE/backups/{name}Download or delete a backup.superadmin
POST/backups/{name}/restoreStage the restore of a backup on the server.superadmin
POST, DELETE/backups/restoreUpload a backup (.tar.gz) and stage it; cancel the staged restore.superadmin
GET/pluginsInstalled plugins.session or token
POST/pluginsInstall or update: the body is the .wasm (application/wasm, up to 4 MB).superadmin, session
POST/plugins/inspectCheck a .wasm without installing it.superadmin, session
PATCH, DELETE/plugins/{id}{enabled} on the server and approved domains; uninstall.superadmin, session
GET/plugins/catalogCatalogue: official plugins and signed remote catalogue.session or token
POST/plugins/catalog/{id}One-click install from the catalogue.superadmin, session
GET, PUT/plugins/devDevelopment mode: state and folder; turn it on or off.superadmin, session
GET/plugins/logsWebSocket with the plugins' log: last lines and new ones.superadmin, session
GET/updatesInstalled and latest published version, whether it can be updated from the panel and the result of the last update.admin
POST/updates/checkCheck now whether there is a new version.admin, session
POST/updates/installDownload, verify and install the signed package of the latest version.superadmin, session
POST/import/previewPreview of the import: {config: "file contents"}. Writes nothing.superadmin, session
POST/import/applyImport.superadmin, session

“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 .zip: it is updated by unpacking the new one and running 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.