Een servernetwerk met Velocity: lobby, survival en minigames onder één adres

Velocity is een proxy waarmee spelers op één adres verbinden en daarna met het commando /server tussen servers wisselen, bijvoorbeeld van de lobby naar survival of naar de minigames. We laten zien hoe je Velocity installeert en instelt, hoe je het via het veilige modern forwarding met je servers koppelt en hoe je de servers achter de proxy zo beveiligt dat niemand er rechtstreeks op kan komen.

Wanneer je een proxy nodig hebt#

De proxy berekent het spel niet zelf, hij stuurt alleen verbindingen door. Hij vraagt weinig rekenkracht: voor tientallen spelers is 1–⁠2 GB geheugen genoeg.

Hoe het netwerk werkt#

Speler ──► mc.example.cz:25565  (Velocity, verifieert het account van de speler)
              │
              ├──► lobby     (Paper, online-mode=false, accepteert alleen de proxy)
              ├──► survival  (Paper, online-mode=false, accepteert alleen de proxy)
              └──► minihry   (Paper, online-mode=false, accepteert alleen de proxy)

1. De speler verbindt met het adres van de proxy. De proxy controleert bij Microsoft of hij een origineel account heeft (online-mode = true).
2. De proxy stuurt hem naar de eerste server uit de lijst try (de lobby).
3. Bij het verbinden geeft de proxy de naam, het UUID, de skin en het echte IP-adres van de speler door aan de server (player info forwarding). De gegevens ondertekent hij met een geheime sleutel die alleen de proxy en jouw servers kennen.
4. De servers achter de proxy (backends) verifiëren zelf niets (online-mode=false) en vertrouwen alleen een proxy met een geldige sleutel. Wie rechtstreeks verbindt, krijgt de melding This server requires you to connect with Velocity.

Proxy, servers en domein#

• Proxy: Velocity 4.x vereist Java 25. Draai de proxy op een VPS (VPS Performance, VPS Budget). Op de proxy horen alleen plugins voor Velocity. Plugins voor Paper werken er niet op.
• Backends: gewone Minecraft-servers. Ze kunnen bij ons draaien als aparte diensten (elk met een eigen adres en poort), of op dezelfde VPS als de proxy.
• Domein (optioneel): spelers typen mc.example.cz in plaats van een IP-adres (Serveradres en domein).

Velocity installeren op een VPS#

Dit geldt voor zowel Ubuntu 24.04 als Debian 13. Voer de commando's uit als root.

1. Installeer Java 25 en het programma curl:

   apt update
   apt install openjdk-25-jre-headless curl

   • apt update – haalt de actuele pakketlijst op.
   • apt install openjdk-25-jre-headless – installeert de runtime van Java 25 zonder grafische bibliotheken (die heb je op een server niet nodig).
   • curl – een programma om bestanden van internet te downloaden (heb je het al, dan gebeurt er niets).

2. Controleer de versie:

   java -version

   De eerste regel van de uitvoer moet 25 bevatten.

3. Maak een gebruiker en een map voor de proxy aan:

   useradd --system --create-home --home-dir /opt/velocity --shell /usr/sbin/nologin velocity

   • useradd --system – maakt een systeemgebruiker zonder wachtwoord aan (de proxy draait niet als root).
   • --create-home --home-dir /opt/velocity – maakt de map /opt/velocity aan, waar de proxy komt te staan.
   • --shell /usr/sbin/nologin – met deze gebruiker kan niemand inloggen.
   • velocity – de naam van de gebruiker.

4. Kopieer op de pagina papermc.io/downloads/velocity (opent in een nieuw venster) de link naar de nieuwste stabiele versie en download die:

   cd /opt/velocity
   curl -o velocity.jar "<DOWNLOAD_URL>"
   chown velocity:velocity velocity.jar

   • cd /opt/velocity – gaat naar de map van de proxy.
   • curl -o velocity.jar – downloadt het bestand en slaat het op als velocity.jar.
   • <DOWNLOAD_URL> – de link die je van de pagina hebt gekopieerd. Vervang hem helemaal, inclusief de punthaken, en laat de aanhalingstekens staan.
   • chown velocity:velocity – het bestand wordt eigendom van de gebruiker velocity.

