ChunkPodFree beta
Sign in

Tools / Configuration

Waterfall Config Creator

Build config.yml and waterfall.yml for a Waterfall proxy. Waterfall is end-of-life, so the article below also covers moving to Velocity.

Waterfall reads BungeeCord's config.yml plus its own waterfall.yml, both in the proxy folder. Download each one

Listener

The address players connect to and what they see in the server list.

IP and port the proxy listens on. 0.0.0.0:25577 listens on every address; use port 25565 so players can leave the port off

Server list message. Supports & color codes. Also written as the MOTD of each server for forced hosts

Player count shown in the server list. It does not limit joins; Player Limit does

GLOBAL_PING lists every player on the network with their ping, GLOBAL lists them without ping, SERVER shows only players on the same server

Most players shown in the tab list

Show the MOTD and player count of the backend server a player would join instead of the proxy's own

Authentication and Forwarding

How players log in and how the proxy passes their identity to the backend servers.

Check every player with Mojang. Keep this on; the backend servers are the ones that set online-mode=false

Send each player's real IP and UUID to the backend servers. Needs bungeecord: true in each server's spigot.yml

Kick players without a Mojang-signed chat key, as enforce-secure-profile does on a vanilla server

Send the player's IP to Mojang during login, so players whose login came from another IP are rejected

Refuse players sent over from another server with the 1.20.5 transfer packet

Pass the Forge handshake through for legacy Forge (1.12.2 and older) servers

Servers

Every backend server the proxy can send players to. The name is what /server and the priorities list use.

Priorities (Join Order)

Servers players join first, in order. If the first is down or full, BungeeCord tries the next.

Always send joining players to the first priority server instead of the server they were last on

Forced Hosts (Domain Routing)

Send players who connect through a given domain straight to one server, such as skyblock.example.com to skyblock.

No forced hosts. Every player goes to the priorities list.

Groups and Permissions

BungeeCord's built-in permissions. Most networks use LuckPerms instead and leave these as they are.

Give players groups by name. Separate several groups with commas

Proxy commands to turn off, separated by commas, such as find, alert

Limits and Timeouts

Most players allowed on the whole network. -1 means no limit

Window in which one IP can make only a few connections. Set -1 behind TCPShield or HAProxy, where players share a few addresses

Connections one IP may make inside the throttle window

Disconnect players after this long without network activity

How long to wait for a backend server when moving a player to it

How long to wait when pinging a backend server for ping passthrough

How long to reuse a backend server's ping response. -1 turns the cache off

Packets larger than this many bytes are compressed. -1 turns compression off

Query, Logging and Advanced

Read the real player IP from a HAProxy PROXY header. Turn on only behind TCPShield, HAProxy or a similar proxy, or every connection fails

Answer GameSpy4 query requests on the query port

Connect to backend servers from the listener's IP. Leave on unless the machine has several addresses and backends reject one of them

Write every proxy command players run to the log

Log every server list ping. Off keeps the log readable on public networks

config.yml · 59 lines
# Waterfall Configuration (config.yml)
# Generated by ChunkPod Tools - 2026-09-23T14:56:55.663Z

online_mode: true
ip_forward: false
enforce_secure_profile: false
prevent_proxy_connections: false
reject_transfers: false
forge_support: false
player_limit: -1
timeout: 30000
server_connect_timeout: 5000
remote_ping_timeout: 5000
remote_ping_cache: -1
connection_throttle: 4000
connection_throttle_limit: 3
network_compression_threshold: 256
log_commands: false
log_pings: true
disabled_commands: []
listeners:
  - host: '0.0.0.0:25577'
    motd: '&1Another Bungee server'
    max_players: 1
    tab_list: GLOBAL_PING
    tab_size: 60
    priorities:
      - lobby
    force_default_server: false
    forced_hosts: {}
    ping_passthrough: false
    bind_local_address: true
    query_enabled: false
    query_port: 25577
    proxy_protocol: false

servers:
  lobby:
    motd: '&1Another Bungee server'
    address: localhost:25565
    restricted: false

permissions:
  default:
    - bungeecord.command.server
    - bungeecord.command.list
  admin:
    - bungeecord.command.alert
    - bungeecord.command.alertraw
    - bungeecord.command.end
    - bungeecord.command.ip
    - bungeecord.command.reload
    - bungeecord.command.kick
    - bungeecord.command.send
    - bungeecord.command.find
    - bungeecord.command.perms

