Repository navigation
Whitelist
New in 2.4.0. Let in only the players you approve. Anyone else who tries to join becomes a join request on the Watch Page and in the admin Discord channel; one click on Approve lets them in from their next login.
Set whitelistMode in conf/settings.yaml (or on the watch page: Config → Settings → Access). It hot-reloads.
| Mode | Who gets in | Join requests |
|---|---|---|
off (default)
|
Everyone. | None. |
notify |
Everyone. | Players who are not on the whitelist are listed, so you can build the list before closing the door. |
enforce |
Whitelisted players, owners and moderators. Everyone else is turned away at the handshake, before they spawn. | Every turned-away player. |
Owners and moderators always get in and don't need an entry. Players already online when you switch to enforce are left alone; the check happens at login. Banned players are refused by the ban layer before the whitelist is asked, so they never show up as requests.
- Set
whitelistMode: notifyfor a few days, or go straight to step 2. - Run
sg whitelist import(or press Add them all on the watch page's Access tab). It adds everyone inregistrations.yaml, i.e. every player who has joined the server before. - Set
whitelistMode: enforce.
From then on, a new player who tries to join is turned away with whitelistMessage on their screen, and you get a join request.
- Watch page: the Join requests panel (Live tab) or the Access tab → Approve. The page also shows a pop-up, the count in the browser tab title, and can play a sound (🔕 / 🔔 in the header).
-
In game:
sg whitelist add <steamid>, or the character name from the request:sg whitelist add Ragnar. - Discord: the admin-channel post contains the exact command.
The player's next login gets in; they don't have to do anything else. Dismiss (sg whitelist deny <steamid>) just clears the request. To keep someone out for good, ban them.
With ServerGuard 2.4.0 or later on their game, the connection-failed screen shows whitelistMessage (default: "This server is whitelist-only. Your request has been sent to the staff - try again once you've been approved."). Valheim itself has only one refusal message, so a player without ServerGuard sees "You are banned". They are not banned.
The same change applies to bans: a banned player now sees banLayerKickMessage, the reason and the end date.
| Command | What it does |
|---|---|
sg whitelist |
Mode, how many are listed, how many requests wait, and how many past players are not listed. |
sg whitelist add <steamid|name> [note] |
Let a player in (approves their request). A name is looked up in the join requests, then in registrations. |
sg whitelist remove <steamid|name> |
Take a player off the list. |
sg whitelist list [filter] |
The list (first 50). |
sg whitelist requests |
The waiting join requests. |
sg whitelist deny <steamid|name|all> |
Dismiss request(s). |
sg whitelist import |
Add everyone who has played here before. |
sg test join <steamid> [character] |
Run the check as if that player tried to join, without a connection. Records a join request like a real attempt, so you can try the watch-page notification alone. |
Every change is posted to the admin channel under the name of whoever made it.
| Setting | Default | |
|---|---|---|
whitelistMode |
off |
off, notify or enforce. |
whitelistMessage |
(see above) | Shown to a turned-away player. |
whitelistNotifyDiscord |
true |
Post each new join request to the admin channel. A player who keeps retrying is posted at most every 30 minutes; every attempt still shows on the watch page. |
conf/whitelist.yaml, hot-reloaded:
players:
- id: "76561198000000000"
name: "Ragnar"
added: "2026-11-09T10:00:00.0000000Z"
addedBy: "76561198000000001"
note: "Discord: ragnar"
requests:
- id: "76561198000000002"
name: "Floki"
first: "2026-11-09T11:00:00Z"
last: "2026-11-09T11:05:00Z"
attempts: 2
refused: trueOnly id matters under players; the rest is for you. requests is managed by ServerGuard (at most 200 are kept). If the file can't be read, ServerGuard keeps using the last list it read, doesn't write the file until it is fixed, and says so in the log and the admin channel.
The whitelist is keyed by SteamID. In enforce mode a connection without a SteamID (crossplay) is refused.