Skip to content

Configuration

JonathanLA edited this page Nov 11, 2026 · 1 revision

Configuration

All knobs live in BepInEx/config/ServerGuard/conf/settings.yaml on the dedicated server. Changes are hot-reloaded — save the file and they take effect within ~1 second. No restart needed.

Core enforcement

Setting Default What it does
enforce true Master kill-switch. When false, ServerGuard logs and posts events but doesn't actually kick anyone. Useful for break-in periods.
violationThreshold 3 Strikes before auto-ban (per-rule). Only rules with countAsViolation: true accumulate.
kickMessage "You cannot join..." Shown to kicked players. Append to it if you want to point users at a Discord.
banReason "Auto-banned..." Logged when a player crosses the threshold.
characterLimit 1 Distinct character names a single SteamID may register on this server.

Mod attestation

Setting Default What it does
requireCompanion true Peers without the companion plugin are kicked. Keep ON.
companionTimeoutSeconds 10 How long to wait for the companion's reply before declaring "no companion".
requireHmac true The companion's reply must carry a valid HMAC signature. Keep ON.
sharedSecret random The password the companion uses to sign its manifest. Auto-generated on first boot. Every client needs this value in their client.yaml.
allowUnlisted false When true, mods not in allowed_mods.yaml are tolerated. Default keeps the allowlist strict.
maxClockSkewSeconds 120 Rejects manifests timestamped more than this far off from server time.
logPeerManifest false Verbose: log every connecting peer's full manifest. Useful for harvesting GUIDs during initial setup.

Per-rule violation accounting

countAsViolation:
  CompanionMissing: false
  HmacInvalid: false
  ChallengeMismatch: false
  RequiredModMissing: false
  DisallowedMod: false
  BannedMod: false
  HashMismatch: false
  CharacterNameLimitExceeded: true
  DevcommandAttempt: true
  SpeedHack: true
  IllegalItem: false
  StackOverflow: false
  AnimationCancel: false
  SkillOverflow: false

A rule with true increments the player's strike count when triggered. Repeat strikes lead to auto-ban (per violationThreshold). A rule with false still fires the event (logged + posted) but doesn't add a strike.

Why connection-attestation rules default to false: connection failures already kick the player at the door. Counting them as strikes would double-punish.

Why in-game rules default to true: if a player repeatedly tries cheats or shows speed-hacking, you want escalation.

A missing rule defaults to false — every new rule is opt-in. Add the line explicitly if you want it to count.

Discord

Setting Default What it does
discordWebhookUrl "" Public channel. Player-facing events (joined, left, kicked, died). Safe to share with the whole community.
discordWebhookUrlAdmin "" Admin channel. Moderation events (violations, config reloads, command audit, daily summary).
discordPublicStaffLogins false (2.5) If true, owners' and moderators' joins and leaves are also posted to the public channel.
discordVerboseMirror false If true, also forwards every ServerGuard log line to the admin channel. Noisy — debug use only.
dailySummaryEnabled true Posts a one-paragraph daily digest.
dailySummaryHourUtc 0 UTC hour the digest fires.
dailySummaryChannel "admin" public, admin, or both.

Admin lifecycle events (joined, left, died) are hidden from the public channel and routed to the admin channel automatically. Players don't see admins coming and going. To announce staff joins and leaves publicly, set discordPublicStaffLogins: true (deaths and kicks stay hidden).

See Discord Integration for details.

Anti-cheat features

Setting Default What it does
enableDevcommandGate true Companion blocks console cheats; server logs the attempts.
enableSpeedCheck true Server polls each peer's position and flags impossibly fast movement.
speedCheckMaxMetersPerSecond 70.0 Threshold. Vanilla sprint ~5, longship ~9; the default only catches teleport-style movement — lower it for a vanilla-ish server.
speedCheckSampleSeconds 1.0 Poll interval.
speedCheckConsecutiveStrikes 3 Over-threshold samples in a row needed to flag.
speedCheckTeleportToleranceMeters 60.0 Single big jumps (portal travel) reset the strike counter instead of incrementing.
enableInventoryCheck true Server-side check that items added to any inventory are known + within stack limits.
inventoryCheckLogOnly true Log violations without blocking the add. Flip to false to actively reject.
inventoryCheckStackTolerance 1.0 Multiplier on each item's m_maxStackSize. Raise for modpacks that bump stacks.
enableAnimationCancelGate true Companion blocks the emote-based attack-cancel exploit. Sheathing is excluded — it's ordinary play.
enableSkillCap true Companion reports skill levels; server flags any above the cap.
skillCapMaxLevel 100.0 Vanilla cap. Raise for modded skill systems.
skillCapTolerance 5.0 Added to max — absorbs float-rounding overshoot.

See Anti-Cheat Features for how each one works.

Forensic logs

Setting Default What it does
enableDeathLog true Public-channel death messages (cause + location + killer).
enableBuildLog true Daily CSV at BepInEx/config/ServerGuard/build_log/YYYY-MM-DD.csv.
buildLogRetentionDays 30 Older CSVs are auto-pruned.

See Forensic Logs.

Optional features

