Skip to main content

💂 Configuring BungeeGuard+

In this tutorial, you will learn how to configure BungeeGuard+ on your server.

Download​

⬇️ Click here to download (source: github.com/@nickuc-com)

Introduction​

BungeeCord installations are insecure by default, and require additional firewall rules to be configured (using IPTables or otherwise) to prevent malicious users from bypassing the proxy and connecting using whatever uuid/username they choose.

This is a well-known problem, and over the years many servers (even large ones) have been successfully targeted using this attack.

The conventional solution​

The conventional solution recommended by the author of BungeeCord is to set up a firewall rule using IPTables or UFW to prevent external connections to the backend servers.

However, there are two main problems with this:​

  1. Configuring these firewall rules is complicated, especially for inexperienced users.

    • Even experienced users sometimes make mistakes or overlook things. Unless the configuration is absolutely perfect, the rules are prone to being broken during subsequent changes, or reset on system restart.

  2. Users on "shared hosting" don't have access to the operating system and most likely can't configure their own firewall rules.

The BungeeGuard solution​

Server administrators install BungeeGuard+ (just an ordinary plugin!) on their proxies and backend servers.

  • On the proxy, BungeeGuard+ adds a secret "authentication token" to the login handshake.
  • On the backend (Spigot server, Paper, etc.), BungeeGuard+ checks the login handshakes to ensure that they contain an allowed authentication token.

Installation​

If you have access to the operating system and are able to configure firewall rules using IPTables (or not), it is strongly recommended that you do so. Then install BungeeGuard as well.

On your proxy server...​

If you are using BungeeCord:​

  1. Make sure ip_forward is set to true in BungeeCord's config.yml.
  2. Add BungeeGuard.jar to the plugins folder. Then restart the proxy. If you have several proxies on your network, do this for each one.
  3. Navigate to /plugins/BungeeGuard/token.yml and annotate the token.

If you are using Velocity:​

  1. Make sure you're using Velocity 1.1.0 or later. 🚨 There's no need to install BungeeGuard.jar - it's already built into Velocity!
  2. Set the player-info-forwarding-mode to "bungeeguard" in velocity.toml, and note the forwarding-secret mode. This is the value used for the BungeeGuard token. If you have several proxies on your network, do this for each one.
  3. Restart the proxy.

On each of your backend servers...​

  1. Make sure you are using Paper 1.9.4+ or have ProtocolLib installed.
  2. Make sure the bungeecord setting is set to true in spigot.yml.
  3. Add BungeeGuard.jar to the plugins folder. Then restart the server.
  4. Navigate to /plugins/BungeeGuard/config.yml. Add the token(s) generated by the proxy(ies) to the list of allowed tokens, as in the example below: 
    # Allowed authentication tokens.
    allowed-tokens:
    - "YOUR TOKEN HERE"
  5. Run bungeeguard reload from the console.

Source Code​

The original BungeeGuard project was created by lucko. Do not confuse BungeeGuard with BungeeGuard+.

Support

Need help? Contact our support team if you still have questions.