DocumentationBot: Version 1

2026-10-01T04:13:05Z

Version 1

New page

{{GameNav}}
Community dedicated servers keep configuration, add-ons, state, cache, replays, and secrets in an isolated writable data directory. The game installation remains read-only and can be replaced during an update.

Community operators configure this environment. Vellocet manages official servers separately.

== Create the server data directory ==

Assign a different absolute data directory to each server process:

<syntaxhighlight lang="text">
GrimwarServer --data-dir /srv/grimwar/community-1 --server-preflight-only
</syntaxhighlight>

Preflight checks the runtime, creates missing operator files, and exits. A normal first launch creates the same layout. Existing operator files are not overwritten.

Use <code>--instance-id <id></code> when the default per-user server location is suitable. <code>GRIMWAR_DATA_DIR</code> and <code>GRIMWAR_INSTANCE_ID</code> provide the corresponding environment settings. Never point two running processes at the same data directory.

Run <code>cmdlhelp</code> in the server console for the current command-line contract. Run <code>cfg_paths</code> for the resolved install, data, config, secret, add-on, replay, state, and cache paths.

=== Common launch options ===

The shared name, map, player-limit, and password contract is documented in [[Dedicated server launch settings]]. Use the traditional aliases on older Grimwar releases. The options below cover Grimwar-specific setup and those existing aliases.

Switches accept <code>-</code>, <code>--</code>, <code>/</code>, or <code>+</code>. A value may follow the switch or use <code>=</code>.

{| class="wikitable"
! Option !! Purpose
|-
| <code>--data-dir <path></code> || Select an absolute writable data root.
|-
| <code>--instance-id <id></code> || Select a named data root below the default per-user location.
|-
| <code>--map <map-id></code> || Start on a registered map. This does not replace the saved rotation.
|-
| <code>--mode <mode-id></code> || Override the startup mode, or select the first rotation entry using that mode when no map is supplied.
|-
| <code>--hostname <name></code> || Override the browser name for this process.
|-
| <code>--max-players <count></code> || Override the total playable slots.
|-
| <code>--steam-game-port <port></code> || Change the internal Steam game-service UDP port.
|-
| <code>--steam-query-port <port></code> || Change the internal Steam query UDP port.
|-
| <code>--server-preflight-only</code> || Validate configuration and create missing operator files, then exit before platform login.
|-
| <code>--server-startup-smoke</code> || Initialize content, Workshop, security, and platform services, then exit before publication.
|-
| <code>+<console-variable> <value></code> || Apply a non-secret console-variable override after <code>autoexec.cfg</code>.
|}

Prefer the secret files described below for passwords. Join-password launch options are supported, but users with sufficient machine access can inspect command lines. Keep platform credentials in the secret environment or deployment files.

== Network transport and ports ==

Community servers use Steam Relay for gameplay and Steam public discovery. The stock server does not accept direct-IP gameplay joins, so do not expose or forward a gameplay UDP port. Install the current dedicated-server build through SteamCMD and allow outbound Steam and HTTPS traffic.

The internal Steam service defaults are <code>27015/UDP</code> for the game service and <code>27016/UDP</code> for queries. Change them only when another local process owns one of those ports. Keep the values distinct.

RCON is separate. Its default <code>27015/TCP</code> does not conflict with <code>27015/UDP</code>. Expose the RCON TCP port only to administrator addresses or a private network.

Official servers use managed direct UDP. A matchmaking deployment is visible only to its assigned players. A standalone official deployment appears in the browser with an '''Official''' badge, but its endpoint is withheld until the joining Steam identity is verified. Community builds cannot enable this contract with a name, tag, or config value.

=== Public discovery and stable references ===

The in-game browser reads community servers directly from Steam. It accepts only the current Grimwar app, secure dedicated-server listings, complete compatible metadata, and a Steam FakeIP. The FakeIP is a relay address rather than the host's origin address. The client does not make separate ping, rules, player, or A2S queries and always joins by the server's numeric SteamID through Steam Relay.

The server is discoverable after it logs <code>Steam relay identity allocated for community discovery</code>, <code>Steam GameServer online</code>, <code>advertise=True</code>, and <code>Dedicated server ready; publication is open</code>. No Supabase account, directory registration, public gameplay port, or IP disclosure is required. A compatible current client only needs to refresh the Internet tab.

