Set up Waterfall (a BungeeCord Fork) on Debian 10

Introduction

Waterfall is a fork of the well-known BungeeCord proxy suite. Waterfall ships features and performance improvements not found in Spigot, especially for larger playercounts, but most importantly, it includes many security fixes and DoS mitigations which are essential when running a Minecraft network. Compared to BungeeCord, Waterfall does pre-releases for new Minecraft snapshots, which allows you to connect to your server running a snapshot!

1. Install Prerequisites

• Deploy a Vultr Debian 10 cloud server instance.
• Create a sudo user.
• Update the Debian server.

Install the required utilities.

$ sudo apt-get install wget apt-transport-https gnupg
	

Import the AdoptOpenJDK GPG key.

$ wget -qO - https://adoptopenjdk.jfrog.io/adoptopenjdk/api/gpg/key/public | sudo apt-key add -

Configure AdoptOpenJDK's apt repository.

$ echo "deb https://adoptopenjdk.jfrog.io/adoptopenjdk/deb $(cat /etc/os-release | grep UBUNTU_CODENAME | cut -d = -f 2) main" | sudo tee /etc/apt/sources.list.d/adoptopenjdk.list

Refresh the package index.

$ sudo apt-get update

Install AdoptOpenJDK and jq.

$ sudo apt-get install adoptopenjdk-11-hotspot -y
$ sudo apt-get install jq -y
	

2. Install Waterfall

Ensure you are in the home directory of the user you plan to use for Waterfall.

$ cd ~
	

Create a folder for Waterfall and download the latest build. This example downloads Waterfall version 1.16. If you need a different version, replace 1.16 with the version you want to download.

$ mkdir waterfall
$ cd waterfall
$ LATEST_BUILD=$(curl -X GET "https://papermc.io/api/v2/projects/waterfall/versions/1.16" -H  "accept: application/json" | jq '.builds[-1]')
$ curl -o waterfall.jar -X GET "https://papermc.io/api/v2/projects/waterfall/versions/1.16/builds/${LATEST_BUILD}/downloads/waterfall-1.16-${LATEST_BUILD}.jar" -H  "accept: application/java-archive" -JO
	

If you want an older build, look up the available build numbers.

$ curl -X GET "https://papermc.io/api/v2/projects/waterfall/versions/1.16" -H  "accept: application/json"

Replace [BUILD_ID] in the following command with the desired build.

$ curl -o waterfall.jar -X GET "https://papermc.io/api/v2/projects/waterfall/versions/1.16/builds/[BUILD_ID]/downloads/waterfall-1.16-[BUILD_ID].jar" -H  "accept: application/java-archive" -JO
	

3. Start the Proxy

Create a startup script for your server.

$ nano start.sh
	

Paste the following into start.sh. The parameters in -Xms512M -Xmx512M configure Java heapspace for 512 MB of RAM. Change this to the amount of RAM you want to allocate for Waterfall. The operating system requires available RAM as well, please don't assign all available RAM to Waterfall. For example, if the VPS has 2 GB RAM, you might consider setting -Xms512M -Xmx512M.

#!/bin/sh
while true
do
java -Xms512M -Xmx512M -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -jar waterfall.jar
echo "restarting in 10"
sleep 10
done
	

4. Setting up the proxy

Once you have successfully installed Waterfall, it is time to get it working properly. One of the most essential steps is to set your connected server instances (e.g. Spigot, Paper) to run in offline-mode, which can be achieved by modifying server.properties to online-mode: false. In addition, you will need to set connection-throttle to -1 in bukkit.yml and bungeecord: true in your spigot.yml.

To support online-mode UUIDs, name changes, and IP bans, enable ip_forward: true in Waterfall's config.yml. If you don't, serious data inconsistencies will occur. Note: You still need to set online-mode to false in the server.properties files of your servers.

Security Notice:

As your servers will now be running without authentication, this poses a new security risk. Users may connect to your servers directly, under any username they wish to use. Unfortunately for them, this issue can be easily combated by restricting access to these servers.

• Waterfall and servers on the same machine
  Edit the server.properties of each server, so that the server-ip value is set to 127.0.0.1. Keep in mind during testing that the player allow list will be ignored for connections coming from the same host as your proxy!

• Waterfall on a VPS
  You will need to secure your setup by using an IP allowlisting plugin to accept connections only from certain IPs (Waterfall and all regular servers). One such plugin is BungeeGuard, which is recommended over IPWhitelist since IPWhitelist is exploitable if the attacker purchases a proxy server on the same VPS as you.

• BungeeCord and servers on different machines
  In this case, a server firewall is needed to ensure no one can access your backend servers. Another way to protect your backend servers (Spigot, Paper e.g.) is to setup a virtual private network (VPN) between your machines and have your servers listen on addresses only accessible through the VPN. A basic linux VPN software is tinc.

• Adding servers to your Waterfall instance
  You must add new entries for each Minecraft server you wish to link under servers in Waterfall's config.yml, consisting of the address (IP/host), MOTD, and whether or not it is restricted.

Optional: Run the proxy in the background

Install screen.

$ sudo apt-get install screen -y

Open an instance of screen.

$ screen -S "waterfall"

Start your server script.

$ cd ~/waterfall
$ ./start.sh   
	

Troubleshooting

If you encounter issues with your backend servers not connecting to the proxy or want to apply further configuration, check the Waterfall configuration or default Bungee configuration.