CatFlapRelay 1.0.0

<div align="center">

🐱 Cat Flap Relay

<div align="center"> <img src="./README/CatFlapRelay.png" width="128" /> </div>

A modern, high-performance TCP/UDP port forwarding toolkit built with .NET 10

</div>

Cat Flap Relay is a dual-stack (IPv4 & IPv6) port relay toolkit. It ships as two components:

Quick Start — CLI

Install & Run

# Build from source
dotnet build CatFlapRelay.CLI -c Release

# On Linux / macOS
catflaprelay-cli --listen 0.0.0.0:8080 --target 192.168.1.100:3389

# On Windows
CatFlapRelay.CLI.exe --listen 0.0.0.0:8080 --target 192.168.1.100:3389

Examples

# Basic TCP+UDP relay
catflaprelay-cli -l 0.0.0.0:25565 -t 10.0.0.5:25565

# TCP only, custom name
catflaprelay-cli -l 0.0.0.0:8080 -t 192.168.1.10:80 --no-udp -n "WebProxy"

# UDP only with larger buffer (512 KB)
catflaprelay-cli -l [::]:53 -t 8.8.8.8:53 --no-tcp -b 524288

# IPv6 listen → IPv4 target (dual-stack bridge)
catflaprelay-cli -l [::]:443 -t 127.0.0.1:8443

# Verbose logging for debugging
catflaprelay-cli -l 0.0.0.0:5000 -t 10.0.0.1:5000 -v

CLI Options

Management Panel (Docker)

The Panel provides a web-based dashboard with Ant Design UI and a Swagger-documented REST API for managing multiple relays.

Deploy with Docker

docker run -d \
  --name catflap-panel \
  --network host \
  -v catflap-data:/app/data \
  -e Admin__UserName=admin \
  -e Admin__Password=YourSecurePassword \
  kingsznhone/catflap-relay:latest

Why --network host? CatFlap Relay forwards traffic between arbitrary ports on the host. Bridge networking adds a NAT layer that breaks relay functionality — host network mode gives the container direct access to all host interfaces and ports. The panel web UI is accessible at http://<host-ip>:8080.

If Admin__Password is not set, a random 16-character password will be generated and printed to the container logs. Check it with: docker logs catflap-panel

No persistent volume? The Panel will fall back to an in-memory SQLite database automatically. All data (relay configs, users) will be lost on restart — useful for quick testing but not recommended for production.

Docker Compose

services:
  catflap:
    image: kingsznhone/catflap-relay:latest
    container_name: catflap-panel
    restart: unless-stopped
    network_mode: host
    volumes:
      - catflap-data:/app/data
    environment:
      - Admin__UserName=admin
      - Admin__Password=YourSecurePassword
      - JwtSettings__Key=YOUR_HEX_SECRET_KEY   # optional, auto-generated if omitted
      # - Cors__AllowedOrigins__0=https://your-domain.com
      # - PanelSettings__MaxRelays=256
      # - PanelSettings__MaxBufferSize=67108864

volumes:
  catflap-data:

Reset Admin Password

Forgot your password? Set the CATFLAP_RESET_ADMIN environment variable:

# Reset with a new explicit password
docker run --rm \
  -v catflap-data:/app/data \
  -e CATFLAP_RESET_ADMIN=true \
  -e Admin__Password=MyNewPassword \
  kingsznhone/catflap-relay:latest

# Reset with an auto-generated password (check container logs)
docker run --rm \
  -v catflap-data:/app/data \
  -e CATFLAP_RESET_ADMIN=true \
  kingsznhone/catflap-relay:latest

Remove CATFLAP_RESET_ADMIN from your normal deployment to prevent resetting on every restart.

Panel Configuration

Configurable via appsettings.json or environment variables (PanelSettings__*):

REST API Examples

# Obtain a JWT token
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YourSecurePassword"}' | jq -r '.token')

# Create a relay
curl -X POST http://localhost:8080/api/v1/relay \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"GameServer","listenHost":"0.0.0.0:25565","targetHost":"10.0.0.5:25565"}'

# List all relays
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/relay

# Start all relays
curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/relay/start-all

Architecture

┌──────────────────────────────────────────────────┐
│                  CatFlapRelay                    │
│  FlapRelay ─ FlapRelayManager ─ FlapRelayFactory │
│  TCP stream relay  │  UDP tunnel relay           │
└──────────┬──────────────────┬────────────────────┘
           │                  │
     ┌─────┴──────────┐ ┌─────┴──────────────────┐
     │CatFlapRelay.CLI│ │  CatFlapRelay.Panel    │
     │ (Console)      │ │ Blazor SSR + REST API  │
     │ Single         │ │ Multi-relay management │
     │ relay mode     │ │ SQLite + JWT Auth      │
     └────────────────┘ └────────────────────────┘

Tech Stack

• .NET 10 — Latest runtime with AOT-friendly serialization
• System.CommandLine — CLI parsing
• Blazor Server + Ant Design — Panel UI
• ASP.NET Core Identity + JWT — Authentication
• Entity Framework Core + SQLite — Persistence
• Serilog — Structured logging

License

MIT © KingsZNHONE