A game-server login token is optional for discovery. Without one, Steam assigns an anonymous server account whose SteamID may change after a restart. For a durable console reference, create a Grimwar game-server login token and set it as the secret environment variable <code>SERVER_PLATFORM_CREDENTIAL</code> in the hosting panel. Steam then logs the process into a persistent game-server account. Never pass the token through <code>-gslt</code>, <code>--gslt</code>, a panel note, or another command-line value; those switches are unsupported and command lines and logs may expose their contents. Rotate a token immediately if it is disclosed.

Run <code>server_id</code> in the server console to print the connection SteamID. Players can keep this relay-safe reference in their notes and reconnect from the game console:

<syntaxhighlight lang="text">
connect 90292054295284751
</syntaxhighlight>

Use the value printed by that server, not the example above. Steam's desktop Favorites feature stores an address and ports; it is separate from a Grimwar SteamID note and should not be treated as the server's durable identity.

== Operator files ==

The first normal or preflight launch creates the following files and directories below the data root:

{| class="wikitable"
! Path !! Purpose
|-
| <code>config/server.cfg</code> || Base non-secret settings.
|-
| <code>config/server.d/</code> || Split non-secret <code>.cfg</code> files.
|-
| <code>config/rulesets/</code> || Operator-defined rulesets.
|-
| <code>config/modes/</code> || Per-mode overrides named <code><mode-id>.cfg</code>.
|-
| <code>config/maps/</code> || Per-map overrides named <code><map-id>.cfg</code>.
|-
| <code>config/autoexec.cfg</code> || Final non-secret overrides.
|-
| <code>config/motd.html</code> || Optional message-of-the-day HTML fragment.
|-
| <code>config/bots.cfg</code> || Optional bot display names, one per line.
|-
| <code>config/banned_user.cfg</code> || Persistent SteamID bans.
|-
| <code>config/rotation.json</code> || Ordered map/mode rotation or map blacklist.
|-
| <code>config/server-addons.json</code> || Workshop items, manual bindings, and collections.
|-
| <code>config/mods/</code> || VMod Admin users, groups, capability grants, and other mod configuration.
|-
| <code>secrets/server.secrets.cfg</code> || Sensitive settings such as the RCON password.
|-
| <code>secrets/server.secrets.d/</code> || Split sensitive <code>.cfg</code> files.
|}

<code>secrets/deployment.cfg</code> is not an operator file. A hosting environment may generate it as the final, owner-restricted override layer.

== Config precedence ==

The server applies configuration in this order. A later assignment to the same console variable wins.

