9954a890c3
New docs/DEPLOY.md covering container image, compose config, volume mounts, host networking, operations, and troubleshooting. Updated README, INSTALL, CHEATSHEET, and DEBUG to reference it. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
164 lines
3.9 KiB
Markdown
164 lines
3.9 KiB
Markdown
# Debugging
|
|
|
|
## Verbose Mode
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
bouncer -c config/bouncer.toml -v 2>&1 | grep 'trying\|K-Lined\|Banned'
|
|
```
|
|
|
|
### "config not found"
|
|
|
|
```bash
|
|
bouncer -c /full/path/to/bouncer.toml
|
|
```
|
|
|
|
### SOCKS5 proxy not running
|
|
|
|
```bash
|
|
ss -tlnp | grep 1080
|
|
```
|
|
|
|
### SOCKS5 proxy can't reach server
|
|
|
|
Test connectivity directly:
|
|
|
|
```bash
|
|
curl --socks5 127.0.0.1:1080 -v telnet://irc.libera.chat:6697
|
|
```
|
|
|
|
If remote DNS fails, test with local resolution:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
sqlite3 config/bouncer.db
|
|
```
|
|
|
|
```sql
|
|
-- 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:
|
|
|
|
```bash
|
|
bouncer -c config/bouncer.toml -v 2>&1 | grep -v aiosqlite
|
|
```
|
|
|
|
The `grep -v aiosqlite` filters out noisy SQLite debug lines.
|
|
|
|
## Container Debugging
|
|
|
|
### Logs
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
podman inspect bouncer --format '{{.HostConfig.LogConfig.Type}}'
|
|
```
|
|
|
|
### Container exits immediately
|
|
|
|
```bash
|
|
podman logs bouncer
|
|
```
|
|
|
|
Likely causes: missing config file, SOCKS5 proxy not running, TOML syntax error.
|
|
|
|
### Shell into running container
|
|
|
|
```bash
|
|
podman exec -it bouncer bash
|
|
```
|