BungeeCord network

On a network behind a BungeeCord or Waterfall proxy, AdminControl does what it does behind Velocity: a banned player cannot join the network, and a kick or ban given on one server takes the player off the whole network. Supported: current BungeeCord builds (checked on build 2104, version 26.1) and Waterfall (checked on 1.21 build 615). Other BungeeCord forks are not tested.

What you need

• A current BungeeCord build or Waterfall, on Java 21 or newer.
• A MySQL or MariaDB database shared by the proxy and every server behind it (see Database).
• online_mode: true in BungeeCord's config.yml, or an authentication plugin on a network without premium accounts (below).
• Internet access from the proxy on its first start with AdminControl (below).
• The servers' ports closed to everything but the proxy, or BungeeGuard (see "Securing the servers").

Install

1. Put the same AdminControl.jar in the proxy's plugins/ folder. One jar works on Paper, Purpur, Folia, Spigot, Velocity, BungeeCord and Waterfall.

2. Start the proxy once. BungeeCord reads the libraries list of the plugin and downloads Adventure (the text library AdminControl uses) from Maven Central into its libraries/ folder. AdminControl then creates plugins/AdminControl/config.yml and tries the database in it (localhost, no password): until you set yours, the log says Could not open the shared database and punishments are not checked on the proxy.

3. In plugins/AdminControl/config.yml on the proxy, enter the database every server uses. The keys are the same as on Velocity:

   # en or pl: the ban screen and the replies of /ac on the proxy.
   language: en
   # A name for this proxy in the logs.
   server-name: proxy
   database:
     type: mysql
     mysql:
       host: db.example.com
       port: 3306
       database: admincontrol
       user: admincontrol
       password: "a-long-random-password"
       pool-size: 4
       use-ssl: true
   

4. Every server behind the proxy runs AdminControl with database.type: mysql and the same database.

5. Restart the proxy and run /ac version on its console: it shows Database: mysql, ready when the proxy reaches the database. With database.type: sqlite AdminControl does not start on the proxy and says why in the log.

The proxy has no panel: the panel of any server shows the whole network (see Network panel).

No internet on the first start

Without access to Maven Central, BungeeCord cannot download the libraries and does not load AdminControl (the log shows an error while resolving net.kyori libraries). Start the proxy once with outbound access, or copy the libraries/ folder from a proxy where it worked. Very old BungeeCord builds do not read libraries at all and do not load the plugin: update the proxy.

A copied libraries/ folder is trusted as it is. Check its files against these SHA-256 sums (the same files as on Maven Central) before you start the proxy with them; net/kyori/ in that folder holds them:

Forwarding

Without forwarding, the servers see every player at the proxy's address: IP bans and "other accounts from the same address" stop working, and AdminControl refuses IP bans of such players so it does not lock everyone out.

• BungeeCord, config.yml: ip_forward: true and online_mode: true. With online_mode: false anyone can join through the proxy with a staff member's name and gets their account, their linked panel account included; such a network needs an authentication plugin on the proxy.
• Each server, spigot.yml: settings.bungeecord: true. In server.properties set online-mode=false (the proxy checks the accounts).

Behind a load balancer or a DDoS shield that sends the PROXY protocol, set proxy_protocol: true for the listener in BungeeCord's config.yml, and then let only the shield reach the proxy's port.

Securing the servers

BungeeCord forwarding has no secret. A server with bungeecord: true believes whoever connects to it about the player's name, UUID and address. Anyone who can reach a server's port directly can join as any player, staff included, and dodge every ban. Do one of these:

• Close each server's port to everything but the proxy (a firewall rule, or the servers listening only on a private address).
• Install BungeeGuard on the proxy and on every server: the proxy then sends a token the servers check.

Once the server has started, AdminControl checks whether BungeeGuard is enabled on it (installed but failed to start counts as missing). It does not check BungeeGuard's tokens. A server in BungeeCord mode without an enabled BungeeGuard logs a warning: This server takes player data from a BungeeCord proxy without BungeeGuard. Its panel shows Unsecured forwarding next to the server in the network servers card, or as a warning on the dashboard when it is the only server. The warning stays when the port is closed by a firewall: AdminControl cannot see firewall rules. The server starts either way.

No flag does not mean safe: only servers with AdminControl (from this version on) report their forwarding. The proxy itself, and servers without AdminControl, show nothing.

What happens where

The same as behind Velocity (see Velocity network): bans and IP bans are checked when a player joins the network, a new ban or a kick takes the player off the network, mutes are enforced on the servers, warnings are shown on the server the player is on. If the database is down or the check takes longer than 3 seconds, the proxy decides with the bans it keeps in memory (the log says checked against the in-memory list); only when that list was never read does it let the player in and log letting them in.

Commands on the proxy

The same commands as on Velocity, run on the proxy console or by a player anywhere on the network:

/ac rollback and /ac restore (CoreProtect, admincontrol.rollback) are not proxy commands: CoreProtect runs on the servers, so a player's /ac rollback goes on to the server they are on, and the proxy console does not run them. /ac ban <player> -r <time> on the proxy answers that CoreProtect is not available there; use the panel or a server's console.

Punishment rights are the same as on the servers: the proxy console may do everything; a player needs admincontrol.punish and a linked panel account, and their panel role sets what they may do.

Give admincontrol.command and admincontrol.punish on the proxy with LuckPerms for BungeeCord, which gives them by UUID. The groups section of BungeeCord's config.yml gives them by name: whoever takes a staff member's old name after a name change gets them too. Everything else a player types under /ac (/ac link, /ac report, /ac reload, or a punishment without proxy permissions) goes on to the server the player is on, which checks its own permissions as before. The proxy console runs only the commands above. AdminControl passes such a line on last, after the command filters of other proxy plugins have seen it as typed; only a plugin listening to BungeeCord's chat event at the highest priority sees it as /admincontrol:ac ... (on clients from 1.19), or as a cancelled line (on older clients, whose line AdminControl sends to the server as typed).

Waterfall

Waterfall is set up the same way. PaperMC no longer develops it: its builds only take BungeeCord's updates, so new Minecraft versions arrive on BungeeCord first.

Known limitations

• The same as on Velocity: mutes are not enforced for chat and commands that a plugin on the proxy handles, and tab completion of /ac on the network lists only the proxy commands.