How to configure a proxy server like BungeeCord or Velocity

Understanding Minecraft Proxy Servers: BungeeCord and Velocity

Configuring a proxy server like BungeeCord or Velocity for Minecraft establishes a central hub that seamlessly connects multiple backend Minecraft servers. This setup allows players to transition effortlessly between various game modes or worlds without ever disconnecting from your network.

Key Mechanics of Proxy Servers

Both BungeeCord and Velocity serve as a crucial “middleman” between players and your individual Minecraft servers. Their primary purpose is to enable multiple servers to operate under a single public IP address, effectively creating a unified network. Within this network, players can move freely between different server types, such as a lobby, a survival world, or various minigames, all while remaining connected to your central proxy.

The architecture of a proxy server network typically requires at least three distinct server instances. One instance is dedicated solely to running the proxy software itself (either BungeeCord or Velocity). The remaining two or more instances function as your backend Minecraft game servers, for example, a welcoming lobby server and other specialized game servers. It’s important to understand that the proxy server itself is not a playable game server; its sole function is to manage and route player connections.

A critical function of these proxies is the secure forwarding of player data, such as IP addresses and UUIDs, to the respective backend servers. However, the methods for achieving this differ significantly between BungeeCord and Velocity:

• BungeeCord: This proxy utilizes an `ip_forward` setting. By default, this method is considered less secure and necessitates additional measures. To prevent direct backend access and mitigate the risk of IP spoofing, server administrators must implement robust firewall rules or deploy a specialized plugin like BungeeGuard.
• Velocity: Velocity employs a more advanced and secure “modern forwarding” method. This technique relies on a cryptographic key, often stored in a secret file, to ensure that only the trusted proxy can communicate with the backend servers. This enhanced security is maintained even if the backend server ports are inadvertently exposed to the internet.

Configuration for these proxies is handled through specific files:

• BungeeCord: Primarily uses `config.yml`, which follows the YAML (YAML Ain’t Markup Language) format.
• Velocity: Uses `velocity.toml`, which is based on the TOML (Tom’s Obvious, Minimal Language) format, designed for ease of configuration compared to YAML.

It’s also important to note that both BungeeCord and Velocity require plugins specifically designed for their respective proxy environments. Standard Spigot or Paper plugins are not compatible with the proxy server itself. However, plugins like LuckPerms can be used for permissions management across the network, and VelocityTools can add utility commands and features.

Finally, for proper integration with the proxy, all backend servers must have their `online-mode` setting configured to `false` within their `server.properties` file. This is because the proxy server takes over the responsibility of authenticating players, ensuring a consistent and secure experience across the network.

Step-by-Step Proxy Server Configuration

1. Prepare Your Servers

• Obtain the necessary server instances: one dedicated to running the proxy software (BungeeCord or Velocity) and at least two additional instances for your backend Minecraft game servers (e.g., a lobby server, a survival server, a minigame server).
• Before proceeding with any configuration changes, ensure that all server instances are completely stopped.

2. Install Proxy Software

• Download the official BungeeCord or Velocity JAR file. Always obtain these files from their respective official sources to ensure authenticity and security.
• Upload the downloaded JAR file to your designated proxy server instance. This server will host the BungeeCord or Velocity software.

3. Initial Proxy Startup

• Start the proxy server once. This initial startup is crucial as it automatically generates the necessary default configuration files. For BungeeCord, this will create `config.yml`, and for Velocity, it will generate `velocity.toml`.
• After the configuration files have been generated, immediately stop the proxy server. This allows you to safely edit the generated files.

4. Configure the Proxy File (config.yml for BungeeCord / velocity.toml for Velocity)

• Network Binding: Locate the `bind` address and port setting. Configure it to your proxy server’s IP address and the desired port, which is commonly `0.0.0.0:25565` by default. This makes the proxy accessible to players.
• IP Forwarding (BungeeCord): For BungeeCord, set `ip_forward: true` in your `config.yml`. This enables the forwarding of player IP addresses to backend servers.
• Player Info Forwarding (Velocity): For Velocity, it is highly recommended to set `player-info-forwarding-mode` to `modern` in your `velocity.toml`. This mode offers superior security and is suitable for Minecraft versions 1.13 and newer.
• Define Backend Servers: Under the `servers` section (BungeeCord) or `[servers]` section (Velocity), meticulously define each of your backend Minecraft servers. For each server, provide a unique name, its internal IP address, and its specific port number.
• Server Priority and Fallback: Specify a `priorities` or `try` list. This list determines the default server players will join upon connecting to your network and establishes the order in which players will be redirected if their target server becomes unavailable.
• Message of the Day (MOTD): Customize the `motd` (message of the day) if you wish to display a specific message to players in the server list.
• Velocity Secret Key: If using Velocity, locate and copy the `forwarding.secret` key from the generated `velocity.toml` file. This key is vital and will be required for configuring your backend servers to communicate securely with the Velocity proxy.

