Building a Modded Minecraft Network: Velocity Proxy with Fabric and Forge

Managing multiple Minecraft servers, especially when they're modded, can quickly become a complex endeavor. Players expect a seamless experience, moving between different game modes or modpacks without needing to re-authenticate or manually connect to a new IP address. This is where a robust proxy solution becomes indispensable. While BungeeCord has been a long-standing choice, its limitations with modern Minecraft versions and modded environments often lead to frustration.

Velocity emerges as a superior, high-performance, and flexible proxy for modern Minecraft networks. Built from the ground up to handle the intricacies of modern Minecraft protocol forwarding, it offers significant advantages for modded setups, including proper UUID and IP forwarding, essential for plugins and server-side authentication. For anyone running a distributed Minecraft network, especially those offering a variety of Fabric and Forge experiences, Velocity is the pragmatic choice.

This article will guide you through the process of establishing a secure and functional Velocity network for both Fabric and Forge backend servers. We'll cover the core concepts, step-by-step configuration of Velocity itself, and the necessary adjustments on your Fabric and Forge instances to ensure proper integration. By the end, you'll have a unified entry point for your players, allowing them to traverse your diverse modded server landscape with ease, all while maintaining crucial player data across the network.

Understanding the Architecture: Velocity and Server Forwarding

Before diving into configuration, it's crucial to grasp the fundamental architecture. A Velocity network operates on a client-server-backend model:

1. Client connects to the Velocity Proxy.
2. Velocity Proxy authenticates the client and forwards them to a designated Backend Server (Fabric, Forge, Spigot, Paper, etc.).
3. Backend Server communicates with Velocity, trusting its forwarded player data (UUID, IP address).

The key to this trust relationship is a secure forwarding mechanism. Velocity uses a modern forwarding protocol (often referred to as "modern forwarding" or "Velocity forwarding") that relies on a shared secret key. This prevents malicious actors from bypassing your proxy and spoofing player identities directly on your backend servers. Unlike older BungeeCord forwarding, Velocity's method is more robust and less prone to spoofing.

Prerequisites:

• Dedicated Server or VPS: Sufficient resources for Velocity and your backend servers. Consider a robust Minecraft server hosting solution or a powerful bare metal setup.
• Java Runtime Environment (JRE) 17 or higher: Required for Velocity and modern Minecraft servers.
• Separate Server Instances: Each backend server (Fabric, Forge) should run in its own directory and ideally on its own unique internal IP/port combination.
• Network Configuration: Understanding of firewall rules (UFW, firewalld, iptables) and port forwarding.
• FabricProxy-Lite (for Fabric): A plugin for Fabric servers to enable Velocity forwarding.
• ModernForwarder (for Forge/Mohist): A mod for Forge/Mohist servers to enable Velocity forwarding.

Setting Up the Velocity Proxy Server

First, we need to set up the Velocity proxy itself. This will be the public-facing entry point for your players.

1. Download Velocity