5. Start de proxy voor de eerste keer, zodat hij zijn configuratie aanmaakt:

   runuser -u velocity -- env MALLOC_ARENA_MAX=2 java -Xms1G -Xmx1G -XX:MaxDirectMemorySize=512M -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -jar velocity.jar

   • runuser -u velocity -- – voert het commando na -- uit als de gebruiker velocity.
   • env MALLOC_ARENA_MAX=2 – beperkt de geheugenarena's van de allocator, zodat de proxy niet onnodig extra geheugen inneemt.
   • -Xms1G -Xmx1G – de proxy krijgt 1 GB heap (in één keer, hij hoeft hem tijdens het draaien niet te vergroten). Verhoog dit voor een groter netwerk naar 2G. De proxy heeft ook buiten de heap veel geheugen nodig voor het netwerk. Geef hem daarom niet meer dan de helft van het geheugen dat je voor hem beschikbaar hebt.
   • -XX:MaxDirectMemorySize=512M – de bovengrens voor netwerkbuffers. Zonder die grens kunnen ze groeien tot de grootte van de heap.
   • -XX:+UseG1GC … -XX:+AlwaysPreTouch – flags die de documentatie van Velocity aanbeveelt (de garbage collector G1, afgestemd op een proxy).
   • -jar velocity.jar – start de proxy.

   Een commando voor een andere geheugengrootte maakt de Startscript-generator voor je.

   Na het starten zie je de regel Done (…)!. Typ end en druk op Enter, dan sluit de proxy af. In de map staan nu de bestanden velocity.toml en forwarding.secret.

6. Wil je dat de proxy permanent draait en na een herstart van de VPS vanzelf start, maak er dan een systemd-service voor aan volgens de handleiding Een applicatie 24/7 op een VPS. Zet in het unit-bestand User=velocity, WorkingDirectory=/opt/velocity, Environment=MALLOC_ARENA_MAX=2 en bij ExecStart het commando uit stap 5 zonder runuser -u velocity -- env MALLOC_ARENA_MAX=2 en met het volledige pad naar Java, dus beginnend met /usr/bin/java -Xms1G ….

7. Sta de poort van de proxy toe in de firewall van de VPS: TCP 25565 (en de UDP-poort van Geyser, als je die gaat gebruiken). Zie Firewall in je klantaccount en UFW.

velocity.toml#

Open het bestand /opt/velocity/velocity.toml (bijvoorbeeld met nano /opt/velocity/velocity.toml). Een voorbeeld met de instellingen voor een netwerk van drie servers (laat de rest van het bestand staan):

bind = "0.0.0.0:25565"
motd = "<gold><bold>StormCraft</bold></gold> <gray>| lobby, survival, minihry"
show-max-players = 100
online-mode = true
force-key-authentication = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

[servers]
lobby = "203.0.113.10:30066"
survival = "203.0.113.11:30067"
minihry = "203.0.113.12:30068"

try = [
    "lobby"
]

[forced-hosts]
"survival.example.cz" = [
    "survival"
]

Uit de secties [advanced] en [query] zijn drie instellingen de moeite waard:

De geheime sleutel voor forwarding#

Bij de eerste start maakt Velocity het bestand forwarding.secret aan met een willekeurige sleutel van 12 tekens. We raden aan die te vervangen door een langere:

1. Genereer een willekeurig wachtwoord van 32 of meer tekens (letters en cijfers) in de wachtwoordgenerator.
2. Zet het als enige regel in /opt/velocity/forwarding.secret (bijvoorbeeld met nano).
3. Dezelfde sleutel vul je daarna in op alle backends.

Backends instellen (Paper en Purpur)#

Bij elke server achter de proxy:

1. Zet op het tabblad Serverinstellingen in de groep Spelers de optie Accountverificatie uit (online-mode=false) en klik op Opslaan.

   Je klantaccount toont een waarschuwing dat iedereen kan verbinden. Achter een proxy met modern forwarding klopt dat: de proxy doet de verificatie en de server accepteert alleen spelers met een geldige sleutel.

2. Open op het tabblad Bestanden het bestand spigot.yml en controleer of settings.bungeecord op false staat:

   settings:
     bungeecord: false

   • bungeecord – schakelt forwarding in het formaat van BungeeCord (legacy) in. Voor modern forwarding moet dit uit staan.

3. Open config/paper-global.yml en stel in de sectie proxies het volgende in:

   proxies:
     velocity:
       enabled: true
       online-mode: true
       secret: "<SECRET>"

   Zet op de plek van <SECRET> de inhoud van het bestand forwarding.secret van de proxy. Vervang hem helemaal, inclusief de punthaken, en laat de aanhalingstekens staan.

4. Herstart de server.

Wat de instellingen in paper-global.yml betekenen:

Op Paper 1.18.2 en ouder staan deze instellingen in het bestand paper.yml onder de namen settings.velocity-support.enabled, settings.velocity-support.online-mode en settings.velocity-support.secret.

Fabric, Forge en NeoForge#

De instellingen van FabricProxy-Lite:

Backends beveiligen#

Een backend met online-mode=false zonder werkende forwarding zou iedereen binnenlaten onder elke gewenste naam. Wat je doet, hangt af van waar de servers draaien:

