> ## Content Index
> Fetch the complete content index at: https://blog.sudowl.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# BungeeCord config.yml — Every Option Explained
- URL: https://blog.sudowl.com/bungeecord-config-yml-explained/
- Published: 2026-04-29T10:00:00.000Z
- Updated: 2026-10-11T10:16:27.000Z
- Description: Full breakdown of BungeeCord's config.yml — listeners, servers, IP forwarding, priorities, the options nobody documents and the ones that bite you.
- Author: Lukas
- Tags: Minecraft, Gameserver, Linux

Ran a BungeeCord network for a couple of years. The config file is short — maybe 60 lines — but half the keys aren't documented anywhere obvious, and the defaults are wrong for most setups.

**TL;DR — minimum viable config:**

```yaml
listeners:
- host: 0.0.0.0:25565
  proxy_protocol: false
  forced_hosts:
    pvp.example.com: pvp
  priorities:
  - lobby
  query_enabled: false
servers:
  lobby:
    address: 127.0.0.1:25566
    restricted: false
  pvp:
    address: 127.0.0.1:25567
    restricted: false
ip_forward: true
online_mode: true

```

Set `ip_forward: true`, set every backend server's `online-mode=false` in their own `server.properties`, and you're 80% there. Rest of this post is what the other 20% does.

If you haven't set up the proxy itself yet, start with the [BungeeCord / Waterfall network setup guide](/minecraft-bungeecord-network-setup/) — this post assumes the proxy is already running.

## listeners

You can have multiple listeners on different ports. 99% of setups have exactly one. The interesting fields:

```yaml
listeners:
- host: 0.0.0.0:25565
  query_port: 25577
  motd: '&6Welcome to the network'
  tab_list: GLOBAL_PING
  max_players: 200
  proxy_protocol: false
  forced_hosts:
    pvp.example.com: pvp
    creative.example.com: creative
  priorities:
  - lobby
  - lobby2
  bind_local_address: true
  ping_passthrough: false
  query_enabled: false
  force_default_server: false

```

**`host`** — bind address. `0.0.0.0:25565` for IPv4, `[::]:25565` for dual-stack. If you're behind a reverse proxy or firewall, you can bind to `127.0.0.1` and only expose via the proxy.

**`forced_hosts`** — domain → backend server mapping. Player connecting to `pvp.example.com:25565` lands on `pvp` directly, skipping the lobby. Set the DNS A record to the proxy IP. Free traffic-routing.

**`priorities`** — fallback chain when a player joins. First entry the proxy can reach gets the connection. List your lobby servers here, in order. If the first one's down, second takes over. Player never sees the failure.

**`tab_list: GLOBAL_PING`** — tab list shows everyone on the network with real ping. `GLOBAL` (no ping) is faster but less useful. `SERVER` shows only the current backend.

**`ping_passthrough: false`** — when `false`, server list ping shows the proxy's MOTD and player count (sum of all backends). When `true`, it forwards the ping to whatever's first in `priorities`. I leave it `false` — I want the network MOTD, not the lobby's.

**`force_default_server: true`** — every login goes through the priority chain, even reconnects. Default `false` means players reconnect to wherever they were when they disconnected. Set `true` if you want everyone to always start at the lobby.

**`proxy_protocol: true`** — only enable if you're behind HAProxy / nginx with PROXY protocol. Otherwise BungeeCord rejects connections because the handshake bytes are wrong.

## servers

```yaml
servers:
  lobby:
    address: 127.0.0.1:25566
    motd: '&6Lobby'
    restricted: false
  pvp:
    address: 127.0.0.1:25567
    motd: '&cPvP arena'
    restricted: true

```

**`address`** — IP:port of the backend. If the backends are on the same box (they should be), use `127.0.0.1` — saves a network hop and avoids exposing the backend ports publicly.

**`restricted: true`** — players need the `bungeecord.server.<name>` permission to use `/server pvp`. Useful for staff-only servers.

The server name (the YAML key, e.g. `lobby`) is what `/server <name>` uses and what `forced_hosts` references. Keep it short.

## ip\_forward

```yaml
ip_forward: true

```

This is the one that catches everyone. When `true`, BungeeCord rewrites the handshake to include the player's real IP and UUID, and the backend trusts it. When `false`, every player on every backend appears with the proxy's IP — bans don't work, plugins like CoreProtect log everything as `127.0.0.1`.

But: `ip_forward: true` only works if the backend has `online-mode=false` in `server.properties` AND nothing else can connect to that backend's port. Bind backend ports to `127.0.0.1` only. UFW rule:

```bash
sudo ufw deny 25566:25600/tcp

```

If a backend port is publicly reachable AND `online-mode=false`, anyone on the internet can connect as any username. Free op for whoever finds it.

[UFW rules reference](/ufw-firewall-rules-ubuntu/).

## online\_mode

```yaml
online_mode: true

```

This is the proxy's setting. `true` means the proxy authenticates players against Mojang. Should always be `true` for a public server. The backends are `online-mode=false` because they trust the proxy — that's the whole IP-forwarding contract.

