CatFlapRelay 1.2.0
dotnet add package CatFlapRelay --version 1.2.0
NuGet\Install-Package CatFlapRelay -Version 1.2.0
<PackageReference Include="CatFlapRelay" Version="1.2.0" />
<PackageVersion Include="CatFlapRelay" Version="1.2.0" />
<PackageReference Include="CatFlapRelay" />
paket add CatFlapRelay --version 1.2.0
#r "nuget: CatFlapRelay, 1.2.0"
#:package CatFlapRelay@1.2.0
#addin nuget:?package=CatFlapRelay&version=1.2.0
#tool nuget:?package=CatFlapRelay&version=1.2.0
<div align="center">
๐ฑ Cat Flap Relay
<div align="center"> <img src="./README/CatFlapRelay.png" width="128" /> </div>
A modern, easy-to-manage, cross-platform TCP/UDP port forwarding toolkit built with .NET 10
English | ็ฎไฝไธญๆ
</div>
Cat Flap Relay is a dual-stack (IPv4 & IPv6) port relay toolkit. It ships as two components:
| Component | Use Case |
|---|---|
| CatFlapRelay.CLI | Lightweight command-line tool โ spin up a TCP/UDP relay in seconds |
| CatFlapRelay.Panel | Full-featured management panel (Blazor + REST API) โ manage multiple relays via browser or API, runs in Docker |
NuGet Library
The core relay engine is available as a standalone NuGet package for embedding into your own .NET applications.
dotnet add package CatFlapRelay
Or via the Package Manager Console:
Install-Package CatFlapRelay
Usage
Step 1 โ Choose a logger
Both APIs accept any ILoggerFactory. Pick whichever suits your project:
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
// No logging (silent) โ zero dependencies
ILoggerFactory loggerFactory = NullLoggerFactory.Instance;
// Built-in console logger โ no extra packages needed
ILoggerFactory loggerFactory = LoggerFactory.Create(b => b.AddConsole());
// Serilog โ install Serilog.Extensions.Logging + a sink of your choice
var serilog = new LoggerConfiguration()
.MinimumLevel.Information()
.WriteTo.Console()
.CreateLogger();
ILoggerFactory loggerFactory = LoggerFactory.Create(b => b.AddSerilog(serilog));
// ASP.NET Core / Generic Host โ resolve from DI
// ILoggerFactory loggerFactory = app.Services.GetRequiredService<ILoggerFactory>();
Step 2A โ Direct instantiation via FlapRelayOption
using CatFlapRelay;
var factory = new FlapRelayFactory(loggerFactory);
var relay = factory.CreateRelay(new FlapRelayOption
{
Name = "MyRelay",
ListenHost = "0.0.0.0:8080",
TargetHost = "192.168.1.100:3389",
TCP = true,
UDP = true,
BufferSize = 131072,
});
relay.Start();
// ...
await relay.StopAsync();
Step 2B โ Fluent builder via RelayBuilder
using CatFlapRelay;
var relay = FlapRelayFactory.CreateBuilder(loggerFactory)
.WithName("MyRelay")
.ListenOn("0.0.0.0:8080")
.ForwardTo("192.168.1.100:3389")
.WithBufferSize(131072)
.WithUdpSenderCount(1) // power of two, 1-64
.WithSocketTimeout(TimeSpan.FromMilliseconds(1000))
.EnableTCP()
.EnableUDP() // or .TCPOnly() / .UDPOnly()
.EnableDualMode() // optional: accept IPv4 on [::] socket (Linux only needs this)
.Build();
relay.Start();
// ...
await relay.StopAsync();
Package page: https://www.nuget.org/packages/CatFlapRelay/
Quick Start โ CLI
Install & Run
# Build from source
dotnet build CatFlapRelay.CLI -c Release
catflaprelay-cli --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, 4 sender workers for many clients at high packet rates
catflaprelay-cli -l [::]:53 -t 8.8.8.8:53 --no-tcp --udp-senders 4
# 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
| Flag | Short | Description | Default |
|---|---|---|---|
--listen |
-l |
Listen endpoint (ip:port, an IP address; host names are not supported) |
required |
--target |
-t |
Target endpoint (ip:port, an IP address; host names are not supported) |
required |
--name |
-n |
Relay display name | Relay_XXXX |
--no-tcp |
Disable TCP forwarding | false |
|
--no-udp |
-U |
Disable UDP forwarding | false |
--buffer-size |
-b |
TCP I/O buffer size in bytes (not used by UDP) | 131072 (128 KB) |
--timeout |
Socket timeout in milliseconds | 1000 |
|
--udp-senders |
Number of UDP sender workers (power of two, 1โ64). Packets of one client always use the same sender, so order is preserved. Only raise for very high packet rates from many clients. | 1 |
|
--dual-mode |
Accept IPv4 connections on an IPv6 socket ([::]). Linux defaults to IPv6-only (RFC 3493); this flag mirrors Windows behaviour. |
false |
|
--verbose |
-v |
Enable debug logging | false |
--quiet |
-q |
Suppress info logging | false |
--log-level |
Set the log level explicitly: Verbose, Debug, Information, Warning, Error, Fatal. Takes precedence over -v / -q |
Information |
Management Panel (Docker)
The Panel provides a web-based dashboard with Ant Design UI and a Swagger-documented REST API for managing multiple relays.
- Create, edit, start, stop and delete relays from the browser; the configuration is stored in SQLite.
- Live statistics per relay: active TCP connections, UDP tunnels, bytes transferred, errors, and UDP datagrams dropped when the relay is overloaded (the
Droppedvalue turns red while it is still growing). - Per-relay settings for TCP/UDP, buffer size, timeouts, UDP sender workers and dual-stack mode.
- The Swagger UI is embedded under API in the sidebar and is also available at
/swagger.
<div align="center"> <img src="./README/Demo.jpg" /> </div>
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 athttp://<host-ip>:8080.
If
Admin__Passwordis 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_ADMINfrom your normal deployment to prevent resetting on every restart.
Panel Configuration
Configurable via appsettings.json or environment variables (__ replaces :, for example PanelSettings__MaxRelays):
| Key | Description | Default |
|---|---|---|
PanelSettings:MaxRelays |
Maximum number of relays | 256 |
PanelSettings:MaxNameLength |
Max relay name length | 128 |
PanelSettings:MaxEndpointLength |
Max host:port string length | 64 |
PanelSettings:MaxBufferSize |
Max I/O buffer size (bytes) | 67108864 (64 MB) |
Admin:UserName |
Initial admin user name | admin |
Admin:Password |
Initial admin password; a random one is generated and logged when empty | (empty) |
JwtSettings:Key |
Hex key used to sign JWTs; generated on every start when empty, which invalidates existing tokens on restart | (empty) |
Cors:AllowedOrigins |
Browser origins allowed to call the API | (none) |
DataPath |
Directory of the SQLite database; an unwritable path falls back to an in-memory database | data (/app/data in Docker) |
ConnectionStrings:DefaultConnection |
SQLite connection string | Data Source=data/app.db; |
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","expiryDays":30}' | 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 + senders โ
โโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโ
โ โ
โโโโโโโดโโโโโโโโโโโ โโโโโโโดโโโโโโโโโโโโโโโโโโโ
โ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
Bug report
Open an issue.
Contribution
PR is welcome.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.15)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.