Navigate to the Velocity downloads page (e.g., PaperMC's downloads for Velocity) and grab the latest stable JAR file. Create a dedicated directory for your Velocity instance.

mkdir ~/velocity_proxy
cd ~/velocity_proxy
wget https://papermc.io/api/v2/projects/velocity/versions/LATEST_VERSION/builds/LATEST_BUILD/downloads/velocity-LATEST_VERSION-LATEST_BUILD.jar -O velocity.jar

Replace LATEST_VERSION and LATEST_BUILD with the actual latest values. For instance, it might look like velocity-3.2.0-SNAPSHOT.jar.

2. Initial Velocity Configuration

Run Velocity once to generate the default configuration files:

java -Xms512M -Xmx1G -jar velocity.jar

This will create a velocity.toml file in your directory. Now, open velocity.toml for editing:

# velocity.toml

# The public-facing address Velocity will bind to. 
bind = "0.0.0.0:25565"

# The secret key for modern forwarding. GENERATE A STRONG, UNIQUE KEY.
# This key MUST be identical on ALL backend servers.
forwarding-secret = "YOUR_SUPER_SECRET_KEY_HERE"

# Configure player info forwarding. MUST be set to 'modern' for modded servers.
player-info-forwarding-mode = "modern"

# List of backend servers. The first server in the list is the default.
[servers]
  lobby = "127.0.0.1:25566"
  modded_fabric = "127.0.0.1:25567"
  modded_forge = "127.0.0.1:25568"

# Default server to connect to when a player joins.
default-servers = ["lobby"]

# What to do if the default server is unavailable.
fallback-servers = ["lobby"]

# Set to true to enable BungeeGuard support (optional, for BungeeCord plugins).
bungeeguard = false

# ... other settings (motd, compression, etc. - adjust as needed)

Crucial points in velocity.toml:

• bind: The IP address and port Velocity listens on. 0.0.0.0:25565 is standard for public access on the default Minecraft port.
• forwarding-secret: GENERATE A STRONG, UNIQUE KEY. This is paramount for security. Use a tool like pwgen -s 64 1 to generate a long, random string. This key must be identical across Velocity and all your backend servers.
• player-info-forwarding-mode = "modern": This is essential for modded servers to correctly forward player UUIDs and IP addresses. Do not use legacy or bungeecord.
• [servers]: Define your backend servers here. The name (e.g., lobby, modded_fabric) is what you'll use in commands like /server. The IP and port are where Velocity will attempt to connect to them. Use internal IPs if servers are on the same machine or private network.
• default-servers: The server players land on when they first connect.

3. Firewall Configuration for Velocity

Ensure your server's firewall allows inbound connections to the Velocity bind port (e.g., 25565/TCP).

sudo ufw allow 25565/tcp
sudo ufw reload

For more complex setups, you might consider isolating your backend servers on internal networks or specific ports only accessible by the Velocity proxy. This is a critical security measure to prevent direct connections to your backend servers, which would bypass your proxy's authentication and potentially allow spoofing.

Configuring Backend Fabric Servers for Velocity

For your Fabric backend servers, you'll need a specific mod to handle Velocity's modern forwarding protocol: FabricProxy-Lite.

1. Install FabricProxy-Lite

Download the latest FabricProxy-Lite JAR from its Modrinth or CurseForge page and place it in the mods directory of each Fabric server you intend to connect to Velocity.

# Example for a Fabric server directory
cd ~/minecraft_servers/fabric_lobby
wget https://modrinth.com/mod/fabricproxy-lite/version/LATEST_VERSION/download -O mods/fabricproxy-lite-LATEST_VERSION.jar

2. Configure FabricProxy-Lite

Run your Fabric server once with FabricProxy-Lite installed. This will generate a fabricproxy-lite.toml file in your server's config directory.

Open config/fabricproxy-lite.toml and make the following changes:

# fabricproxy-lite.toml

# The secret key. MUST match the 'forwarding-secret' in velocity.toml.
secret = "YOUR_SUPER_SECRET_KEY_HERE"

# Set to true to enable Velocity forwarding.
enabled = true

# Optional: Customize the disconnect message for invalid connections.
disconnect-message = "Invalid proxy connection or secret mismatch!"

Key configuration points:

• secret: This MUST be the exact same secret key you set in your velocity.toml.
• enabled = true: Ensures the mod is active.

3. Adjust server.properties

On your Fabric backend server, open server.properties and ensure the following:

# server.properties

online-mode=false
server-port=25566 # Use a unique port for each backend server

Why online-mode=false? Velocity handles player authentication. If your backend servers also try to authenticate players, it will cause conflicts and disconnections. The backend servers trust Velocity's authentication.

4. Firewall for Fabric Backend

Crucially, your backend Fabric servers should NOT be directly accessible from the internet. They should only accept connections from your Velocity proxy's IP address.

# Assuming Velocity is on the same machine, allowing localhost connections
sudo ufw allow from 127.0.0.1 to any port 25566
# If Velocity is on a different machine, replace 127.0.0.1 with Velocity's IP
# sudo ufw allow from YOUR_VELOCITY_IP to any port 25566
sudo ufw deny 25566/tcp # Deny all other external connections to this port
sudo ufw reload

Configuring Backend Forge/Mohist Servers for Velocity

For Forge or Mohist (a hybrid Forge/Paper server), you'll need a different mod to handle Velocity forwarding, such as ModernForwarder or VelocityUtilities.

1. Install ModernForwarder

Download the latest ModernForwarder JAR from its CurseForge page and place it in the mods directory of each Forge/Mohist server.

# Example for a Forge server directory
cd ~/minecraft_servers/forge_modpack
wget https://www.curseforge.com/minecraft/mc-mods/modernforwarder/download/LATEST_FILE_ID/file -O mods/modernforwarder-LATEST_VERSION.jar

2. Configure ModernForwarder

Run your Forge server once with ModernForwarder installed. This will generate a modernforwarder.conf file in your server's config directory.

Open config/modernforwarder.conf and make the following changes:

# modernforwarder.conf

# The secret key. MUST match the 'forwarding-secret' in velocity.toml.
secret = "YOUR_SUPER_SECRET_KEY_HERE"

# Ensure forwarding is enabled.
enabled = true

Similar to FabricProxy-Lite, the secret here must exactly match your Velocity proxy's forwarding-secret.

3. Adjust server.properties

On your Forge/Mohist backend server, open server.properties and ensure the following:

# server.properties

online-mode=false
server-port=25568 # Use a unique port for each backend server

4. Firewall for Forge Backend

Again, ensure your Forge backend servers are not directly accessible from the internet. They should only accept connections from your Velocity proxy's IP address.

# Assuming Velocity is on the same machine, allowing localhost connections
sudo ufw allow from 127.0.0.1 to any port 25568
# If Velocity is on a different machine, replace 127.0.0.1 with Velocity's IP
# sudo ufw allow from YOUR_VELOCITY_IP to any port 25568
sudo ufw deny 25568/tcp # Deny all other external connections to this port
sudo ufw reload

Security, Performance, and Troubleshooting

Security Considerations

• Strong Forwarding Secret: This is your first line of defense against IP spoofing. Generate a long, random alphanumeric string and keep it confidential.
• Firewall Backend Servers: This cannot be stressed enough. Your backend servers should NEVER be directly accessible from the internet. Only allow connections from your Velocity proxy's IP address.
• DDoS Protection: Your Velocity proxy, being the public-facing component, will be the target of any network attacks. Ensure your game server infrastructure or hosting provider offers robust DDoS protection.
• Regular Updates: Keep Velocity, FabricProxy-Lite, ModernForwarder, and your server jars updated to patch known vulnerabilities.

Performance Tuning

• Velocity Resources: While Velocity is lightweight, it still requires CPU and RAM. Allocate sufficient resources, especially if you anticipate many concurrent players. A minimum of 1GB RAM for Velocity itself is a good starting point.
• Java Flags: For both Velocity and your backend servers, consider optimizing Java Virtual Machine (JVM) arguments. Common flags include -Xms and -Xmx for heap size, and garbage collector tuning flags like -XX:+UseG1GC. For more in-depth tuning, consider reading up on Optimisation de vos ressources.
• Network Bandwidth: Ensure your server's network uplink can handle the aggregate traffic of all players across all backend servers.

Troubleshooting Common Issues

• "Disconnected: You are not authorized to connect to this server." (or similar):
  • Cause: Mismatched forwarding secret between Velocity and a backend server.
  • Fix: Double-check that the forwarding-secret in velocity.toml and the secret in fabricproxy-lite.toml/modernforwarder.conf are identical. Copy-paste to avoid typos.
• "Disconnected: This server is in online mode." or similar authentication errors:
  • Cause: A backend server still has online-mode=true in server.properties.
  • Fix: Set online-mode=false in server.properties for ALL backend servers.
• Cannot connect to backend server (Velocity logs show connection refused/timeout):
  • Cause: Firewall blocking connections, incorrect IP/port in velocity.toml, or backend server not running.
  • Fix: Verify backend server is running. Check firewall rules on the backend server to ensure it allows connections from Velocity's IP on its specified port. Confirm the IP and port in velocity.toml are correct and match the backend server's server-port.
• Players are unable to see their skins or UUID-related issues:
  • Cause: player-info-forwarding-mode is not set to modern in velocity.toml, or a forwarding mod/plugin is missing/misconfigured on a backend server.
  • Fix: Ensure player-info-forwarding-mode = "modern" in velocity.toml. Confirm FabricProxy-Lite or ModernForwarder is installed and correctly configured on the respective backend servers.

Conclusion

By following these steps, you've established a robust and secure Velocity network capable of handling both Fabric and Forge modded Minecraft servers. Players now have a single entry point to your diverse server ecosystem, benefiting from seamless transitions and proper player data forwarding. This architecture not only enhances the player experience but also provides a solid foundation for scaling your Minecraft network and implementing advanced features, all while maintaining critical security measures against common vulnerabilities.

FAQ

Why use Velocity instead of BungeeCord for modded servers?

Velocity uses a more modern and secure forwarding protocol compared to BungeeCord's legacy forwarding. BungeeCord often struggles with modded clients and servers, leading to issues with UUIDs, IP forwarding, and general compatibility. Velocity is designed from the ground up for modern Minecraft versions and handles modded environments much more gracefully, ensuring player data is correctly passed to backend servers.

Do I need to run all servers on the same machine?

No, you do not. While running them on the same machine (using localhost IP addresses like 127.0.0.1 for backend servers) simplifies internal networking, Velocity is designed to proxy across multiple physical or virtual machines. If your backend servers are on different machines, simply use their respective internal IP addresses (or public IPs if they are on separate public networks, though internal IPs are preferred for security and latency) in your velocity.toml configuration.

How do I add more backend servers to my Velocity network?

To add more backend servers, you need to perform three main steps: First, ensure the new backend server has a unique internal port (e.g., 25569). Second, install and configure the appropriate forwarding mod (FabricProxy-Lite or ModernForwarder) on the new server, making sure its secret key matches Velocity's. Third, add an entry for the new server in the [servers] section of your Velocity's velocity.toml file. Don't forget to restart Velocity and the new backend server after making these changes, and adjust your firewall rules.

What is the purpose of setting online-mode=false on backend servers?

Setting online-mode=false on your backend servers is critical because Velocity handles the initial player authentication with Mojang's services. If backend servers also attempt to authenticate players, it creates a conflict: the player has already been authenticated by Velocity, and the backend server will see them as unauthenticated or attempting a duplicate authentication. By disabling online-mode on the backends, you instruct them to trust the player data (UUID, IP) forwarded by the Velocity proxy, which has already performed the necessary authentication.

Can I mix Fabric and Forge servers on the same Velocity network?

Yes, absolutely. One of Velocity's strengths is its ability to proxy different types of Minecraft servers. As demonstrated in this guide, you simply need to install the correct forwarding mod (FabricProxy-Lite for Fabric, ModernForwarder for Forge) on each respective backend server and ensure they all share the same forwarding-secret with your Velocity proxy. Players can then seamlessly switch between your Fabric and Forge servers using Velocity's /server command, provided the client has the necessary mods for the target server.