BungeeCord's config.yml determines listeners, backend addresses and start priorities. Check keys, indentation and the targets that are actually reachable from the proxy's point of view. An error-free YAML file does not yet protect offline-mode backends from direct access.
A syntactically valid configuration is not yet a secure network. As soon as backends use
online-mode=false, their TCP port must be protected from direct connections. The complete procedure is in the BungeeCord setup pillar.
Secure basic skeleton
online_mode: true
ip_forward: true
player_limit: -1
server_connect_timeout: 5000
remote_ping_timeout: 5000
servers:
lobby:
address: <LOBBY-ADDRESS>:<PORT>
motd: '&aLobby'
restricted: false
survival:
address: <SURVIVAL-ADDRESS>:<PORT>
motd: '&aSurvival'
restricted: false
listeners:
- host: 0.0.0.0:<PROXY-PORT>
motd: '&aMy Network'
priorities:
- lobby
- survival
force_default_server: true
forced_hosts:
survival.example.net: survival
max_players: 100
tab_list: GLOBAL_PING
query_enabled: false
proxy_protocol: false
Placeholders must be replaced with panel addresses. A public backend address in the example is not permission to leave the port publicly open.
Global fields
| Field | Meaning | Safe classification |
|---|---|---|
online_mode |
Authentication at the proxy | true for normal premium networks |
ip_forward |
IP, UUID and profile to the backend | required, but not access control |
player_limit |
Global hard player limit | 0 or less means unlimited |
server_connect_timeout |
Time allowed for the backend connection | too small causes false alarms, too large causes long waits |
remote_ping_timeout |
Timeout for backend pings | A ping is not the same as a real join |
remote_ping_cache |
Cache for backend status | can briefly show an old status |
connection_throttle |
Time window for new connections | not complete bot/DDoS protection |
forge_support |
Additional Forge handshake support | check mod loader compatibility separately |
servers: naming backends
Every key under servers is an internal name. address must be reachable from the proxy process's point of view. restricted: true requires the permission bungeecord.server.<name>, but does not prevent direct network access to the backend port.
Avoid using the same public proxy domain as a backend address: it can create a loop. Use a specific internal, private or otherwise proxy-approved address.
listeners: public entry points
host must match the assigned proxy allocation. priorities is the ordered list for start and fallback. A typo like Lobby instead of lobby is enough for no default target to be found.
force_default_server: true starts new connections via the priorities/forced-host logic. With false, BungeeCord can try to restore a previously used target.
max_players is not player_limit
listeners.*.max_players controls the player count shown in the server list. player_limit is the global hard limit. Set both deliberately; a pretty display does not replace capacity measurement.
forced_hosts and DNS
forced_hosts maps a hostname to an internal server name. DNS still points to BungeeCord. For a domain and a non-standard port, use the domain/SRV guide.
Don't mix up fields
proxy_protocolis for an upstream HAProxy/PROXY protocol sender, not for normal BungeeCord forwarding.query_enabledopens a separate UDP service when needed; don't enable it as a precaution.ping_passthroughtakes over a target's MOTD and status, but makes a backend outage more visible.restrictedis a BungeeCord permission, not a firewall./greloaddoes not reliably reload every plugin and permission change; plan a restart.
Configuring the backend side to match
Set server.properties to online-mode=false and settings.bungeecord: true in spigot.yml. With Paper, proxies.bungee-cord.online-mode must match the proxy's online_mode. Before making a change, read the secure forwarding guide and create a tested backup using the copy/rollback path described in the version change guide.
Validation
- Use only spaces, no tabs.
- Check indentation and strings containing special characters.
- Compare all names in
prioritiesandforced_hostswithservers. - Restart the backend and proxy completely.
- Test TCP, Minecraft ping and a real lobby join separately.
- Test from an independent source that the backend port is blocked.
If BungeeCord can't reach a lobby, the fallback error guide helps. Only after this basic test, install proxy and backend plugins at the right level.
FAQ
Why shouldn't I copy the config.yml from a tutorial?
Because fields and default values change between builds. Let BungeeCord generate the file itself with your installed version and carry over only the values you really want to adjust. A field from an old example may be missing in your build or have a different meaning.
What is the difference between max_players and player_limit?
listeners.*.max_players is display only: the number clients see in the server list. player_limit is the hard global limit above which the proxy rejects connections (0 or less means unlimited). Set both deliberately — a high display value does not replace capacity measurement.
Is restricted: true enough to protect a backend?
No. restricted is a BungeeCord permission and requires bungeecord.server.<name> for switching via the proxy. It doesn't stop anyone from contacting the backend port directly. The protection there is a firewall or private network, not the proxy configuration.
Do I have to restart after a change, or is /greload enough?
Plan a restart. /greload re-reads the configuration, but doesn't reliably carry every plugin and permission change into the running state. For changes to listeners, servers or forwarding, a full restart is the only dependable way.
Why must the proxy domain not be used as a backend address?
Because the proxy would then address itself as the target and a loop arises. Under servers.<name>.address belongs the address at which the proxy process reaches the backend — an internal or private address, not the public name your network's DNS points to.
Primary sources
- Official BungeeCord configuration reference
- Current BungeeCord defaults in the source
- Paper Global Configuration
Checking a routing change without a DNS misjudgment
Compare every listener priority and every forced_hosts target name with an existing key under servers. Then check the backend address from the proxy network; a public domain can point back to the proxy itself. Test the join first via the known proxy address and then via the domain. If only one of the paths works, investigate DNS and host routing separately. Back up the previous config.yml and revert only the target change in question. The backend firewall and forwarding stay active during this test; briefly opening all ports is not a YAML check.
