Generic Layer 4 Proxy & Firewall (generic)
The Generic Layer 4 Plugin provides universal, protocol-agnostic TCP proxying and firewall capabilities. It protects custom services, proprietary TCP protocols, and raw sockets with high-performance connection rate limiting, CIDR allowlists and denylists, geo-IP filtering, automated tarpitting, and zero-copy byte piping.
Capabilities & Threat Defense
| Threat / Attack Vector | Defense Mechanism | Action Taken |
|---|---|---|
| TCP SYN Floods & Connection Spam | Token bucket rate limiting per client IP | Excess connections throttled or dropped |
| Port Scanners & Hostile Networks | CIDR allowlist / denylist filtering | Unauthorized networks rejected on Accept() |
| Automated Crawlers & Scrapers | TCP Tarpitting (tarpit) | Holds socket open with delayed bytes to burn attacker resources |
| Geographic Threat Actors | Geo-IP lookup and country filtering | Non-permitted countries blocked before proxying |
Installation
The generic protocol handler is built into RouteWarden core and also available as a standalone plugin from the official repository:
# Install using short nametcp-warden plugins install generic# Or install via Git repository URLtcp-warden plugins install https://github.com/routewarden/plugins/genericConfiguration Reference
Add a generic TCP proxy service to tcp-warden.yaml:
services: custom_tcp_guard: listen: ":15432" upstream: "127.0.0.1:5432" protocol: "tcp" # Or "generic", "raw" rate_limit: connections_per_minute: 120 burst: 30 tarpit: enabled: false initial_delay: "5s" max_delay: "30s" ip_filtering: allowed_cidrs: - "10.0.0.0/8" - "192.168.0.0/16" blocked_cidrs: - "198.51.100.0/24"Configuration Options
| Field | Type | Default | Description |
|---|---|---|---|
listen | string | Required | Local proxy listen address and port (":15432"). |
upstream | string | Required | Target backend server address and port ("127.0.0.1:5432"). |
protocol | string | "tcp" | Set to "tcp", "generic", or "raw". |
rate_limit.connections_per_minute | int | 0 | Max new connections allowed per minute per IP (0 = disabled). |
rate_limit.burst | int | 0 | Maximum burst capacity above the sustained limit. |
tarpit.enabled | bool | false | When true, delays responses to suspicious clients. |
ip_filtering.allowed_cidrs | []string | [] | List of allowed IP ranges. If set, unlisted IPs are dropped. |
ip_filtering.blocked_cidrs | []string | [] | List of explicitly blocked IP ranges. |
Network & Deployment Architecture
For non-privileged TCP ports (> 1024), RouteWarden simply acts as a standard Layer 4 reverse proxy or container gateway:
Option A: Direct Reverse Proxy
Direct clients to connect to RouteWarden's listen port, which inspects and forwards traffic to the backend target:
# Direct reverse proxy configurationservices: custom_app: listen: ":9000" upstream: "127.0.0.1:9001" # Or remote host "10.0.0.100:9000" protocol: "tcp"Option B: Docker Host Network Proxy
Run RouteWarden in network_mode: host to transparently guard backends running directly on the host or inside containers:
services: tcp-warden: image: ghcr.io/routewarden/tcp-warden:latest container_name: tcp-warden network_mode: host restart: unless-stopped volumes: - ./tcp-warden.yaml:/etc/routewarden/tcp-warden.yaml:roTesting & Verification
Verify TCP socket reachability and rate-limiting enforcement:
# Verify connectivity through generic proxync -zv 127.0.0.1 15432# Connection to 127.0.0.1 15432 port [tcp/*] succeeded!