Setting Default What it does
enableSelfTest true Runs a suite of smoke tests at boot. Posts to admin Discord on failure.
selfTestPostOnPass false Also post a green-check confirmation when all tests pass.
enablePingLog false Tracks each peer's RTT. Posts first ping + session avg to admin channel. Useful for spotting VPN / proxy users.
pingLogSampleSeconds 5 Sample interval.
enableMetrics true Internal counters at BepInEx/config/ServerGuard/metrics.yaml.

Cheat item removal

Setting Default What it does
enableCheatItemRemoval true On login, the companion removes the listed items from any non-admin player's inventory (after they spawn).
cheatItems [SwordCheat, SledgeCheat] Prefab names to remove. Add more entries to strip other items. Admins are always exempt.
enableCheatItemRemoval: true
cheatItems:
  - SwordCheat
  - SledgeCheat

Arrival shout

Vanilla makes every player shout the localised "I have arrived!" line the first time they spawn into a session. If your server already posts a login notification, that shout is just noise.

Setting Default What it does
enableArrivalShout true false = the companion swallows the automatic first-spawn shout. Players can still shout manually.
enableArrivalShout: false

Hot-reloads to everyone already online — the server re-pushes the setting on save, so nobody has to reconnect.

Requires the companion plugin, since the shout originates on the client. A vanilla client (one allowed in via requireCompanion: false) will still shout.

Forced map positions

By default Valheim lets each player decide whether their position is shared on the map — the public position toggle on the minimap, which starts off. Turn this on and the server overrides that choice, so every player is permanently visible on everyone else's map.

Setting Default What it does
enableForceMapPositions false Forces every peer's public-position flag on. Off = vanilla behaviour (each player chooses).
forceMapPositionsExemptAdmins false If true, moderators keep their own toggle and can stay hidden. Owners are always exempt.
enableForceMapPositions: true
forceMapPositionsExemptAdmins: false

Enforcement is server-side: clients push their position and public/private flag to the server roughly every 2 seconds, and the server rewrites the flag on arrival before broadcasting the player list. A player who flips the toggle off — or a modified client that lies about it — is corrected on the next sync, so there is no way to opt out from the client.

Both settings hot-reload. After saving settings.yaml, the change takes effect within ~2 seconds; no restart is needed. Turning it back off also self-heals within one sync, restoring each player's own choice.

Before 1.7.0 these two keys were missing from the generated settings.yaml — the file was written by a serializer that omits anything still at its default, so every option defaulting to false/0/empty was invisible. Fixed in 1.7.0: fresh installs list every option, and existing servers get the missing ones appended on next boot with their current values (your edits and comments are left alone).

Ban layer

An independent SteamID denylist checked inside the connection handshake, so a banned player is refused before they can spawn — unlike Valheim's own ban list, which is only swept every 5 seconds.

Setting Default What it does
enableBanLayer true Master switch.
banLayerKickMessage "You are banned from this server." Shown to a refused player, followed by the ban reason.
banLayerMirrorToVanilla true Also write bans into Valheim's banlist.txt.

The list lives in conf/bans.yaml and hot-reloads. Manage it with sg ban, sg unban and sg bans. Full detail: Bans and Console Guard.

Console guard

Controls what players can run in the F5 console, and what happens to their key binds.

Setting Default What it does
consoleGuardMode restricted open / restricted / whitelist / disabled.
consoleGuardExemptModerators true Moderators keep full console access. Owners always do.
consoleGuardBindPolicy purge allow / block / purge / wipe. Key binds can run commands without the console being open.
consoleBlockedCommands [] Extra command names to block.
consoleAllowedCommands [] The permitted set when consoleGuardMode: whitelist.
consoleGuardReportAttempts true Log/post/count blocked attempts.

Enforced on the client side of ServerGuard (every player runs it). Full detail and the per-command reasoning: Bans and Console Guard.

Staff dev commands (2.0)

Setting Default What it does
enableOwnerDevcommands true Owners can use every dev command on this server and count as vanilla admins.
enableModeratorDevcommands true Moderators can use the commands in moderatorDevcommands.
moderatorDevcommands goto pos removedrops stopevent find The moderator list. devcommands is always allowed. fly, debugmode, spawn, itemset, nocost, noplacementcost and location are refused for moderators even if listed.

Players get nothing from these — the console guard applies to them as before. Full explanation on Privilege Tiers.

Cheat taint detection (2.0)

Setting Default What it does
enableCheatTaintDetection true Report items and builds the game itself marked as cheat-made.
cheatTaintPolicy log log posts to the admin channel; strip also removes the items from the player; violation also records a CheatedItem strike.
cheatTaintBypassPolicy log What to do with a character carrying the bypasscheatchecks key (set by yesiuseddevcommandsbutiwantmyachievementsanyway) — the game then marks nothing that character does, so cheat-taint detection cannot see it. log posts to the admin channel once per session; kick also disconnects the player. The key lives in the character file, so they are refused until they use a character without it. No strike.
cheatTaintExemptModerators false Moderators are reported too unless this is on. Owners are always exempt.
cheatTaintFlagUsedCheats true Also report (once per session) characters carrying the game's permanent "used dev commands" mark.
cheatTaintIgnoredItems [] Prefab names to ignore. Valheim auto-flags any item over 10000 total damage — list modded weapons here.
cheatTaintNoticeTitle empty Title of the popup players get on their first login after launching the game. Empty = the built-in title. Up to 120 characters.
cheatTaintNoticeText empty Body of that popup. Empty = the built-in text. Up to 2000 characters, but keep it about as long as the built-in text (roughly 600) so it fits the popup. {consequence} becomes the built-in sentence for your current cheatTaintPolicy. See the example below.
enableDebugFlyCheck true Flag players whose character reports debug fly (rule DebugFly, server-side).

