🛡️Setup BungeeGuard+

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


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 any uuid/username they choose.

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

The conventional solution

The conventional solution recommended by the BungeeCord author is to configure a firewall rule using iptables or ufw to prevent outside 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 setup is absolutely perfect, rules are prone to being broken during later changes, or reset on system reboot.

  2. Users on "shared hosting" do not have access to the underlying system and most likely cannot setup their own firewall rules.

The BungeeGuard solution

Server admins 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 etc. server), BungeeGuard+ checks login handshakes to ensure they contain an allowed authentication token.

It's really that simple.


If you have access to the underlying system and are able to setup firewall rules using iptables (or otherwise), it is strongly recommended you that do so. Then, install BungeeGuard as well.

On your proxy server...

If you are using BungeeCord

  1. Ensure 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 multiple proxies in your network, do this for each of them.

  3. Navigate to /plugins/BungeeGuard/token.yml and make a note of the token.

If you are using Velocity

  1. Ensure you are using Velocity 1.1.0 or newer. (There is no need to install BungeeGuard.jar - it is built into Velocity already!)

  2. Set player-info-forwarding-mode to "bungeeguard" in velocity.toml, and make note of the forwarding-secret. This is the value used for the BungeeGuard token. If you have multiple proxies in your network, do this for each of them.

  3. Restart the proxy.

On each of your backend Minecraft servers...

  1. Ensure you are either using Paper 1.9.4+ or have ProtocolLib installed.

  2. Ensure 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 allowed-tokens list.

    # Allowed authentication tokens.  
      - "AUSXEwebkOGVnbihJM8gBS0QUutDzvIG009xoAfo1Huba9pGvhfjrA21r8dWVsa8"

  5. Run bungeeguard reload from console.

Source code

The source code for BungeeGuard is available via GitHub: https://github.com/nickuc/BungeeGuard


The original project is by lucko (https://github.com/lucko/BungeeGuard), licensed under the MIT license.

If you face a problem with the BungeeGuard+, do not open an issue in the original repository, nor report it on the Spigot page. They are different software! Use the nLogin BungeeGuard repository instead.

Last updated