Skip to content

Whitelist

JonathanLA edited this page Nov 11, 2026 · 1 revision

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.

Modes

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.

Switching an existing server to enforce

  1. Set whitelistMode: notify for a few days, or go straight to step 2.
  2. Run sg whitelist import (or press Add them all on the watch page's Access tab). It adds everyone in registrations.yaml, i.e. every player who has joined the server before.
  3. 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.

Approving

  • 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.

What the refused player sees

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.

Commands

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.

Settings

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.

The file

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: true

Only 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.

Clone this wiki locally