Server Administration Guide

Audience: Server operators, tournament organizers, competitive league administrators, and content creators / casters.

Prerequisites: Familiarity with TOML (for server configuration — if you know INI files, you know TOML), command-line tools, and basic server administration. For design rationale behind the configuration system, see D064 in decisions/09a-foundation.md and D067 for the TOML/YAML format split.

Status: This guide describes the planned configuration system. Iron Curtain is in the design phase — no implementation exists yet. All examples show intended behavior.

Who This Guide Is For

Iron Curtain’s configuration system serves four professional roles. Each role has different needs, and this guide is structured so you can skip to the sections relevant to yours.

Regular players do not need this guide. Player-facing settings (game speed, graphics, audio, keybinds) are configured through the in-game settings menu and settings.toml — see 02-ARCHITECTURE.md for those.

Quick Start

Running a Relay Server with Defaults

Every parameter has a sane default. A bare relay server works without any configuration file:

./ic-server

This starts a relay on the default port with:

• Up to 1,000 simultaneous connections
• Up to 100 concurrent games
• 16 players per game maximum
• All default match rules, ranking, and anti-cheat settings

Creating Your First Configuration

To customize, create a server_config.toml in the server’s working directory:

# server_config.toml — only override what you need to change
[relay]
max_connections = 200
max_games = 50

Any parameter you omit uses its compiled default. You never need to specify the full schema — only your overrides.

Start the server with a specific config file:

./ic-server --config /path/to/server_config.toml

Validating a Configuration

Before deploying a new config, validate it without starting the server:

ic server validate-config /path/to/server_config.toml

This checks for:

• TOML syntax errors
• Unknown keys (with suggestions for typos)
• Out-of-range values (reports which values will be clamped)
• Cross-parameter inconsistencies (e.g., matchmaking.initial_range > matchmaking.max_range)

Configuration System

Three-Layer Architecture

Configuration uses three layers with clear precedence:

Priority (highest → lowest):
┌────────────────────────────────────────┐
│ Layer 3: Runtime Cvars                 │  /set relay.tick_deadline_ms 100
│ Live changes via console commands.     │  Persist until restart only.
├────────────────────────────────────────┤
│ Layer 2: Environment Variables         │  IC_RELAY_TICK_DEADLINE_MS=100
│ Override config file per-value.        │  Docker-friendly.
├────────────────────────────────────────┤
│ Layer 1: server_config.toml            │  [relay]
│ Single file, all subsystems.           │  tick_deadline_ms = 100
├────────────────────────────────────────┤
│ Layer 0: Compiled Defaults             │  (built into the binary)
└────────────────────────────────────────┘

Rule: Each layer overrides the one below it. A runtime cvar always wins. An environment variable overrides the TOML file. The TOML file overrides compiled defaults.

Environment Variable Naming

Every cvar maps to an environment variable by:

1. Uppercasing the cvar name
2. Replacing dots (.) with underscores (_)
3. Prefixing with IC_

Runtime Cvars

Server operators with Host or Admin permission can change parameters live:

/set relay.max_games 50
/get relay.max_games
/list relay.*

Runtime changes persist until the server restarts — they are not written back to the TOML file. This is intentional: runtime adjustments are for in-the-moment tuning, not permanent policy changes.

Hot Reload

Reload server_config.toml without restarting:

• Unix: Send SIGHUP to the relay process
• Any platform: Use the /reload_config admin console command

Hot-reloadable parameters (changes take effect for new matches, not in-progress ones):

• All match lifecycle parameters (match.*)
• All vote parameters (vote.*)
• All spectator parameters (spectator.*)
• All communication parameters (chat.*)
• Anti-cheat thresholds (anticheat.*)
• Telemetry settings (telemetry.*)

Restart-required parameters (require stopping and restarting the server):

• Relay connection limits (relay.max_connections, relay.max_connections_per_ip)
• Database PRAGMA tuning (db.*)
• Workshop P2P transport settings (workshop.p2p.*)

Validation Behavior

The configuration system enforces correctness at every layer:

Cross-Parameter Consistency Rules

These relationships are enforced automatically:

• catchup_sim_budget_pct + catchup_render_budget_pct = 100. If not, render budget adjusts to 100 - sim_budget.
• rank.rd_floor < rank.rd_ceiling. If violated, floor is set to ceiling - 50.
• matchmaking.initial_range ≤ matchmaking.max_range. If violated, initial is set to max.
• match.penalty.abandon_cooldown_1st_secs ≤ 2nd ≤ 3rd. If violated, higher tiers are raised to match lower.
• anticheat.degrade_at_depth ≤ anticheat.queue_depth. If violated, degrade is set to queue_depth × 0.8.

Subsystem Reference

Each subsystem section below explains: what the parameters control, when you would change them, and recommended values for common scenarios. For the complete parameter registry with types and ranges, see D064 in decisions/09f-tools.md.

Relay Server (relay.*)

The relay server accepts player connections, orders and forwards game data between players, and enforces protocol-level rules. These parameters control the relay’s resource limits and timing behavior.

Connection Management

When to change these:

