CrespoGuard Relay¶

TCP relay for RF Online servers. Community covers the self-hosted encrypted tunnel/proxy path with IP bans and rate limiting; paid tiers add dashboard/HWID/edge capabilities.

Overview¶

The CrespoGuard Relay sits between your players and your game server. It can provide encrypted login transport, transparent forwarding, rate limiting, and IP bans. Management dashboards and HWID ban workflows are paid-tier capabilities. Two connection modes are available:

Transparent Proxy (any RF client) — Plain TCP proxy. Works with any vanilla RF client. No launcher required.

Encrypted Tunnel (CrespoGuard Launcher) — AES-256-GCM encrypted tunnel. Requires CrespoGuard Launcher. Encrypts player credentials and game data in transit.

Both modes are available to Community operators when the relay package is deployed and configured.

Deployment Options¶

You choose where the relay runs. Self-hosted Community relay is the default; hosted/edge relay is a paid managed option.

Self-Hosted (Free with any tier)¶

You run the relay on your own machine or VPS. Community self-hosting covers the encrypted tunnel/proxy path, IP bans, and rate limiting. If the relay runs on a separate machine from your game server, players connect to the relay address instead of the origin game server. Dashboard, HWID bans, and managed edge routing are paid-tier capabilities.

Player                           Your VPS / Machine
┌────────────┐    plain TCP     ┌───────────────────┐      ┌──────────────┐
│ Any RF     ├──────────────────┤ CrespoGuard Relay ├──────┤ LoginServer  │
│ client     │  (transparent)   │ (port 10002)      │      │ (port 10001) │
└────────────┘                  │                   │      └──────────────┘
                                │ Rate limiting     │
┌────────────┐   AES-256-GCM    │ IP bans           │      ┌──────────────┐
│ CrespoGuard├──────────────────┤ GeoIP + threat DB ├──────┤ ZoneServer   │
│ Launcher   │   (encrypted)    │ Dashboard (paid)  │      │ (port 27780) │
└────────────┘                  └───────────────────┘      └──────────────┘

Edge-Hosted (Paid / Fortress Lane)¶

CrespoGuard can host relay infrastructure for paid deployments that need managed edge routing. Players connect to the assigned edge route instead of a server-owner-managed VPS.

Player                           CrespoGuard Edge            Your Server
┌────────────┐    plain TCP     ┌───────────────────┐      ┌──────────────┐
│ Any RF     ├──────────────────┤ CrespoGuard       ├──────┤ LoginServer  │
│ client     │  (transparent)   │ Edge Relay        │      │ (port 10001) │
└────────────┘                  │                   │      └──────────────┘
                                │ Rate limiting     │
┌────────────┐   AES-256-GCM    │ IP bans           │      ┌──────────────┐
│ CrespoGuard├──────────────────┤ GeoIP + threat DB ├──────┤ ZoneServer   │
│ Launcher   │   (encrypted)    │ Dashboard         │      │ (port 27780) │
└────────────┘                  │                   │      └──────────────┘
                                │ edge.crespoguard  │
                                │ .com              │
                                └───────────────────┘

Which should you choose?

	Self-Hosted (Free)	Edge-Hosted (Paid)
Cost	Free for the self-hosted Community relay path	Paid/provisioned per customer
IP masking	Yes, if relay is on a separate machine	Yes, always
Setup	You manage the relay binary and VPS	Provisioned by CrespoGuard, then configured in your launcher
Feature set	Community relay features	Follows the provisioned paid tier
Best for	Server owners who already have a VPS or want full control	Server owners who want IP masking without managing infrastructure

Pricing¶

Tier	Price	Max Players	Relay Capability
Community	Free	50	Self-hosted relay, IP bans, rate limiting, manual updates
Guard	$15/mo	50	Dashboard, HWID bans, combat features, IP masking
Shield	$30/mo	200	Multi-zone proxy, file logging
Fortress	$50-75/mo	500	Edge relays, PROXY protocol, health checks

Edge Routing¶

Paid edge routing can provide:

Managed IP masking without a server-owner VPS
CrespoGuard manages the relay binary, updates, and uptime
Players connect to edge.crespoguard.com with your route code
Feature set follows the provisioned customer tier
Available only when provisioned for the customer package/tier

v3.1 Features¶

GeoIP Country Filtering¶

Restrict connections by country. Only players from allowed countries can connect — all others are rejected before reaching your game server.

{
  "GeoIPEnabled": true,
  "GeoIPFile": "geoip.csv",
  "GeoIPAllowedCountries": ["US", "BR", "PH", "ID", "MY", "TH", "VN"]
}

Requires a geoip.csv database file. See Relay Databases for format specs, download sources, and example files.

