Configure Velocity Forwarding on Paper

When running backend servers behind a Velocity proxy, it's essential to correctly configure player information forwarding. This ensures that player UUIDs, skins, and IP addresses are passed from the proxy to the server, allowing plugins to function correctly and maintaining online-mode security. This guide will walk you through setting up modern Velocity forwarding on your PaperMC (or Paper-fork) server.

Prerequisites

Before you begin, ensure you have the following:

• A server running Paper (or a fork like Purpur) version 1.14 or newer.
• A Velocity proxy that is already configured to connect to your Paper server.
• You have already generated a secure forwarding secret in your Velocity proxy's velocity.toml file.

How to Configure Velocity Forwarding

Follow these three steps on each backend Paper server you want to connect to your Velocity proxy.

1. Disable Online Mode in server.properties:

   Your Velocity proxy will handle player authentication, so the backend server must be in offline mode to accept the forwarded connection. Navigate to your Server Properties file.

   • Find the online-mode setting.
   • Set it to false.

   online-mode=false

   
2. Disable BungeeCord Support in spigot.yml:

   To use Velocity's modern forwarding, you must disable the legacy BungeeCord forwarding protocol to prevent conflicts. Navigate to the root of your server files and open the spigot.yml file.

   • Find the bungeecord setting under the settings section.
   • Set it to false.

   settings:
     bungeecord: false

   
3. Enable Velocity Forwarding in paper-global.yml:

   This is the final and most important step. You need to tell your Paper server to trust your Velocity proxy. Navigate to the config folder and open the paper-global.yml file.

   • Set enabled: to true under the velocity section.
   • Paste your forwarding secret into the secret: field. This must exactly match the secret in your Velocity proxy's configuration.
   • Ensure online-mode: is set to true. This tells Paper to trust the online-mode data being forwarded from Velocity.

   proxies:
     velocity:
       enabled: true
       secret: "your-secret-here"
       online-mode: true

   
4. Restart Your Paper Server:

   For all these changes to take effect, perform a full restart of your Paper server.

Troubleshooting Common Issues

• Error: "If you wish to use IP forwarding, please enable it in your BungeeCord config as well!" - This message usually means your forwarding secret in paper-global.yml does not match the secret in your Velocity proxy's velocity.toml file. Double-check that they are identical.
• Player skins are not showing up or have the wrong UUID: This typically happens if online-mode: is set to false in your paper-global.yml. It must be set to true for Paper to accept the forwarded player data correctly.

Conclusion

Properly configuring modern Velocity forwarding is a critical step for creating a secure and functional server network. By following these steps, you ensure seamless communication between your proxy and backend servers, providing a smooth experience for your players and allowing your plugins to work as intended.