BungeeCord config.yml Explained: Secure Settings

The BungeeCord config.yml defines where the proxy listens, which backends it knows, and where new players are sent. Always generate it with the installed version. Old examples can contain fields or defaults that no longer match the current build.

Valid YAML does not prove a secure network. Once backends use online-mode=false, their TCP ports must reject direct connections. Follow the complete BungeeCord setup guide.

Secure baseline

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

Replace placeholders with panel addresses. Showing a public backend address in a configuration does not mean its port should be public.

Global fields

servers: name each backend

Every key under servers is an internal name. address must be reachable from the proxy process. restricted: true requires bungeecord.server.<name>, but does not block direct network access to the backend port.

Do not use the public proxy domain as a backend address; that can create a loop. Use a concrete internal, private, or otherwise proxy-only address.

listeners: public entry points

host must match the assigned proxy allocation. priorities is the ordered entry and fallback list. A case mismatch such as Lobby versus lobby is enough to leave the proxy without a default target.

With force_default_server: true, new connections start through priorities or forced-host routing. With false, BungeeCord may try to restore a previously used target.

max_players is not player_limit

listeners.*.max_players changes the slot count displayed in the server list. player_limit is the global hard limit. Configure both intentionally; a display value is not a capacity benchmark.

forced_hosts and DNS

forced_hosts maps a requested hostname to an internal server name. DNS still points at BungeeCord. Use the domain and SRV guide for a custom hostname or non-default port.

Do not confuse these settings

• proxy_protocol expects a real HAProxy/PROXY Protocol sender; it is unrelated to ordinary BungeeCord forwarding.
• query_enabled adds a UDP service; do not open it without a use case.
• ping_passthrough exposes a target's MOTD and status, so backend failure can affect the list response.
• restricted is a BungeeCord permission, not a firewall.
• /greload does not reliably reload every plugin and permission change; plan a restart.

Match the backend settings

Set online-mode=false in server.properties and settings.bungeecord: true in spigot.yml. For Paper, proxies.bungee-cord.online-mode must match the proxy's online_mode. Read the secure forwarding guide before changing identity settings and use the backup/clone/rollback workflow in the version-switch guide.

Validation checklist

1. Use spaces, not tabs.
2. Verify indentation and quote strings with special characters.
3. Match every name in priorities and forced_hosts to a key under servers.
4. Fully restart the backends and proxy.
5. Test TCP, Minecraft ping, and a real lobby join separately.
6. Test from an independent source that the backend port is blocked.

If BungeeCord cannot reach the lobby, follow the fallback error guide. Add proxy and backend plugins at the right layer only after this baseline passes.

Primary sources

• Official BungeeCord configuration guide
• Current BungeeCord defaults in source
• Paper global configuration