ASN-Based Filtering¶

Block connections from known datacenter and VPN providers by Autonomous System Number (ASN). This catches proxy/VPN traffic that GeoIP alone misses — datacenter IPs are rarely legitimate RF Online players.

{
  "ASNBlockEnabled": true,
  "ASNBlockList": [12345, 67890]
}

Look up ASN numbers at ipinfo.io. Add ASN numbers to the ASNBlockList array. Connections from IPs belonging to those ASNs are rejected before reaching your game server.

Requires an asn.csv database file. See Relay Databases for format specs, download sources, and example files.

TCP Fingerprinting¶

Passive OS detection using TCP connection characteristics. Flags connections that don't match a Windows TCP stack — since RF Online only runs on Windows, non-Windows fingerprints indicate bots, proxied traffic, or attack tools.

Flagged connections are logged and optionally blocked. No client-side changes required — detection is fully passive.

{
  "TCPFingerprintEnabled": true,
  "TCPFingerprintMode": "flag"
}

Set TCPFingerprintMode to "block" to drop non-Windows connections, or "flag" to log without blocking.

Prometheus Metrics¶

Exposes relay metrics on a /metrics endpoint in Prometheus exposition format, served on the dashboard port. Grafana-ready out of the box. Prometheus metrics are enabled by default (PrometheusEnabled = true).

{
  "PrometheusEnabled": true
}

See the /metrics endpoint for the full list. Metrics are served on the same port as the dashboard (behind authentication — see Dashboard Authentication) — no separate port configuration needed.

Restrict the dashboard port to your monitoring infrastructure — do not expose it publicly.

Adaptive Rate Limiter¶

Burst-tolerant rate limiting — allows short spikes of legitimate reconnect activity (e.g., after a zone crash) without triggering false positives, while still blocking sustained floods.

{
  "RateLimitPerIP": 15,
  "RateLimitWindowSec": 60
}

Configure per-IP rate limits with RateLimitPerIP (max connections) and RateLimitWindowSec (time window in seconds).

Admin Portal Rate Limiting

The admin portal uses persistent rate limiting that survives restarts. The relay itself uses in-memory rate limiting, which is fine since it runs as a long-lived process.

Tor Exit Node Blocking¶

Tor exit nodes are blocked via URLs in the ThreatIntelURLs list — no separate toggle needed. Add a Tor exit node list URL to ThreatIntelURLs and the relay will automatically fetch and refresh it alongside other threat intel sources.

Connections from known Tor exit nodes are blocked alongside the existing Threat Intel and GeoIP layers.

Anti-Replay Protection¶

Anti-replay protection for the CGRD encrypted tunnel. Detects and rejects replayed packets. Prevents replay attacks without rejecting legitimate out-of-order delivery.

Async Rotating Logger¶

Structured log output with automatic rotation. Logs are written asynchronously to avoid blocking the relay's event loop.

{
  "LogToFile": true,
  "LogMaxSizeMB": 10,
  "LogMaxFiles": 5
}

Enable file logging with LogToFile. Each log file rotates at LogMaxSizeMB (default 10MB), keeping up to LogMaxFiles rotations (default 5). Output is structured for easy parsing by log aggregation tools.

Optimized Proxying¶

On Linux, the relay uses optimized zero-copy data transfer between sockets for improved throughput.

Enabled automatically on Linux when the kernel supports it. No configuration required. On Windows, the relay falls back to standard proxying.

Requirements¶

A running RF Online server (LoginServer + ZoneServer)
A Windows or Linux machine for the relay (can be the same machine as your game server)
The CrespoGuard Relay binary (CrespoGuardRelay.exe or Linux build)
A CrespoGuard package/tier appropriate for the intended player cap
The CrespoGuard Launcher configured with SecureLogin (PSK must match) — required for encrypted tunnel mode; not needed for transparent proxy mode

Bridge API Key¶

The CrespoGuard Bridge requires a BRIDGE_API_KEY environment variable to be set. The bridge will exit on startup if this variable is missing.

Setting the API Key¶

Generate a random string and set it as an environment variable before starting the bridge:

Option 1: .env file (recommended for self-hosted)

BRIDGE_API_KEY=your-random-secret-key-here

Option 2: Environment variable

export BRIDGE_API_KEY="your-random-secret-key-here"

Option 3: Windows environment

set BRIDGE_API_KEY=your-random-secret-key-here

Generate a secure key with:

python -c "import secrets; print(secrets.token_urlsafe(32))"

The bridge uses this key in the X-Bridge-Key header for all authenticated endpoints. Any request to an authenticated endpoint without a valid X-Bridge-Key header is rejected. See the Bridge HTTP API for the full endpoint reference.

