bouncer/docs/DEBUG.md

Debugging

Verbose Mode

bouncer -c config/bouncer.toml -v

Shows: SOCKS5 connections, DNS resolution, IRC registration, state transitions, K-line detection, nick changes, channel joins, client events, backlog replay.

Log Format

HH:MM:SS LEVEL module message

Connection States in Logs

Log message	Meaning
connecting to ...	SOCKS5 + TLS handshake starting
connected, registering as <nick>	Random identity sent to server
registered as <nick>	Server accepted registration (001)
probation started (15s)	Watching for K-line
server ERROR: ... (K-Lined)	K-lined during probation
probation passed, connection stable	Safe to reveal identity
switching nick: <random> -> <real>	Changing to configured nick
nick changed: <old> -> <new>	Server confirmed nick change
joined #channel	Channel join successful
reconnecting in Ns (attempt N)	Backoff before retry

Common Issues

K-lined on every attempt

All SOCKS5 exit IPs may be banned on the target network. The bouncer will keep retrying with exponential backoff, cycling through different exit IPs (DNS round-robin). This is expected behavior -- it will eventually find a clean IP if one exists.

Check which IPs are being tried:

bouncer -c config/bouncer.toml -v 2>&1 | grep 'trying\|K-Lined\|Banned'

"config not found"

bouncer -c /full/path/to/bouncer.toml

SOCKS5 proxy not running

ss -tlnp | grep 1080

SOCKS5 proxy can't reach server

Test connectivity directly:

curl --socks5 127.0.0.1:1080 -v telnet://irc.libera.chat:6697

If remote DNS fails, test with local resolution:

curl --socks5 127.0.0.1:1080 -v https://$(getent ahostsv4 irc.libera.chat | head -1 | awk '{print $1}'):6697 -k

Nick already in use

During probation (random nick): bouncer generates another random nick. After probation (configured nick): bouncer appends _ and retries.

WARNING bouncer.network [libera] nick in use, trying mynick_

TLS certificate errors

All TLS connections use the system CA store. Self-signed certs are not currently supported.

Connection drops after registration

Typical for networks that ban proxy/VPN IPs. The bouncer handles this: detects the K-line, waits with backoff, reconnects with fresh identity.

Inspecting the Backlog

sqlite3 config/bouncer.db

-- recent messages
SELECT datetime(timestamp, 'unixepoch', 'localtime') as time,
       network, sender, target, command, content
FROM messages ORDER BY id DESC LIMIT 20;

-- message counts per network
SELECT network, COUNT(*) as msgs FROM messages GROUP BY network;

-- last client disconnect per network
SELECT network, last_seen_id,
       datetime(last_disconnect, 'unixepoch', 'localtime') as disconnected
FROM client_state;

-- search messages
SELECT * FROM messages WHERE content LIKE '%keyword%' ORDER BY id DESC LIMIT 10;

Watching Live Logs

Run bouncer in foreground with verbose:

bouncer -c config/bouncer.toml -v 2>&1 | grep -v aiosqlite

The grep -v aiosqlite filters out noisy SQLite debug lines.

Container Debugging

Logs

podman logs -f bouncer                          # follow
podman logs --tail 50 bouncer                   # last 50 lines
podman logs bouncer 2>&1 | grep -E 'INFO|WARN'  # important only
podman logs bouncer 2>&1 | grep -v aiosqlite    # filter sqlite noise

No log output from container

Two things must be set:

1. PYTHONUNBUFFERED=1 in the Containerfile
2. logging: driver: k8s-file in compose.yaml

Verify log driver:

podman inspect bouncer --format '{{.HostConfig.LogConfig.Type}}'

Container exits immediately

podman logs bouncer

Likely causes: missing config file, SOCKS5 proxy not running, TOML syntax error.

Shell into running container

podman exec -it bouncer bash