Users, roles and security
Roles
| Role | Who it is for |
|---|---|
superadmin | Everything, including system settings, plugins, backups, updates, import and managing other administrators. |
admin | Manages users (except administrators and superadministrators), every network and security; sees the system. |
moderator | Sees users and the audit log, and can suspend and reactivate normal and limited users. |
user | Manages their own networks, channels and history. It is the default role. |
limited | Uses networks an administrator prepares for them; manages channels and history, but does not add, edit or delete networks. |
What each role can do
| Permission | superadmin | admin | moderator | user | limited |
|---|---|---|---|---|---|
| Edit system settings, install plugins, backups, import, update | yes | — | — | — | — |
| See the system, manage users, security and every network | yes | yes | — | — | — |
| See users and the audit log, suspend users | yes | yes | yes | — | — |
| Manage their own networks | yes | yes | yes | yes | — |
| Use their networks, channels, history, chat, modules and plugins | yes | yes | yes | yes | yes |
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
| Area | Measure |
|---|---|
| Passwords | Argon2id (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 credentials | SASL 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). |
| TLS | rustls, 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 text | Forbidden on public addresses unless insecure = true is set explicitly. The default port without TLS only accepts the local network. |
| Brute force | IP 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. |
| Logs | Passwords, AUTHENTICATE, OPER and messages to services (NickServ IDENTIFY, X LOGIN, Q AUTH…) are never logged, at any level. |
| Input | Lines 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. |
| Resources | Limits on total connections and on clients and networks per user; bounded queues per client and towards the server; maximum registration time. |
| SQL | Every query uses bound parameters. |
| Privileges | The service runs as the unprivileged xbnc user, with systemd isolation. In Docker: unprivileged user, read-only, no capabilities. |
| Panel: sessions | A 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 origin | CSRF token required on every request that changes something; requests and WebSockets with another site's Origin are refused. |
| Panel: headers | Strict 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: abuse | 20 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 access | The first account can only be created with a one-time code that the service writes to its log. |
| Secrets in the API | Passwords are never returned; only whether they exist. |
| API tokens | 256 bits with the xbnc_ prefix; only their SHA-256 is stored. Scope, expiry, last use and IP visible, immediate revocation. |
| Modules | Built 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 files | Paths built only from sanitised names (a channel cannot leave its folder), folders 0700 and files 0600. |
| Plugins | WebAssembly 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. |
| DCC | Offers 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 login | On networks without NickServ (IRCnet, EFnet) automatic mode never sends the password. |
| Translations | Language 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. |
| FiSH | Key exchange accepts 5 requests per minute and 100 keys per session; decrypted text cannot break lines. |
| Webhooks | http(s) only, no user in the URL or control characters, certificate verified, no redirects followed, 10 s at most. |
| Import | Superadministrators only; it never grants that role; the preview returns no secrets. |
| Audit log | Every action of the panel, of IRC and of the command line is recorded with date, author and detail (Security → Audit, or xbncd audit). |
| Fuzzing | IRC 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
| Key | Default | What it does |
|---|---|---|
hostname | xbnc | Server name the clients see. |
language | en | Default 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/locales | Folder 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_file | required | Path 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]
| Key | Default | What it does |
|---|---|---|
path | required | SQLite 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. |
ha | false | High availability (needs url): several nodes share the database; one works and the others wait to take over. |
[[listen]] (one per port)
| Key | Default | What it does |
|---|---|---|
address | required | Address 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). |
insecure | false | Allow plain text on a public address (not recommended). |
lan_only | false | Local network clients only (loopback, private, link-local, CGNAT/Tailscale, IPv6 ULA). The rest get an explanatory ERROR. May go without TLS. |
[web]
| Key | Default | What it does |
|---|---|---|
address | required | Address 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. |
insecure | false | Unencrypted HTTP on a public address (only behind a TLS proxy on a trusted network). |
secure_cookies | true with TLS | Marks 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_hours | 12 | Session length in hours (sliding). |
trust_proxy | false | Trust X-Forwarded-For and X-Real-IP from a proxy on loopback, so blocking uses the real IP. |
shared | false | Serve 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]
| Key | Default | What it does |
|---|---|---|
retention_days | 30 | Delete messages older than N days. 0, forever. |
playback_max | 1000 | Maximum messages played back on reconnection. |
new_client_playback | 100 | Messages for a device that had never connected. |
chathistory_max | 500 | Maximum limit accepted in CHATHISTORY. |
[limits]
| Key | Default | What it does |
|---|---|---|
max_connections | 1000 | IRC client connections in total. |
max_clients_per_user | 10 | Devices connected per user. |
max_networks_per_user | 10 | Networks per user. |
login_max_failures | 5 | Failures before an IP is blocked. |
login_window_seconds | 600 | Window in which failures are counted. |
login_block_seconds | 900 | Length of the block. |
registration_timeout_seconds | 30 | Time for a client to complete its login. |
client_queue | 4096 | Lines queued per client before disconnecting it as slow (when it comes back it gets what was pending). |
[log]
| Key | Default | What it does |
|---|---|---|
level | info | Filter: error, warn, info, debug, trace, or per module (info,xbncd=debug). The RUST_LOG variable takes priority. Credentials are masked at every level. |
[dcc]
| Key | Default | What it does |
|---|---|---|
public_ip | the one xBNC uses towards the network | Address announced on IRC. Needed behind NAT. If the connection to the network is IPv6, the public IPv4 is announced. |
ports | any free one | Range 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)
| Key | Default | What it does |
|---|---|---|
host | required | Mail server. |
port | 587 | Port. |
security | starttls | starttls, tls (port 465) or none (local relays only). |
username, password | — | Credentials. |
from | required | Sender, for example xBNC <xbnc@example.org>. |
[oidc] (OpenID Connect)
| Key | Default | What it does |
|---|---|---|
name | — | Text of the button (Google, Keycloak…). |
issuer | required | URL of the issuer; its /.well-known/openid-configuration is read. |
client_id, client_secret | required | Details of the application registered with the provider. The return address is https://YOUR-PANEL/api/v1/auth/oidc/callback (uses public_url). |
scopes | openid profile email | Scopes requested. |
username_claim | preferred_username | Claim used as the name of automatically created accounts. |
auto_create | false | Create the xBNC account the first time someone signs in. |
link_existing | false | Link with a local account of the same name (only with providers you control). |
default_role | user | Role of the accounts created. |
allowed_groups | [] (everyone) | If given, only members of one of these groups may sign in. |
groups_claim | groups | Claim with the groups. |
[ldap]
| Key | Default | What it does |
|---|---|---|
url | required | ldaps://host:636, or ldap://host:389 with starttls = true. |
starttls | false | Use STARTTLS. |
bind_dn | required | DN used to bind; {{username}} is replaced by the name typed. |
ca_file | system certificates | PEM file with the authority of the LDAP server. |
auto_create, link_existing, default_role | false, false, user | As in [oidc]. |
[updates]
| Key | Default | What it does |
|---|---|---|
check | true | Check 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)
| Key | Default | What 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.
| Command | What it does | Options |
|---|---|---|
xbncd run | Runs the bouncer in the foreground (the service does this). SIGHUP (systemctl reload) re-reads networks, channels, users and languages. | — |
xbncd init | Creates the database and the secret key. | — |
xbncd check-config | Checks the configuration file and exits. | — |
xbncd info | Shows the panel address and how clients connect. | — |
xbncd setup-code | Shows the one-time code to create the first administrator. | — |
xbncd user add NAME | Creates 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 list | Lists the users. | — |
xbncd user passwd NAME | Changes the password. | --password-stdin |
xbncd user role NAME ROLE | Changes the role. | — |
xbncd user enable|disable NAME | Reactivates or suspends an account (after a reload, its networks disconnect). | — |
xbncd user reset-2fa NAME | Removes two-step verification (lost phone). | — |
xbncd user delete NAME --yes | Deletes the user, their networks and their history. | --yes (confirm) |
xbncd network add USER NAME --host SERVER | Adds 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 USER | Lists a user's networks. | — |
xbncd network enable|disable USER NAME | Enables or disables a network. | — |
xbncd network delete USER NAME --yes | Deletes a network. | --yes |
xbncd channel add USER NETWORK CHANNEL | Saves a channel to join automatically. | --key (asks for the channel key) |
xbncd channel list USER NETWORK | Lists the saved channels. | — |
xbncd channel delete USER NETWORK CHANNEL | Removes a saved channel. | — |
xbncd plugin install FILE.wasm | Installs or updates a plugin; each user turns it on in their networks. | --yes (accept the permissions it asks for) |
xbncd plugin list | Lists the installed plugins. | — |
xbncd plugin remove ID | Uninstalls a plugin and deletes its settings on every network. | — |
xbncd plugin check FILE.wasm | Checks a plugin and shows its manifest. | — |
xbncd plugin pack PLUGIN.wasm MANIFEST.json -o OUTPUT.wasm | Puts the manifest (JSON) inside a compiled plugin. | -o, --output (required) |
xbncd plugin catalog-keygen -o KEY | To publish a catalogue: creates the signing key (keep it safe). | -o, --output |
xbncd plugin catalog-entry FILE.wasm URL | To publish a catalogue: prints the index entry of a plugin published at URL (https://). | — |
xbncd plugin catalog-sign --key KEY INDEX | To publish a catalogue: signs the index (writes INDEX.sig). | -k, --key |
xbncd backup DESTINATION | Consistent copy of the database, with xBNC running. | — |
xbncd migrate-to-postgres URL | Copies the SQLite database to a new, empty PostgreSQL one. Stop xBNC first; then set database.url. | — |
xbncd import PATH | Brings 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 FOLDER | Imports 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 audit | Latest administrative actions. | --limit N (50) |
xbncd release keygen | To 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-update | Installs 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 list | Languages 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
| Script | Use |
|---|---|
scripts/install.sh | Installs 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>).
| What | How it ends up in xBNC |
|---|---|
| Users | With their name. Administrators become admin (never superadmin). Users that already exist in xBNC are not touched. |
| Passwords | Those 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. |
| Networks | Server, 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. |
| Channels | With their keys (encrypted). Disabled ones are not imported. |
| SASL, NickServ and commands on connect | SASL goes to the network; the NickServ password and the commands on connect go to “Commands on connect” (encrypted). They need the data folder. |
| Client certificate | Imported if it is in the data folder and its key matches. |
| Modules | The xBNC equivalent is turned on (table below). |
| Logs | The 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 bouncer | In xBNC |
|---|---|
keepnick | Keep nick |
simple_away, away, autoaway, awaynick | Automatic away (with the delay and message of simple_away) |
autoop | Automatic op and voice (add the entries again: the syntax is different) |
kickrejoin | Rejoin after a kick (with its delay) |
stickychan | Sticky channels (with the list) |
buffextras | Events in the history |
log | Log files |
route_replies | Replies to whoever asked |
cert | Client certificate |
alias, watch | Aliases and Watch words (add the entries again) |
block_motd | Hide the MOTD |
ctcpreplies | CTCP replies (with the reply to VERSION) |
perform, nickserv, sasl | Commands on connect and the network's SASL |
chansaver, savebuff, playback, clientbuffer, webadmin, controlpanel, fail2ban, lastseen, notes, clearbufferonmsg, simple_disconnect, missingmotd, certauth, listsockets, identfile, partyline | Already 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):
| Alert | Fires when | Default |
|---|---|---|
network_down | A 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_logins | There are N or more failed sign-ins (IRC, panel and tokens) in the last 10 minutes. | 30 |
memory | The process memory goes over N MB. | off |
database | The 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
*statusin 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"]
| Metric | Type | What it measures |
|---|---|---|
xbnc_info | gauge | Server version (label version). |
xbnc_uptime_seconds | gauge | Seconds since it started. |
xbnc_users | gauge | Accounts. |
xbnc_networks | gauge | Configured networks. |
xbnc_networks_running{state} | gauge | Connections by state: connected, connecting, disconnected, reconnecting. |
xbnc_irc_clients | gauge | Connected IRC clients. |
xbnc_connections | gauge | IRC connections open to the bouncer, also unauthenticated ones. |
xbnc_blocked_ips | gauge | Addresses blocked after failures. |
xbnc_server_bytes_received_total, xbnc_server_bytes_sent_total | counter | Bytes received from and sent to the IRC servers. |
xbnc_client_bytes_received_total, xbnc_client_bytes_sent_total | counter | Bytes received from and sent to the clients. |
xbnc_server_lines_total | counter | Lines received from the servers. |
xbnc_messages_stored_total | counter | Messages stored in the history. |
xbnc_reconnects_total | counter | Reconnections to IRC servers. |
xbnc_client_logins_total | counter | Successful IRC client logins. |
xbnc_failed_logins_total | counter | Failed logins (IRC and panel). |
xbnc_history_messages | gauge | Messages stored in the history. |
xbnc_database_bytes | gauge | Size of the database. |
xbnc_resident_memory_bytes | gauge | Process memory. |
xbnc_log_lines_dropped_total | counter | Lines of the log module dropped because the disk could not keep up. |
xbnc_dcc_relays_total | counter | DCC sends and chats relayed by xBNC. |
xbnc_dcc_bytes_total | counter | DCC bytes relayed by xBNC. |
xbnc_alerts_firing{alert} | gauge | Active 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.
| Scope | Can |
|---|---|
read | GET requests only. |
write | Everything 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). |
metrics | GET /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
POST /auth/loginwith{"username", "password"}(andtotp_codeif the account has two-step verification). The answer brings thexbnc_sessioncookie and, in the body,csrf.- Send the cookie with every request, and with POST, PUT, PATCH and DELETE the header
X-CSRF-Tokenwith that value (GET /auth/mereturns it again). - Requests with an
Originheader 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
| Method | Route | What it does | Who |
|---|---|---|---|
GET | /health | Health check. | no session |
GET | /i18n | Installed 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 | /setup | First setup with the one-time code. | no session |
POST | /auth/login | Sign in: {username, password, totp_code}. Returns the xbnc_session cookie and the csrf field. | no session |
POST | /auth/logout | Close the session. | session |
GET | /auth/me | Your account, your permissions and the CSRF token. | session or token |
GET | /auth/methods | Ways of signing in the server offers (passkeys, OpenID Connect, LDAP). | no session |
GET | /auth/oidc/start | Redirects to the OpenID Connect provider. | no session |
GET | /auth/oidc/callback | Return from the OpenID Connect provider. | no session |
POST | /auth/passkey/options | Starts signing in with a passkey (WebAuthn challenge). | no session |
POST | /auth/passkey | Signs in with the passkey's answer. | no session |
GET | /dashboard | Summary of the Home page (global for administrators). | session or token |
GET | /presets | Well-known networks for the wizard. | session or token |
GET, POST | /networks | List (?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}/channels | Channels, 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}/history | Retention 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}/conversations | Conversations with their number of messages. | owner or admin |
GET, DELETE | /networks/{id}/history | Search: 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/export | Download: ?format=txt|json and ?target=. | owner or admin |
GET | /networks/{id}/chat | WebSocket 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-connect | Commands on connect: {commands: "/msg X login …"}; empty deletes them. | owner or admin |
GET, PUT, DELETE | /networks/{id}/cert | Client 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/generate | Generate a new certificate. | owner or admin |
GET | /modules | Module catalogue: ids, settings with type and limits. | session or token |
GET | /networks/{id}/modules | State 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}/plugins | Plugins of a network. | owner or admin |
PUT | /networks/{id}/plugins/{plugin} | {enabled, config}. | owner or admin |
GET | /mentions | Messages that mention you, newest first (?before=ms&limit=). | session or token |
GET | /notes | Your 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/password | Change your password (closes your other sessions). | session only |
PUT | /me/avatar | Profile 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/avatar | Remove your profile photo. | session or token |
GET | /users/{id}/avatar | A 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}/avatar | Remove a user's photo (manage_users, on roles below yours). | session or token |
POST | /me/totp/setup | Start turning on two-step verification (secret and QR code). | session only |
POST | /me/totp/enable | Turn it on with a code. | session only |
POST | /me/totp/disable | Turn it off. | session only |
GET, POST | /me/passkeys | Your passkeys; register one. | session only |
POST | /me/passkeys/options | Start registering a passkey. | session only |
DELETE | /me/passkeys/{id} | Remove a passkey. | session only |
GET, DELETE | /me/identities | Linked external accounts (OpenID Connect, LDAP); unlink. | session only |
POST | /me/identities/oidc | Start linking your OpenID Connect account. | session only |
GET, PUT | /me/notifications | Notification settings (the Telegram token comes back hidden). | session or token |
POST | /me/notifications/test | Send a test notification to every channel. | session or token |
GET, POST, DELETE | /me/push | Devices with push; subscribe {endpoint, keys: {p256dh, auth}, label}; remove {endpoint}. | session or token |
GET | /push/key | VAPID public key for Web Push. | session or token |
GET | /diagnostics | Test report: what each of your networks supports and how xBNC handled it (no secrets or messages). | session or token |
GET, POST | /tokens | Your 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 | /sessions | Panel sessions (?all=true: all of them, administrators). | session |
DELETE | /sessions/{id} | Close a session. | session |
GET, POST | /users | List 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}/password | Reset the password (closes their sessions). | admin |
GET | /users/{id}/usage | Networks, clients and history space used against their quotas. | moderator |
GET | /security | Sign-ins and blocked IPs. | moderator |
DELETE | /security/blocked/{ip} | Unblock an IP. | admin |
GET | /audit | Audit log. | moderator |
GET, PUT | /settings | Live settings. | see: admin; edit: superadmin |
GET | /system | Version, database, listeners and counters. | admin |
POST | /system/restart | Restart xBNC (the service starts it again). | superadmin |
GET | /alerts | Active alerts. | admin |
GET | /metrics | Metrics in Prometheus format. | admin or metrics token |
GET | /ws | WebSocket 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 | /backups | Backups, 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}/restore | Stage the restore of a backup on the server. | superadmin |
POST, DELETE | /backups/restore | Upload a backup (.tar.gz) and stage it; cancel the staged restore. | superadmin |
GET | /plugins | Installed plugins. | session or token |
POST | /plugins | Install or update: the body is the .wasm (application/wasm, up to 4 MB). | superadmin, session |
POST | /plugins/inspect | Check a .wasm without installing it. | superadmin, session |
PATCH, DELETE | /plugins/{id} | {enabled} on the server and approved domains; uninstall. | superadmin, session |
GET | /plugins/catalog | Catalogue: official plugins and signed remote catalogue. | session or token |
POST | /plugins/catalog/{id} | One-click install from the catalogue. | superadmin, session |
GET, PUT | /plugins/dev | Development mode: state and folder; turn it on or off. | superadmin, session |
GET | /plugins/logs | WebSocket with the plugins' log: last lines and new ones. | superadmin, session |
GET | /updates | Installed and latest published version, whether it can be updated from the panel and the result of the last update. | admin |
POST | /updates/check | Check now whether there is a new version. | admin, session |
POST | /updates/install | Download, verify and install the signed package of the latest version. | superadmin, session |
POST | /import/preview | Preview of the import: {config: "file contents"}. Writes nothing. | superadmin, session |
POST | /import/apply | Import. | 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.