Files

user a58848395c docs: rewrite all documentation for stealth connect and current state

Update README, PROJECT, ROADMAP, TASKS, TODO, USAGE, CHEATSHEET,
INSTALL, and DEBUG to reflect stealth connect, probation window,
markov nick generation, local DNS resolution, and multi-IP failover.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-19 18:31:20 +01:00

3.1 KiB

Raw Blame History

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.

3.1 KiB Raw Blame History