Proxy Protocol für Minecraft: Wozu es nötig ist und wie man es einrichtet

Was ist Proxy Protocol

Wenn ein Minecraft-Server hinter einem Reverse Proxy steht (ob DDoS-Schutz, CDN oder ein eigener Proxy-Server), tritt ein grundlegendes Problem auf: Der Server sieht die IP-Adresse des Proxys, nicht die echte IP des Spielers. Für den Server sehen alle Verbindungen so aus, als kämen sie von ein und derselben Adresse.

Proxy Protocol löst genau dieses Problem. Es ist ein einfaches Protokoll, ursprünglich für HAProxy entwickelt, das die ursprünglichen Verbindungsinformationen (IP-Adresse und Port des Clients) ganz am Anfang einer TCP-Verbindung überträgt. Der Proxy fügt einen speziellen Header hinzu, bevor er den Traffic ans Backend weiterleitet, und das Backend liest ihn aus, um zu erfahren, wer sich tatsächlich verbunden hat.

Es gibt zwei Versionen des Protokolls. Proxy Protocol v1 überträgt Daten im Textformat, v2 im Binärformat. Die zweite Version ist kompakter und schneller zu parsen. Die meisten modernen Lösungen (einschließlich MineGuard) verwenden v2.

Warum euer Minecraft-Server das braucht

Ohne echte IP-Adressen fallen etliche Server-Mechaniken aus, auf die sich Administratoren täglich verlassen.

Bans und Moderation

Der offensichtlichste Fall. IP-Bans sind eines der wichtigsten Werkzeuge gegen Griefer und Cheater. Wenn der Server nur die IP des Proxys sieht, ist es unmöglich, einen bestimmten Spieler per IP zu bannen. Schlimmer noch: Wenn man versucht, diese eine sichtbare IP zu bannen, werden alle Spieler getrennt.

Geo-Blocking und Geo-Analytik

Viele Server beschränken Verbindungen nach Geografie. Ein Server könnte Verbindungen aus Regionen blockieren, aus denen typischerweise Bot-Traffic kommt. Oder ein Event-Server ist nur für eine bestimmte Region geöffnet. Ohne echte IPs funktioniert Geo-Filterung schlicht nicht.

Dazu kommt Analytik: Zu verstehen, woher die Spieler kommen, ist nützlich für die Weiterentwicklung des Projekts. Welche Regionen wachsen, wo man Werbung schalten sollte, ob zusätzliche Server-Standorte nötig sind.

Plugins und Limits

Unzählige Plugins basieren auf der Spieler-IP. Verbindungslimits pro IP, Anti-Bot-Systeme, Voting-Systeme, Account-Verknüpfungen. Wenn alle Spieler "von" derselben Adresse kommen, funktionieren diese Plugins entweder gar nicht oder fehlerhaft.

Logging

Bei einem Vorfall (Account-Kompromittierung, interner Angriff, Regelverstoß) sind Logs mit echten IP-Adressen der einzige Weg, die Situation aufzuklären. Logs, in denen alle dieselbe IP haben, sind wertlos.

Proxy Protocol für Paper einrichten

Paper (und seine Forks wie Purpur) unterstützen Proxy Protocol seit relativ neuen Versionen. Die Konfiguration hängt davon ab, welche Paper-Version ihr verwendet.

Paper 1.19.4 und neuer

In der Konfigurationsdatei config/paper-global.yml sucht die Sektion proxies:

proxies:
  proxy-protocol: true

Datei speichern und den Server neu starten. Fertig.

Ältere Paper-Versionen

Für Versionen vor 1.19.4 liegt die Konfiguration in paper.yml:

settings:
  proxy-protocol: true

Wichtiger Hinweis

Nach dem Aktivieren von Proxy Protocol erwartet der Server einen PP-Header bei jeder eingehenden Verbindung. Das bedeutet, dass direkte Verbindungen (ohne Proxy) nicht mehr funktionieren. Aktiviert diese Option nicht, bevor der Proxy eingerichtet ist, sonst kann sich niemand mehr auf den Server einloggen, auch ihr nicht.

Wenn ihr auf einer lokalen Maschine testet und euch direkt verbindet, müsst ihr PP entweder während des Testens deaktivieren oder euch über den Proxy verbinden.

Proxy Protocol für Velocity einrichten

Velocity ist ein beliebter Proxy-Server für Netzwerke mit mehreren Backend-Servern. Wenn eure Architektur so aussieht: "DDoS-Schutz -> Velocity -> Paper", dann muss PP auf Velocity aktiviert werden. Velocity gibt die echte IP dann über seinen eigenen Forwarding-Mechanismus an die Backend-Server weiter.

In velocity.toml:

[advanced]
haproxy-protocol = true

Nach dem Neustart liest Velocity PP-Header aus eingehenden Verbindungen.

Proxy-Ketten

Ein typisches Setup für einen geschützten Server:

Spieler → DDoS-Schutz (PP v2) → Velocity (haproxy-protocol = true) → Paper

In diesem Setup wird PP nur auf Velocity aktiviert. Paper erhält echte IPs über den eingebauten Modern-Forwarding-Mechanismus von Velocity. PP auf Paper zu aktivieren ist nicht nötig.

Wenn ihr kein Velocity habt und die Architektur einfacher ist:

Spieler → DDoS-Schutz (PP v2) → Paper (proxy-protocol = true)

Dann wird PP direkt auf Paper aktiviert.

Aktiviert PP nicht gleichzeitig auf Velocity und Paper in derselben Kette. Paper hinter Velocity soll keine PP-Header erwarten.

Wie Proxy Protocol mit DDoS-Schutz funktioniert

Ein DDoS-Schutzdienst für Minecraft funktioniert als Reverse Proxy: Er nimmt eingehende Verbindungen auf seiner eigenen IP entgegen, filtert schädlichen Traffic heraus und leitet sauberen Traffic an euren echten Server weiter. Ohne Proxy Protocol sieht der Server die IP des Filters statt die IP des Spielers.

MineGuard unterstützt Proxy Protocol v2. Es wird mit einem einzigen Häkchen im Control Panel unter den Netzwerkeinstellungen aktiviert. Danach fügt der Filter automatisch einen PP v2-Header zu jeder weitergeleiteten Verbindung hinzu und übergibt die echte Spieler-IP an euren Server.

Was technisch passiert:

1. Ein Spieler verbindet sich mit der geschützten Adresse (MineGuard Filter-IP).
2. Der Filter analysiert den Traffic und filtert Angriffe und Bots heraus.
3. Legitime Verbindungen werden an euren echten Server weitergeleitet.
4. Am Anfang der TCP-Verbindung wird ein PP v2-Header mit IP und Port des Spielers eingefügt.
5. Euer Server (Paper/Velocity) liest den Header und sieht die echte IP.

Die gesamte Kette ist für den Spieler transparent. Er verbindet sich einfach mit einer Adresse und spielt, ohne den Schutz oder das Proxying zu bemerken.

Typische Fehler bei der Einrichtung

Im Laufe der Zeit haben sich bei der Arbeit mit Proxy Protocol im Minecraft-Kontext einige Stolperfallen angesammelt, in die besonders häufig getreten wird.

Fehler 1: MOTD wird nicht angezeigt oder ist fehlerhaft

Wenn ein Minecraft-Client einen Server-List-Ping sendet, um die MOTD abzurufen, stellt er eine normale TCP-Verbindung her. Wenn auf dem Server Proxy Protocol aktiviert ist, aber der MOTD-Request ohne PP-Header kommt (etwa von einem Monitoring-Tool oder direkt), kann der Server das Paket nicht parsen und bricht die Verbindung ab.

Lösung: Stellt sicher, dass alle Verbindungen zum Server über den Proxy laufen, der den PP-Header sendet. Wenn ihr direktes Monitoring braucht, verwendet Tools, die PP-Header senden können, oder überwacht über einen separaten Port ohne PP.

Fehler 2: Doppeltes Proxy Protocol

Ein klassisches Szenario: DDoS-Schutz sendet einen PP-Header an Velocity, Velocity leitet die Verbindung an Paper weiter, und auf Paper ist ebenfalls PP aktiviert. Paper versucht, einen PP-Header aus den Daten zu lesen, die Velocity sendet, findet keinen (weil Velocity sein eigenes Forwarding-Protokoll verwendet) und stürzt ab oder lehnt die Verbindung ab.

Die Regel ist einfach: PP wird nur am ersten empfangenden Glied eurer Infrastruktur aktiviert.

• Velocity vorhanden? PP auf Velocity aktivieren, Paper ohne PP lassen.
• Kein Velocity? PP auf Paper aktivieren.
• Niemals PP auf beiden aktivieren.

Fehler 3: PP auf dem Proxy aktiviert, aber nicht auf dem Server

Der Proxy sendet einen PP-Header, aber der Server erwartet ihn nicht. Der Server versucht, den Header als Beginn eines Minecraft-Handshakes zu interpretieren, kann ihn nicht parsen und lehnt die Verbindung ab. Spieler sehen "Connection refused" oder "Can't connect to server."

Fehler 4: PP auf dem Server aktiviert, aber nicht auf dem Proxy

Die Spiegelsituation. Der Server erwartet einen PP-Header, bekommt aber direkt einen Minecraft-Handshake. Gleiches Ergebnis: Die Verbindung bricht ab.