groups: {}

What is the Waterfall config?

This Waterfall config creator writes both files a Waterfall proxy reads: config.yml, the BungeeCord file with your listeners, servers and IP forwarding, and waterfall.yml, the extra settings Waterfall adds on top. Use the "File" select to switch between them, download each one, and put both in the proxy folder. The rest of this page explains what Waterfall is, what each waterfall.yml setting does, how to set up config.yml for a network, and how to move to Velocity.

Waterfall is end-of-life. PaperMC stopped developing Waterfall in 2024 and recommends Velocity for every network. The existing Waterfall builds still run, but they get no new Minecraft versions, bug fixes or security fixes. If you are building a new network, use the Velocity config builder instead. This tool is for networks that still run Waterfall and need to change a setting before they migrate.

What Waterfall is

Waterfall was PaperMC's fork of BungeeCord, the proxy md_5 wrote to join several Minecraft servers into one network. Players connect to the proxy, and the proxy moves them between backend servers without a disconnect. Waterfall kept BungeeCord's plugin API and its config.yml, so BungeeCord plugins run on it unchanged, and added fixes for stability and abuse on large networks.

That shared history is why this tool has two files:

FileWhere it comes fromWhat it covers
config.ymlBungeeCordListeners, servers, priorities, forced hosts, ip_forward, groups, permissions
waterfall.ymlWaterfallTab-complete throttle, plugin channel limits, packet rewriting, DNS, logging

Both files sit in the Waterfall folder, next to the jar. Waterfall creates them on the first start, and it fills in any key a file leaves out with its default when it starts. That rewrite also drops comments, so keep notes about your changes elsewhere.

config.yml on Waterfall

The config.yml form in this tool is the same one the BungeeCord config creator uses, and the output loads on either proxy. That page explains every key in detail. The short version for a Waterfall network:

  • Listener. Set host to 0.0.0.0:25565 so players can join without typing a port, and set the motd. The MOTD generator previews & color codes before you paste them in.
  • Servers. Add every backend server by name with its host:port. The names are what /server and the priorities list use.
  • Priorities. List the servers new players join, in order. Every name must also be under servers, or Waterfall stops at startup with a "not defined" error. The tool warns you when one is missing.
  • Forced hosts. Map a domain such as skyblock.example.com to one server so players who connect through it skip the lobby.
  • ip_forward. Turn it on, and set bungeecord: true in each backend's spigot.yml with online-mode=false in its server.properties. The spigot.yml generator and server.properties generator write those files.

Because the backend servers run in offline mode and trust the proxy, their ports must not be reachable from the internet. Firewall them so only the proxy can connect, or bind them to 127.0.0.1 when everything runs on one machine.

waterfall.yml settings

waterfall.yml is short. Every key the tool writes is listed here with its default.

Tab completion

code
throttling:
  tab_complete: 1000
disable_modern_tab_limiter: true

throttling.tab_complete is how many milliseconds a player must wait between tab-complete requests. Old clients sent a request for every keystroke, and spamming them was a cheap way to lag a proxy. 0 turns the throttle off.

disable_modern_tab_limiter: true applies that throttle only to clients older than 1.13. Newer clients send tab-complete requests as the player types a command, so throttling them makes command suggestions feel broken. Leave it on unless you only allow 1.13 and newer clients and see abuse.

Plugin channel limits

code
registered_plugin_channels_limit: 128
plugin_channel_name_limit: 128

Clients and mods register plugin message channels with the proxy. These two settings cap how many channels one connection can register and how long a channel name can be. They protect the proxy from clients that register thousands of channels to use up memory. Large modpacks can register more than 128 channels; if Forge or Fabric players get kicked with a message about too many channels, raise registered_plugin_channels_limit to 256 or 512.

Packet rewriting

code
disable_entity_metadata_rewrite: false
disable_tab_list_rewrite: true

When a player switches servers, entity IDs on the new server differ from the ones the client knows, so BungeeCord rewrites them in packets. disable_entity_metadata_rewrite: true skips that rewrite inside entity metadata packets. Some mods need it on; on a plugin network, leave it off, because turning it on can break effects that point at an entity after a server switch, such as a fishing line or a leash.

