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

Wiki Help

Help

Common problems with their causes and solutions, and how to test the beta on real networks.

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

SymptomLikely causeSolution
“The build failed” and “Killed” in the outputThe 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

SymptomLikely causeSolution
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 exampleThe 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 minutesIP 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 accountThe 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 passwordYou have several networks and did not say which.Add /network to the user.
Your account has no networks yetThe account has no network, or it is disabled.Add one in Networks → Add network, or enable it.
From home, the domain does not connectYour 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 certificateThe 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 networkYou use 6667 from outside.Use 6697 with SSL.
The client does not connect and nothing appears in the logThe 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 portThe client has SSL on against 6667.Turn SSL off or use 6697.
Log: TLS handshake failedThe client does not accept the self-signed certificate.Turn on “accept invalid certificates” or use --domain with --letsencrypt.

Problems with a network

SymptomLikely causeSolution
*status: connection failed: … invalid peer certificateInvalid 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 outWrong 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 failedWrong SASL account or password.Correct them in the network configuration.
SASL is configured but this server does not offer SASL PLAINThe network does not support SASL.Remove SASL and use Services login.
Your host is trying to (re)connect too fast -- throttledThe 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 workWrong services account or password.Check Services login; the reason arrives through *status.
On IRCnet it does not identifyIRCnet 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 nickKeep nick goes back to the saved nick./msg *status setnick new, or turn the module off.
I see “�” instead of accented lettersRare: 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 identifyThe 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

SymptomLikely causeSolution
/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 nothingYour client does not send commands it does not know./quote name arguments.
The autoop module does not give opYou 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 answerIts sites are not approved.A superadministrator approves them in Plugins (“Sites it may connect to”).
A plugin has stopped on a networkIt failed five times in a row.Look at the Plugins log; turn it off and on again after fixing it.
No log files appearThe 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 timeYour time zone is not set.Your account → Time zone.

Panel and service

SymptomLikely causeSolution
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 pageSecure cookie over HTTP without TLS.Use HTTPS or localhost (or secure_cookies = false, for testing only).
Everyone gets blocked behind NginxWithout 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 firstNot initialised.sudo -u xbnc xbncd init.
secret key … is accessible by other usersKey permissions too open.sudo chmod 600 /var/lib/xbnc/secret.key && sudo chown xbnc:xbnc /var/lib/xbnc/secret.key.
listener … has no TLS certificatePublic 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 supportsYou went back to an older binary.Use the new binary or restore the previous backup.
Changes made from the command line do not showThe service was not reloaded.sudo systemctl reload xbnc.
A new language does not appear in the panelThe 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 trafficThe client's queue filled up.Increase client_queue; when it comes back it gets what was pending.
Playback was truncatedThere 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.

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

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

Known limits

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