ReferenceConfiguration

allowlist.json

Allowed players when allow-list is enabled.

Players permitted to join when allow-list=true is set in server.properties. BDS rejects connections from anyone not on this list.

Use the allowlist add <gamertag> server command instead of editing by hand when possible - it resolves XUIDs for you and reloads the file in place. Gamertags containing spaces must be quoted: allowlist add "Example Name".

Sample

[
  {
    "ignoresPlayerLimit": false,
    "name": "PlayerName"
  },
  {
    "ignoresPlayerLimit": true,
    "name": "AnotherPlayer",
    "xuid": "2533274912345678"
  }
]

Fields

FieldTypeRequiredDescription
namestringYesXbox Live gamertag. Case-insensitive.
xuidstringNoXbox user ID. Recommended - prevents impersonation if a gamertag is renamed. Auto-populated when the matching player first connects, or when added via allowlist add.
ignoresPlayerLimitboolNo (default false)If true, this player can join even when max-players is reached. BDS still enforces a soft cap of max-players + 1 (or 30, whichever is higher) on total connections.

Server commands

CommandDescription
allowlist on / offEnable or disable allowlist enforcement at runtime. Does not modify allow-list in server.properties.
allowlist add <gamertag>Add a player. Resolves XUID on first connect.
allowlist remove <gamertag>Remove a player.
allowlist listList current entries.
allowlist reloadReload after a manual edit.

Migrating from whitelist.json

allowlist.json was previously named whitelist.json. For backward compatibility, if a whitelist.json is present BDS uses it instead of allowlist.json. To migrate:

  1. Delete the auto-generated allowlist.json.
  2. Rename whitelist.json to allowlist.json.
  3. Restart the server.

config/commands.json

Re-level or hide individual commands without a plugin.

banned-ips.json

IP addresses banned from the server.

On this page

SampleFieldsServer commandsMigrating from whitelist.json