{| class="wikitable"
! Order !! Source
|-
| 1 || <code>config/server.cfg</code>
|-
| 2 || <code>config/server.d/*.cfg</code>, sorted by filename without regard to case
|-
| 3 || The ruleset selected by <code>sv_ruleset</code>
|-
| 4 || <code>config/modes/<active-mode-id>.cfg</code>
|-
| 5 || <code>config/maps/<active-map-id>.cfg</code>
|-
| 6 || <code>config/autoexec.cfg</code>
|-
| 7 || Command-line <code>+variable value</code> overrides
|-
| 8 || <code>secrets/server.secrets.d/*.cfg</code>, sorted by filename without regard to case
|-
| 9 || <code>secrets/server.secrets.cfg</code>
|-
| 10 || Generated <code>secrets/deployment.cfg</code>
|}

Each non-comment line in a normal CFG file is submitted as a console command. Quote values that contain spaces:

<syntaxhighlight lang="text">
hostname "Toronto Community Server"
bot_quota 4
mp_timelimit 30
</syntaxhighlight>

Use numeric prefixes when the order inside <code>server.d</code> matters, such as <code>10-identity.cfg</code> and <code>20-gameplay.cfg</code>. Lines beginning with <code>//</code> or <code>#</code> are comments.

Sensitive identifiers containing terms such as <code>password</code>, <code>secret</code>, <code>token</code>, or <code>apikey</code> are ignored in non-secret files and command-line overrides. Secret layers suppress their command output.

Run authenticated <code>cfg_reload</code> to reapply the CFG stack and selected ruleset for the current map and mode. It does not synchronize Workshop items, reload manually staged packages, or load <code>server-addons.json</code>. Restart after changing those inputs. <code>rotation.json</code> is read by rotation selection rather than by <code>cfg_reload</code>.

== Basic server settings ==

Uncomment or add only the values the server needs in <code>config/server.cfg</code>. For example:

<syntaxhighlight lang="text">
hostname "Toronto Community Server"
sv_ruleset casual

bot_quota 4
bot_quota_mode 0
bot_difficulty 2

mp_timelimit 30
mp_roundtime 0
mp_winlimit 0
mp_maxrounds 0
sv_match_end_policy 1
</syntaxhighlight>

<code>0</code> lets the active mode supply its default where supported. <code>sv_match_end_policy</code> accepts <code>0</code> for a next-map vote, <code>1</code> for automatic travel to the next rotation entry, or <code>2</code> to quit after the match.

Use the console's variable help for the current value contract. The generated <code>server.cfg</code> also lists common bot, match, security, inventory, and movement settings.

=== Rulesets ===

Community and listen servers default to the bundled <code>casual</code> ruleset. Put a custom ruleset in <code>config/rulesets/<name>.cfg</code>:

<syntaxhighlight lang="text">
// config/rulesets/community_plus.cfg
exec rulesets/casual.cfg
mp_allowspectators 0
</syntaxhighlight>

Select it with <code>sv_ruleset community_plus</code>. A ruleset supports one console-variable assignment per line, <code>exec rulesets/<name>.cfg</code> inheritance, blank lines, and comments. It rejects arbitrary commands, nested paths, unknown or sensitive variables, include cycles, and invalid values.

During a live or overtime round, a console change to <code>sv_ruleset</code> applies at the next round boundary unless the command includes <code>now</code>.

=== Per-mode and per-map overrides ===

Name each override file with the canonical runtime ID. Map overrides run after mode overrides, so a map can refine a shared mode configuration:

<syntaxhighlight lang="text">
// config/modes/arena.cfg
mp_roundtime 12
bot_quota 6
</syntaxhighlight>

<syntaxhighlight lang="text">
// config/maps/as_compound.cfg
mp_roundtime 10
</syntaxhighlight>

When <code>as_compound</code> runs in <code>arena</code>, the round time is 10 because the map file is later in the stack. A map played in another mode still receives its map file. Put an override in <code>autoexec.cfg</code> only when it must win for every map and mode.

== Message of the day ==

Enable the generated <code>config/motd.html</code> fragment from <code>server.cfg</code>:

<syntaxhighlight lang="text">
sv_motd_enabled 1
sv_motd_title "Server Rules"
sv_motd_file "motd.html"
</syntaxhighlight>

The file is shown after a player joins and before deployment. It may contain inline HTML, CSS, and <code>data:</code> images or fonts. Scripts, forms, frames, plugins, media, navigation, and network requests are blocked. The title is limited to 128 characters and the HTML payload to 64 KiB. File lookup stays inside the server config root and accepts only <code>.html</code> files.

== Bot names and bans ==

Leave <code>config/bots.cfg</code> blank to use the built-in bot names. To replace them, add one display name per line:

<syntaxhighlight lang="text">
Mara
"Copper Jack"
Ash
</syntaxhighlight>

<code>config/banned_user.cfg</code> stores one SteamID64 per line. An optional second value is a Unix expiry time; <code>0</code> means permanent:

<syntaxhighlight lang="text">
# permanent
76561198000000000 0
</syntaxhighlight>

Authenticated console and RCON commands update the file:

<syntaxhighlight lang="text">
banid <steamid|userid|name> [minutes] [kick]
removeid <steamid>
</syntaxhighlight>

A missing or zero duration creates a permanent ban. Use a positive duration for a temporary ban.

== Configure RCON ==

Put RCON settings in <code>secrets/server.secrets.cfg</code>:

<syntaxhighlight lang="text">
rcon_enable 1
rcon_password "use-a-long-unique-password"
rcon_port 27015
rcon_maxclients 3
rcon_timeout 30
rcon_failures 3
rcon_ban_time 300
rcon_log 1
</syntaxhighlight>

Restrict the secret directory at the operating-system level. Expose the RCON TCP port only to administrator addresses or a private network. Do not reuse the server password or a Steam credential as the RCON password.

== Configure map and mode rotation ==

<code>config/rotation.json</code> stores map/mode pairs. <code>listMode</code> defaults to <code>whitelist</code>, which keeps the declared order:

<syntaxhighlight lang="json">
{
"listMode": "whitelist",
"entries": [
"as_compound",
{
"map": "bz_ordainment",
"mode": "blitz"
},
{
"map": "community_castle",
"mode": "arena"
},
{
"map": "community_castle",
"mode": "koth"
}
]
}
</syntaxhighlight>

Use internal map IDs from the installed package manifests. A string is shorthand for an object with a <code>map</code> field and no <code>mode</code> field. The same map can appear more than once when each entry has a different mode. Duplicate map/mode pairs are removed.

=== How a mode is selected ===

For each whitelist entry, the server resolves the mode in this order:

# The entry's explicit <code>mode</code> value.
# The map entry's <code>defaultModeId</code> in its installed <code>addon.json</code> or built-in map data.
# <code>sandbox</code> when the map declares no default.

Map ID prefixes are not part of mode selection. A map named <code>bz_example</code> does not select <code>blitz</code> unless its map metadata declares that default or the rotation entry supplies <code>"mode": "blitz"</code>.

An explicit mode must be built in or registered by an active VMod before the map starts. Otherwise the mode cannot be activated.

=== Blacklist rotation ===

Set <code>listMode</code> to <code>blacklist</code> to rotate every registered map except the listed defaults:

<syntaxhighlight lang="json">
{
"listMode": "blacklist",
"entries": [
"as_compound",
"community_ruins"
]
}
</syntaxhighlight>

Blacklist expansion runs after Workshop synchronization. Each registered map contributes one pair using its default mode, and the remaining maps are sorted by internal ID without regard to case. An empty blacklist rotates every registered map. Excluding every map stops startup with an error.

An object entry can exclude an exact map/default-mode pair, but a blacklist cannot assign an alternative mode or add a second pairing. Use a whitelist when a map must run with an override or in several modes.

=== Startup and match transitions ===

Workshop synchronization and add-on loading finish before the final startup map is selected. Missing or unavailable whitelist entries are skipped in file order. Startup fails when no loadable entry remains.

The launch options interact with the saved rotation as follows:

{| class="wikitable"
! Launch input !! Startup result !! Next rotation result
|-
| No map or mode || First loadable entry || Following entry
|-
| <code>--mode <mode></code> only || First loadable entry with that mode; startup fails if none exists || Following entry
|-
| <code>--map <map></code> || Requested registered map, even when it is outside the rotation || First entry when the active map/mode pair is outside the rotation
|-
| <code>--map <map> --mode <mode></code> || Requested pair || Following entry when that exact pair exists; otherwise the first entry
|}

Use authenticated console or RCON for an immediate manual change:

<syntaxhighlight lang="text">
changelevel <map-id> [mode-id]
</syntaxhighlight>

Omitting the mode uses the map default, then <code>sandbox</code>. The saved rotation remains unchanged.

== Install Workshop add-ons ==

<code>config/server-addons.json</code> controls Workshop acquisition. Store every Steam published-file or collection ID as a JSON string so the 64-bit value cannot lose precision.

{| class="wikitable"
! Field !! Use it when
|-
| <code>items</code> || Steam should download a direct Map or Content item for the server.
|-
| <code>collections</code> || Steam should expand a collection and install its child items.
|-
| <code>manualItems</code> || A complete Release package is already installed below <code><data-root>/addons</code> and must be bound to its client-visible Workshop item.
|}

A combined configuration looks like this:

<syntaxhighlight lang="json">
{
"schemaVersion": 1,
"workshop": {
"depotId": "",
"items": [
"1234567890"
],
"manualItems": [
{
"publishedFileId": "2345678901",
"addonId": "community_castle"
}
],
"collections": [
"3456789012"
]
}
}
</syntaxhighlight>

Leave <code>depotId</code> empty unless Vellocet support directs you to change it. Grimwar supplies the dedicated-server depot.

=== Steam-managed items and collections ===

<code>items</code> contains direct Workshop published-file IDs. The server downloads and updates them through Steam under <code><data-root>/cache/steam-workshop-server</code>.

<code>collections</code> contains Workshop collection IDs. The server resolves the collection and installs its children. A joining client acquires only the package for the active map and any session-wide requirements, not the full server collection.

For container deployments, <code>--workshop-items</code> or <code>GRIMWAR_WORKSHOP_ITEMS</code> adds direct item IDs to the file configuration:

<syntaxhighlight lang="text">
GrimwarServer --workshop-items=1234567890,2345678901
GRIMWAR_WORKSHOP_ITEMS=1234567890,2345678901
</syntaxhighlight>

Comma, semicolon, and whitespace separators are accepted. Collections remain in <code>server-addons.json</code>. <code>--workshop-depot-id</code> and <code>GRIMWAR_WORKSHOP_DEPOT_ID</code> are advanced depot overrides, not normal setup values.

=== Manually staged Workshop package ===

<code>manualItems</code> binds a local server package to a Workshop item that clients can download. Use it for a mixed package that contains a map or reusable audio plus a VMod, or when the operator manages server files outside Steam.

# Build or obtain the complete, unmodified Release package.
# Put the directory below <code><data-root>/addons</code>. The package root itself must contain <code>addon.json</code>.
# Read the package <code>id</code> and <code>buildId</code> from <code>addon.json</code>.
# Add its Workshop published-file ID and manifest add-on ID to <code>manualItems</code>.
# Remove the same published-file ID from <code>items</code>.
# Restart the server and inspect <code>[ServerWorkshop]</code> logs.

Example layout:

<syntaxhighlight lang="text">
/srv/grimwar/community-1/
addons/
community_castle/
addon.json
mod.json
CommunityCastle.csx
maps/
config/
server-addons.json
</syntaxhighlight>

The local server package and client-visible Workshop package must have the same add-on ID and build ID. Map and VMod uploads include declared server source; map-bound snapshots remain inside the compiled scene. Clients do not execute it. Replace the staged server package every time the Workshop item is rebuilt.

One published-file ID may appear in <code>items</code> or <code>manualItems</code>, never both. Duplicate published-file IDs or add-on IDs in <code>manualItems</code> make the configuration invalid.

Clients do not download files from <code><data-root>/addons</code>. They receive the sanitized Map or Content item from Steam and verify its published-file ID, add-on ID, and exact build ID. The current Workshop visibility must allow those clients to access it.

When every configured identity uses <code>manualItems</code>, the server does not request a Workshop download. A collection still requires Steam so the server can query its children.

See [[Grimwar/Steam Workshop addons#How Grimwar identifies maps and content|How Grimwar identifies maps and content]] for the manifest fields that distinguish a map from reusable content. Put every installed map ID used by the server in a whitelist rotation. Blacklist rotation considers installed maps automatically.

== Install VMods ==

# Run <code>vmod_runtime_paths</code> and use the printed add-on directory.
# Copy the complete VMod add-on folder below <code><data-root>/addons</code>.
# Restart, or run <code>vmod_runtime_reload</code> while no scripted mode is active.
# Confirm the package with <code>vmod_runtime_list</code>.

VMod-only packages are server-only and are installed manually. A mixed package can publish its map or audio to Workshop, but the server still needs the complete package. Admin users, groups, and external capability grants live below <code><data-root>/config/mods</code>. See [[Grimwar/VMod|VMod scripting and administration]].

== Startup and diagnostics ==

Before opening the server publicly:

# Run preflight with the production data directory.
# Start the server and confirm it reaches its ready/listening state.
# Run <code>status -v</code> and verify the <code>community</code> role, <code>steam-relay</code> transport, build, protocol, map, mode, ruleset, data path, and player limit.
# Run <code>cfg_paths</code> and confirm the data, config, secret, and add-on roots.
# Confirm each Workshop or manual item loaded and every rotation map registered.
# Join with a separate Steam account and test authentication, required-content delivery, round transition, and map change.
# Test RCON from an allowed administrator address.

Useful log prefixes are:

{| class="wikitable"
! Prefix !! Check
|-
| <code>[ServerWorkshop]</code> || Server configuration, manual bindings, collection expansion, downloads, validation, and activation.
|-
| <code>[AddonCatalog]</code> / <code>[AddonLoader]</code> || Package selection, validation, dependencies, and runtime loading.
|-
| <code>[ServerRotation]</code> || Unknown entries, selected map/mode pairs, and next-map resolution.
|-
| <code>[WorkshopDL]</code> || Exact client/server published-file, add-on, and build matching.
|-
| <code>[SteamWorkshop]</code> || Steam installation and update state.
|-
| <code>[ContentDL]</code> || Content provider selection and completion.
|-
| <code>[Net]</code> || Pre-login requirements; set <code>net_log 2</code> for per-add-on identities.
|}

Do not add a public gameplay mapping when preflight or Steam startup fails. Fix the reported Steam login, credential, port conflict, package, or network error first.

Back up the data directory before game or add-on updates. It contains operator configuration, VMod state, source selections, bans, and other mutable server data. The game installation is not a substitute for that backup.

[[Category:Grimwar]] [[Category:Dedicated servers]]

Grimwar/Dedicated servers - Revision history

DocumentationBot: Version 1