Example notice wording in settings.yaml:

cheatTaintNoticeTitle: Fair play on this server
cheatTaintNoticeText: |
  We keep this server cheat-free. Valheim marks anything made with cheat commands, and we can see those marks.

  {consequence}

  Questions? Ask a moderator on our Discord.

Changes hot-reload, but a player who has already seen the popup since launching the game won't see it again until they restart the game.

The three rules (CheatedItem, CheatedBuild, DebugFly) default to informational in countAsViolation. Details on Anti-Cheat Features.

Personal progression (2.1)

Boss kills, Hildir's quests and the troll/surtling/bat raid unlocks are recorded per character instead of per world, and each player's game only sees their own. On by default.

Setting Default
enablePersonalProgression true Master switch. false = shared vanilla progress, immediately.
progressionKeys defeated_*, killedtroll, killed_surtling, killedbat, hildir* Which world keys count as progress.
progressionCreditRadius 50 A boss is credited to players within this many metres...
progressionRequireDamage true ...who also damaged it.
progressionSeedFromCharacters true Existing characters keep the kills their character file records (once).
progressionForcePlayerRaids true Keep the Player based raids world modifier on.
enablePersonalTemple true Start-temple altars per character.
personalAltarsRequireKill true Trophies only take hold for players who defeated that boss.
progressionDiscordPosts true Public first-kill posts and admin credit posts.

Full explanation: Personal Progression.

Inventory seal (2.2)

Setting Default What it does
enableInventorySeal true Sealed accounts lose, on every join, the items their character did not carry on this server before. Nobody is sealed unless you run sg seal add or a mod (Blót) seals them. false = keep the seals but stop enforcing them.

Watch page (2.3)

Setting Default What it does
enableWatchPage false Serve the staff watch page. See Watch Page.
watchPagePort 0 The extra TCP port your host gives you (DatHost: custom1). 0 = not set.
watchPageBindAddress 0.0.0.0 Network address to listen on.
watchPagePublicUrl empty The address staff open, e.g. http://myhost.example:20871/. Only used in messages.
watchPageAllowedIps [] Optional IP allowlist. Empty = any address with a valid key.
watchPageActions true false = watch only, no kick / ban / seal / whitelist buttons.
watchPageConfigEditor true (2.4) Owners can edit settings, allowed mods and moderators on the page (checked, comments kept, old file saved as .bak). false = the page never writes them.

Whitelist (2.4)

Setting Default What it does
whitelistMode off off = anyone joins. notify = anyone joins, unlisted players become join requests. enforce = only players in conf/whitelist.yaml (and staff) get in; the rest are turned away and become join requests. See Whitelist.
whitelistMessage This server is whitelist-only. … Shown to a turned-away player (needs ServerGuard 2.4.0 on their game).
whitelistNotifyDiscord true Post each new join request to the admin channel.

Raid alerts

Raid / random-event start, pause, resume, and end are posted to the public Discord channel automatically (no setting to enable — it follows discordWebhookUrl). Events are named with their in-game title (e.g. "The Horde Is Attacking") rather than the internal code name.

Quick Login panel (client-side)

The title-screen one-click login panel is configured on each client in client.yaml, not in the server's settings.yaml. See Quick Login Panel.

Files written by the plugin

Path Purpose
conf/settings.yaml This file.
conf/owners.yaml Owner SteamIDs — exempt from every rule. See Privilege Tiers.
conf/moderators.yaml Moderator (staff) SteamIDs. Renamed from admins.yaml in 1.7.0, migrated automatically.
conf/bans.yaml ServerGuard ban list. See Bans and Console Guard.
conf/allowed_mods.yaml Mod allowlist.
modset_fingerprint.txt Current modset hash (publish this to your community).
registrations.yaml SteamID → character names mapping. Hot-reloaded; or use sg unregister.
violations.yaml Current per-player violation strikes. Hot-reloaded; or use sg pardon.
conf/watch_keys.yaml Watch-page access keys (hashes only). Hot-reloaded; or use sg watch key / revoke.
conf/whitelist.yaml Whitelisted players and waiting join requests (2.4). Hot-reloaded; or use sg whitelist / the watch page. See Whitelist.
conf/*.yaml.bak The previous version of a file saved from the watch page's config editor.
conf/progress.yaml Personal progression ledger, one entry per character, bound to the world. Hot-reloaded; or use sg progress.
metrics.yaml Aggregate counters.
build_log/YYYY-MM-DD.csv Daily build/destroy events.

Clone this wiki locally