# 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
```