How to Install and Configure BungeeGuard on a BungeeCord Server Network

BungeeGuard is a security plugin designed to protect Minecraft server networks using BungeeCord or compatible proxies.

When a Minecraft server uses BungeeCord, players normally connect through the proxy before being forwarded to backend servers such as Spigot or Paper. Without proper protection, an attacker may be able to connect directly to a backend server and attempt to spoof information normally provided by the proxy.

BungeeGuard adds an authentication token to the proxy-to-server connection. Backend servers then verify that the connection contains a token belonging to an authorised proxy.

This guide explains how to install and configure BungeeGuard on a BungeeCord network hosted with Beacon Hosting.

[SECURITY] Use the current official BungeeGuard release. BungeeGuard 1.4.0 fixed a security issue affecting BungeeCord proxy installations where the authentication token could be exposed to players on affected setups. If you are upgrading an existing BungeeGuard installation, update the proxy plugin and rotate your authentication token.

What Is BungeeGuard?

BungeeGuard is a Minecraft security plugin that protects BungeeCord backend servers from unauthorised proxy connections and BungeeCord protocol spoofing.

BungeeGuard is installed on both your BungeeCord proxy and the backend Minecraft servers.

The proxy adds a secret authentication token to the connection, while each backend server checks that the token is valid.

This provides an additional layer of protection for networks where backend servers should only accept connections forwarded through an authorised proxy.

BungeeGuard is not a replacement for proper network security. Where possible, backend servers should also be protected with firewall or network-level restrictions.

What You Need Before Installing BungeeGuard

Before starting, you should have:

• A working BungeeCord proxy
• At least one backend Minecraft server
• Spigot, Paper, or another supported Bukkit-based server on the backend
• Access to the /plugins directory on your servers
• Access to your BungeeCord configuration files

The BungeeGuard project requires settings.bungeecord: true in spigot.yml and checks that the backend allowed-tokens configuration contains valid tokens.

For current installations, check the BungeeGuard project's compatibility requirements before deploying it to an unusual or very old server version.

Step 1: Download BungeeGuard

Download BungeeGuard from its official project distribution channels:

BungeeGuard on SpigotMC

The current official release is BungeeGuard 1.4.0.

You need the:

BungeeGuard.jar

file.

Step 2: Install BungeeGuard on Your BungeeCord Proxy

Open your Beacon Hosting control panel and select your BungeeCord proxy server.

Navigate to:

/plugins

Upload:

BungeeGuard.jar

Start or restart your BungeeCord proxy.

After BungeeGuard starts, it will generate its required files inside:

/plugins/BungeeGuard/

Open:

/plugins/BungeeGuard/token.yml

The proxy-generated authentication token is stored here.

Copy the token somewhere secure. You will need it when configuring every backend server connected to this proxy.

Treat the token like a password. Do not publish it or share it with untrusted users.

Step 3: Enable BungeeCord Support on Your Backend Server

Before configuring BungeeGuard, make sure the backend Minecraft server is configured for BungeeCord forwarding.

Open:

spigot.yml

Find:

settings:
  bungeecord: false

Change it to:

settings:
  bungeecord: true

Save the file.

BungeeGuard performs a configuration check for this setting and will not consider the backend correctly configured if it is disabled.

Step 4: Install BungeeGuard on the Backend Server

Install BungeeGuard.jar on every backend Minecraft server that receives connections from your BungeeCord proxy.

Upload:

BungeeGuard.jar

to:

/plugins

Start or restart the backend server once.

BungeeGuard will generate:

/plugins/BungeeGuard/config.yml

Open this file.

You should see an:

allowed-tokens:

section.

Add the token generated by your BungeeCord proxy:

allowed-tokens:
  - "your-generated-token-here"

The official configuration supports multiple authorised tokens, so you can add more than one proxy token if the backend needs to accept connections from multiple trusted proxies.

Important: Remove Default or Example Tokens

If the generated configuration contains example tokens, remove them.

The allowed-tokens list should contain only tokens belonging to proxies you actually trust.

BungeeGuard's own documentation specifically recommends ensuring that this list contains only your authorised tokens.

Step 5: Repeat the Configuration for Every Backend Server

If your network contains multiple Minecraft servers, repeat the backend installation and configuration for each server.