Admin API Authentication¶

The following admin API endpoints require Bearer token authentication using a valid license key:

Endpoint	Method	Description
`/api/v1/config/{deploymentId}`	GET	Fetch deployment config — validates deployment ownership against the license
`/api/v1/update?product=X`	GET	Check for product updates — validates the license matches the requested product
`/api/v1/relay/telemetry`	POST	Submit relay telemetry data

All requests must include the Authorization header:

Authorization: Bearer <license_key>

The config endpoint validates that the license key owns the specified deployment
The update endpoint validates that the license key is associated with the requested product
All three endpoints are rate-limited

Quick Setup¶

Step 1: Activate Your License¶

CrespoGuardRelay.exe --activate YOUR-ACTIVATION-CODE

Step 2: Generate Config¶

CrespoGuardRelay.exe --generate-config server.json

Step 3: Configure¶

Edit server.json:

{
  "ServerName": "Your Server",
  "ListenIP": "0.0.0.0",
  "ListenPort": 10002,
  "TargetIP": "127.0.0.1",
  "TargetPort": 10001,
  "PSK": "same_key_as_modules_json",
  "MaxClients": 75,
  "PublicIP": "YOUR_PUBLIC_IP",
  "MaskServerIP": true,
  "DashboardEnabled": true,
  "DashboardPort": 8081,
  "DashboardApiKey": "YOUR_GENERATED_KEY",
  "RateLimitPerIP": 15,
  "RateLimitWindowSec": 60,
  "MaxConnectionsPerIP": 5,
  "IPBansFile": "ipbans.json"
}

The PSK must match the SecureLoginPSK in your launcher's modules.json.

Step 4: Start the Relay¶

CrespoGuardRelay.exe server.json

Step 5: Configure the Launcher¶

Add SecureLogin to your launcher's modules.json and re-encrypt config.bin:

{
  "SecureLogin": {
    "EnableSecureLogin": true,
    "SecureLoginType": 1,
    "SecureLoginHost": "YOUR.PUBLIC.IP",
    "SecureLoginIP": "YOUR.PUBLIC.IP",
    "SecureLoginPort": 10002,
    "SecureLoginPSK": "YOUR_64_CHAR_HEX_PSK"
  }
}

See Creating config.bin for the full encryption walkthrough.

Firewall Rules¶

Port	Direction	Purpose
10002 TCP	Inbound	Relay listen (encrypted tunnel)
27780 TCP	Inbound	ZoneServer (or zone proxy)
8081 TCP	Inbound	Dashboard (restrict to your admin IP!)

Block your real LoginServer port from external access — only the relay (localhost) should reach it.

Upgrading Tiers¶

Tier upgrades are server-side: purchase or provision the higher tier, activate the new code where required, and restart the relay/server component. Higher tiers may add capabilities, not just player cap. See Premium Tiers for full tier documentation.

Auto-Update¶

Relay auto-update is available only when enabled for the deployed package/tier. Otherwise, replace the relay binary manually during maintenance.

{
  "AutoUpdateEnabled": true
}

AutoUpdateEnabled defaults to true. Set to false in server.json to disable.

Telemetry¶

The relay sends anonymous usage statistics on startup and every 24 hours. No personally identifiable information (PII) is collected. Telemetry data includes:

Relay version
Operating system
Player cap (max clients)
Enabled features
Peak player count
Connection statistics
DDoS protection statistics

{
  "TelemetryEnabled": true
}

TelemetryEnabled defaults to true. Opt out by setting it to false in server.json.

Upgrading the Relay Binary¶

To upgrade the relay to a new version:

Stop the relay — terminate the running CrespoGuardRelay.exe process
Replace the binary — overwrite CrespoGuardRelay.exe (or the Linux binary) with the new version
Start the relay — launch with the same server.json. Your configuration is preserved; no changes needed.

If AutoUpdateEnabled is enabled for the deployed package, the relay updates itself automatically on startup. Otherwise, use manual binary replacement.

Dashboard Authentication¶

The dashboard API supports three authentication methods:

Bearer token header — Authorization: Bearer <api_key>
API key header — X-API-Key: <api_key>
Query parameter — ?key=<api_key> (exchanges for a cg_session HttpOnly cookie for subsequent requests)

All three methods authenticate against the DashboardApiKey configured in server.json.

Auto-Generated API Key¶

On first run, if DashboardApiKey is empty, set to "CHANGE_ME", or "REPLACE_WITH_RANDOM_API_KEY", the relay automatically generates a 32-character random hex key and writes it back to server.json. This ensures the dashboard API is protected from the moment the relay starts — no manual key generation needed.