Fehler 5: Firewall blockiert Ports oder Protokolle

PP funktioniert über normale TCP-Verbindungen, nicht auf einem separaten Port. Aber wenn ihr strenge Firewall-Regeln habt, die nur Verbindungen von bestimmten IPs erlauben, stellt sicher, dass die IP des Proxy-Servers (oder des DDoS-Schutz-Filters) erlaubt ist. Das gilt auch für iptables/nftables-Regeln: Sie müssen Traffic vom Proxy durchlassen.

Funktionalität überprüfen

Nach der Einrichtung solltet ihr sicherstellen, dass alles korrekt funktioniert. Einige Möglichkeiten:

Über Server-Logs

Verbindet euch mit dem Server und prüft die Logs. Wenn in latest.log eure echte IP steht (nicht die des Proxys oder Filters), funktioniert PP.

[Server thread/INFO]: PlayerName[/203.0.113.45:52341] logged in

Wenn stattdessen die Adresse des Proxys erscheint (z. B. eine interne IP eures Schutzdienstes), stimmt etwas in der Konfiguration nicht.

Über Plugins

Ein GeoIP-Plugin oder jedes andere Plugin, das die IP eines Spielers anzeigt, zeigt die echte Adresse, wenn PP richtig konfiguriert ist.

Über Befehle

Auf Paper könnt ihr die IP eines verbundenen Spielers über /whois (wenn das entsprechende Plugin installiert ist) oder über den Essentials-Befehl /seen <player> prüfen.

Sicherheit und Proxy Protocol

Es gibt einen wichtigen Sicherheitsaspekt, über den selten gesprochen wird. Wenn euer Server PP-Header akzeptiert, kann theoretisch jeder, der sich direkt mit dem Server verbindet (am Proxy vorbei), seine IP fälschen, indem er einen gefälschten PP-Header sendet.

Deshalb ist es entscheidend:

1. Direkten Zugriff auf den Server sperren. Erlaubt über die Firewall nur Verbindungen von euren Proxy-/Schutz-IPs. Alles andere muss blockiert werden.

2. Die echte Server-IP nicht veröffentlichen. Wenn ein Angreifer eure echte IP kennt, kann er euch direkt angreifen und den Schutz umgehen. Verwendet in DNS-Einträgen und auf Server-Listing-Seiten nur die Adresse des Schutzdienstes.

3. Konfiguration nach Updates prüfen. Wenn ihr Paper oder Velocity aktualisiert, stellt sicher, dass die PP-Einstellungen nicht auf Standardwerte zurückgesetzt wurden.

Bei der Nutzung von MineGuard kennt nur das Filtersystem die echte IP eures Servers. Spieler sehen ausschließlich die Adresse des Filters, was eine zusätzliche Schutzebene bietet.

Proxy Protocol und BungeeCord

BungeeCord verdient eine separate Erwähnung. Es unterstützt ebenfalls Proxy Protocol, aber der Mechanismus unterscheidet sich etwas von Velocity.

In BungeeCords config.yml:

proxy_protocol: true

Es funktioniert genauso: BungeeCord beginnt, PP-Header aus eingehenden Verbindungen zu lesen.

Wenn ihr allerdings zwischen BungeeCord und Velocity wählt, ist Velocity aus mehreren Gründen vorzuziehen: Es ist schneller, hat bessere Modern-Forwarding-Unterstützung und wird aktiver weiterentwickelt. Proxy Protocol funktioniert auf beiden gleich gut, aber insgesamt ist Velocity die modernere Lösung.

Zusammenfassung

Proxy Protocol ist eine einfache Sache, die ein konkretes Problem löst: den Verlust echter IP-Adressen beim Proxying. Ohne PP verliert ihr die Möglichkeit, per IP zu bannen, Geo-Filterung einzusetzen, ordentliche Analytik zu sammeln und Plugins voll zu nutzen.

Die Einrichtung dauert ein paar Minuten: auf dem Proxy (oder DDoS-Schutz) aktivieren, auf dem empfangenden Server aktivieren, Logs prüfen. Merkt euch drei Regeln:

• PP wird nur an einem Glied der Kette aktiviert.
• Direkter Zugriff auf den Server muss per Firewall gesperrt sein.
• Nach dem Aktivieren von PP funktionieren direkte Verbindungen (ohne Proxy) nicht mehr.

Wenn ihr MineGuard zum Schutz eures Servers nutzt, dauert das Aktivieren von PP v2 genau einen Klick im Panel. Euer Server sieht weiterhin echte Spieler-IPs, und der Schutz filtert weiterhin den Müll-Traffic. Alle sind zufrieden.