• LAN tournament: Raise max_connections_per_ip to 10–20 (many players behind one NAT). Lower max_games to match your bracket size.
• Small community server: Lower max_connections to 200 and max_games to 50 to match your hardware.
• Large public server: Raise max_connections toward 5000–10000 and max_games toward 1000, but ensure your hardware can sustain it (see Capacity Planning).
• Under DDoS / connection spam: Lower connect_rate_per_sec to 3–5 and idle_timeout_unauth_secs to 15–30.

Timing & Reconnection

When to change these:

• Competitive league (low latency): Keep effective deadline behavior inside 90–140ms envelope (D060). If running a fixed value, start around 110ms.
• Casual / high-latency regions: Keep effective deadline behavior inside 120–220ms envelope (D060). If running a fixed value, start around 160ms.
• Training / debugging: Raise tick_deadline_ms to 500 and reconnect_timeout_secs to 300 for generous timeouts.

Recommendation: Leave tick_deadline_ms at 120 unless you have specific latency data for your player base. The adaptive run-ahead system handles most cases automatically.

QoS Envelope Alignment (D060)

The relay’s match QoS auto-profile should stay within these envelopes:

If your runtime currently supports only a fixed relay.tick_deadline_ms, choose the baseline above and tune by observed late-order rate. If match auto-profile envelopes are available, prefer those and keep fixed overrides minimal.

Catchup (Reconnection Behavior)

When to change these: These control how aggressively a reconnecting client catches up to the live game state. Higher max_ticks_per_frame means faster catchup but more stutter during reconnection. The defaults work well for most deployments. Only increase max_ticks_per_frame (to 60–120) if you need sub-10-second reconnections and your players have powerful hardware.

Match Lifecycle (match.*)

These parameters control the lifecycle of individual games, from lobby acceptance through post-game.

When to change these:

• Tournament: Raise countdown_secs to 5–10 for dramatic effect. Lower loading_timeout_secs only if you’ve verified all participants have fast hardware.
• Casual community: Lower postgame_timeout_secs to 120 — players want to re-queue quickly.
• Mod development: Raise loading_timeout_secs to 600 for large total conversion mods.

Pause Configuration (match.pause.*)

Recommendations per deployment:

Disconnect Penalties (match.penalty.*)

When to change these:

• Tournament: Set abandon_cooldown_1st_secs to 0 — admin handles penalties manually.
• Casual: Lower all penalties (e.g., 60/300/600) to keep the mood light.
• Competitive league: Keep defaults or increase for stricter enforcement.

Spectator Configuration (spectator.*)

V59 wall-time floor enforcement: The security floor for ranked (120s) and tournament (180s) is defined in wall-clock seconds, not ticks. The relay computes the minimum tick count at match start: min_delay_ticks = floor_secs × tps_for_speed_preset. If spectator.delay_ticks falls below this computed minimum, the relay clamps it upward. This ensures the floor holds at any game speed (D060). The tick values below assume Normal (~20 tps); at other speeds the relay adjusts automatically.

For casters / content creators:

• Set full_visibility: true so casters can see entire battlefield
• Set max_per_match: 200 or higher for large audiences
• Delay depends on whether stream sniping is a concern in your context

Vote Framework (vote.*)

The vote system allows players to initiate and resolve team votes during matches.

Global Settings

Per-Vote-Type Parameters

Each vote type (surrender, kick, remake, draw) follows the same parameter schema:

Kick-specific protections:

Remake-specific:

Recommendations:

• Tournament: Disable surrender and remake entirely (vote.surrender.enabled: false, vote.remake.enabled: false). The tournament admin decides match outcomes.
• Casual community: Consider disabling kick (vote.kick.enabled: false) in small communities — handle disputes personally.
• Competitive league: Keep defaults. Consider lowering vote.surrender.min_game_time_secs to 180 for faster concession.

Protocol Limits (protocol.*)

These parameters define hard limits on what players can send through the relay. They are the first line of defense against abuse.

Warning: Raising protocol limits above defaults increases the abuse surface. The defaults are tuned for competitive play. Only increase them if you have a specific need and understand the anti-cheat implications.

When to change these:

• Large team games (8v8): You may want to raise max_markers_per_team to 50–60 for more tactical coordination.
• VoIP quality: Raising max_voice_packets_per_second beyond 50 is unlikely to improve quality — the Opus codec is efficient. Consider raising chat.voip_bitrate_kbps instead.
• Mod development: Mods that use very large orders might need max_order_size raised to 8192 or 16384.

Communication (chat.*)

VoIP bitrate guidance:

When to change these:

• Tournament with casters: Raise voip_bitrate_kbps to 64 for clearer casting audio.
• Persistent chat trolling: Lower rate_limit_messages to 3 and raise rate_limit_window_secs to 5.
• Disable VoIP entirely: Set chat.voip_enabled: false if your community uses a separate voice platform (Discord, TeamSpeak).

Anti-Cheat / Behavioral Analysis (anticheat.*)

These parameters tune the automated anti-cheat system. The system analyzes match outcomes and in-game behavioral patterns to flag suspicious activity for review.

Tuning philosophy:

• Lower thresholds = more sensitive = more false positives. Appropriate for high-stakes competitive environments.
• Higher thresholds = less sensitive = fewer false positives. Appropriate for casual communities where false positives are more disruptive than cheating.

Recommendations:

Sub-Pages