## groups and permissions

```yaml
groups:
  md_5:
  - admin
permissions:
  default:
  - bungeecord.command.server
  - bungeecord.command.list
  admin:
  - bungeecord.command.alert
  - bungeecord.command.end
  - bungeecord.command.find
  - bungeecord.command.ip
  - bungeecord.command.reload
  - bungeecord.command.send

```

Built-in permissions system. `default` applies to everyone, named groups (e.g. `admin`) apply to listed players. `groups` maps player name → group names.

For anything bigger than 5 admins, install LuckPerms-Bungee instead. The built-in system has no inheritance, no wildcards, and reloads only via `/bungee` — fine for a quick test, painful at scale.

## connection\_throttle

```yaml
connection_throttle: 4000
connection_throttle_limit: 3

```

Per-IP rate limit. `connection_throttle: 4000` \= 4 seconds. Same IP making more than `connection_throttle_limit` connections in that window gets a temporary block. Default 3 is fine for a small server. Bigger networks with NAT'd schools / dorms need 10+ or you'll lock out half the players when the bell rings.

## stats

```yaml
stats: a-uuid-string

```

Anonymous metrics for the BungeeCord project. Auto-generated. You can leave it. Setting `disable_entity_metrics: true` only matters for old plugins, ignore it.

## remote\_ping\_cache

```yaml
remote_ping_cache: -1

```

How long (ms) BungeeCord caches backend ping responses. `-1` \= forever (until backend reconnects). `5000` \= 5 seconds. Useful if your network gets hammered by ping bots — caching means backends don't see the load. Default is `-1`, which is fine.

## Full annotated config I actually run

```yaml
player_limit: -1
ip_forward: true
permissions:
  default:
  - bungeecord.command.server
  - bungeecord.command.list
  admin:
  - bungeecord.command.alert
  - bungeecord.command.end
  - bungeecord.command.find
  - bungeecord.command.ip
  - bungeecord.command.reload
  - bungeecord.command.send
  - bungeecord.command.kick
groups:
  Lukas:
  - admin
timeout: 30000
connection_throttle: 4000
connection_throttle_limit: 3
servers:
  lobby:
    motd: '&6Welcome'
    address: 127.0.0.1:25566
    restricted: false
  survival:
    motd: '&aSurvival'
    address: 127.0.0.1:25567
    restricted: false
  creative:
    motd: '&bCreative'
    address: 127.0.0.1:25568
    restricted: false
listeners:
- host: 0.0.0.0:25565
  motd: '&6&lThe Network &7- &fpick a world'
  max_players: 100
  priorities:
  - lobby
  forced_hosts:
    survival.example.com: survival
    creative.example.com: creative
  query_enabled: false
  ping_passthrough: false
  proxy_protocol: false
  tab_list: GLOBAL_PING
disabled_commands:
- disabledcommandhere
network_compression_threshold: 256
online_mode: true
log_commands: false
forge_support: false

```

## Gotchas

- Editing `config.yml` while the proxy is running: BungeeCord overwrites your file when it shuts down. Stop the proxy before editing, or run `/bungee` to reload — but reload doesn't pick up listener changes, only servers and permissions. For listener changes, full restart.
- YAML indentation is 2 spaces. Tabs break the parser silently — proxy starts with a default config and you wonder where your servers went.
- `forge_support: true` only matters if backends run Forge with FML. For vanilla / Paper / Fabric, leave it `false`.
- `network_compression_threshold` on the proxy and the backends should match. Mismatch = slow connections, not broken ones, so you might not notice for weeks.
- The proxy doesn't validate that backends have `online-mode=false`. It just rewrites the handshake. If a backend is online-mode `true`, players get kicked with "bad login" and the cause isn't obvious.

## Picking the right proxy

Whether you actually want BungeeCord or its fork Waterfall is a different question — see [Waterfall vs BungeeCord](/waterfall-vs-bungeecord-minecraft-proxy/). The config syntax is identical between them, so this post applies to both.

## Backing up

`config.yml` lives next to the JAR. Back up the whole proxy directory nightly:

```bash
rsync -a --delete /opt/bungeecord/ /backup/bungeecord/$(date +%F)/

```

Pattern from [rsync backups on Linux](/rsync-backup-linux/). The config is small but losing it means rebuilding the network mapping from memory, which is no fun on a Friday night.

---

### Related posts

- [Velocity Minecraft Proxy — Setup From Scratch in 10 Minutes](https://blog.diengdoh.com/velocity-minecraft-proxy-setup-from-scratch/?ref=blog.sudowl.com)
- [BungeeCord / Waterfall Setup — Running a Minecraft Server Network](https://blog.diengdoh.com/minecraft-bungeecord-network-setup/?ref=blog.sudowl.com)
- [Minecraft Java Server on Linux — Paper, systemd, and Memory Tuning](https://blog.diengdoh.com/minecraft-java-server-linux/?ref=blog.sudowl.com)