How to use the dedicated server
Recommended Hardware
We recommend running the Bedrock Minecraft Server on 64-bit Intel or AMD processor machines with at least 2 cores and 1 Gb
RAM.
Platforms
Linux
The Linux version of the Bedrock Server requires Ubuntu 18 or later. Other distributions are not supported. Unzip the container file
into an empty folder. Start the server with the following command:
LD_LIBRARY_PATH=. ./bedrock_server
Windows
The Windows version of the Bedrock Server requires either:
Windows 10 version 1703 or later
Windows Server 2016 or later
Unzip the container file into an empty folder. Start the server by executing the bedrock_server.exe file.
On some systems, when you wish to connect to the server using a client running on the same machine as the server is running on,
you will need to exempt the Minecraft client from UWP loopback restrictions:
CheckNetIsolation.exe LoopbackExempt -a -p=S-1-15-2-1958404141-86561845-1752920682-3514627264-368642714-
62675701-733520436
.
Configuration
The server will try to read a file named server.properties . Some of these options are only read when a new world is created, while
some others are read every startup. The file should contain a list with keys and values separated with an equal sign, one per line.
The following options are available. If a value as a number in parenthesis, that number can be used instead of the text value.
Default When is it
Option name Possible values Notes
value used
Any string (no semicolon Dedicated This is the server name shown in the in-game server
server-name Always
allowed) Server list.
Always or only
gamemode survival, creative, adventure survival
for new players
force-gamemode=false(or force-gamemode is not
defined in the server.properties file) prevents the
server from sending to the client gamemode values
other than the gamemode value saved by the server
during world creation even if those values are set in
force-
true, false false Always server.properties file after world creation.
gamemode
force-gamemode=true forces the server to send to
the client gamemode values other than the
gamemode value saved by the server during world
creation if those values are set in server.properties
file after world creation.
difficulty peaceful, easy, normal, hard easy Always
allow-cheats true, false false Always If true then cheats like commands can be used.
The maximum numbers of players that should be
max-players Any integer 10 Always able to play on the server. Higher values have
performance impact.
Default When is it
Option name Possible values Notes
value used
Integer between 1024 and Values below 1024 may be used, but are generally
server-port 19132 Always
65535 reserved for well known applications
Integer between 1024 and Values below 1024 may be used, but are generally
server-portv6 19133 Always
65535 reserved for well known applications
Listen and respond to clients that are looking for
servers on the LAN. This will cause the server to
bind to the default ports (19132, 19133) even when
enable-lan-
true, false true Always 'server-port' and 'server-portv6' have non-default
visibility
values. Consider turning this off if LAN discovery is
not desirable, or when running multiple servers on
the same host may lead to port conflicts.
Bedrock The name of level to be used/generated. Each level
level-name Any string Always
level has its own folder in /worlds .
The seed to be used for randomizing the world. If left
level-seed Any string World creation
empty a seed will be chosen at random.
If true, all connected players must be authenticated
with Xbox Live. Clients connecting to remote (non-
LAN) servers will always require Xbox Live
online-mode true, false true Always
authentication regardless of this setting. If the server
accepts connections from the Internet, then it is
highly recommended to enable online-mode.
If true then all connected players must be listed in
allow-list true, false false Always the separate allowlist.json file. See the Allowlist
section.
The maximum allowed view distance. Higher values
view-distance Any integer greater than 5 32 Always
have performance impact.
After a player has idled for this many minutes they
player-idle- Any positive integer,
30 Always will be kicked. If set to 0 then players can idle
timeout including 0
indefinitely.
Maximum number of threads the server will try to
max-threads Any integer 8 Always use. If set to 0 or removed then it will use as many
as possible.
The world will be ticked this many chunks away from
An integer in the range [4,
tick-distance 4 Always any player. Higher values have performance
12]
impact.
default-player- Which permission level new players will have when
visitor, member, operator member Always
permission-level they join for the first time.
texturepack- If the world uses any specific texture packs then this
true, false false Always
required setting will force the client to use it.
content-log-file-
true, false false Always Enables logging content errors to a file.
enabled
Determines the smallest size of raw network payload
compression- An integer in the range [0-
1 Always to compress. Can be used to experiment with CPU-
threshold 65535]
bandwidth tradeoffs.
compression- Determines the compression algorithm to use for
zlib, snappy zlib Always
algorithm networking.
server- client-auth, server- Always Changes the server authority on movement:
authoritative- server-auth, auth "client-auth": Server has no authority and accepts
movement server-auth-with-rewind all positions from the client.
"server-auth": Server takes user input and
simulates the Player movement but accepts the
Client version if there is disagreement.
"server-auth-with-rewind": The server will replay
local user input and will push it to the Client so it can
correct the position if it does not match. The clients
will rewind time back to the correction time, apply the
correction, then replay all the player's inputs since
Default When is it
Option name Possible values Notes
value used
then. This results in smoother and more frequent
corrections.
Only used with "server-auth-with-rewind". This is the
tolerance of discrepancies between the Client and
player-position- With "server- Server Player position. This helps in problematic
acceptance- Any positive float 0.5 auth-with- scenarios. The higher the number, the more tolerant
threshold rewind" the server will be before asking for a correction.
Passed value of 1.0, the chance of missing cheating
increases.
The amount that the direction the player is attacking
player- can differ from the direction the player is looking as
movement- Any positive float in the cos(x) where x is the angle between the two vectors.
0.85 Always
action-direction- range of [-1.00, 1.00] A value of 1 means the two vectors must be parallel,
threshold 0 means anything in front of the player, and -1
means any vector.
If true, the server will compute block mining
operations in sync with the client so it can verify that
server-
Not when the client should be able to break blocks when it
authoritative- true, false false
client-auth thinks it can. This setting cannot be combined with
block-breaking
client authoritative movement and will be disabled if
that setting is enabled.
server-
When server-
authoritative-
authoritative- This increase the range of block breaking. This is
block-breaking- Any float above 1.0 1.5
block-breaking squared and multiplied with the default range.
pick-range-
is true
scalar
This represents the level of restriction applied to the
chat for each player that joins the server. "None" is
the default and represents regular free chat.
"Dropped" means the chat messages are dropped
chat-restriction None, Dropped, Disabled None Always and never sent to any client. Players receive a
message to let them know the feature is disabled.
"Disabled" means that unless the player is an
operator, the chat UI does not even appear. No
information is displayed to the player.
If true, the server will inform clients that they should
disable-player-
true, false false Always ignore other players when interacting with the world.
interaction
This is not server authoritative.
client-side-
If true, the server will inform clients that they have
chunk-
true, false true Always the ability to generate visual level chunks outside of
generation-
player interaction distances.
enabled
If true, the server will send hashed block network
block-network- ID's instead of id's that start from 0 and go up. These
true, false true Always
ids-are-hashes id's are stable and won't change regardless of other
block changes.
Internal Use
disable-persona true, false false
Only
If true, disable players customized skins that were
disable-custom- customized outside of the Minecraft store assets or
true, false false Always
skins in game assets. This is used to disable possibly
offensive custom skins players make.
If "Disabled" the server will dynamically calculate
how much of the player's view it will generate,
assigning the rest to the client to build. Otherwise
server-build-
Disabled, 0.0-1.0 Disabled Always from the overridden ratio tell the server how much of
radius-ratio
the player's view to generate, disregarding client
hardware capability. Only valid if client-side-
chunk-generation-enabled is enabled.
Folders
When unpacking you will see a few folders and the binary executable. When starting the server for the first time a bunch of new
(empty) folders will be created. The folders you should care about are the following:
Folder name Purpose
behavior_packs This is where new behavior packs can be installed. At the moment there's no way of activating them in a level.
resource_packs This is where new resource packs can be installed. At the moment there's no way of activating them in a level.
This folder will be created at startup if it doesn't already exist. Every world created will have a folder named
worlds
according to their level-name inside the server.properties file.
Allowlist
If the allow-list property is enabled in server.properties then the server will only allow selected users to connect. To allow a user to
connect you need to know their Xbox Live Gamertag. The easiest way to add a user to the allowlist is to use the command allowlist
add <Gamertag> (eg: allowlist add ExampleName ). Note: If there is a white-space in the Gamertag you need to enclose it with double
quotes: allowlist add "Example Name"
If you later want to remove someone from the list you can use the command allowlist remove <Gamertag> .
The allowlist will be saved in a file called allowlist.json . If you want to automate the process of adding or removing players from it
you can do so. After you've modified the file you need to run the command allowlist reload to make sure that the server knows about
your new change.
NOTE: This file was previously named whitelist.json . For backwards compatability, if a whitelist.json file is also present, it will be
used instead of allowlist.json . To migrate, delete the default allowlist.json file, rename whitelist.json to allowlist.json , then
restart the server.
The file contains a JSON array with objects that contains the following key/values.
Key Type Value
name String The gamertag of the user.
Optional. The XUID of the user. If it's not set then it will be populated when someone with a matching
xuid String
name connects.
True if this user should not count towards the maximum player limit. Currently there's another soft limit
ignoresPlayerLimit Boolean of 30 (or 1 higher than the specified number of max players) connected players, even if players use
this option. The intention for this is to have some players be able to join even if the server is full.
Example allowlist.json file:
[
{
"ignoresPlayerLimit": false,
"name": "MyPlayer"
},
{
"ignoresPlayerLimit": false,
"name": "AnotherPlayer",
"xuid": "274817248"
}
]
Permissions
You can adjust player specific permissions by assigning them roles in the permissions.json that is placed in the same directory as the
server executable. The file contains a simple JSON object with XUIDs and permissions. Valid permissions are: operator , member ,
visitor . Every player that connects with these accounts will be treated according to the set premission. If you change this file while
the server is running, then run the command permission reload to make sure that the server knows about your new change. You
could also list the current permissions with permission list . Note that online-mode needs to be enabled for this feature to work since
xuid requires online verification of the user account. If a new player that is not in this list connects, the default-player-permission-
level option will apply.
Example permissions.json file:
[
{
"permission": "operator",
"xuid": "451298348"
},
{
"permission": "member",
"xuid": "52819329"
},
{
"permission": "visitor",
"xuid": "234114123"
}
]
Crash reporting
If the server crashes it will automatically send us various information that helps us solve it for the future.
Commands
You can issue commands to the server by typing in the console. The following commands are available. < > means a parameter is
required, [ ] means it's optional and | denotes different allowed values. Strings can be enclosed in double quotes, ", if they contain
spaces.
Command syntax Description
kick <player name
Immediately kicks a player. The reason will be shown on the kicked players screen.
or xuid> <reason>
stop Shuts down the server gracefully.
save <hold |
Used to make atomic backups while the server is running. See the backup section for more information.
resume | query>
on and off turns the allowlist on and off. Note that this does not change the value in the server.properties
file!
allowlist <on | off | list prints the current allowlist used by the server
list | reload>
reload makes the server reload the allowlist from the file.
See the allowlist section for more information.
Adds or removes a player from the allowlist file. The name parameter should be the Xbox Gamertag of the
player you want to add or remove. You don't need to specify a XUID here, it will be resolved the first time the
allowlist <add |
player connects.
remove> <name>
See the Allowlist section for more information.
list prints the current used operator list.
permission <list |
reload makes the server reload the operator list from the ops file.
reload>
See the Permissions section for more information.
Promote a player to operator . This will also persist in permissions.json if the player is authenticated to XBL. If
permissions.json is missing it will be created. If the player is not connected to XBL, the player is promoted for
op <player>
the current server session and it will not be persisted on disk. Defualt server permission level will be assigned
to the player after a server restart.
Demote a player to member . This will also persist in permissions.json if the player is authenticated to XBL. If
deop <player>
permissions.json is missing it will be created.
Changes a server setting without having to restart the server. Currently only two settings are supported to be
changesetting
changed, allow-cheats (true or false) and difficulty (0, peaceful , 1, easy , 2, normal , 3 or hard ). They do not
<setting> <value>
modify the value that's specified in server.properties .
Backups
The server supports taking backups of the world files while the server is running. It's not particularly friendly for taking manual
backups, but works better when automated. The backup (from the servers perspective) consists of three commands.
Command Description
save hold This will ask the server to prepare for a backup. It’s asynchronous and will return immediately.
After calling save hold you should call this command repeatedly to see if the preparation has finished. When it returns
a success it will return a file list (with lengths for each file) of the files you need to copy. The server will not pause while
save query
this is happening, so some files can be modified while the backup is taking place. As long as you only copy the files in
the given file list and truncate the copied files to the specified lengths, then the backup should be valid.
save
When you’re finished with copying the files you should call this to tell the server that it’s okay to remove old files again.
resume