For example:

BungeeCord Proxy
│
├── Survival Server
├── Skyblock Server
├── Minigames Server
└── Lobby Server

Each backend should have:

/plugins/BungeeGuard/

with its BungeeGuard configuration containing the authentication token generated by your authorised proxy.

You do not generate a different proxy token for every backend when they all belong to the same proxy. The backend servers can authorise the same proxy token.

Step 6: Restart the Network

After configuring BungeeGuard on the proxy and every backend, restart the proxy and backend servers.

A full restart is the simplest way to ensure that both sides load the new configuration correctly.

BungeeGuard also provides a reload command on supported installations:

bungeeguard reload

However, restarting the affected servers is generally preferable when initially configuring the plugin because it removes ambiguity about which configuration has been loaded.

Step 7: Test Your BungeeCord Network

Connect to your Minecraft network through the normal BungeeCord proxy address.

If everything is configured correctly, players should be able to connect normally and move between backend servers.

You should also verify that your backend servers are not intended to be publicly accessible directly.

BungeeGuard authenticates proxy-to-backend connections, but it should not be treated as a complete replacement for firewall or network-level security.

Where possible, restrict direct access to backend server ports so that only your authorised proxy can reach them.

BungeeGuard Troubleshooting

Players Cannot Connect After Installing BungeeGuard

Check the following:

• settings.bungeecord: true is enabled in spigot.yml
• BungeeGuard is installed on both the proxy and backend
• The backend allowed-tokens contains the correct proxy token
• The token was copied correctly
• The allowed-tokens list contains no unwanted example tokens
• There are no YAML formatting errors in config.yml
• The backend is running a supported server version
• Any required dependency such as ProtocolLib is installed where applicable
• The proxy and backend have been restarted after configuration

BungeeGuard performs configuration checks before allowing players to connect, including checking the BungeeCord setting and authorised token configuration.

Where Is the BungeeGuard Token?

On the BungeeCord proxy, the generated token is located at:

/plugins/BungeeGuard/token.yml

On each backend server, the token is configured in:

/plugins/BungeeGuard/config.yml

under:

allowed-tokens:

I Updated BungeeGuard. Do I Need to Change the Token?

If you are upgrading an affected BungeeGuard/BungeeCord installation, yes, rotate the token.

BungeeGuard 1.4.0 addressed a vulnerability where the token could be exposed to players on affected BungeeCord setups. The official security notice recommends updating to 1.4.0 or later and rotating tokens.

After generating the new token, replace the old token in the allowed-tokens configuration on every backend server.

Can I Use Multiple BungeeCord Proxies?

Yes.

BungeeGuard supports multiple authentication tokens in the backend allowed-tokens list.

For example:

allowed-tokens:
  - "proxy-one-token"
  - "proxy-two-token"

This allows the backend to accept connections from multiple authorised proxies.

Is BungeeGuard Necessary?

BungeeGuard is strongly recommended for BungeeCord networks where backend servers need protection from unauthorised proxy connections.

The traditional approach is to restrict backend access using firewall rules. Spigot's BungeeCord documentation recommends restricting access to backend servers, while BungeeGuard provides an additional application-level authentication mechanism that is particularly useful on shared hosting where customers may not have access to the underlying firewall.

For the strongest setup, use BungeeGuard together with appropriate firewall or network restrictions rather than relying on either mechanism alone.

Why Use Beacon Hosting for Minecraft Networks?

Beacon Hosting provides Minecraft server hosting with Java and Bedrock support, NVMe storage, DDoS protection, and a web-based control panel.

For Minecraft networks, Beacon's control panel provides tools for managing server files, console access, player management, server configuration, backups, and SFTP across your servers. This can make managing a proxy and multiple backend Minecraft servers easier without requiring direct access to the underlying machine.

Beacon Hosting supports popular Minecraft server software including Vanilla, Paper, Spigot, Purpur, Fabric, Forge, NeoForge, and Quilt, depending on the server's requirements.

Plans start from $1/GB, with an eligible 2-day free trial and no card required.

If you're building a BungeeCord network with a proxy, lobby, survival server, minigames, or other backend servers, Beacon Hosting provides the server hosting and management tools needed to run the individual components of the network.

Start Your Minecraft Server Network With Beacon Hosting