Common problems
Always start with the log and with *status: sudo journalctl -u xbnc -n 100 --no-pager and, from your client, /msg *status status.
Installation
| Symptom | Likely cause | Solution |
|---|---|---|
| “The build failed” and “Killed” in the output | The machine ran out of memory while building (it needs about 2 GB, swap included). | Add swap and run the installer again: sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile |
| “The ready-made binary does not run on this system” | The system is older than 2019 (glibc older than 2.28). | Nothing to do: the installer builds it by itself. It takes a few minutes. |
| “Rust could not be installed” | The server cannot reach https://sh.rustup.rs (firewall or proxy). | Allow HTTPS to sh.rustup.rs and static.rust-lang.org, or install Rust by hand and run the installer again. On x86_64 this step is not needed: the program comes ready-made. |
| “about 3 GB of free space are needed” | Not enough disk to build. | Free space, or unpack the .zip on a disk with more room. |
| “systemd is required” | The system does not use systemd (Alpine, containers). | Use Docker (see Docker above) or a distribution with systemd. |
You cannot connect
| Symptom | Likely cause | Solution |
|---|---|---|
| The client says “invalid certificate” | You installed by IP with a self-signed certificate. | Accept the certificate in the client or move to a domain: sudo ./scripts/install.sh --reconfigure --domain … --letsencrypt … |
| Wrong user or password (user “…”) | Wrong user or password. | The server password is user/network@device:password, with the panel user and password. The panel shows yours ready to copy in Networks → your network; sudo xbncd info lists them. |
| “YOUR_PASSWORD” is the example | The example was copied without the password. | Write your password after the colon. It does not count as a failed attempt. |
| Too many failed logins from your address (…): it is blocked for N more minutes | IP blocked after failures, on IRC and in the panel. A client reconnecting by itself with a wrong password blocks it again and again. | Correct (or close) the client, then unblock the IP in Security → Blocked IPs, or wait. |
| There is no network called “…” in your account | The network in the server password is not one of yours. | Use the short name of the network as the panel shows it (the message lists them). |
| Say which network to use in the server password | You have several networks and did not say which. | Add /network to the user. |
| Your account has no networks yet | The account has no network, or it is disabled. | Add one in Networks → Add network, or enable it. |
| From home, the domain does not connect | Your router does not support NAT loopback (hairpin NAT). | From home use the local IP of the xBNC machine (From your local network, in the panel). |
| By the local IP, the client rejects the certificate | The certificate is for the domain (Let's Encrypt), not for the IP. | Use port 6667 without SSL from home, or turn on “accept invalid certificates”. |
| this port uses SSL/TLS. Enable SSL… | You connect to 6697 without SSL. | Turn on SSL or use 6667 from your local network. |
| this port only accepts connections from the local network | You use 6667 from outside. | Use 6697 with SSL. |
| The client does not connect and nothing appears in the log | The client does not reach the machine (IP, port or firewall). | sudo xbncd info; from the client: openssl s_client -connect IP:6697 (Linux) or Test-NetConnection IP -Port 6697 (Windows). |
| Log: client sent TLS to a plain-text port | The client has SSL on against 6667. | Turn SSL off or use 6697. |
| Log: TLS handshake failed | The client does not accept the self-signed certificate. | Turn on “accept invalid certificates” or use --domain with --letsencrypt. |
Problems with a network
| Symptom | Likely cause | Solution |
|---|---|---|
| *status: connection failed: … invalid peer certificate | Invalid IRC server certificate (self-signed or expired) or missing root certificates. | sudo apt install ca-certificates; check the host and the TLS port. If the network uses its own certificate, trust it with /msg *status addfingerprint FINGERPRINT. |
| *status: registration timed out | Wrong port (TLS against a port without TLS or the other way round). | Check the network's port and TLS (Undernet: 6667 without TLS). |
| SASL authentication failed | Wrong SASL account or password. | Correct them in the network configuration. |
| SASL is configured but this server does not offer SASL PLAIN | The network does not support SASL. | Remove SASL and use Services login. |
| Your host is trying to (re)connect too fast -- throttled | The network slows down repeated reconnections from your IP. | Wait; xBNC waits at least 2 minutes. Do not click Connect several times. |
| The channels are not joined: “Your host is still not hidden after … seconds” | +x was asked for (commands on connect or Services login) but the network has not hidden the host, usually because the X login failed. | Check the account and password of X; xBNC joins as soon as the host is hidden. /msg *status joinnow joins right away, with the real host. |
| The login with X, Q or AuthServ does not work | Wrong services account or password. | Check Services login; the reason arrives through *status. |
| On IRCnet it does not identify | IRCnet has no NickServ; xBNC does not send the password on purpose. | Use SASL from sasl.ircnet.com on the network, or nothing. |
| The nick ends in “_” | The nick was taken when connecting. | Turn on Keep nick or type /nick your-nick. |
| xBNC keeps changing my nick | Keep nick goes back to the saved nick. | /msg *status setnick new, or turn the module off. |
| I see “�” instead of accented letters | Rare: xBNC converts Latin-1 to UTF-8. | If it is the other person who cannot see your accents, add their channel or nick in Character encoding. |
| The client certificate does not identify | The fingerprint is not in your account, the network does not use TLS or you did not reconnect. | Add the fingerprint (SHA-512 on Libera, SHA-1 on OFTC) and reconnect. |
Modules and plugins
| Symptom | Likely cause | Solution |
|---|---|---|
| /msg *plugin only shows “Usage: MSG <nick> <message>” | That is your client's help: you wrote nothing after the name. | /msg *poll help. |
| An alias does nothing | Your client does not send commands it does not know. | /quote name arguments. |
| The autoop module does not give op | You do not have op, the mask does not match or the other person does not answer the challenge. | Check the real user@host with /whois, and the key. |
| A plugin with web access does not answer | Its sites are not approved. | A superadministrator approves them in Plugins (“Sites it may connect to”). |
| A plugin has stopped on a network | It failed five times in a row. | Look at the Plugins log; turn it off and on again after fixing it. |
| No log files appear | The log module is off or there are no permissions on /var/lib/xbnc/logs. | Turn it on; the service log says if it cannot write. |
| Scheduled tasks run at another time | Your time zone is not set. | Your account → Time zone. |
Panel and service
| Symptom | Likely cause | Solution |
|---|---|---|
| The panel does not load (connection refused) | [web] is missing or it listens on 127.0.0.1. | sudo xbncd info; to redo the configuration, sudo ./scripts/install.sh --reconfigure. |
| “The page was out of date” | Old CSRF token after signing in again. | Reload the page. |
| “Request refused because it came from another site” | public_url does not match the browser's address. | Correct public_url or use that address. |
| After signing in you are back at the sign-in page | Secure cookie over HTTP without TLS. | Use HTTPS or localhost (or secure_cookies = false, for testing only). |
| Everyone gets blocked behind Nginx | Without trust_proxy, everything comes from 127.0.0.1. | trust_proxy = true and the X-Forwarded-For header in Nginx. |
| secret key file … not found; run xbncd init first | Not initialised. | sudo -u xbnc xbncd init. |
| secret key … is accessible by other users | Key permissions too open. | sudo chmod 600 /var/lib/xbnc/secret.key && sudo chown xbnc:xbnc /var/lib/xbnc/secret.key. |
| listener … has no TLS certificate | Public port without TLS. | Add tls_cert and tls_key, use lan_only or 127.0.0.1. |
| database schema version N is newer than this binary supports | You went back to an older binary. | Use the new binary or restore the previous backup. |
| Changes made from the command line do not show | The service was not reloaded. | sudo systemctl reload xbnc. |
| A new language does not appear in the panel | The file is not in locales_dir, has another name or xBNC was not reloaded. | xbncd locales check FILE; copy it to /etc/xbnc/locales/CODE.json and sudo systemctl reload xbnc. The log says which languages were loaded. |
| The client disconnects on its own with a lot of traffic | The client's queue filled up. | Increase client_queue; when it comes back it gets what was pending. |
| Playback was truncated | There were more than playback_max pending messages. | Increase playback_max or use a client with draft/chathistory. |
| You lost the setup code | — | sudo xbncd setup-code, or create the user from the command line. |
| You lost the phone with two-step verification | — | sudo -u xbnc xbncd user reset-2fa user. |
| You forgot the password of the only administrator | — | sudo -u xbnc xbncd user passwd user. |
More detail in the log
# In /etc/xbnc/xbnc.toml: [log] level = "info,xbncd=debug"
sudo systemctl restart xbnc
sudo journalctl -u xbnc -f
sudo journalctl -u xbnc --since "1 hour ago" -p warning
With trace every IRC line is logged (with credentials masked). Go back to info when done: with debug, nicks and channels appear.
Testing the beta
Version 1.0.0 is being tested on real networks (Undernet, Libera.Chat, freenode, Rizon, EvilNet, IRCnet and others) before it is declared stable.
- Install it and add your networks.
- Follow the test plan in
testenv/real/PLAN.md: one section per network, module and plugin. - If something fails, download the test report from Your account.
- Send it with what you did, what you expected, what happened, the network, the client, the approximate time, the version (
/msg *status version) and the warnings of the log (sudo journalctl -u xbnc --since "1 hour ago" | grep -E "WARN|ERROR"; review it before sending it).
If the project is on GitHub, use the “Test report” issue template. Security flaws are not made public: follow SECURITY.md.
Known limits
- Undernet and QuakeNet do not offer TLS: the connection to those networks is unencrypted.
- FiSH is old cryptography (Blowfish, without integrity): it protects from the network's servers, it is no replacement for end-to-end encryption. Decrypted messages are stored in your history like the rest.
- Some clients do not send commands they do not know: aliases need
/quote. - DCC between an IPv6-only client and an IPv4-only one is not translated.
- Search by pieces of words is only used when there are no whole-word matches.
- If the process stops abruptly, a few seconds of history may be repeated.
- In a language added as a file, the replies of the official plugins come in English (they speak English and Spanish).
- In this beta installation is from the source code; no .deb or .rpm packages are published.
- Still to be checked on real networks: login with X, NickServ, Q and AuthServ; invite and unban; plugins with web access; FiSH with real clients; installer with real systemd and Let's Encrypt; DCC between networks; SASL EXTERNAL; importer with real installations.