Backend-Join-Guard/README.md

BackendJoinGuard

BackendJoinGuard blockiert direkte Joins auf Backend-Servern und erlaubt nur Verbindungen vom Proxy.

Wichtig:

• Dieses Plugin kommt auf jeden Backend-Server.
• Es kommt nicht auf den Proxy.
• Es kann komplett eigenständig genutzt werden.
• Optional kann es seine Regeln zentral von StatusAPI beziehen.

Zweck

BackendJoinGuard verhindert, dass Spieler einen Unterserver direkt betreten und damit den Proxy-Schutz umgehen.

Das Plugin prüft beim Login die Quell-IP des Spielers. Nur erlaubte Proxy-IPs oder CIDR-Netze dürfen durchgelassen werden. Alle anderen Verbindungen werden direkt vor dem Join geblockt.

Betriebsarten

Standalone

BackendJoinGuard nutzt nur seine eigene config.yml. Das ist sinnvoll, wenn du keinen zentralen Sync willst oder das Plugin unabhängig von StatusAPI betreiben möchtest.

StatusAPI Sync

BackendJoinGuard lädt seine Schutzregeln regelmäßig von StatusAPI. Wenn der Sync ausfällt, bleiben die lokalen Werte aus der config.yml als Fallback erhalten.

Installation

1. Die JAR in den plugins-Ordner jedes Backend-Servers kopieren.
2. Server starten, damit die config.yml erzeugt wird.
3. Konfiguration anpassen.
4. Server neu starten oder /backendguard reload ausführen.

Konfiguration

Datei: config.yml

Lokale Guard-Werte

• enforcement-enabled Aktiviert oder deaktiviert den Direktjoin-Schutz.

• log-blocked-attempts Loggt geblockte Direktjoin-Versuche in die Konsole.

• kick-message Nachricht für geblockte Spieler.

• allowed-proxy-ips Liste exakter Proxy-IPs.

• allowed-proxy-cidrs Liste erlaubter Netze im CIDR-Format.

Beispiel:

enforcement-enabled: true
log-blocked-attempts: true
kick-message: "&cBitte verbinde dich nur ueber den Proxy-Server."

allowed-proxy-ips:
  - "127.0.0.1"
  - "::1"
  - "185.123.45.67"

allowed-proxy-cidrs:
  - "10.0.0.0/24"

StatusAPI Sync

Konfigurationsblock:

statusapi-sync:
  enabled: true
  base-url: "http://127.0.0.1:9191"
  endpoint-path: "/network/backendguard/config"
  api-key: "DEIN_SYNC_KEY"
  interval-seconds: 60
  log-sync-errors: true

Bedeutung:

• enabled Aktiviert den zentralen Abruf über StatusAPI.

• base-url Basis-URL deiner StatusAPI auf dem Proxy.

• endpoint-path Standard-Endpunkt für den Guard-Sync.

• api-key Optionaler Schutz für den Sync-Endpunkt. Muss identisch zu backendguard.sync.api_key in StatusAPI sein.

• interval-seconds Wie oft BackendJoinGuard die Regeln neu abruft.

• log-sync-errors Loggt Sync-Probleme in die Backend-Konsole.

Passende StatusAPI-Konfiguration

Wenn du den Sync-Modus nutzen willst, pflegst du die zentralen Werte in StatusAPI über network-guard.properties.

Relevante Schlüssel:

backendguard.enforcement_enabled=true
backendguard.log_blocked_attempts=true
backendguard.kick_message=&cBitte verbinde dich nur ueber den Proxy-Server.
backendguard.allowed_proxy_ips=127.0.0.1,::1,185.123.45.67
backendguard.allowed_proxy_cidrs=10.0.0.0/24
backendguard.sync.api_key=DEIN_SYNC_KEY

Beispiele

Alles auf einer Maschine

Nutze in der Regel:

• allowed-proxy-ips: 127.0.0.1, ::1
• base-url: http://127.0.0.1:9191

Proxy auf einem anderen Host

Nutze die echte Proxy-IP:

• allowed-proxy-ips: 185.123.45.67
• base-url: http://185.123.45.67:9191

Internes Netzwerk

Nutze interne IP oder CIDR:

• allowed-proxy-ips: 10.0.0.10
• allowed-proxy-cidrs: 10.0.0.0/24
• base-url: http://10.0.0.10:9191

Befehl

Command	Beschreibung
/backendguard reload	Lädt die Config neu und startet bei aktivem Sync sofort einen neuen Abruf

Permission

Permission	Beschreibung
backendguard.admin	Darf BackendJoinGuard verwalten

Funktionsweise

BackendJoinGuard prüft beim PreLogin die IP-Adresse des Clients.

• Erlaubte Proxy-IP: Join erlaubt
• Erlaubtes CIDR-Netz: Join erlaubt
• Alles andere: Join wird direkt geblockt

Troubleshooting

Spieler werden trotz Proxy geblockt

• Prüfe, ob wirklich die Proxy-IP in allowed-proxy-ips eingetragen ist.
• Prüfe bei mehreren Netzsegmenten, ob ein CIDR-Eintrag sinnvoller ist.
• Prüfe, ob Velocity/Bungee korrekt als vorgeschalteter Proxy arbeitet.

Sync mit StatusAPI funktioniert nicht

• Prüfe base-url.
• Prüfe, ob StatusAPI auf dem konfigurierten Port erreichbar ist.
• Prüfe, ob api-key identisch zu backendguard.sync.api_key ist.
• Prüfe die Backend-Konsole bei aktiviertem log-sync-errors.

Standalone oder Sync?

• Wenn du maximale Einfachheit willst: Standalone.
• Wenn du zentrale Verwaltung willst: StatusAPI Sync.
• Wenn StatusAPI ausfällt, bleiben im Sync-Modus die lokalen Werte als Absicherung bestehen.