5. Configure Backend Servers

• Disable Online Mode: For every backend server, navigate to its `server.properties` file and set `online-mode=false`. This is critical as the proxy handles player authentication.
• Enable Proxy Support:
  • For Spigot/Paper servers, open `spigot.yml` and set `bungeecord: true`.
  • For Paper servers utilizing Velocity, access `config/paper-global.yml`, enable Velocity support, and paste the `forwarding.secret` key you copied from your Velocity proxy’s `velocity.toml`.
• Velocity Forwarding Mods (if applicable): If your backend servers run non-Paper/Spigot software, such as Fabric or Forge, you may need to install specific forwarding mods. Examples include FabricProxy-Lite for Fabric or PCF for Forge, to ensure proper Velocity integration.
• Secure Backend Ports: To prevent players from bypassing the proxy and connecting directly to your backend servers, implement firewall rules that block external access to their ports. Alternatively, bind your backend servers to the loopback IP address (`127.0.0.1`), making them accessible only from the proxy server on the same machine.

6. Start Servers

• Begin by starting all of your backend Minecraft servers first.
• Once all backend servers are fully operational, then start your proxy server (BungeeCord or Velocity).

7. Test Connection

• Attempt to connect to your Minecraft network using the IP address of your proxy server. Verify that you can join the default server and seamlessly transition between different backend servers.

Important Tips for Proxy Server Management

• Java Version: Ensure that your Velocity proxy server is running on Java 11 or a higher version for optimal performance and compatibility.
• Security (Velocity): Always prioritize using the `modern` forwarding mode. Confirm that the `forwarding.secret` key is precisely configured on both your Velocity proxy and all backend servers to maintain robust network security.
• Security (BungeeCord): For BungeeCord, it is imperative to implement strict firewall rules to restrict direct access to backend server ports. Alternatively, deploy a plugin like BungeeGuard to secure player connections and prevent direct access.
• Server Resources: Allocate sufficient RAM for your proxy and backend servers. BungeeCord typically requires around 1GB of RAM. A hub server might need 2-3GB, while backend game servers will demand more RAM depending on the specific game mode and player count.
• Performance: To minimize latency and ensure a smooth player experience, host your proxy server and all backend servers within the same datacenter or geographical region. Using lightweight lobby servers and pre-loading backend servers can also significantly enhance overall performance.
• Plugins: Only install plugins specifically designed for proxy environments on the proxy server itself. Regular Spigot/Paper server plugins belong exclusively on your backend game servers.
• Dedicated IP: If you have access to a dedicated IP address, it is best practice to assign it directly to your BungeeCord or Velocity proxy server.
• Lobby Server: Always configure a default lobby server that players are automatically directed to upon connecting. Ensure this lobby server is consistently online; if it’s offline, players will be unable to join your network.
• Testing: After completing your setup, thoroughly test all connections and player forwarding functionalities to ensure everything is working as expected.

Common Mistakes to Avoid

• Incorrect online-mode: Failing to set `online-mode=false` on your backend servers is a critical error. This can allow players to bypass your proxy, potentially leading to unauthorized access and player impersonation.
• Misconfigured IP Forwarding: Incorrect settings for `ip_forward` in BungeeCord or `player-info-forwarding-mode` in Velocity can cause various issues, including problems with UUIDs, player skins not loading correctly, or players being unable to connect at all.
• Exposed Backend Ports: Leaving backend server ports open to direct internet access poses a significant security risk, especially when `online-mode=false`. Always secure these ports using firewalls or by binding them to `127.0.0.1`.
• YAML Formatting Errors: BungeeCord’s `config.yml` is highly sensitive to correct indentation and syntax. Even minor formatting errors can prevent the configuration from loading, causing the proxy to malfunction.
• Using Non-Proxy Plugins: Attempting to install and use standard Spigot/Paper plugins directly on the proxy server will not work and can lead to errors or instability.
• Forgetting to Restart: Many configuration changes, particularly those made to `config.yml` or `velocity.toml`, require a full server restart to take effect. Always restart your servers after making changes.
• Ignoring Fallback Servers: Not configuring fallback servers in your `try` list means that if a player’s target server goes offline, they might be completely kicked from the network instead of being seamlessly redirected to another available server.
• High Latency: Hosting your proxy server and backend game servers in geographically distant locations can introduce noticeable lag when players switch between servers, negatively impacting the player experience.