• Backends bij ons (aparte diensten): het adres en de poort stellen wij automatisch in (server-ip kun je niet wijzigen), de servers zijn dus bereikbaar vanaf internet. De bescherming komt van modern forwarding: met proxies.velocity.enabled: true weigert de server iedereen die niet via de proxy met een geldige sleutel binnenkomt. Gebruik daarom nooit legacy of none.
• Backends op dezelfde VPS als de proxy: stel in server.properties van elke backend server-ip=127.0.0.1 in en vul in velocity.toml de adressen 127.0.0.1:<PORT> in. De servers zijn dan van buitenaf helemaal niet bereikbaar. Sta in de firewall van de VPS alleen de poort van de proxy toe.
• Backends op een andere VPS: sta in de firewall van de backend de poort van de server alleen toe vanaf het IP-adres van de proxy (Firewall in je klantaccount).

Wisselen tussen servers en plugins op de proxy#

Plugins op de proxy (in de map /opt/velocity/plugins, de versie voor Velocity):

• LuckPerms – rechten voor de commando's van de proxy. Voor rechten op de servers moet LuckPerms ook op elke backend staan en moeten alle instanties dezelfde MySQL/MariaDB-database gebruiken (MySQL voor plugins). Stel op elke backend in de configuratie van LuckPerms een andere server in (bijvoorbeeld lobby, survival), zodat je rechten per server kunt geven, en messaging-service: sql, zodat wijzigingen meteen op alle servers gelden. Meer in de handleiding LuckPerms.
• Geyser en Floodgate – Bedrock-spelers, installeer ze alleen op de proxy (handleiding).
• spark – profilering van de proxy, het commando sparkv.

Controle#

1. Start de proxy en de backends. In de console van de proxy zie je Listening on …:25565 en Done (…)!.
2. Verbind in het spel met het adres van de proxy. Je komt op de server lobby terecht.
3. Typ /server survival: je wisselt van server zonder dat de verbinding wordt verbroken.
4. Controleer in de console van de backend de regel met jouw verbinding: daar moet je echte IP-adres in staan, niet het adres van de proxy. Dan werkt forwarding. De console in je klantaccount verbergt IP-adressen in de standaard ingeschakelde streamermodus. Klik voor deze controle bovenaan op Gegevens tonen.
5. Probeer rechtstreeks met het adres van een backend te verbinden. Je moet This server requires you to connect with Velocity. krijgen.

Als iets niet werkt#

Your server did not send a forwarding request to the proxy. Make sure the server is configured for Velocity forwarding.#

Op de backend staat modern forwarding niet aan. Controleer proxies.velocity.enabled: true in config/paper-global.yml (bij Fabric FabricProxy-Lite) en of je de server na de wijziging hebt herstart.

Unable to verify player details#

De sleutel op de backend komt niet overeen met forwarding.secret op de proxy. Kopieer hem opnieuw (zonder extra spaties of lege regels) en herstart de backend.

This server requires you to connect with Velocity.#

Je verbindt rechtstreeks met de backend. Dat klopt, de server is beschermd. Zie je de melding ook als je via de proxy verbindt, dan staat player-info-forwarding-mode op de proxy op iets anders dan modern.

Unable to connect you to lobby. Please try again later.#

De proxy kon de backend niet bereiken: de server draait niet, het adres of de poort in [servers] komt niet overeen met het adres op het tabblad Netwerk van die server, of een firewall blokkeert de verbinding.

There are no available servers to connect you to. Try again later or contact an admin.#

Geen enkele server uit de lijst try is bereikbaar. Start de lobby of voeg een reserveserver toe aan try.

Spelers hebben na de overstap naar de proxy een lege inventaris en andere rechten#

De spelers hebben een ander UUID gekregen. De oorzaak is player-info-forwarding-mode = "none" (offline UUID's) of een verschil tussen online-mode op de proxy en proxies.velocity.online-mode op de backend. Stel modern forwarding in en zet beide waarden op true. De gegevens onder de oude UUID's blijven in de bestanden van de wereld en de plugins staan. Maak een back-up voordat je een groot netwerk naar een proxy overzet.

De proxy laat Bedrock-spelers niet binnen of ze kunnen niet typen#

Zie Crossplay met Bedrock: Geyser moet op de proxy staan en in velocity.toml moet force-key-authentication uit staan.

Meer bronnen#

• Velocity: eerste stappen (opent in een nieuw venster)
• Velocity: player information forwarding (opent in een nieuw venster)
• Velocity: configuratie (opent in een nieuw venster)
• Velocity: servers beveiligen (opent in een nieuw venster)
• Paper: globale configuratie (opent in een nieuw venster)
• LuckPerms: installatie op een netwerk (opent in een nieuw venster)