How to Connect Multiple Minecraft Servers with Velocity
Connect several Paper servers behind the Velocity proxy on a Linux VPS or dedicated server: secure player forwarding, closed internal ports and rollback.
On this page
Your values
Enter them once and the commands in this guide update.
Velocity is a Minecraft proxy: players connect to a single address, then move from one server to another without disconnecting. This guide places your existing server behind Velocity and adds a lobby server, on the same machine.
It follows on from the Create a Minecraft Server and Install and Update Plugins on Paper guides. It reuses the minecraft user, the /opt/minecraft/server folder, the minecraft.service service and the mc-console command.
By the end of this guide, you will have:
- Velocity listening on public port
25565, so your players keep the same address - two Paper servers reachable only from the machine itself
- secure forwarding of player identities, with their UUIDs and inventories preserved
Prerequisites
- A Paper server, set up with the two guides mentioned above, with Java 25,
curlandjq - SSH access with a user that has
sudoprivileges - About 2 GB of free memory on top of your current server: 1 GB for Velocity and up to 1 GB for the lobby
- Enough disk space for a full copy of the server folder
Velocity, BungeeCord or Waterfall?
| Velocity | BungeeCord | Waterfall | |
|---|---|---|---|
| Project | PaperMC, active development | SpigotMC, the original proxy | PaperMC, end of life |
| Secure identity forwarding | Yes, signed with a secret | No | No |
| Plugins | Velocity API | BungeeCord API | BungeeCord API |
PaperMC recommends Velocity over BungeeCord and Waterfall, and no longer maintains Waterfall.
BungeeCord remains a defensible choice in only one case: an essential proxy plugin that does not exist for Velocity, since Velocity does not load BungeeCord plugins. Because its identity forwarding is not signed, closing the internal ports as described below matters even more.
Understand the Target Setup
| Service | Name in Velocity | Folder | Listen address | Reachable from |
|---|---|---|---|---|
velocity.service |
/opt/minecraft/velocity |
0.0.0.0:25565 |
Internet | |
minecraft.service |
survie |
/opt/minecraft/server |
127.0.0.1:25566 |
This machine only |
minecraft-lobby.service |
lobby |
/opt/minecraft/lobby |
127.0.0.1:25567 |
This machine only |
Back Up the Server
Stop the server, then create a full archive. It stays stopped until the configuration is complete, because Velocity will take over port 25565:
sudo systemctl stop minecraft.service
sudo mkdir -p /opt/minecraft/backups
sudo tar -czf /opt/minecraft/backups/avant-velocity-$(date +%F-%H%M).tar.gz -C /opt/minecraft server
sudo ls -lh /opt/minecraft/backupsInstall Velocity
Create a script that downloads the latest stable build and verifies its checksum. You will reuse it for updates:
sudo nano /opt/minecraft/velocity-update.sh#!/bin/bash
# Downloads the latest stable Velocity build and replaces velocity.jar
set -euo pipefail
VERSION="${1:?Specify the Velocity version, for example 4.3.1}"
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
API="https://fill.papermc.io/v3/projects/velocity/versions/$VERSION/builds"
mkdir -p /opt/minecraft/velocity
cd /opt/minecraft/velocity
BUILD=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -c 'map(select(.channel == "STABLE")) | .[0]')
if [ "$BUILD" = "null" ]; then
echo "No stable build found for Velocity $VERSION." >&2
exit 1
fi
URL=$(echo "$BUILD" | jq -r '.downloads."server:default".url')
SHA256=$(echo "$BUILD" | jq -r '.downloads."server:default".checksums.sha256')
curl -fL -H "User-Agent: $UA" -o velocity.jar.new "$URL"
echo "$SHA256 velocity.jar.new" | sha256sum -c -
if [ -f velocity.jar ]; then
mv velocity.jar velocity.jar.old
fi
mv velocity.jar.new velocity.jar
echo "Velocity $VERSION, build $(echo "$BUILD" | jq -r '.id'), is in place."On the UA line, replace your-domain.com with your website address or a way to contact you. Then run the script:
sudo chmod 755 /opt/minecraft/velocity-update.sh
sudo -u minecraft /opt/minecraft/velocity-update.sh 4.3.1The line velocity.jar.new: OK confirms that the file is intact.
Create the service:
sudo nano /etc/systemd/system/velocity.service[Unit]
Description=Velocity Minecraft Proxy
After=network.target
[Service]
User=minecraft
WorkingDirectory=/opt/minecraft/velocity
ExecStart=/usr/bin/java -Xms1G -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15 -jar /opt/minecraft/velocity/velocity.jar
SuccessExitStatus=130 143
Restart=on-failure
RestartSec=20
StandardInput=null
[Install]
WantedBy=multi-user.targetThese Java options are the ones recommended by the Velocity documentation. Start the proxy once to generate its configuration:
sudo systemctl daemon-reload
sudo systemctl start velocity.service
sudo journalctl -u velocity.service -n 30 --no-pagerWait for the Done line. The Player info forwarding is disabled! warning is normal at this stage. Then stop the proxy and protect its folder, which contains the secret:
sudo systemctl stop velocity.service
sudo chmod 700 /opt/minecraft/velocity
sudo ls -l /opt/minecraft/velocityYou should see velocity.toml and forwarding.secret.
Configure Velocity
sudo -u minecraft nano /opt/minecraft/velocity/velocity.tomlCheck or change these lines, at the top of the file:
bind = "0.0.0.0:25565"
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"Then replace the entire contents of the [servers] and [forced-hosts] sections:
[servers]
lobby = "127.0.0.1:25567"
survie = "127.0.0.1:25566"
try = [
"lobby",
"survie"
]
[forced-hosts]try sets the order in which servers are tried at login, or when a player is kicked from a server. The [forced-hosts] section stays empty: the bundled examples point to factions and minigames servers that do not exist on your setup, and Velocity would refuse to start.
Connect the Existing Server
Make the server listen on the loopback interface, on its new port, and hand authentication over to the proxy:
sudo -u minecraft sed -i \
-e 's/^server-ip=.*/server-ip=127.0.0.1/' \
-e 's/^server-port=.*/server-port=25566/' \
-e 's/^online-mode=.*/online-mode=false/' \
/opt/minecraft/server/server.properties
sudo grep -E '^(server-ip|server-port|online-mode)=' /opt/minecraft/server/server.propertiesNext, enable modern forwarding in the Paper configuration, with the secret generated by Velocity:
SECRET=$(sudo cat /opt/minecraft/velocity/forwarding.secret)
sudo -u minecraft sed -i "/^ velocity:/,/^ \{0,2\}[a-z]/{s/^ enabled: .*/ enabled: true/;s/^ online-mode: .*/ online-mode: true/;s/^ secret: .*/ secret: '$SECRET'/;}" /opt/minecraft/server/config/paper-global.yml
unset SECRET
sudo chmod 700 /opt/minecraft/server/configCheck the result without displaying the secret:
sudo grep -A3 '^ velocity:' /opt/minecraft/server/config/paper-global.yml | sed 's/secret: .*/secret: (hidden)/'
sudo grep -qF "$(sudo cat /opt/minecraft/velocity/forwarding.secret)" /opt/minecraft/server/config/paper-global.yml && echo "Secret matches" || echo "Secret differs"
sudo grep 'bungeecord:' /opt/minecraft/server/spigot.ymlYou should get enabled: true, online-mode: true, Secret matches and bungeecord: false. This last setting must stay at false with modern forwarding.
Create the Lobby Server
The lobby reuses the same server.jar and the same global Paper configuration:
sudo -u minecraft mkdir -p /opt/minecraft/lobby/config
sudo chmod 700 /opt/minecraft/lobby/config
sudo -u minecraft cp /opt/minecraft/server/server.jar /opt/minecraft/lobby/
sudo -u minecraft cp /opt/minecraft/server/config/paper-global.yml /opt/minecraft/lobby/config/
echo "eula=true" | sudo -u minecraft tee /opt/minecraft/lobby/eula.txtCreate its settings, with a flat world and no monsters:
sudo -u minecraft tee /opt/minecraft/lobby/server.properties > /dev/null <<'EOF'
server-ip=127.0.0.1
server-port=25567
online-mode=false
motd=Lobby
max-players=50
level-type=minecraft\:flat
generate-structures=false
gamemode=adventure
force-gamemode=true
difficulty=peaceful
allow-nether=false
view-distance=6
simulation-distance=4
EOFCreate its service:
sudo nano /etc/systemd/system/minecraft-lobby.service[Unit]
Description=Minecraft Lobby Server
After=network.target
[Service]
User=minecraft
WorkingDirectory=/opt/minecraft/lobby
ExecStart=/usr/bin/java -Xms512M -Xmx1G -jar /opt/minecraft/lobby/server.jar nogui
ExecStop=/bin/kill -SIGINT $MAINPID
SuccessExitStatus=130 143
TimeoutStopSec=180
Restart=on-failure
RestartSec=20
StandardInput=null
[Install]
WantedBy=multi-user.targetStart Everything
Start both servers, then follow the lobby's first startup until the Done line appears:
sudo systemctl daemon-reload
sudo systemctl start minecraft.service
sudo systemctl enable --now minecraft-lobby.service
sudo journalctl -u minecraft-lobby.service -fExit the log view with Ctrl+C, then start the proxy:
sudo systemctl enable --now velocity.service
sudo journalctl -u velocity.service -n 30 --no-pagerCheck That the Internal Ports Are Closed
sudo ss -ltnp | grep -E ':(25565|25566|25567)\b'Port 25565 must listen on all addresses. Ports 25566 and 25567 must show 127.0.0.1 or [::ffff:127.0.0.1], never 0.0.0.0, * or [::].
The firewall does not change: only port 25565 stays open. With UFW, this command must display nothing:
sudo ufw status | grep -E '2556[67]'Then test the ports from another computer. The first must respond, and the second must fail:
nc -zv -w 5 SERVER_IP 25565
nc -zv -w 5 SERVER_IP 25566If a Server Is on Another Machine
The loopback interface only works within a single machine. On a second machine, make the server listen on a private address, ideally that of a WireGuard tunnel, enter this address in velocity.toml, then allow only the proxy. On that second machine, with UFW:
sudo ufw allow from PROXY_IP to any port 25566 proto tcpOr with iptables:
sudo iptables -A INPUT -p tcp -s PROXY_IP --dport 25566 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 25566 -j DROPVerify the Result
First, check the three services:
systemctl is-active velocity.service minecraft.service minecraft-lobby.serviceThen connect with your Minecraft client, using the same address as before. You should arrive in the lobby. Type:
/server
/server survieThe first command lists the servers, and the second transfers you without disconnecting. Your builds and inventory should be there. Finally, check what the server received:
sudo journalctl -u minecraft.service --since "10 minutes ago" --no-pager | grep -E 'UUID of player|logged in with entity id'You should see your public IP address, not 127.0.0.1. The third block of the UUID must start with 4, which indicates an authenticated account.
Plugins and the Proxy
Paper plugins stay in each server's plugins folder. Velocity has its own plugins, which go in /opt/minecraft/velocity/plugins and are loaded by restarting the proxy.
If you use Geyser and Floodgate, their installation changes behind a proxy: follow the Floodgate documentation for Velocity.
Back Up the Proxy and the Lobby
The backup.sh script from the base guide does not cover these folders. First, protect the backups folder, since the archives will contain the secret:
sudo chmod 700 /opt/minecraft/backupsThen add this line to /opt/minecraft/backup.sh, after the existing tar line. The world_ prefix lets the script's automatic cleanup take this archive into account:
tar -czf $BACKUP_DIR/world_proxy_$DATE.tar.gz -C /opt/minecraft velocity lobbyUpdate
When a new version of Minecraft comes out, update Velocity before the servers so that it accepts the new clients. Players are disconnected during the operation:
sudo systemctl stop velocity.service
sudo tar -czf /opt/minecraft/backups/velocity-$(date +%F-%H%M).tar.gz -C /opt/minecraft velocity
sudo -u minecraft /opt/minecraft/velocity-update.sh 4.3.1
sudo systemctl start velocity.serviceThen update the survie server as explained in the Paper guide, and copy its file to the lobby:
sudo systemctl stop minecraft-lobby.service
sudo tar -czf /opt/minecraft/backups/lobby-$(date +%F-%H%M).tar.gz -C /opt/minecraft lobby
sudo -u minecraft cp /opt/minecraft/server/server.jar /opt/minecraft/lobby/server.jar
sudo systemctl start minecraft-lobby.serviceRoll Back
To return to a single server on port 25565, without losing what has been played since:
sudo systemctl disable --now velocity.service minecraft-lobby.service
sudo systemctl stop minecraft.service
sudo -u minecraft sed -i \
-e 's/^server-ip=.*/server-ip=/' \
-e 's/^server-port=.*/server-port=25565/' \
-e 's/^online-mode=.*/online-mode=true/' \
/opt/minecraft/server/server.properties
sudo -u minecraft sed -i "/^ velocity:/,/^ \{0,2\}[a-z]/{s/^ enabled: .*/ enabled: false/;s/^ secret: .*/ secret: ''/;}" /opt/minecraft/server/config/paper-global.yml
sudo systemctl start minecraft.serviceThe velocity and lobby folders stay in place. If a more serious problem occurs, restore the avant-velocity-… archive as described in the Restore the Backup section of the Paper guide.
Troubleshooting
Start with the logs of the proxy and of the server concerned:
sudo journalctl -u velocity.service -n 100 --no-pager
sudo journalctl -u minecraft.service -n 100 --no-pager
sudo journalctl -u minecraft-lobby.service -n 100 --no-pager"Unable to connect you to lobby. Please try again later."
Velocity cannot reach this server. Check that it is started and has finished loading, then that the port in velocity.toml matches server-port. The ss command above shows the ports actually open.
"There are no available servers to connect you to."
No server in the try list accepted the player. Check this list and start at least one of these servers.
"Your server did not send a forwarding request to the proxy"
Modern forwarding is not active on the Paper server. Check for enabled: true in config/paper-global.yml, then restart the server. If its logs show Velocity is enabled, but no secret key was specified, the secret is empty: go back to the Connect the Existing Server section.
"Unable to verify player details"
The Paper secret does not match forwarding.secret. Run the secret copy command again on the server concerned, then restart it. For the lobby, use the path /opt/minecraft/lobby/config/paper-global.yml.
"This server requires you to connect with Velocity."
The player is reaching the Paper server without going through the proxy, or Velocity is not using modern mode. Check player-info-forwarding-mode and the address the player is using. If they were able to reach 25566 from the Internet, close this port immediately.
"This server is only compatible with Minecraft 1.13 and above."
Modern forwarding refuses clients older than 1.13. These players must move to a newer version.
Velocity does not start
| Log message | Cause | Solution |
|---|---|---|
Can't bind to …:25565 |
The port is already in use, often by a Minecraft server | Check server-port and use sudo ss -ltnp |
Server 'factions' for forced host '…' does not exist |
An example remains in [forced-hosts] |
Empty the section |
Fallback server … is not registered in your configuration! |
A name in try is missing from [servers] |
Correct the name |
You don't have a forwarding secret set |
The secret file is empty or cannot be found | Check forwarding.secret |
UnsupportedClassVersionError |
Java is too old | Install Java 25 |
"FAILED TO BIND TO PORT" on a Paper server
Two services are using the same port. Check server-port in each server.properties: 25566 for survie, 25567 for the lobby.
Players have lost their inventory
The server assigned them a different UUID, usually because forwarding was not active or because proxies.velocity.online-mode does not match Velocity's online-mode. Stop the server, correct these settings and restart it: the original data remains in the world, under the old UUID.
To go further, see the official Velocity documentation, especially its pages on player information forwarding and security.