Repository navigation
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.
| 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. |
| 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. |
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: falseA 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.
| 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.
| 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.
| 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.
| 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. |
| 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
- SledgeCheatVanilla 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: falseHot-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.
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: falseEnforcement 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 tofalse/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).
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.
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.
| 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.
| 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.
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.
| 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. |
| 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. |
| 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 / 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.
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.
| 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. |