halo --server runs the game as a host with no window, sound or player of
its own: other machines join it on the LAN, by its invite link or from the
server browser, as they join any host. port/linux/README.md, "Dedicated
server", says how to run one; this document is the reference for what it
takes and answers: the command line, the exit codes, the commands, the
HTTP API, the remote console (RCON) over WebSocket, the events, the log and
the files. docs/master_protocol.md is the master servers' protocol, which
the server publishes to and the server browser reads.
The code is port/linux/src/server_*.c (the platform side: the mode, the
standard input, the log, the rotation's grammar, the HTTP and WebSocket
server, the master servers' publisher) and port/linux/game/server_*.c
(the game side: the director that plays one game after another, the
commands, the gametypes, the status). The Android and iOS apps have no
dedicated server: they compile those files to nothing, but for
server_json.c (the JSON reader, which the server browser's list of master
servers uses in every build) and server_rotation.c (the rotation's
grammar and the gametype rules), which every build compiles.
In OpenH1. The server is OpenCE's, brought in with its network side
(by default a dedicated server hosts OpenH1 120 Tick games, which OpenCE's
players join too at 30; with server.game_mode it hosts OpenH1 60 Tick
games, or Legacy games, OpenCE's own netcode at 30 ticks a second for
everyone: "OpenH1 games" below). OpenH1's builds run
the game as a guest of a 64-bit host (port/linux/host), so the server
runs there too: halo --server on the Linux builds (and the macOS and
Windows ones), its signals caught by the host for it
(port/linux/host/host_desktop.c's host_server_*), and its HTTPS to the
master servers made in the host (host_https_request,
port/android/host/host_https.c). The server updates itself from
OpenH1's releases (server.auto_update, "Updates" below) when it runs from
the Linux release's tree or the Windows build's folder. Not in OpenH1:
OpenCE's deploy/ folder (Docker, Helm, systemd, the panels' eggs and
their CI).
A game panel (Pterodactyl, PufferPanel, MCSManager: deploy/) runs one
server and reads its standard output; deploy/systemd and deploy/docker
run servers on one machine. For many servers on many machines, opence-fleet
(github.com/OpenCommunityEdition/opence-fleet)
is one control plane over them all: an agent on each machine runs the
servers and drives each through this document's API, as the owner from
the machine itself (server.web_owner_password, below). What it relies on
is named in the status's and the RCON's capabilities: owner_web (the
owner's role over the web, from loopback), ban_address (sv_ban_address,
POST /api/bans), stop (sv_stop, POST /api/stop, the drain event),
event_addresses (addresses in the player events) and identity (the
status's pid, instance...).
| Argument | What it does |
|---|---|
--server |
Dedicated server mode (as HALO_SERVER=1 or server.enabled = true) |
--config <path> |
The settings file; default config.toml beside the executable. HALO_CONFIG_FILE, when it is set, wins over --config |
--version |
Prints OpenH1 build-<n> (network version <v>) and exits 0 |
--keygen |
Writes a new publisher key (server.publisher_key_file) unless one exists, prints its public key and key id, exits 0; exits 3 when the key cannot be made, read or written |
--sign <text> |
Prints the publisher key's Ed25519 signature of the text, in hex (an application's proof of key), exits 0; exits 3 without a text or a usable key |
--probe [<invite>] |
A look at a server, for a list site that shows its state: joins nothing and never starts a server (whatever --server, HALO_SERVER or server.enabled say). It finds the invite's game over its tunnel (without an invite, the LAN's first) and prints it as one line of JSON, the game of the invite's host alone (never another game that answers), and exits 0; when nothing answers in 30 seconds it prints {"ok":false,"error":"no game answered in 30 seconds"} and exits 1. Internet play is as set (network.online, on by default), which an invite needs |
--relay |
A relay alone ("Relays", below): no game, no game data, no window; it relays on network.tunnel_port (2302 if none) until SIGTERM or SIGINT, and exits 0 (4 when the port is taken) |
--help |
Prints these, exits 0 |
--version, --help, --keygen, --sign, --probe and --relay write no settings: the
settings file is read, never completed or made. --probe wins over
--server, HALO_SERVER and server.enabled: a probe never writes to
config.toml.
A probe's line:
{"ok":true,"name":"OpenCE Server","map":"bloodgulch","gametype":"ctf","players":5,"max_players":16,
"teams":true,"in_progress":true,"open":true,"dedicated":true,"network_version":38,"kind":0,
"tick_rate":30,"openh1_version":0}gametype is the game engine's name (ctf, slayer, oddball, king,
race, or none), kind the OpenCE gametype's kind the host sends (0 for
none), open whether it takes players now. network_version is the
version the game advertises: OpenCE's network version for a Legacy game and
an OpenH1 game that OpenCE players join too, and an OpenH1 game's protocol
version with its top bit set (0x8000) for one that only OpenH1 players
join. tick_rate is the game's (30 for a Legacy game) and openh1_version
the OpenH1 protocol version of an OpenH1 game (0 for a Legacy game).
The release has a halo-server script beside halo, which runs
halo --server with its arguments.
Use the same executable and --server workflow with an explicit MCC namespace:
[server]
rotation = 'mcc_maps\2898867177\Lava_Lab:slayer, mcc_maps\a10:coop'
rotation_fallback = falseInstall local maps/packages under the data root's mcc_maps, or enable
game.workshop_maps to discover this machine's installed MCC Workshop items.
An intact copied Workshop folder (mcc_maps/<id>/maps/<level>.map) and a
manual package (mcc_maps/<package>/<level>.map) both use the rotation name
mcc_maps\<package>\<level>: do not add the physical maps subfolder.
Local packages work with Steam discovery disabled. Keep their metadata and
authored resources together; the server resolves the same layout as clients.
Campaign maps require coop; multiplayer maps require a multiplayer gametype.
The MCC adapter checks version-13 headers without routing them through Xbox
or CE loaders. Resource/content validation still occurs before gameplay.
Base dependencies must be installed locally on the server and each player.
The server still needs Xbox maps/ui.map for its menus.
sv_maps and the web map picker include MCC multiplayer and campaign entries
with kind mcc and their package identity. The MCC catalog is cached during
server operation; restart after adding or removing local packages. Use sv_map mcc_maps\2898867177\Lava_Lab slayer for an immediate
change. Rotations and voting preserve explicit MCC paths; bare map names keep
their existing Xbox/CE lookup order. network.map_share automatically offers
eligible MCC packages with custom resources, metadata and previews, excluding
base resources. See MCC package sharing.
| Code | Meaning |
|---|---|
| 0 | Stopped: quit, sv_stop (now, or at the end of its drain), SIGTERM or SIGINT |
| 1 | A fatal error in the game (a halt, a map that failed to load); the last error lines were logged. The process exits within 5 seconds of the error, even when what runs at the exit (a hook, a listing's withdrawal) does not return |
| 2 | No usable game data: maps/ui.map, or every rotation map, missing or not a cache file; nothing was bound |
| 3 | Bad server configuration: no rotation entry that can be played (and server.rotation_fallback off), server.web_port past 65535, a web port the server may not bind (a port below 1024 without the right to it) or whose server.web_bind is an address the machine does not have, or a web password (admin, moderator or viewer) shorter than 8 characters with the web port bound beyond loopback (on loopback, a warning), or the owner's (server.web_owner_password) shorter than 8 wherever it is bound; --keygen or --sign failing. An entry that cannot be played (a bad gametype file among them) is left out with a warning: the server stops only when none is left |
| 4 | A port in use: the tunnel's UDP port, or the web port (another program listens on it) |
| 5 | Restart asked for (sv_restart, now or at the end of its drain, or an update installed: server.auto_update = "install", the default, installs a new release as soon as a check finds it, on a thread of its own, the server going on meanwhile. Then, of a release of the same network version, it stops with 5 once the server has been empty for 10 minutes; of a new network version (one its players' games no longer join), it says "This server updates after this game" and stops with 5 when the game ends (in the lobby, after 30 seconds' notice), a game going on past server.update_game_minutes (30) since the install being ended as sv_end_game ends it (game_ended's reason update). An install that fails is tried again at the next check: "Updates", below) |
| 128 + n | Stopped by signal n: a second SIGTERM or SIGINT, or the shutdown not done 5 seconds after the first |
SIGTERM and SIGINT stop the server: a game in progress goes to its
postgame, every machine is told, the listings are withdrawn, and it exits 0.
SIGHUP reloads the server's settings, the rotation and the gametype files
(sv_reload). SIGUSR1 prints the status on standard output. SIGPIPE and
SIGTTIN are ignored.
One line per event, for the operator and the panel:
2026-10-19T18:03:11Z INFO server: ready (tunnel 2302/udp, web 127.0.0.1:8080, listing public)
2026-10-19T18:03:40Z INFO player: Milenko joined (slot 0, machine 1)
2026-10-19T18:04:02Z INFO game: started: CTF on bloodgulch, 2 players
The fields are the time (UTC), the level (INFO, WARN, ERROR), the
category (server, lobby, game, player, chat, moderation, net,
master, console, health) and the text. server: ready is printed once,
when the lobby is open and, for a public server, its listing has been
published (or 10 seconds on, as the brokers are other people's): it is the
line a panel waits for. With server.log_format = "json" each line is an
object instead, and the line a panel waits for holds "msg":"ready (:
{"time":"2026-10-19T18:03:11Z","level":"info","cat":"server","msg":"ready (tunnel 2302/udp, ...)"}Every line is also kept in the log the web's viewers read (/api/log,
sv_log, the RCON's log events), but for these, which go to standard
output alone: the web password a first start makes, the invite (a
private server's lets anyone in; /api/status gives it to admins), and
the owner's console, the commands typed on standard input or read from the
init file and what they answered (a password's command is shown as (a password's command) there too).
A health line comes once a minute: health: players=3 frame_ms_max=4.1 frame_ms_avg=1.20 cpu=2.1% rss=96MB (the longest and the mean frame of
the last minute, in milliseconds). Standard error keeps the platform
layer's halo-linux: lines, and debug.txt everything, as for a player's
game.
The same commands come from standard input, server.init_file (run once at
the start, a command a line, #, ; and // starting comments), the telnet
console (debug.telnet_console, loopback), the RCON, POST /api/command
and the web page. Each runs on the game's thread between frames. Every
command has a role; a caller may run it if their role is that one or above:
viewer < moderator < admin < owner (standard input, the
init file and the telnet console are the owner's: whoever holds the
process; so is a sign-in to the web or the RCON with
server.web_owner_password from the machine itself: "Signing in"). When
standard input ends and server.console_exit_on_eof is on, its last line
runs, whether or not a line's end ended it, and then the server stops.
A <player> is a slot number (sv_players lists them) or the start of a
name; a name that begins more than one player's is refused. A <duration>
is a number and a unit (45s, 30m, 2h, 7d, 1w), a bare number of
minutes, or forever; ten years at most. A word in quotes ("two words")
is one word.
A command's text (a notice, a reason, sv_set's value, a name) is kept to
printable ASCII: control characters (a line's end, a tab) and other bytes
outside it are dropped, as are the quotes around the whole text, and
standard input's and the init file's lines are cleaned so before they run.
The web is stricter where it takes a value as it is: PUT /api/settings
refuses a value with a control character (schema), and nothing is changed
for that setting. A command's reply is sent whole, however many lines.
Commands that are not the server's (the game's own console commands, the
scripts' globals and functions) need the owner role: from the web or the
RCON they are refused (not a command of the server's) but to the owner's
session. The server's
commands come first, so kick and ban are always the server's below, not
the game's console commands of those names.
| Command | Role | What it does |
|---|---|---|
help [command] |
viewer | The commands, or one command's use |
sv_status [--json] |
viewer | The server's state, map, gametype, players, uptime, games played, network version, the kind of game hosted (server.game_mode, "OpenH1 games" below), listing and next game |
sv_players [--json] |
viewer | Each player's slot, name, team, score, kills, deaths, assists, ping and machine; with the owner role or server.log_addresses, their address and hardware id |
sv_rotation (sv_mapcycle), sv_maps, sv_gametypes, sv_version, sv_log [n] |
viewer | Lists: the rotation, the maps there are, the gametypes, the build, the log's last n lines |
sv_bans (sv_banlist), sv_settings |
admin | Lists: the bans of bans.txt, the settings sv_set changes |
sv_masters, sv_publisher |
viewer | The master servers and how each answered; the publisher key's id and public key (never its seed) |
say <text> (sv_say) |
moderator | A notice on every machine's screen |
tell <player> <text> |
moderator | A notice on one player's machine |
kick <player> (sv_kick) |
moderator | Drops the player's machine; it may join again. A player still in the game whose machine has gone is taken out (a ban of one is refused: there is nothing to ban) |
ban <player> [<duration>] [<reason>] (sv_ban) |
moderator (a day at most), admin | Drops the player's machine and bans its address and hardware id, for the duration (else for ever). A moderator must give a duration of a day or less: a ban for ever, or longer, is refused |
unban <number|address|hardware id> (sv_unban) |
admin | Takes a ban out of bans.txt; the machine may join again at once, by the LAN or the internet |
sv_ban_address <address|hardware id|discord:<id>> [<duration>] [<reason>] |
admin | Bans an IPv4 address (a.b.c.d), a hardware id (up to 32 hex digits) or a verified Discord account (discord: and its id, below), its machine here or not: its line in bans.txt as ban writes it (the other part none), so that sv_bans, unban and GET /api/bans see it, and a machine present of that address or hardware id is dropped as ban drops it (player_left's reason banned). Answers ban <n> added (n: its number in sv_bans) |
sv_vpn |
viewer | The VPN policy, the netlist held (its masters, serial, ranges, age) and the joins refused for it ("VPNs and linked Discord accounts") |
sv_vpn_check <address> |
moderator | Whether an IPv4 address is refused as a VPN's, and by what (netlist, vpn_block.txt, vpn_allow.txt) |
sv_vpn_fetch |
admin | Fetches the masters' netlists now |
mute <player> [<minutes>], unmute <player> |
moderator | The host's mute of a player's chat, voice and pings for everyone |
sv_map <map> [<gametype>], sv_map <entry> |
moderator | Plays that game (or a rotation entry, map:gametype+rule=value; a co-op one too), below |
sv_map_next (sv_next) |
moderator | Ends the game without its scores and plays the rotation's next |
sv_end_game |
moderator | Ends the game: its scores, then the next |
bots <command> [--json] |
admin | Directs the bots: orders, traits, adding and removing them (bots help; docs/bot_control.md) |
sv_rotation_set <entries>, sv_rotation_add <entry>, sv_rotation_del <n>, sv_rotation_begin [<n>] (sv_mapcycle_add, _del, _begin) |
admin | Changes the rotation (written to server.rotation, 4096 characters at most) |
sv_set <setting> <value> |
admin | Changes one of the server's settings, now where it can be, and in config.toml (below); a setting its environment variable sets is refused. A value is 256 characters at most |
sv_name <name>, sv_maxplayers <n>, sv_password [<password>], sv_public <0|1>, sv_motd <text> |
admin | sv_set of server.name, server.max_players, server.password, server.public, server.motd |
sv_reload |
admin | Reads config.toml's server settings, the rotation and the gametype files again (as SIGHUP) |
sv_map_after <map> [<gametype>], sv_map_after <entry> |
moderator | Plays that game once the game played (or the lobby's, about to be) is over; the rotation goes on after it |
sv_team <player> |
moderator | Puts the player on the other team: in the lobby by its record (every machine sent it), in a game as Host Controls moves them (their unit killed first, without statistics; an OpenH1 game of OpenH1 machines alone) |
sv_teams shuffle|balance |
moderator | Shuffles or balances the teams of a team game being played, as Host Controls does (an OpenH1 game of OpenH1 machines alone) |
sv_lock_teams [0|1] |
moderator | Players keep the team they are on in the lobby (their changes refused); alone, says whether they do |
sv_admin [list], sv_admin add <player|key> [<name>], sv_admin remove <player|key|key id> |
owner | The admins in the game ("Admins in the game", below): admins.txt's keys, server.admins, and each player's key id; a player here added by the key their game proved, or a key (64 hex digits) given |
sv_stop [now|game|empty] [<notice>], sv_stop cancel |
owner | Stops the server (exit code 0): now (the default) as quit does; game once the game being played is over, empty once nobody plays (a drain, below); cancel the drain waiting. The notice is said to every machine first |
sv_restart [now|game|empty] [<notice>], sv_restart cancel |
owner | As sv_stop, with exit code 5 (restart me) |
quit (exit) |
owner | Stops the server (exit code 0) |
sv_map's game is played as soon as it can be, and its answer says when:
next: <entry> (now) in the lobby before its start was sent (the lobby
takes the entry, and the rotation's entry it replaced is played after it),
(now: this game ends) while a game is played (it ends at once, without
its scores), and (once this game is over) once the lobby's start was sent
or while a map loads (it is the next game). sv_map of the game being
played plays it again. The rotation goes on after it.
A drain (sv_stop or sv_restart with game or empty, POST /api/stop) is a stop that waits: the listings are withdrawn as sv_public 0 withdraws them (a new invite, the masters told), without the setting
changing; new machines are refused as while a map loads (the game is not
open: the LAN's search shows it closed, a join by the invite is told the
game is not open); then the server stops. With game it stops once no
game is played nor about to be: at once in the lobby with nobody in it, or
with no countdown running (fewer players than server.min_players);
otherwise once the game played (or about to start) is over and its
postgame shown. With empty it stops once nobody is on the server (at once
if nobody is now). sv_stop cancel (or sv_restart cancel) ends the
drain: the server is listed again as server.public says and takes new
players. A drain event says each (after: now, game, empty or
cancel), and the stop that ends a drain has the shutdown reason
drained. /api/status's drain is the drain waiting, or null.
A co-op entry (<level>:coop) is ended as a game is: by sv_end_game,
sv_map_next, sv_map, server.empty_seconds and server.idle_minutes.
It has no scores: the server goes back to the lobby at once (no postgame),
and a level won ends it with game_ended's reason score.
sv_set (and the settings of the web page, PUT /api/settings) changes
these settings, which sv_settings and GET /api/settings list:
server.name, server.max_players, server.min_players,
server.password, server.public, server.rotation_fallback,
server.lobby_seconds, server.postgame_seconds, server.empty_seconds,
server.idle_minutes, server.team_start, server.team_switch,
server.team_switch_cooldown_seconds, server.motd,
server.frame_rate, server.game_mode, server.web_password,
server.web_moderator_password, server.log_format,
server.log_addresses, server.status_file, server.auto_update,
server.coop_difficulty, server.region, server.master_publish,
server.chat_filter, server.chat_filter_slurs, server.chat_filter_swearing,
server.chat_filter_insults,
server.master_publish_address, server.metrics, server.vpn_policy,
server.vpn_fail, server.vpn_check_lan, server.link_min_age_days,
server.link_one_seat, server.update_check_minutes,
server.update_game_minutes, server.max_machines_per_address,
server.afk_kick_minutes, server.afk_kick_when_full,
server.afk_kick_full_minutes, server.coop_bsp_switch,
server.coop_bsp_switch_cooldown_seconds,
server.vehicle_riding_override_gametype, server.map_vote,
server.map_vote_choices, server.map_vote_seconds, and
network.text_chat,
network.voice_lobby, network.voice_mode, network.voice_kbps,
network.votekick, network.vote_end_game, network.votekick_threshold,
network.votekick_percent, network.votekick_minutes,
network.votekick_ban_minutes, network.map_share,
network.map_share_upload, network.public_address,
network.coop_friendly_fire, network.coop_player_collisions,
network.coop_ally_friendly_fire, network.coop_team_wipe,
network.shield_effects, network.fire_origins, network.vehicle_riding,
network.allow_opence, network.pings and
network.allow_hit_sounds (whether the players may hear their hit
sounds, audio.hit_sounds: false forbids them, an OpenH1 game's
record telling its OpenH1 clients, from the next lobby). Of them,
server.status_file, server.auto_update and server.log_addresses need
the owner role: from the web's admin, sv_set of one of them (POST /api/command) answers 403 forbidden, and PUT /api/settings leaves it
out, in its errors with the code forbidden and the message <setting> needs the owner role (the server's console); the owner's session changes
them both ways. A web password is empty or
8 characters or more. A value outside a setting's choices or range is
refused (400 failed from sv_set, schema in PUT /api/settings's
errors), with <setting> takes a whole number from <min> to <max> (or
from <min>) or <setting> is one of <a>|<b>|<c>; a choice may be given
in either case, and is kept as the table spells it:
| Setting | Choices or range |
|---|---|
server.max_players |
2 to 127 |
server.min_players |
1 to 16 |
server.lobby_seconds, server.postgame_seconds |
0 to 300 |
server.empty_seconds, server.idle_minutes |
0 or more |
server.frame_rate |
30 to 120 |
server.game_mode |
openh1_120, openh1_60, openh1_30, legacy |
server.team_start |
one, both, skip |
server.team_switch_cooldown_seconds |
0 to 3600 |
server.log_format |
text, json |
server.auto_update |
off, check, install |
server.coop_difficulty |
easy, normal, hard, impossible |
network.text_chat |
on, links, off |
server.chat_filter |
off, censor, block |
server.vpn_policy |
off, link, block |
server.vpn_fail |
open, closed |
server.link_min_age_days |
0 to 3650 |
server.update_check_minutes |
5 to 1440 |
server.update_game_minutes |
0 to 240 |
server.max_machines_per_address |
0 to 128 |
server.afk_kick_minutes |
0 to 60 |
server.afk_kick_full_minutes |
2 to 60 |
server.coop_bsp_switch |
majority, anyone |
server.coop_bsp_switch_cooldown_seconds |
0 to 300 |
server.map_vote_choices |
2 to 8 |
server.map_vote_seconds |
5 to 120 |
server.chat_filter_slurs, server.chat_filter_swearing, server.chat_filter_insults |
off, severe, strong, mild |
network.voice_mode |
off, team_proximity, team_enemy_proximity, team_global, team_global_enemy_proximity |
network.voice_kbps |
8 to 64 |
network.votekick_threshold |
dynamic, static |
network.votekick_percent |
1 to 100 |
network.votekick_minutes |
0 to 60 |
network.votekick_ban_minutes |
1 to 1440 |
network.map_share_upload |
16 to 256000 |
network.coop_friendly_fire |
off, on, shields_only, explosives_only |
network.coop_team_wipe |
auto, revert, respawn (auto: a public server, server.public with internet play, only respawns the team) |
network.shield_effects |
stock, glow, light_show, overshield, glow_overshield, light_show_overshield, players |
network.vehicle_riding, server.vehicle_riding_override_gametype |
true, false (from the next map) |
A dedicated server may also keep words out of its chat and its players'
names (server.chat_filter, off by default): the words of streamer mode's
list, by group, each group from the least severity its setting names
(server.chat_filter_slurs, mild by default: every slur;
server.chat_filter_swearing and server.chat_filter_insults, off).
censor shows a line's words as stars to everyone; block refuses the
line (its sender is told "Your line was not sent: it has words this server
does not allow") and refuses at the door a machine whose player's name has
them, which an updated game shows as "The host refused: your player name"
(an older one says the game is closed). Each is logged (chat filter: …,
refusing a machine … its name has words the server's filter keeps out).
Links are network.text_chat's, refused by default. A list of words is
not a moderator: spaced letters and look-alikes get past it.
The players the owner makes admins have the pause menu's and the scoreboard's HOST CONTROLS in the server's game, as a player who hosts has them, and the lobby's: the same screens, showing the server's game. What an admin does there is a request the server runs as its own command, at the admin role, as the web page's and the RCON's are; so it is logged and is an event as those are, and the players see what the command shows them (its notices, a kicked player's leaving). Several players may be admins.
An admin is a key, not a password. Each OpenH1 game proves a key of its
own for this server to the server as it joins (an OpenH1 game of this
version, in an OpenH1 game: server.game_mode not legacy): the server
sends it the server's id (admin_id.txt, beside admins.txt, made at
random the first time: keep it, as the admins' keys come from it) and a
nonce, and the game signs the nonce, bound to its connection, with a key
it makes for that server id alone from a secret of its own (admin.key
beside its config.toml, made the first time a server asks: not the
player key a Discord link uses, which is never shown). A key is never taken
on the game's word, and its proof is good for that connection alone.
For the players' privacy, one player's key differs from server to server,
and says nothing of their Discord account or player key: servers cannot
tell, by it, that two of their players are one. A server that claimed
another's id would learn the player's key there, not more; the key is no
password, and a proof is bound to the nonce and the connection it was
made for (an internet play tunnel's secret: on a LAN, where there is none,
keep server.admins to the LAN's players). A player who moves to another
computer, or loses admin.key, has a new key, which the owner makes an
admin again.
A game that proved a key listed in admins.txt (in
paths.logs, else the data root, beside bans.txt: a key of 64 hex digits
or a key id of 16 a line, anything after it on the line a name, #
beginning a comment) or in server.admins (keys or key ids, separated by
commas) is an admin's, from the next second; one taken out is no longer.
The owner makes a player an admin:
- on the web page (the owner's session): Make admin beside a player whose
game proved a key (the players'
key_id, the owner's to see), and Remove admin; the players list marks admins; - by
sv_admin add <player>(standard input, the owner's RCON orPOST /api/command), which writes the key their game proved here toadmins.txtwith their name;sv_admin add <key>adds a key given;sv_admin remove <player|key|key id>takes it out;sv_adminlistsadmins.txt,server.adminsand each player's key id; - or in
server.admins, oradmins.txtby hand.
A player finds their own key id for the server they play on with the
console's admin (which says too whether that server has them an admin).
What an admin's Host Controls do, and the command each runs:
| Host Controls | Command |
|---|---|
| PLAYERS: KICK, BAN... (an hour, a day, for good; a reason), MUTE... (10 minutes, an hour, a day), UNMUTE, MOVE TO RED/BLUE | kick, ban <slot> <duration> <reason>, mute, unmute, sv_team |
| GAME: END GAME NOW, RESTART ROUND (the game played again: its entry), SHUFFLE and BALANCE TEAMS, ANNOUNCE..., LOCK TEAMS | sv_end_game, sv_map <the entry played>, sv_teams, say, sv_lock_teams |
| MAPS (the server's maps and gametypes): PLAY NOW, AFTER THIS GAME, ADD TO PLAYLIST | sv_map, sv_map_after, sv_rotation_add |
| PLAYLIST (the server's rotation, its next marked): PLAY NOW, AFTER THIS GAME, REMOVE | sv_map, sv_map_after, sv_rotation_del |
BANS (bans.txt's newest 128): UNBAN |
unban <number> |
| The scoreboard's Kick, Ban (for good), Move to the other team | kick, ban, sv_team |
A player is named to the server by slot and by the name the admin's list had
there: a request for a slot that holds another player now is refused, as the
web's are. The owner's commands (the server's settings and passwords, the
rotation replaced, stopping or updating the server, sv_admin) are never
offered, nor are a player host's bots, rules, score and time limits,
password, listing, maximum players and votekick, which on a dedicated server
are its settings. An admin's game asks a few things a second at most (the
server takes 4 a second, bursts of 8, and drops the rest).
Each request run is logged (admin <name> (key <id>) ran "<command>" from the game: done or refused) and is an admin_command event; the command's own
log line and event (kick, ban...) say by as admin <name> (key <id>),
and a ban's reason in bans.txt ends (by admin <name> (key <id>)).
A Legacy game (server.game_mode legacy), whose machines play OpenCE's
protocol, has no admins in the game: its OpenH1 machines are sent nothing
new.
server.game_mode picks the kind of game the server hosts
(port/linux/NETCODE.md, "OpenH1 and Legacy games"):
| Value | The games |
|---|---|
openh1_120 (the default), openh1_60 |
An OpenH1 game at 120 or 60 ticks a second: each OpenH1 player's sub-steps go between the machines, and OpenCE players join it too, at 30, when network.allow_opence is on (it is off by default) |
openh1_30 |
An OpenH1 game at 30, as a player's Server Setup offers it |
legacy |
OpenCE's netcode at 30 ticks a second, which OpenCE's players and OpenH1's join alike |
The server hosts an OpenH1 game as a player's game hosts one, with the
differences of any dedicated server (port/linux/NETCODE.md, "Dedicated
servers"): it has no player of its own, so its ticks give its clients'
players their sub-steps as they came and send them on to the other
clients, and it sends no live controls of its own. Its LAN advertisement
and listing are an OpenH1 game's (OpenCE's network version with the rate
and the OpenH1 protocol version beside it, which the server browser's
OpenH1 tab lists as "GOAT H1 120 Tick, OpenCE can join"; with
network.allow_opence off, the OpenH1 protocol version alone, which OpenCE
does not list), with the dedicated flag as ever. Every rotation entry,
gametype file, vote and the map vote play as in a Legacy game; a co-op
entry is played at the game's rate too. The frames of an OpenH1 game come
at least as often as its tick rate (server.frame_rate is raised to it),
and between its frames the server waits on its socket and reads what comes
as it comes, so that each sub-step of a client's is sent on to the others
at once, not at the next frame.
A change of server.game_mode (sv_set, PUT /api/settings,
sv_reload) is taken in the lobby once nobody is on the server: the
players there keep the kind of game they joined (sv_status says it
waits), and an OpenH1 game's rate changes from the next game, as a player's
host changes it. network.allow_opence is taken at once: an OpenH1 game
closed to OpenCE players keeps those in it. The status's game_mode,
game_mode_name, tick_rate and opence, the lobby's log line
(lobby: hosting: GOAT H1 120 Tick, OpenCE can join (server.game_mode)) and
the game_started and game_ended events say what is hosted.
A server takes nothing of a player's host's network.game_mode and
network.sim_rate. Before server.game_mode, a server took its kind of
game from them; such a server hosts OpenH1 120 Tick games now, unless
server.game_mode says otherwise (openh1_60 for a network.sim_rate
of 60, legacy for a network.game_mode of legacy). A server that
finds either of them set (to another value than its default in
config.toml, or by its environment variable) says so as it starts: WARN server: network.sim_rate = 60 is a player's host's setting, which a dedicated server leaves aside: server.game_mode (openh1_120) says what it hosts.
The players vote to kick a player (network.votekick: the scoreboard's
right-click, or the console's votekick <name>) and to end the game
(network.vote_end_game: !endgame in the chat). While a vote runs every
player sees its box at the left of the screen, and F1 votes yes, F2 no
(controls.vote_yes, controls.vote_no), or a controller's D-pad left and
right, which then do nothing else (!yes and !no in the chat do too).
The yes votes needed are network.votekick_threshold's, of the players who
may vote: dynamic (the default) scales them, more than half up to 8, then
40% (at least 5) up to 32, then 30% (at least 13); static asks
network.votekick_percent (50 by default) of them, rounded up, and for a
kick never more than those who can vote yes. At least 2 either way, and
more yes than no; a vote the no votes have made lost ends at once. A vote to end the game may start from 30 seconds played on the
server, not in a game's first minute, and ends it as sv_end_game does,
its scores and postgame shown (game_ended's reason vote).
server.map_vote (off by default) lets the players choose the next game:
as the lobby opens after a game with players in it, the server offers
server.map_vote_choices (4) entries of the rotation picked at random (not
the one just played, nor one twice), every player's lobby opens its vote
screen, and after server.map_vote_seconds (20), or once every machine has
voted, the entry with the most votes is played next (a tie, or no vote, at
random among them); the rotation goes on after it. sv_map (an entry
interposed) and a changed rotation set the vote aside. map_vote_started
and map_vote_ended events say each.
A player away from the controls (no button pressed or let go, no stick or
trigger held, the view not turned) for server.afk_kick_minutes (5; 0:
never) is told a minute before and then kicked (player_left's reason
afk, an afk_kick event), free to join again at once. Only time in a
game counts: not the lobby, the postgame, a cinematic, nor a player dead.
With server.afk_kick_when_full a player is kicked only while the game is
full, after server.afk_kick_full_minutes (3).
server.max_machines_per_address (0: no limit) refuses a machine whose
address (an internet play peer's real one) has that many in the game
already (join_refused's reason address_full); an updated game shows
"The host refused: too many players from your address".
In a co-op game a loading zone (a trigger that moves the team to another
part of the level) switches only once more than half of the living players
who are not away stand in zones to the same part (server.coop_bsp_switch
majority, the default; anyone: the first player in one). The others see
"Waiting for N more players to cross"; a mission script's switch is not
held. After a switch the zones wait server.coop_bsp_switch_cooldown_seconds
(15) before another, the players told when they open; each switch is told
to everyone, logged and a coop_bsp_switch event names who crossed.
network.vehicle_riding is the base setting. In multiplayer the
gametype's vehicle_riding rule ("Gametype files", below) overrides it:
a gametype without the rule is off, whatever the base says. In co-op a
rotation entry's own riding rule overrides it.
server.vehicle_riding_override_gametype = true turns the gametype's
override off, so multiplayer uses the base setting.
Both settings default to false; changes through sv_set or the web
page count from the next map. A map's own choice still wins.
For example (a co-op entry's own rule and a map's choice still win):
network.vehicle_riding |
server.vehicle_riding_override_gametype |
Riding |
|---|---|---|
true |
false |
On in co-op; multiplayer follows each gametype |
false |
true |
Off in multiplayer (unless a map turns it on) |
true |
true |
On in co-op and multiplayer (unless a map turns it off) |
In a team game a player changes their own team by saying !switch (or
!team) in the chat, the whole line, in either case. The line goes to no
one, not even when the player is muted: the server moves them, and everyone
sees "Guven switched to the Blue team", or tells them alone why not. The
server decides, and moves a player only
- with
server.team_switchon (the default); - while a team game is played: not in the postgame, nor in a game without teams ("!switch works only in team games"), nor in co-op, nor in Infection, whose teams are its roles ("Infection decides the teams");
- once in
server.team_switch_cooldown_seconds(30; 0: no wait), each player ("You can switch teams again in 12 seconds"); - with the gametype's auto team balance on (
balancein a gametype file), to a team that has fewer players than theirs, them counted: the new team is then one player bigger than the old at most. 5 against 4 may become 4 against 5, but 4 against 4 stays ("Blue has 4 players, Red 4: that would unbalance the teams"). With the balance off, a player may switch whatever the numbers.
A living player dies as they switch, a death no one is credited with: no
suicide is scored and no kill counted, what they carry (a flag, the ball)
drops, and they respawn on the new team after the gametype's respawn time
(and its suicide penalty). They join the new team as they die, once what
they carried has dropped, never while they still hold it; if another
player kills them first, the kill is that player's and the switch is made
all the same. While a switch waits for its death, the auto team balance's
rule counts the player in the new team. A dead player changes team at once,
and their respawn goes on as it was. The cooldowns start again with each
map. The team scores stay as they were, the points a player scored staying with the
team they scored them for, and the player's own score goes with them.
Every machine sees the new team with the player's next life, as it does the
auto team balance's moves, so a client of any network version takes it.
Each switch is logged (player: Guven switched to the Blue team (!switch)); there is no event for it, as there is none for the auto team
balance's moves.
server.auto_update is install by default (check only says when a
release is out; off never looks). The server asks GitHub for OpenH1's
latest release (build-<n>) server.update_check_minutes (30) after the
last check (the first within two minutes of its start), and when there is
a newer one says so (a warning event) and, with install, installs it
on a thread of its own, the server playing on meanwhile: the release's zip
for this build (OpenH1-Linux.zip, OpenH1-Linux-ARM64.zip,
OpenH1-Linux-VR.zip, OpenH1-Windows.zip, or their -debug builds')
downloaded into the game's folder (update.partial-<network.port>, so
that servers that share a folder do not share it), checked against the
release's SHA256SUMS and its signature by OpenH1's release key, as the
game's own updates are (a download that does not match is deleted and
refused), unpacked, and each of
its files put in place of the running server's, which become <name>.old
and are deleted when the new build starts. An install that fails (the
download, its check, a file that cannot be replaced: the files replaced before it are
put back) is logged and tried again at the next check.
The release's notes give its network versions (Network version: <n> and
Standard network version: <n>, written by the release job:
tools/ci_build.py notes). One of the same versions restarts the server
(exit code 5) once it has been empty for 10 minutes; one of a new version,
which its players' games no longer join, tells the players "This server
updates after this game" and restarts it once the game ends, in the lobby
after 30 seconds' notice, and a game still going on
server.update_game_minutes (30; 0: no limit) after the install is ended
as sv_end_game ends it, its scores shown. What runs the server must start
it again on exit code 5 (systemd's Restart=on-failure, Docker's
--restart, a panel's restart), and it starts the new build.
Only a server that runs from files it may replace updates itself: the
Linux release's tree (bin/openh1 beside share/openh1, as the release's
zip unpacks it, or as install.sh puts it in ~/Applications/OpenH1) and
the Windows build's folder, of a build CI numbered. A build without a
number (one built from the sources), a tree a package manager installed
(share/openh1/packaged) or that the server may not write, the Steam
Frame's package, and the macOS, iOS and Android apps log once that
server.auto_update is set but the build does not update itself, and why;
what runs them updates them.
A dedicated server refuses by default machines that join from the address
of a VPN, a Tor exit or a datacenter, as the master servers' netlist says
(docs/master_protocol.md, "The netlist"), and lets one in that shows a
pass of a Discord account linked at a master the server publishes to ("Player
keys, links and passes" there): a player on a VPN links a Discord account
once, and joins. server.vpn_policy, live:
| Value | A machine from a listed address |
|---|---|
link (the default) |
is refused with "This server blocks VPNs: link Discord in Settings, Account to join, or turn your VPN off", unless it shows a pass (which an updated game does at once, by itself, when it holds one) |
block |
is refused, pass or not ("This server does not allow VPNs") |
off |
joins |
The server fetches the netlist of each master it publishes to (the masters
of server.masters_file, or every built-in official master when it names
none) every hour, keeps the newest of each on disk
(netlist-<master key id>.bin beside bans.txt) and checks the union of
them. Until it holds one, server.vpn_fail decides: open (the default)
lets every machine in, closed refuses those from the internet as
block would. server.vpn_list names a netlist file checked besides
the masters' (a full path, or beside config.toml; for a server that
publishes nowhere, or a test), read at the start and by sv_reload. Beside
bans.txt, vpn_allow.txt names ranges never refused and vpn_block.txt
ranges refused besides, one a line (203.0.113.0/24, 198.51.100.7, or
198.51.100.1-198.51.100.9; # starts a comment), read at the start and by
sv_reload. Only a machine's real internet address is checked (an
internet play peer's endpoint, distributed_real_address): a LAN's
machines are not, unless server.vpn_check_lan (for tests) says so.
A pass is taken from the masters the server publishes to alone (with
server.master_publish and a publisher key): a server that publishes
nowhere takes none, and a player from a listed address joins it only with
server.vpn_policy off. With a pass, the server also refuses an account
younger than server.link_min_age_days (365 by default: a year, from the
account's id; "This server needs a Discord account a year old to join over
a VPN") and, with server.link_one_seat (on by default), a second machine
of an account already in the game ("Your Discord account is already
playing on this server"). A pass that does not check (another master's, out
of date, not this connection's) is refused as "Your Discord link could not
be checked". The machine of a pass is a verified Discord account: its id
and username (discord_id, discord_name, discord_verified in
/api/players and player_joined, with the addresses: for the owner, or
every role with server.log_addresses) replace what
the machine says of itself, and ban bans the account too. Each refusal
is logged (refusing a machine @<address>: vpn …) and is a join_refused
event. An older game is told the game is closed.
A dedicated server's text chat is its network.text_chat's, listed or
not: on by default (lines with links refused), links, or off, live
(sv_set network.text_chat off), as a game a player hosts follows its
host's.
The settings sv_set does not change (server.web_viewer_password,
server.web_owner_password, server.web_port, server.web_bind, server.web_trusted_proxy, the
paths, the master servers' files...) are changed in config.toml or their
environment variables: sv_reload reads the file's server.* settings
again, and the web port and its address are bound once, at the start. The
rotation is changed by the sv_rotation_* commands.
The server listens on server.web_port (8080; 0 for none) at
server.web_bind (127.0.0.1, an IPv4 address). Bound beyond loopback,
every web password that is set (admin, moderator, viewer) must have 8
characters or more, else the server exits with code 3; the owner's
(server.web_owner_password) must have 8 or more wherever the port is
bound. The page (/), the API
(/api/...), the RCON (/ws), /healthz and /metrics share the port.
Requests are HTTP/1.1 (or 1.0), GET, HEAD, POST, PUT or DELETE
(HEAD is answered as GET is, without the body, and counts as a read,
as a GET; /api/login takes POST alone), a head of 8 KB at most whose
lines end with CRLF (a bare LF, a CR inside a line, or more after the empty
line that ends it: 400 bad_request) and a body of 64 KB at most, sent within 10 seconds of the
connection's opening or of its last answer (a connection that sends
nothing is closed then too). Transfer-Encoding and Expect are refused.
24 connections are taken at once; when they are all taken, the oldest that
waits for a request (no RCON, no request being answered) is closed for a
new one. A client that does not read its answers is read no further once
256 KB of them wait, and is closed past 2 MB.
Every request but /healthz counts against its address's allowance, the
page's files, /metrics, a sign-in and the RCON's upgrades (/ws) too: 60
a minute, or 600 with a session (429 rate_limited past it, with
Retry-After: 60). Behind server.web_trusted_proxy, a request's address
is the last entry of its X-Forwarded-For (the one the proxy appended: an
IPv4 address, a.b.c.d or a.b.c.d:port, or an IPv6 one, v6, [v6] or
[v6]:port), and its X-Forwarded-Host and X-Forwarded-Proto are
believed, whether or not it sends X-Forwarded-For; from any other
address they are ignored. IPv6 clients are counted by their /64: one
host's addresses share its allowance and its lockouts. Every answer is JSON
(Content-Type: application/json) unless said, with
Cache-Control: no-store, X-Content-Type-Options: nosniff,
Referrer-Policy: same-origin (under no-referrer a browser would send
the page's own changes with Origin: null) and
Content-Security-Policy: default-src 'self'; frame-ancestors 'none'.
POST /api/login with {"password":"…"} answers
{"ok":true,"token":"<64 hex>","role":"admin","csrf":"<32 hex>","expires":<unix seconds>}
and sets the cookie opence_session=<token>; HttpOnly; SameSite=Strict; Path=/, with Secure when the request came through
server.web_trusted_proxy with X-Forwarded-Proto: https (never from
another address, whatever it says). The admin password
(server.web_password) gives the admin role, the moderator password
(server.web_moderator_password) the moderator role, the viewer password
(server.web_viewer_password) the viewer role; {"by":"…"} beside the
password names who signed in, in the log. A session lasts 12 hours, or 30
minutes without a request (the RCON's messages do not count: a page left
open asks GET /api/session now and then); 16 are kept at most, of every
role.
The owner's password (server.web_owner_password, empty by default: none)
gives the owner role, for a supervisor on the server's own machine (a
fleet's agent, a panel's daemon): what standard input may do, over the
API and the RCON (quit, sv_stop, sv_restart, POST /api/stop, the
owner's settings by sv_set and PUT /api/settings, the game's own
console commands by POST /api/command, the players' addresses and
hardware ids in /api/players and the events). It signs in only when the
connection's own peer address is in 127.0.0.0/8 and is not the trusted
proxy's: never by X-Forwarded-For, and never through
server.web_trusted_proxy, even one on the machine itself. From any other
address the right owner's password is refused with 403 forbidden (the
RCON's auth: {"code":"forbidden"}, and the connection closes 1008),
and counts toward the address's lockout as a wrong password does. An
owner's session is used from the machine itself alone, as it was begun
(from elsewhere its token is no session: 401, the RCON's auth with it
denied). A password that is also another role's gives the owner role
from the machine itself and the other role from elsewhere: give the owner
a password of its own.
A script passes Authorization: Bearer <token>. The page passes the
cookie, and on every request that changes something the header
X-CSRF-Token: <csrf>; the Origin of such a request (and of the
WebSocket's) must be the server's own. An Origin: null is taken only
when the browser's Sec-Fetch-Site says same-origin.
POST /api/logout ends the session (with the X-CSRF-Token by the
cookie; GET answers 405). GET /api/session answers
{"ok":true,"role":…,"csrf":…,"expires":…}, or 401.
When server.web_password, server.web_moderator_password,
server.web_viewer_password or server.web_owner_password changes
(sv_set and the settings change the first two; sv_reload reads any of
them from config.toml), the sessions of its role end and that role's RCON
connections close (1008, the password changed).
Five wrong passwords from an address (an IPv6 one's /64) in 10 minutes
lock it out for 10 minutes (429), and no more than 30 passwords a minute
are checked in all. /api/login takes POST alone (any other method:
405).
{"ok":false,"error":{"code":"forbidden","message":"needs the admin role"}}| Status | Codes |
|---|---|
| 400 | bad_request, schema (a field missing or out of range), failed (the command ran and failed: its lines in lines), rejected (rotation entries: rejected[]), invalid (a gametype file: line) |
| 401 | denied (no session, or a wrong password) |
| 403 | forbidden (the role; the owner's password from beyond the machine), csrf, origin |
| 404 | not_found (also a command that is not one, a player or a ban that is not there) |
| 405 | method |
| 409 | pinned (a setting its environment variable sets), changed (a player's action whose slot holds another player now: the current name in name, nothing done) |
| 413 | too_large |
| 426 | bad_request (the WebSocket's version is not 13) |
| 429 | rate_limited, locked (with Retry-After) |
| 500 | internal (out of memory, a file that cannot be written) |
| 503 | loading (the game did not answer in 20 seconds, as while a map loads; with Retry-After: 5), starting, busy (8 RCON connections already; with Retry-After: 5) |
| Method, path | Role | Body → answer |
|---|---|---|
GET /healthz |
none | 200 {"state":"lobby"} (or loading, playing, postgame) while the server hosts and its frames run; 503 with {"state":"starting"}, {"state":"stalled"} (no frame for a minute) or the other state otherwise |
GET /metrics |
none (server.metrics) |
Prometheus text |
GET /api/status |
viewer | The status (below) |
GET /api/players |
viewer | {"ok":true,"players":[<player>…]} (with address and hwid for the owner, or every role with server.log_addresses; and discord_id, discord_name and discord_verified with them: a verified account's, else what the machine says, "" for none) |
POST /api/players/{slot}/kick |
moderator | {"name":"<the player's name, checked>"} → {"ok":true,"lines":[…]}, or 409 changed when the slot holds another player |
POST /api/players/{slot}/ban |
moderator | {"name":…,"duration":"1d","reason":"…"} (no duration: for ever, which a moderator's ban cannot be: 400 failed) |
POST /api/players/{slot}/mute |
moderator | {"name":…,"minutes":10} |
POST /api/players/{slot}/unmute |
moderator | {"name":…} |
POST /api/players/{slot}/tell |
moderator | {"name":…,"text":"…"} |
POST /api/say |
moderator | {"text":"…"} |
GET /api/rotation |
viewer | {"ok":true,"index":0,"entries":[<entry>…],"next":<entry>} |
PUT /api/rotation |
admin | {"entries":["bloodgulch:ctf",…]} → the rotation, or 400 rejected with "error":{…,"rejected":[{"index":1,"entry":"…","reason":"…"}]} and nothing changed |
POST /api/rotation/next |
moderator | {}: sv_map_next |
POST /api/rotation/play |
moderator | {"map":"…","gametype":"…"}: sv_map (map may be a whole rotation entry, map:gametype+rule=value, 255 characters at most, as the page sends one with rules; a map or gametype that cannot be played: 400 failed) |
GET /api/gametypes |
viewer | {"ok":true,"builtin":["slayer",…],"schema":{"fields":[<field>…]},"files":[{"name":…,"base":…,"description":…,"error":null}]} (builtin: the Xbox's gametypes, then OpenCE's; a file that cannot be read has base and description empty and error saying why) |
GET /api/gametypes/{name} |
viewer | {"ok":true,"name":…,"text":"<the TOML>"} |
PUT /api/gametypes/{name} |
admin | {"text":"<TOML>"} → {"ok":true}, or 400 invalid with line and message (a name is a–z, 0–9, _ and -, 32 at most) |
DELETE /api/gametypes/{name} |
admin | {"ok":true} |
GET /api/maps |
viewer | {"ok":true,"maps":[{"name":"bloodgulch","level":"levels\\test\\bloodgulch\\bloodgulch","kind":"xbox","title":"Blood Gulch"}…]} (kind: xbox, custom or mcc; title is the map's display name, else its name) |
GET /api/bans |
admin | {"ok":true,"bans":[{"n":0,"when":"2026-10-19 18:00:00","ip":"…","hwid":"…","discord_id":"…","discord_verified":true,"players":"…","reason":"…","until":<unix>|null}…]} |
GET /api/vpn |
viewer | {"ok":true,"policy":"link","fail":"open","lists":[{"master":"<url>","key_id":"…","serial":12,"generated":<unix>,"fetched":<unix>|null,"ranges":30582,"error":""}…],"file":"<server.vpn_list>","allow_ranges":0,"block_ranges":0,"held":true,"refused":{"vpn_link_required":0,"vpn_blocked":0,"vpn_link_invalid":0,"vpn_link_too_new":0,"vpn_link_in_use":0}} (held: a list is held, from a master or the file) |
POST /api/vpn/check |
moderator | {"ip":"203.0.113.5"} → {"ok":true,"listed":true,"by":"netlist"} (by: netlist, vpn_block.txt, vpn_allow.txt, or "") |
POST /api/bans |
admin | {"ip":"203.0.113.5","hwid":"…","discord_id":"…","names":"…","duration":"1d","reason":"…"} (ip, hwid or discord_id (a verified account's: up to 20 digits), or more than one; the rest may be left out: no duration is for ever) → {"ok":true,"n":<the new ban's number in GET /api/bans>}: sv_ban_address, a machine present of the address or the hardware id dropped; 400 schema for an address that is not IPv4, a hardware id that is not hex, a duration that is not one |
DELETE /api/bans/{n} |
admin | {"ok":true} |
GET /api/settings |
admin | {"ok":true,"settings":[<setting>…]} |
PUT /api/settings |
admin | {"server.name":"…","server.max_players":16,"server.public":true,…} (a value as JSON, a boolean, a number or a string, or its text: "true", "16"; null empties it) → {"ok":true,"applied":["server.name"],"errors":[{"name":…,"code":…,"message":…}]}; each setting is changed or refused on its own |
POST /api/command |
the command's | {"line":"sv_status"} (511 characters at most) → {"ok":true,"lines":["…"]}, or a refusal (failed, forbidden, not_found, pinned) with the command's lines |
POST /api/stop |
owner | {"after":"now|game|empty","notice":"…","restart":false} (notice and restart may be left out) or {"cancel":true} → {"ok":true,"lines":["…"]}: sv_stop (sv_restart with restart) after notice, or sv_stop cancel (400 failed with no drain waiting); 400 schema for another after |
GET /api/log?after=<n>&limit=<m> |
viewer | {"ok":true,"lines":[{"n":12,"time":<ms>,"level":"info","cat":"game","text":"…"}…],"next":12,"missed":0} (limit 1 to 1024, 256 by default; the chat's lines for admins only) |
GET /api/events?after=<seq> |
viewer | {"ok":true,"events":[<event>…],"next":<seq>,"missed":0} (player_joined and player_left with address and hwid for the owner, or every role with server.log_addresses) |
GET /ws |
The RCON (below) | |
GET /, /app.js, /app.css, /icon.svg |
none | The page (server.web_ui) |
next is the after of the next request: the last line's n (or event's
seq) read. An after past the latest (as after a restart) reads from the
start. missed counts lines or events that left the ring (2048 lines, 512
events) before they were asked for.
{"ok":true,"time":1760900000123,"name":"OpenCE Server","state":"playing",
"build":"build-206","network_version":38,"openh1_version":11,"game_mode":"openh1_120",
"game_mode_name":"GOAT H1 120 Tick, OpenCE can join","tick_rate":120,"opence":true,
"uptime":3600,"games_hosted":4,
"map":"bloodgulch","level":"levels\\test\\bloodgulch\\bloodgulch","gametype":"ctf","variant":"CTF","teams":true,
"players":5,"max_players":16,"machines":5,"countdown":-1,"game_seconds":312,"team_scores":[2,1],
"listing":{"online":true,"public":true,"password":false,"invite":"openh1://join/…"},
"rotation":{"index":0,"count":3,"next":{"text":"sidewinder:team_slayer","map":"sidewinder","gametype":"team_slayer"}},
"frame_ms_max":4.1,"frame_ms_avg":1.2,"tick_ms_avg":1.2,
"masters":[{"url":"https://master1.example.org","listed":true,"probe":"ok","code":"","message":"","updated":1760899990}],
"update":{"available":false,"build":""},
"drain":null,
"pid":4021,"started":1760896400,"instance":"eu-1","region":"eu","tunnel_port":2302,
"publisher_key_id":"3f9a2c7d1e5b8a04","web_port":8080,
"capabilities":["events","status","rotation","settings","bans","owner_web","ban_address","stop","event_addresses","identity"]}state is waiting (the menus settling), hosting (making the game),
lobby, loading, playing, postgame or stopping. countdown is the
lobby's seconds left, -1 when it is not counting. team_scores is null
in a game without teams. frame_ms_max and frame_ms_avg are the longest
and the mean frame of the last minute (tick_ms_avg is the mean again, for
older readers). game_mode is the kind of game hosted, as server.game_mode
spells it (a change of the setting waits for the server to be empty: "OpenH1
games"; before the server hosts, what the setting says), game_mode_name
its name as the server browser says it (Legacy, GOAT H1 120 Tick, OpenCE can join), tick_rate its tick rate (30 for a Legacy game), opence whether
OpenCE players join it now, and openh1_version the build's OpenH1 protocol
version (network_version its network version). invite is given to
admins only (empty for others). An entry of the rotation is
{"text":"sidewinder:team_slayer+score=50","map":"sidewinder","gametype":"team_slayer","rules":{"score":50},"rejected":null}
(rejected is why it cannot be played, else null). drain is the
drain waiting (sv_stop game...), {"after":"game","restart":false,"since":<unix seconds>}, else null. pid is the server's process, started when it
started (seconds since 1970), instance the name the master servers know
it by (server.instance, else the slug of server.name they are given),
region server.region, tunnel_port the tunnel's UDP port
(network.tunnel_port; 0 when network.online is off), publisher_key_id
the publisher key's id (16 hex digits; empty without a key: sv_publisher)
and web_port server.web_port. capabilities is the RCON's hello's. The rotation's
index (in the status and GET /api/rotation) is the entry being played,
-1 while an sv_map game is played or before the first lobby; next is
the entry after the one played last (the first while none has been).
A player is
{"slot":0,"name":"Milenko","team":0,"score":3,"kills":3,"deaths":1,"assists":0,"ping":42,"machine":1,"joined":1760899000,"muted":false,"admin":false}
(admin: an admin in the game, "Admins in the game"; with the owner role,
also key_id, the key their game proved to this server, "" for none);
with the owner role, or server.log_addresses, also
"address":"203.0.113.5","hwid":"…". team is 0 (red), 1 (blue) or -1
(no teams); ping is in milliseconds, null when it is not known yet.
client is the player's machine's build as its game tells it (shortly
after it joins), for every role:
{"build":282,"flavor":"release","version":"OpenCE Linux | build 282 (release)","repository":"OpenCommunityEdition/OpenCE","mods":["trollface 1.0"]}
(build 0 for a build CI did not number, repository empty when the build
does not know it, mods the mods it plays in their load order, each its
folder and its version), or null from a game that does not tell it. It is
what the player's game says, which a changed build can make anything.
A setting is
{"name":"server.name","type":"string","value":"OpenCE Server","default":"OpenCE Server","comment":"…","env":"HALO_SERVER_NAME","pinned":false,"secret":false,"choices":null,"min":null,"max":null};
type is boolean, integer, real or string, and value and
default are of that type in JSON (true, 16, "OpenCE Server"); a
reader should also take their text ("true", "16"), which older servers
sent. choices lists a word setting's words, min and max bound a
number's, each null where there is none (the table above). env is
null for a setting no environment variable sets. A secret one (the
passwords) has value and default empty and "set":true when it is
set. pinned is a setting
its environment variable (env) sets: it cannot be changed.
A gametype schema field is
{"key":"score_to_win","alias":"score","table":"universal","engine":"all","type":"integer","min":0,"max":999,"choices":null,"default":null,"description":"…"}
(table: the gametype file's table it goes in, universal, options,
ctf, slayer, oddball, king or race; engine: all, or the game
engine whose table it is; type: integer, boolean or choice).
GET /ws with Upgrade: websocket and the subprotocol opence-rcon-1.
Every frame is text holding one JSON object. The server speaks first:
→ {"type":"hello","protocol":1,"server":"OpenCE Server","build":"build-206","network_version":38,
"openh1_version":11,"game_mode":"openh1_120",
"capabilities":["events","status","rotation","settings","bans","owner_web","ban_address","stop","event_addresses","identity","vpn","link","game_mode"]}
← {"type":"auth","password":"…","by":"sam"} or {"type":"auth","token":"<session token>"}
→ {"type":"auth","ok":true,"role":"admin"}
→ {"type":"auth","ok":false,"error":{"code":"denied"}} and the connection closes (1008)
← {"type":"command","id":1,"line":"kick Milenko"} or {"type":"command","id":1,"command":"say","args":["two words"]}
→ {"type":"reply","id":1,"ok":true,"lines":["Milenko kicked by the host"]}
→ {"type":"reply","id":2,"ok":false,"lines":["…why…"]} (the command ran and failed)
→ {"type":"reply","id":3,"ok":false,"lines":[],"error":{"code":"busy","message":"…"}} (not run)
← {"type":"subscribe","events":["player","chat","game","moderation","status","log","master"],"after":1830}
→ {"type":"event","seq":1831,"time":1760900000123,"event":"player_joined","slot":3,"name":"Milenko",…,"replay":true}
→ {"type":"event","seq":1831,"time":…,"event":"status","status":{…the status…}} (at the subscribe, then every 2 s)
→ {"type":"event","time":…,"event":"log","n":5120,"level":"info","cat":"game","text":"…"} (no seq: n is its sequence)
← {"type":"ping"}
→ {"type":"pong"}
→ {"type":"overflow"} and the connection closes (1013): the client read too slowly
→ {"type":"error","id":…,"error":{"code":"…","message":"…"}} (an unknown type, a malformed message)
A connection signed in with the page's cookie (on the same origin) needs no
auth message: its hello is followed by {"type":"auth","ok":true,…}.
The capabilities say what the server has beyond the first release's
(events, status, rotation, settings, bans): owner_web,
ban_address, stop, event_addresses and identity ("Panels and
fleets"), vpn (the VPN policy, /api/vpn, join_refused), link
(verified Discord accounts: discord_* in players, bans by discord_id)
and game_mode (the kind of game hosted and its tick rate in the status,
the hello and the game's events: "OpenH1 games");
a client checks for one before it uses it. The owner's password
signs in from the server's own machine alone ("Signing in").
A command is a line, or a command and its args, which the server
joins with spaces, quoting an argument that holds a space or is empty (511
characters in all at most). Ids are the client's (a number or a string),
echoed in the reply; each command gets exactly one reply. A connection
runs one command at a time: a command sent before the last one's reply is
not run. A reply whose command ran has ok and the command's lines, and
no error, whether it succeeded or failed; one that was not run has ok
false, no lines and an error: denied (not signed in), rate_limited
(32 commands a second, in bursts of 64), bad_request (no command, or too
long), busy (another command's reply is awaited) or loading (the game
did not answer in 20 seconds; the command may still have run, and is never
sent again by the server). after replays the events still in the ring
since that sequence number, marked "replay":true. A connection holds 1024
messages for the client at most; 8 connections are taken at once (a ninth
upgrade answers 503 busy), and each upgrade counts against its address's
allowance (above). The
event groups are player (player_joined, player_left, map_share), chat
(chat), game (lobby_opened, countdown, game_started,
game_ended, postgame, score, kill, afk_kick, coop_bsp_switch,
map_vote_started, map_vote_ended), moderation (kick, ban,
unban, mute, unmute, speed_hack, join_refused, admin_command), status (status), log
(log, each log line as {"n","level","cat","text"}), master
(master), and server (server_started, reloaded, warning,
drain, shutdown), which every subscriber gets.
The log's lines of the chat category go to the chat group, the others
to log.
status and log events go to their subscribers as they come and are
not kept in the ring: after does not replay them (/api/log reads the
log's own ring). A status event's seq is the latest event's (no new
number: the same one comes again until another event), and a log event
has no seq: its n, the log line's number and /api/log's cursor, is
its sequence. A client keeps one cursor for the events (seq, of the
events of the ring) and another for the log's lines (n); a client that
reconnects with after may get events it had, and drops those whose seq
it has seen (a status event is never dropped so).
Every event has seq (rising, never reused while the server runs; a
status event has the latest one's, a log event none: above), time
(milliseconds since the epoch) and event:
| Event | Fields |
|---|---|
server_started |
name, build, network_version, openh1_version, game_mode (server.game_mode as the server starts), pid, started, instance, region, tunnel_port, publisher_key_id, web_port (as the status's), rotation[] (the entries' texts) |
lobby_opened |
map, gametype, variant (the gametype's name as the game shows it), teams, index (the rotation's entry) |
countdown |
seconds (-1: paused) |
game_started |
map, gametype, variant, teams, game_mode, tick_rate (as the status's), team_scores[] (team games), players[] |
game_ended |
map, gametype, variant, teams, game_mode, tick_rate, reason (score, time, idle, empty, command, next, update: a new network version's install, vote: the players' vote to end it), duration (seconds), team_scores[] (team games), players[] |
postgame |
seconds |
player_joined |
slot, name, team, machine; address, hwid, discord_id, discord_name, discord_verified for the owner, or every role with server.log_addresses |
join_refused |
name (the machine's), reason (vpn_link_required, vpn_blocked, vpn_link_invalid, vpn_link_too_new, vpn_link_in_use, address_full); address, hwid as player_joined's |
player_left |
slot, name, reason (left; kicked and banned when the server's kick, ban or sv_ban_address dropped the machine, banned for a speed hack's drop too, afk for a player away); address, hwid (as it joined) as player_joined's |
afk_kick |
players (the machine's players' names), seconds (away) |
coop_bsp_switch |
from, to (the level's parts), players[] (the names of those who crossed) |
map_vote_started |
seconds, choices[] ({"map","gametype","index"}: the rotation's entries) |
map_vote_ended |
map, gametype, index, votes (the winner) |
chat |
channel (everyone, team, vehicle), slot, name, text (admins only; the lines the host sends on) |
kill |
killer, victim (slots; -1 for none), weapon (the killer's weapon's or the killing object's tag name, or null), friendly_fire |
score |
map, gametype, variant, teams, team_scores[] (team games), players[] (once a second at most, on a change) |
kick, ban, unban, mute, unmute |
name, by, reason?, until? (by: the role, or admin <name> (key <id>) for an admin in the game) |
admin_command |
name, key_id, line, ok: an admin's request from the game, the command it ran and whether it did ("Admins in the game") |
speed_hack |
machine, names, rate, ahead_ticks, action (kicked, or unverified: its datagrams alone said so, and it stays) |
map_share |
machine, map, state (asked, downloading at each tenth, downloaded or failed once for each request), progress (0 to 100: a percentage already) |
warning |
text (a newer release, with server.auto_update) |
reloaded |
rotation_changed, rejected[] ({"entry","reason"} of each entry left out) |
master |
url, listed, probe, code, message |
drain |
after (now, game, empty, cancel), restart (exit code 5), notice (empty for none) |
shutdown |
reason (quit, sv_stop, sv_restart, drained: a drain's end, signal <n>, update installed, nothing to play, debug.exit_after), code (the exit code) |
Players in events are as in /api/players for the viewer role (no
addresses), but for player_joined and player_left, which carry the
player's address and hardware id ("" when not known) to the owner, and to
every role when server.log_addresses is on (/api/players' rule), in the
RCON's events, their replay and GET /api/events alike. variant is the gametype's name as the game shows it (Co-op
in a co-op entry).
A ban is a line of bans.txt (in paths.logs, else the data root). A
timed ban is kept out by its line's until= alone, and ends then. A ban
for ever, and a machine dropped for cheating, also keep the machine out
for the rest of the run by its address, its real address or its hardware
id. A player reached through a relay is known by the address the relay saw
its packets come from ("Relays"), never one it gave of itself. sv_ban_address and POST /api/bans write such a line for an address
or a hardware id with no player of it needed (the part not given is
none). unban takes the line out and readmits the machine by
the line's address or hardware id, whether it joins on the LAN or by
internet play.
A line's discord_id is a verified Discord account's when it has no
(self-reported) after it: ban writes it so for a machine that showed a
pass, and sv_ban_address discord:<id> and POST /api/bans' discord_id
write it. Such a line keeps out every machine that shows a pass of that
account, from any address. What a machine says of its Discord account
itself is written with (self-reported) and never matched: anyone could
say it.
server.rotation (and sv_rotation_set, PUT /api/rotation) is a list of
entries, map[:gametype[+rule=value...]], separated by commas, semicolons
or new lines; a line that begins with # is a comment (to its line's end,
commas and all). The text is 4096 characters at most (the entries past it
are left out, with a warning), an entry 255 characters and the list 64
entries. config.toml keeps a string setting of up to 4096 characters, so
a rotation that long is saved whole and read back after a restart.
- The map is a multiplayer map's name (
bloodgulch: the Xbox'smaps/<name>.map, else a Custom Edition map ofcustom_maps),custom_maps\<name>(a Custom Edition map;/is taken for\), or a level's path (levels\test\bloodgulch\bloodgulch). A campaign level is played as co-op only:<level>:coop, atserver.coop_difficulty. - The gametype (
slayerwhen there is none) is a built-in's name (slayer,team_slayer,slayer_pro,elimination,phantoms,endurance,rockets,snipers,stalker,ctf,ironctf,ctf_pro,invasion,oddball,team_oddball,reverse_tag,accumulation,juggernaut,king,team_king,king_pro,crazy_king,race,team_race,rally,team_rally, and Halo PC's namesffa,ffa_slayer,teamslayer,tslayer,koth,team_koth,iron_ctf,teamrace,teamoddball), an OpenCE gametype's (swat,infection,gun_game,hardcore,hardcore_ctf,hardcore_oddball,hardcore_king), a gametype file's name (gametypes/<name>.toml), orfile=<name>(a gametype a player's game saved, below). A gametype's name is letters, digits,_,-and., in any case. - A rule is a gametype rule's name or its short name (
score,time,weapons,ff...;GET /api/gametypes's schema lists them), with a value it takes; a rule of another game engine than the gametype's is refused. 48 rules at most; a rule given twice is the last. OpenCE's gametype options are rules too:kills_scoreandpoints_per_capture(CTF: a kill scores a point and a capture that many, the score to win still in captures),multi_hill(King of the Hill: 2 to 5 hills at once) andforce_team_spawns(a team game's players spawn at their own team's CTF spawn points):bloodgulch:ctf+kills_score=true.
A co-op entry's riding rule (a10:coop+riding=true or =false)
overrides network.vehicle_riding for that entry only. An entry without
it uses the setting; a map's own choice still wins over both.
An entry that cannot be played (a map that is not there, a bad gametype
file, a rule out of range) is left out with a warning, at the start and at
sv_reload; sv_rotation_set and PUT /api/rotation change nothing when
one of their entries cannot be played.
A change of the rotation (sv_rotation_*, PUT /api/rotation,
sv_reload) keeps its place: the next game is the entry after the one
played last, found again in the new list (the first entry only when none
has been played yet). sv_reload takes the rotation again when its text
changed, and also when only its entries' rejections changed (a map or a
gametype file added or taken out since).
sv_reload also requests an MCC catalog refresh. It runs on the next pregame
frame, or after the current game returns to the lobby; it never rescans during
gameplay or loading. Refresh the web page after that point to see newly copied
MCC packages. Ordinary /api/maps requests reuse the catalog. Xbox and Custom
Edition map enumeration is unchanged.
server.team_start decides how a team game starts. one (the default)
starts it with the players of one team. both waits, saying nothing,
for a player on each team. skip, when one player waits for a team game
that sv_map did not ask for, plays the rotation's next entry without
teams instead (if it has one); it is checked when the lobby opens and
again when its countdown would begin. With no entry left, the server
stops with exit code 3 (2 when no rotation map is there), or plays
bloodgulch:slayer with server.rotation_fallback.
A gametype file, gametypes/<name>.toml (the name a–z, 0–9, _
and -), is a built-in or OpenCE gametype (base) and rules over it:
base = "team_king" # the gametype it starts from
name = "Moving Hill" # the name the game shows: 11 characters of printable ASCII
[universal]
score_to_win = 3
[options]
time_limit = 15
friendly_fire = "off"
[king]
moving_hill = trueEach rule goes in its table (the schema's table): [universal],
[options], and one game engine's, [ctf], [slayer], [oddball],
[king] or [race]. A file gives each rule its full name
(vehicle_set, team_vehicles, score_to_win): the short names
(vehicles, score) are the rotation's alone. A file is 64 KB at most.
deploy/gametypes has examples. The server reads the gametypes folder
beside config.toml if there is one, else the data root's, and writes the
web page's files to it.
A gametype a player's game saved is played with file=<name>: copy the
saved gametype, as <name>.gametype, into the same gametypes folder
(beside config.toml if there is one, else the data root's).
vehicle_riding under [universal] is a boolean: true lets players
standing on a moving vehicle ride along with it; no rule means off.
Stock gametypes and older saved ones have it off. In rotation entries its
short name is riding (bloodgulch:ctf+riding=true). The dedicated
override and a map's own choice take precedence ("Vehicle riding", above).
A public server (server.public, with network.online and
network.public_lobby) is published to each master server of
masters.txt (docs/master_protocol.md). A change that a list shows (the
listing made public or private, a player joining or leaving, the name, the
map) is published within 5 seconds. Made private, the server makes a new
invite and sends the masters a closed publish, which takes it off their
lists;
network.public_lobby = false stops the publishing too. A master's
Retry-After is kept (a day at most). key_revoked and
publisher_revoked stop the publishing to that master for the run;
unknown_key, publisher_pending, application_denied and
listing_taken are logged once a minute while they last.
Players whose networks keep them apart (both behind NATs that give each
destination a port of their own, which hole punching cannot meet: many
mobile carriers, carrier-grade NAT, offices) connect through a relay
(port/linux/src/p2p_relay.c; port/linux/README.md, "Relays"). Only
servers relay, never a player's machine, and a pair uses a relay only once
a direct connection has failed.
- A dedicated server relays as
server.relaysays."game"(the default): only pairs one side of which is a player of its own game (map sharing between its players), whom it tells that it relays."any": any two machines, for a server that players name in theirrelays.txt."off": none. - A relay alone (
halo --relay): any two machines, onnetwork.tunnel_port(2302 if none), with no game data. It logs its counts each minute they change (pairs, formed, ended, refused, challenged, packets and bytes forwarded, packets dropped by its limits). A small VPS serves: a pair of players takes their game's traffic both ways, some tens of kilobytes a second. - Where players learn of relays:
relays.txtbesidemasters.txt(network.relays_file; a dedicated server's own,server.relays_file, which it offers its joiners and tells its players of): the project's own,net.goath1.com:2302(deploy/net), by default and when there is no file (an empty one names none); and what the dedicated server of their game tells them. - Limits (both):
server.relay_pairs(64) pairs at once, 8 for each address;server.relay_upload(8192 KB/s) in all, 256 KB/s for each pair and 1 MB/s for each address; binds answered 20 times a second for each address and 2000 in all. A side not heard for 15 seconds is let go, a pair idle for 30 seconds ends, and one unpaired for 25. - What a relay is shown. Each machine binds with a token made from its session's secret and the relay's address (HMAC-SHA256), so each relay has a token of its own, which says nothing of the secret or of the tunnel's keys, and which no relay can use at another. A bind is taken only with a cookie the relay gave its address (an HMAC of the address, the port, the token and the time, by a secret of the relay's), so a bind with a forged source binds nothing and reflects only a smaller challenge. The relay forwards only tunnel packets (sealed end to end, which it cannot read or change), only between the two addresses it checked. It learns both machines' addresses; it tells the host's side where the player's packets come from (the address the host bans and votes by, as on a direct connection), and the player's side nothing about the host.
The relay's packets (the tunnel's UDP socket; their first byte 0x6A,
version 2):
| Packet | Bytes |
|---|---|
| BIND (machine to relay) | 0x6A, B, 2, side (0 the host's, 1 the joiner's), token (32), nonce (8), cookie (16; zeros at first) |
| CHALLENGE (relay to machine) | 0x6A, C, 2, 0, the bind's nonce (8), cookie (16) |
| BOUND (relay to machine) | 0x6A, K, 2, state (0 waiting, 1 paired, 2 refused), the bind's nonce (8), the pair's channel (8), the other side's IPv4 address and port (to side 0 once paired; else zeros), 2 zeros |
| DATA | 0x6A, D (machine to relay) or d (relay to machine), the channel (8), one tunnel packet |
| RELEASE (machine to relay) | 0x6A, X, 2, side, token (32): from that side's address alone |
A machine binds every half second until paired, then every 4 seconds. The
machines offer each other relays through signalling (a sealed R message,
version 2, on the session's topics, which OpenCE and older builds pass
over): the offering machine's identifier and side, a count (3 at most),
each relay's address and port, and a tag (HMAC-SHA256 by the session's
secret), taken one a second and 8 in all for a session. A dedicated server
tells each player of its game its relays in a tunnel packet of its own
(_packet_relays). These are OpenH1 protocol version 16's.
A server (or a player's host) behind a NAT that nothing can punch through
(carrier-grade NAT, a NAT that gives each destination a port of its own)
can still be joined by every player, OpenCE's too, through a front: a
public UDP port on a relay of halo --relay
(port/linux/src/p2p_front.c; port/linux/NETCODE.md, "Fronts"). The
server keeps one session with the front, which gives it a port of its
own; the server lists that port as one more of its addresses (after
network.public_address, before its own), joiners punch to it as to any,
and the front passes each tunnel packet that reaches the port down the
session, and the server's answers back out of the port. The tunnel stays
sealed end to end: a front sees the addresses of the server and of the
players who reach it, never what they send.
Setting one up:
- On a machine with a public address (a small VPS), in
config.tomlbesidehalo --relay:server.front_ports = "2310-2325"(a port for each server it serves, 64 at most). Open UDPnetwork.tunnel_port(2302) and those ports in its firewall. - On each server,
halo --keygenwrites its publisher key (the one the master servers know it by, if it publishes) and prints its public key,ed25519:<hex>. - On the front, put each server's public key on a line of
front_operators.txtbesideconfig.toml(server.front_operators_file; read again each minute), and starthalo --relay. It logs the ports and the keys it allows. - On the server,
network.front = "<the front's address>:2302". It logs "front ... registered this machine: joiners are offered ..." once the front gives it a port; the server needs no port forwarded of its own.
A port stays with a server's key while it is registered, and is given back to the same key when it registers again after a lapse, so its address stays the same. A registration lapses after 15 seconds without a renewal (the server renews every 4); the server gives the front up after 12 seconds without an answer and asks again every second, its listed address withdrawn meanwhile.
Limits. REGISTERs answered: 200 a second in all; signatures checked: 50
a second. A registration's clients: 64, 8 from one address; a client the
server never answered is forgotten after 5 seconds and gives way first when
the table is full (so a flood from forged addresses cannot keep players
out), one answered after 20 seconds of silence. Bytes: 256 KB/s for each
client, 2 MB/s for each registration (both ways), and server.relay_upload
for the front in all. The front passes only tunnel packets of a tunnel
packet's sizes, to a registered server's port alone, and sends a player
only what its server sent it: nothing a front sends to an address it has
not checked is larger than what that address sent it.
The front's packets (UDP; the front's on its network.tunnel_port, the
server's on its tunnel's socket; their first byte 0x6B, version 1):
| Packet | Bytes |
|---|---|
| REGISTER (server to front) | 0x6B, R, 1, 0, the publisher key (32), nonce (8), cookie (16; zeros at first), Ed25519 signature (64) of "openh1 front register 1", the key, the nonce and the cookie |
| CHALLENGE (front to server) | 0x6B, C, 1, 0, the REGISTER's nonce (8), cookie (16: an HMAC by a secret of the front's of the address and port the REGISTER came from, its key and the 30-second period) |
| REGISTERED (front to server) | 0x6B, G, 1, state (0 registered, 1 refused: the key is not allowed, 2 full: no port free), the REGISTER's nonce (8), the session (8), the public port (2, network order), 2 zeros |
| FROM (front to server) | 0x6B, F, the session (8), the client's number (4), the client's IPv4 address and port as the front saw them (6), one tunnel packet |
| TO (server to front) | 0x6B, T, the session (8), the client's number (4), one tunnel packet, which the front sends to that client from the public port |
A REGISTER is taken only with a cookie the front gave its address in this period or the last, and a key in the operators' file, and a good signature (the same REGISTER again, the keep-alive, is not checked again). The front takes TO only from the registered server's address with its session, and the server takes FROM only from its front's address with its session.
| File | What |
|---|---|
config.toml |
Every setting (beside the executable; HALO_CONFIG_FILE, else --config, names another) |
init.txt (server.init_file) |
Commands run at the start, in the data root unless a full path |
gametypes/<name>.toml |
Gametype files: the gametypes folder beside config.toml if there is one, else the data root's |
gametypes/<name>.gametype |
Gametypes saved by a player's game (file=<name> in the rotation): the same gametypes folder |
publisher.key |
The publisher key for the master servers (beside config.toml). On Windows, a server's config.toml and publisher.key are given an access list of their owner alone (the entries inherited for Administrators and SYSTEM taken out) |
masters.txt |
The master servers (server.masters_file: beside config.toml, else beside the executable); the release's names the project's master and OpenCE's official masters (OpenCE's, HaloBase's and Unicade's), which are also built in for one that names none: the server publishes to each, checks addresses against all their netlists and takes passes any of them signed (docs/master_protocol.md) |
relays.txt |
The relays the server offers players who cannot reach it, and tells its players of (server.relays_file, found as masters.txt is): host[:port] on each line; the project's, net.goath1.com:2302, by default ("Relays") |
bans.txt, cheaters.txt, debug.txt |
In paths.logs, else the data root |
admins.txt, admin_id.txt |
Beside bans.txt: the players' keys (or key ids) who are admins in the game, and the server's id their keys for it are made from ("Admins in the game") |
vpn_allow.txt, vpn_block.txt, netlist-<master key id>.bin |
Beside bans.txt: ranges never refused as a VPN's, ranges refused besides, and the masters' netlists held ("VPNs and linked Discord accounts") |
status.json (server.status_file) |
The status, written every 2 seconds |
A password's file (HALO_SERVER_WEB_PASSWORD_FILE, HALO_SERVER_WEB_OWNER_PASSWORD_FILE, HALO_SERVER_WEB_MODERATOR_PASSWORD_FILE, HALO_SERVER_WEB_VIEWER_PASSWORD_FILE, HALO_SERVER_PASSWORD_FILE) |
A container's secret: when the plain variable is not set, the file's first line (its CR and LF off) is the setting's value, which is then pinned as the plain variable's would be (sv_set and PUT /api/settings refuse it, 409 pinned). Read once, at the start; a file that cannot be read is logged, and the setting is config.toml's |
OpenCE's releases have a SHA256SUMS signed with OpenCE's release key; OpenH1's
releases are not signed so, and OpenH1 has neither that key nor
tools/release_sign.sh.