How to build a Minecraft network with Velocity or BungeeCord

A proxy lets players join one address and move between several Minecraft servers, such as a lobby, a survival world and a minigame server. The proxy itself has no world. Players connect to it, and it passes them on to the servers behind it, which are called backend servers.

On PlayNHost, each backend server and the proxy are separate servers, each with its own plan and its own address. Instances cannot take their place, because only one instance of a server runs at a time. See How to use instances to switch between worlds.

Which proxy to choose

This guide uses Velocity with Paper servers behind it. BungeeCord and Waterfall are noted at the end. All three appear as server types under Proxies in Edit Server Type. See Minecraft server types explained.

Before you start

• Order or set up the proxy server and at least two backend servers. Put them in the same location, so players do not wait on long hops between them. See Where your server runs and how location works.
• The backend servers should run Paper or a Paper fork such as Purpur. Velocity's secure forwarding is set up in Paper's settings.
• Players only ever get the proxy's Server Address. Keep the backend addresses to yourself.

The main weakness of this setup. Every PlayNHost server has its own address, so a player who learns a backend's address could try to join it directly and skip the proxy. Secure forwarding with the secret is what stops a direct join from working, so keep the secret private and never publish a backend address. See the first item under "Things that catch people out" below.

• Every backend server's version must be one the proxy and your players can use. Players join the proxy, so their game version must match what the backends accept.

Step 1: start the proxy and copy its secret

1. Set up a server of type Velocity. It takes no version choice. Start it once, then stop it. It creates its settings file, velocity.toml, and a secret file, forwarding.secret.
2. Open Files on the proxy and open forwarding.secret. Copy the text in it. It is a password for your network. Do not share it, post it in a ticket or hand a backup to anyone.

Step 2: set up each backend server

Do this on every Paper server that will sit behind the proxy.

1. Start the server once so its settings files exist, then stop it.
2. Open Settings, then Server Properties (Java). Switch Online mode off and click Save only. Velocity's documentation requires this on every backend server, because the proxy does the sign-in check instead.

3. Open Settings, then Paper's Global Settings. This page exists on Paper 1.19 and newer. Older Paper versions keep these settings in a different file (paper.yml) and have no such page, so upgrade them first or open a ticket. Use the search box to find these three settings under proxies.velocity, change them, and click Save only:

   • enabled: switch on.
   • online-mode: it must match online-mode in the proxy's velocity.toml. That is on unless you changed it.
   • secret: paste the text you copied from forwarding.secret.
4. Start the server.

Turning Online mode off is only safe behind a proxy that forwards players securely, which these steps set up. A backend server with Online mode off and no forwarding lets anyone join under any name, including yours. See How to join your Minecraft server.

Step 3: tell the proxy about the backends

1. On the proxy, open Settings, then Velocity Settings. Set player-info-forwarding-mode to MODERN. Click Save only.
2. In the servers section of velocity.toml, give each backend a name and its address as host:port. Velocity connects to it directly, so no player has to type it. Start with the Server Address shown on that backend's Overview page. We cannot promise that a proxy can always reach a backend by that address, because the panel describes this entry as an internal address rather than the one players use. If the proxy cannot reach a backend (players are sent back or kicked, and the proxy's Console shows a connection error), open a ticket, choose the proxy under Which server?, name the backend server in the message, and ask which address the proxy should use.
3. In the same section, try holds the names of the servers players land on first, in order. Velocity uses the next one if the first is down. Put your lobby first.
4. Start the proxy.

The settings page only edits entries that already exist in the file. To add a new backend, stop the proxy, open velocity.toml in Files, add a line under the servers section, save, and start the proxy again.

Join and test

1. Start every backend server and wait for it to say Online.
2. Start the proxy.
3. In Minecraft Java Edition, join with the proxy's Server Address. You should arrive on the first server in the try list.
4. In the game, type /server and the name of another backend to move. On Velocity, a name from the servers section works.
5. If a player appears with the wrong name, a different UUID or no skin, forwarding is not working. Check that the same secret is on the proxy and on every backend, and that player-info-forwarding-mode is MODERN.

For how to read the proxy's Console and what its filters show, see How to use the console and run commands.

Things that catch people out

• Backend servers are reachable by their own address. Players who know a backend's address could try to join it directly. Velocity's own security guide says a firewall is the first choice and that modern forwarding is not a replacement for one. With modern forwarding and the secret in place, a backend does not accept players unless the data carries the secret. Keep the secret private and do not publish backend addresses. If you need stricter access, open a ticket and ask what is possible.
• Wrong secret. A backend that has a different secret rejects the connection, and the player is sent back to the first server or kicked. Copy the secret again.
• Player limits. The player count shown by the proxy is only a number. Each backend still enforces the player slots of its own plan. See How to rename your server and change player slots.
• Whitelist, ops and bans are stored on each backend server. Set them on every backend, or use a permissions plugin that spans the network. See How to set up a whitelist and ban players.
• Plugins on the proxy are different from plugins on Paper. In Modding, then Plugins, a proxy shows only proxy plugins. See How to install plugins on Paper, Spigot and Purpur.
• Modded backend servers need extra steps that depend on the mod loader. Open a ticket if you want to try one.
• Bedrock players can join through Geyser on the proxy. See How to let Bedrock players join your Java server with Geyser.

BungeeCord and Waterfall

The setup is the same in outline, with different settings.

1. Start the proxy once. Its settings are in Settings, then Proxy Settings, which is the config.yml file.
2. Add the backends under the servers entries as host:port, and list them in priorities under listeners. The address question from Step 3 applies here too. Turn on ip_forward so players keep their real identity.
3. On each backend, turn Online mode off, and in Settings, Spigot Settings, turn on bungeecord under settings. The panel describes this setting as safe only if the server cannot be reached directly. Because every PlayNHost server has its own address, BungeeCord's forwarding offers much weaker protection than Velocity's, and this is a strong reason to pick Velocity for a new network.

If you cannot decide, pick Velocity.

Related

• Minecraft server problems and fixes
• How to find and change your server's ports and IP address