c5b0430da8
- docker-compose.yml for podman-compose deployment - Makefile: add up/down/logs compose targets - README: plugin table, container quickstart, make targets - PROJECT: plugin categories, deployment matrix, design decisions - ROADMAP: v0.1 done, v0.2 current, v0.3-v1.0 planned - TASKS: current sprint with priorities - TODO: full backlog organized by wave - CHEATSHEET: reorganized by category (OSINT, Red Team, OPSEC) - INSTALL: container deployment instructions - DEBUG: container logs, hot-reload, DNS troubleshooting - USAGE: all 19 commands documented Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
118 lines
2.7 KiB
Markdown
118 lines
2.7 KiB
Markdown
# Debugging
|
|
|
|
## Verbose Mode
|
|
|
|
```bash
|
|
derp --verbose # Bare metal
|
|
make up # Compose (--verbose in compose file)
|
|
podman run ... derp --verbose # Manual container
|
|
```
|
|
|
|
Shows all IRC traffic:
|
|
|
|
```
|
|
>>> NICK derp
|
|
>>> USER derp 0 * :derp IRC bot
|
|
<<< :server 001 derp :Welcome
|
|
>>> JOIN #test
|
|
```
|
|
|
|
## Log Levels
|
|
|
|
Set in `config/derp.toml`:
|
|
|
|
```toml
|
|
[logging]
|
|
level = "debug" # debug, info, warning, error
|
|
```
|
|
|
|
Or override with `--verbose` flag (forces debug).
|
|
|
|
## Container Logs
|
|
|
|
```bash
|
|
make logs # podman-compose
|
|
podman logs -f derp # direct
|
|
```
|
|
|
|
## Common Issues
|
|
|
|
### Connection refused
|
|
|
|
```
|
|
ERROR derp.irc connection lost: [Errno 111] Connection refused
|
|
```
|
|
|
|
- Check `host` and `port` in config
|
|
- Verify TLS setting matches port (6697 = TLS, 6667 = plain)
|
|
- Test connectivity: `nc -zv <host> <port>`
|
|
- In container: ensure DNS resolution works (check `/etc/resolv.conf`)
|
|
|
|
### Nickname in use
|
|
|
|
The bot appends `_` to the nick and retries automatically:
|
|
|
|
```
|
|
<<< :server 433 * derp :Nickname is already in use
|
|
>>> NICK derp_
|
|
```
|
|
|
|
### TLS certificate errors
|
|
|
|
For self-signed certificates, set `tls_verify = false` in config:
|
|
|
|
```toml
|
|
[server]
|
|
tls_verify = false
|
|
```
|
|
|
|
### Plugin load failures
|
|
|
|
```
|
|
ERROR derp.plugin failed to load plugin: plugins/broken.py
|
|
```
|
|
|
|
- Check plugin for syntax errors: `python -c "import py_compile; py_compile.compile('plugins/broken.py')"`
|
|
- Ensure handlers are `async def`
|
|
- Check imports (`from derp.plugin import command, event`)
|
|
- In container with mounted plugins: verify mount path and permissions
|
|
|
|
### No response to commands
|
|
|
|
- Verify `prefix` in config matches what you type
|
|
- Check that the plugin is loaded: `!plugins`
|
|
- Ensure the bot has joined the channel (check logs for `JOIN`)
|
|
- Try `!ping` first to confirm basic connectivity
|
|
|
|
### Hot-reload issues
|
|
|
|
- `!reload <plugin>` re-reads the file from disk
|
|
- In container: plugins are mounted read-only, edit on host then `!reload`
|
|
- Core plugin cannot be unloaded (but can be reloaded)
|
|
- Check logs for `loaded plugin` / `unloaded plugin` messages
|
|
|
|
### DNS plugin timeouts
|
|
|
|
- The DNS plugin uses raw UDP to the system resolver
|
|
- In container: resolver is typically `127.0.0.11` (Podman DNS)
|
|
- Fallback: `8.8.8.8` if no resolver found in `/etc/resolv.conf`
|
|
|
|
## Testing IRC Connection
|
|
|
|
```bash
|
|
# Test raw IRC (without the bot)
|
|
openssl s_client -connect irc.libera.chat:6697
|
|
# Then type: NICK testbot / USER testbot 0 * :test
|
|
```
|
|
|
|
## Inspecting State
|
|
|
|
From IRC, use these commands:
|
|
|
|
```
|
|
!plugins # List loaded plugins + handler counts
|
|
!help <plugin> # Show plugin description + commands
|
|
!uptime # Bot uptime
|
|
!version # Running version
|
|
```
|