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, allowing backend servers to verify that connections actually came through an authorised proxy.

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

What Is BungeeGuard?

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

BungeeGuard works by installing the plugin on both your BungeeCord proxy and your backend Minecraft servers.

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

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

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 your backend
• Access to the /plugins directory on your servers
• Access to your BungeeCord configuration files

For current BungeeGuard versions, backend servers should use Paper 1.9.4 or newer, or have ProtocolLib installed. The BungeeGuard installation guide also requires settings.bungeecord: true in spigot.yml.

Step 1: Download BungeeGuard

Download BungeeGuard from the official BungeeGuard GitHub repository or its official SpigotMC resource.

The current BungeeGuard release is available from the project's official distribution channels.

Download the BungeeGuard.jar file.

Do not download plugins from random third-party websites, as modified or malicious plugin files can compromise your Minecraft server.

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.

BungeeGuard will generate its required files inside:

/plugins/BungeeGuard/

After the proxy has started successfully, open:

/plugins/BungeeGuard/token.yml

Your BungeeGuard authentication token will be stored in this file. Copy the token somewhere secure because you will need to add it to every backend server connected to this proxy.

Treat this token like a secret. Do not publish it or share it with untrusted users.

Step 3: Enable BungeeCord Support on Your Backend Server

Before configuring BungeeGuard, make sure your backend Minecraft server is configured to accept BungeeCord forwarding.

Open your backend server's:

spigot.yml

Find:

settings:
  bungeecord: false

Change it to:

settings:
  bungeecord: true

Save the file.

This setting is required for BungeeGuard to operate correctly on supported Bukkit-based backend servers.

Step 4: Install BungeeGuard on Your Backend Servers

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

Upload the plugin to:

/plugins

Start or restart the backend server once.

BungeeGuard will create:

/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"

If you have multiple authorised proxies, you can add multiple tokens to the list.

Important: Remove Default Tokens

If the generated configuration contains example or default tokens, remove them.

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

Step 5: Repeat the Configuration for Every Backend Server

If your network contains multiple Minecraft servers, repeat the previous steps for each backend.

For example:

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

Each backend server should have:

/plugins/BungeeGuard/BungeeGuard.jar
/plugins/BungeeGuard/config.yml

and the allowed-tokens list should contain the authentication token generated by your authorised BungeeCord proxy.

Step 6: Restart Your Minecraft Network

After configuring BungeeGuard, restart your proxy and backend servers.

Alternatively, BungeeGuard provides a reload command for applying configuration changes on supported setups:

bungeeguard reload

The official installation instructions recommend running this command from the server console after configuring the backend token.

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.

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

BungeeGuard provides authentication between your proxy and backend servers, but it should not be treated as a replacement for proper network security.

Where possible, restrict direct access to backend server ports using firewall rules or network-level access controls.

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
• There are no extra spaces or formatting errors in config.yml
• The backend is running a supported server version
• ProtocolLib is installed if required by your server software
• The proxy and backend have been restarted or BungeeGuard has been reloaded

BungeeGuard performs configuration checks when it starts and requires the backend's allowed-tokens configuration to contain valid authorised tokens.

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:

Can I Use Multiple BungeeCord Proxies?

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

This allows a backend server to accept connections from multiple authorised proxies while rejecting connections that do not contain an approved token.

Is BungeeGuard Necessary?

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

The traditional approach to protecting backend servers is to restrict access using firewall rules. BungeeGuard provides an additional application-level authentication mechanism that is particularly useful on shared hosting environments where customers may not have access to the underlying firewall.

For the strongest setup, use BungeeGuard alongside appropriate firewall and network restrictions rather than relying on either mechanism alone.