Getting Started with TCP Warden

TCP Warden is distributed as a single static binary and as a multi-arch container image (ghcr.io/routewarden/tcp-warden:latest).

---

Deployment Options

Option 1: Docker Compose (Recommended)

Docker Compose provides automated persistent storage for configuration files, modular plugins, and audit logs.

services:  tcp-warden:    image: ghcr.io/routewarden/tcp-warden:latest    container_name: tcp-warden    restart: unless-stopped    # Linux: 'network_mode: host' for raw socket IP visibility.    # macOS/Windows: use 'ports:' (e.g. "9091:9091", "2222:2222") instead.    network_mode: host    environment:      - AUTO_INSTALL_PLUGINS=ssh postgres # Optional: auto-install plugins on boot    volumes:      - tcp-warden-config:/etc/routewarden      - tcp-warden-data:/var/lib/routewarden      - tcp-warden-logs:/var/log/routewardenvolumes:  tcp-warden-config:  tcp-warden-data:  tcp-warden-logs:

First-Run Template Auto-Creation

On initial boot, if /etc/routewarden/tcp-warden.yaml does not exist, TCP Warden automatically creates a fully-commented default configuration template in the tcp-warden-config volume.

Optional: CrowdSec Integration

CrowdSec integration is completely optional. If you want to connect TCP Warden to CrowdSec LAPI for collaborative threat intelligence, automated bouncers, and shared decision lists, follow the dedicated CrowdSec Integration Guide.

---

Verifying the Daemon

TCP Warden exposes an HTTP management endpoint on port 9091 (configurable via api.listen):

# Health checkcurl -s http://127.0.0.1:9091/health# {"status":"ok","version":"3.4.0"}# Active service statscurl -s http://127.0.0.1:9091/stats# Query service status./tcp-warden status --api http://127.0.0.1:9091

Output of ./tcp-warden status:

🛡️  TCP Warden Daemon Status (http://127.0.0.1:9091)
----------------------------------------------------------------------
SERVICE        PROTOCOL   ACTIVE CONNS   TOTAL ALLOWED   TOTAL BLOCKED
----------------------------------------------------------------------
ssh            ssh        0              12              1
smtp           smtp       0              5               0

---

Directory & Volume Layout

When deployed in production, TCP Warden organizes files across dedicated paths:

Path	Volume	What it stores
/etc/routewarden/tcp-warden.yaml	tcp-warden-config	Main configuration file (auto-generated on first boot).
/var/lib/routewarden	tcp-warden-data	Persistent runtime state: SQLite bans.db, installed plugins, and recompiled binary.
/var/log/routewarden/tcp-warden.jsonl	tcp-warden-logs	Structured audit log file recording all connection and security events.

---

Next Steps

• Explore Configuration Reference to configure proxy listeners, rate limits, and GeoIP rules.
• Review Modular Protocol Plugins to enable database and IoT protocol inspection.
• Optionally set up collaborative community threat defense with CrowdSec Integration (Optional).
• Query health and stream events via Management API & SSE.