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

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.

Transport

The transport property selects which network protocol the server uses to accept client connections. Two values are supported:

• raknet (default) — The traditional Bedrock UDP transport. The server listens directly on server-port (IPv4) and server-portv6 (IPv6), and clients connect to that address and port. This is the mode used by all previous releases.
• nethernet — A WebRTC-based transport. The server listens on a single dual-stack TCP socket on server-port for an HTTP-based signaling handshake, then negotiates a UDP connection with each client that carries the gameplay traffic.

  When transport=nethernet, the following additional properties apply:

  • server-ip — The local address to bind the listening socket to. Leave empty to bind to all interfaces. Accepts either an IPv4 or IPv6 literal. When empty, the server prefers a dual-stack IPv6 socket so that one listener serves both IPv4 and IPv6 clients, and falls back to IPv4-only if dual-stack is unavailable.
  • server-udp-ports — Constrains the local UDP port range and optionally publishes an external NAT/port-forwarding mapping for clients. See the UDP port configuration for NetherNet section below.

  Tip for servers open to the Internet: Because the NetherNet handshake on server-port speaks HTTP/TCP, it is recommended to put a reverse proxy (for example nginx, HAProxy, or a managed edge service) in front of server-port to terminate connections, enforce request and rate limits, and absorb abusive traffic before it ever reaches the server. Only the signaling traffic on server-port needs to be forwarded through the proxy — the gameplay traffic flows directly between the client and the server over the negotiated UDP connection.

UDP port configuration for NetherNet

By default, the NetherNet transport allocates UDP ports for client connections from the operating system's ephemeral range, which is fine for most LAN and outbound-friendly deployments but is not always suitable for servers that sit behind a firewall or NAT. server-udp-ports lets you pin the local port range the server uses, and/or describe a port mapping that clients should connect to.

Each entry takes one of the following forms:

• internal or start-end — restricts the UDP port allocation window to the given port or inclusive range. Use this to confine the server to a specific set of local ports (for example, a firewall-opened range).
• [ip:]external[-external]:internal[-internal] — publishes a NAT or port-forwarding mapping that the server advertises to clients. Use this when the address or port the server binds locally differs from the address or port clients must connect to (for example, when the server sits behind a 1:1 NAT or a router-level port-forwarding rule).
  • internal is the local UDP port the server actually binds to.
  • external is the port clients reach from outside — the port the NAT or router translates to internal. The optional ip: prefix is the public address those clients see (IPv6 literals must be enclosed in square brackets); omit it to advertise the host's own addresses.
  • Either side may be a single port or a start-end range. If both are ranges they must be the same length, and each external port is paired with the internal port at the same offset.

Multiple entries can be supplied on a single line separated by commas, and the property may also appear on more than one line to accumulate entries. Some examples:

# Restrict local UDP allocation to the specified range
server-udp-ports=49152-49200

# Bind locally to ports 32000-32100 and advertise them to clients as external ports 19132-19232
server-udp-ports=19132-19232:32000-32100

# Same, but advertised on a specific public IPv4 address
server-udp-ports=203.0.113.10:19132-19232:32000-32100

# Same, but advertised on a specific public IPv6 address
server-udp-ports=[2001:db8::1]:19132-19232:32000-32100

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:

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.

Example allowlist.json file:

[
    {
        "ignoresPlayerLimit": false,
        "name": "MyPlayer"
    },
    {
        "ignoresPlayerLimit": false,
        "name": "AnotherPlayer",
        "xuid": "274817248"
    }
]

Packet Rate Limit Config

If the enable-packet-rate-limiter property is enabled in server.properties, the server will use the packet rate limiter feature. Following the configuration described by the packetlimitconfig.json file, specific types of packets will be limited and rejected.

To reload the packet rate limiter configuration on the flight, use the server command reloadpacketlimitconfig. The server will reload the configuration from the packetlimitconfig.json file and update it for all of its clients.

The packetlimitconfig.json file contains a JSON array with a list of limit groups. Each group contains a list of packet ids and the corresponding packet rate limit algorithm that will be applied to them. Only BucketPacketLimitAlgorithm is currently supported. Additionally, the file can also use a default algorithm that will be applied to limit the rate for all packet types, on top of the ones specified by the limit groups.

BucketPacketLimitAlgorithm requires two parameters:

Example of the packetlimitconfig.json file:

{
    "limitGroups": [{
        "minecraftPacketIds": [193, 4],
        "algorithm": {
            "name": "BucketPacketLimitAlgorithm",
            "params": {
                "drainRatePerSec": 0.0013,
                "maxBucketSize": 1
            }
        }
    }, {
        "minecraftPacketIds": [9],
        "algorithm": {
            "name": "BucketPacketLimitAlgorithm",
            "params": {
                "drainRatePerSec": 10,
                "maxBucketSize": 50
            }
        }
    }],
    "defaultAlgorithm": {
        "name": "BucketPacketLimitAlgorithm",
        "params": {
            "drainRatePerSec": 0.0013,
            "maxBucketSize": 1
        }
    }
}

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.

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.