disable_tab_list_rewrite: true skips rewriting player UUIDs in tab list packets. That rewrite only changes anything when the backend servers see different UUIDs from the real ones, which happens when ip_forward is off. With ip_forward: true, keep the default.

Game version, DNS and logging

code
game_version: ""
use_netty_dns_resolver: true
log_initial_handler_connections: true

game_version is the version text a client sees in the server list when its version is not supported. Empty shows the range the proxy supports. Networks that only allow one version sometimes set it to that version so players know what to install.

use_netty_dns_resolver: true resolves backend server hostnames without blocking a network thread. Keep it on.

log_initial_handler_connections logs a "has connected" line for every ping and login attempt. On a public network listed on server list sites, that is one line per ping, so the Quiet Logs preset turns it off together with log_pings in config.yml.

Recommended values

SettingPlugin networkModded network (Forge or Fabric)Behind TCPShield or HAProxy
ip_forwardtruetruetrue
proxy_protocolfalsefalsetrue
connection_throttle40004000-1
throttling.tab_complete100010001000
registered_plugin_channels_limit128256 or more128
disable_entity_metadata_rewritefalseas your mods needfalse
log_initial_handler_connectionstruetruefalse

Behind TCPShield or HAProxy, every player arrives from a few addresses, so the connection throttle would block real players. Set connection_throttle: -1 there and turn proxy_protocol on, as the Behind TCPShield preset does.

Moving from Waterfall to Velocity

Since Waterfall no longer gets updates, plan the move to Velocity. Most of the work is in the proxy config and the backend forwarding settings; the backend worlds and plugins stay as they are.

  1. Check your proxy plugins. Velocity does not run BungeeCord plugins. Most popular ones (LuckPerms, Geyser, ViaVersion, TAB, LibertyBans, spark) have Velocity builds. Replace the rest or find alternatives before you switch.
  2. Write velocity.toml. The Velocity config builder has the same parts as config.yml: [servers] for your backend list, try for the priorities, and [forced-hosts] for domains. Copy your server names and addresses across.
  3. Switch to modern forwarding. Set player-info-forwarding-mode = "modern" in Velocity. On each Paper backend, set bungeecord: false in spigot.yml and turn on proxies.velocity in paper-global.yml with the secret from Velocity's forwarding.secret. The Paper config generator writes that part. Modern forwarding signs the player data with the secret, so a backend cannot be joined directly even if a port is left open.
  4. Keep legacy forwarding for old backends. Spigot servers, and Paper older than 1.13, cannot use modern forwarding. Velocity's legacy mode works with bungeecord: true, the same way Waterfall did.
  5. Test before you switch the DNS. Run Velocity on another port, join through it, check skins, permissions and server switching, then swap it onto the public port.

Velocity gets support for new Minecraft versions from PaperMC. The Minecraft 1.21.5 notes for server admins cover how proxies handle a new version across backends.

Common mistakes

  1. Running Waterfall for a new network. It will not get new Minecraft versions or security fixes. Start on Velocity.
  2. Backend ports open to the internet. With online-mode=false on the backends, anyone who reaches a backend port can join as any player.
  3. ip_forward set on only one side. ip_forward: true in config.yml needs bungeecord: true in every backend's spigot.yml.
  4. Editing only config.yml. The tab-complete and plugin channel limits live in waterfall.yml. Download both files if you change settings in both.
  5. A priority that is not a server. Waterfall will not start until every name in priorities is under servers.
  6. Turning disable_modern_tab_limiter off without a reason. Command suggestions stop updating as players type.

How to install the generated files

  1. Stop Waterfall with end.
  2. Pick config.yml in the "File" select, set it up, and download it. Then pick waterfall.yml and download that too.
  3. Replace both files in the Waterfall folder. To keep settings this tool does not cover, copy only the keys you changed into your existing files.
  4. Make sure each backend has bungeecord: true in spigot.yml and online-mode=false in server.properties.
  5. Start Waterfall and check the console for YAML errors or "not defined" messages, then join through the proxy and run /server to test switching.

A Waterfall or Velocity proxy needs little memory; 512 MB to 1 GB covers most networks. How much RAM a Minecraft server needs covers the backends, and the JVM arguments generator writes start flags. For managed hosting, check out ChunkPod.

Frequently Asked Questions