Velocity Config Builder

⚡What is Velocity?

Velocity is a modern, high-performance Minecraft proxy server designed to connect multiple backend servers together. Built from the ground up with performance and scalability in mind, Velocity offers significant advantages over older proxy solutions like BungeeCord and Waterfall. It supports Minecraft Java Edition versions 1.7.2 through the latest releases and provides advanced features like modern player information forwarding, optimized network handling, and excellent plugin compatibility.

The velocity.toml configuration file uses the TOML format (Tom's Obvious Minimal Language), which is more human-readable and less error-prone than traditional property files. This tool helps you generate a properly formatted velocity.toml with all the settings you need for your network.

✨Ask the AI assistant

The AI assistant under the generator reads the velocity.toml you've built and answers questions about it: how to set up Paper for modern forwarding, why players land on the wrong server, or what a setting does. It's free, with 20 questions a day.

🔧Key Configuration Sections

Main Configuration

The main section contains essential proxy settings:

• bind: The IP address and port your proxy listens on (default: 0.0.0.0:25577). Players connect to this address.
• motd: Message of the day shown in the server list. Supports Minecraft color codes (& codes).
• show-max-players: Maximum player count displayed in server list (not a hard limit).
• online-mode Important: Enables Mojang authentication. Should be true for public servers.

Player Information Forwarding

• modern Recommended: Velocity's native forwarding. Requires Velocity's forwarding plugin on Paper/Spigot backends.
• bungeeguard: Compatible with BungeeGuard plugin for enhanced security over legacy mode.
• legacy: BungeeCord-style IP forwarding. Less secure but compatible with more plugins.
• none: No forwarding. Only use for testing or lobby-only servers.

Server Definitions

The [servers] section defines your backend servers. Each server needs a unique name and address:

[servers]
lobby = "lobby:25565"
survival = "survival:25565"
creative = "creative:25565"

The try list defines fallback servers. When a player first connects or gets disconnected, Velocity will try these servers in order.

Forced Hosts

Force players connecting via specific domains to specific servers. Perfect for network organization:

[forced-hosts]
"lobby.example.com" = ["lobby"]
"survival.example.com" = ["survival"]
"*.minigames.example.com" = ["minigames"]

Supports wildcards for subdomain matching.

Advanced Settings

Performance and behavior tuning options:

• compression-threshold: Packet size (bytes) before compression kicks in. Lower values use more CPU but less bandwidth. Default 256 works well for most setups.
• compression-level: ZLIB compression level (1-9). Higher = better compression but more CPU usage. -1 uses default (6).
• login-ratelimit: Milliseconds between logins from same IP. Protects against connection spam (default 3000ms).
• connection-timeout: How long to wait for backend server connection before failing (default 5000ms).
• tcp-fast-open Linux: Linux kernel feature to reduce connection latency. Requires kernel 3.7+ and sysctl configuration.

🚀Performance Optimization

⚠️Common Configuration Mistakes

1. Exposing Backend Servers

2. Mismatched Forwarding Modes

Problem: Proxy uses modern forwarding but backend uses legacy, or vice versa.

Solution: Ensure all backend servers use the same forwarding method as configured in velocity.toml. Check Paper/Spigot config.yml for velocity-support.

3. Missing Forwarding Secret

Problem: Backend servers can't verify the proxy's identity.

Solution: Copy the forwarding.secret file from Velocity to all backend servers. Ensure file permissions are secure (0600).

4. Wrong Bind Address

Problem: Proxy won't start or isn't accessible.

Solution: Use 0.0.0.0:25577 to listen on all interfaces. Use specific IP if you need to bind to particular interface. Ensure port isn't already in use.

5. No Try Servers

Problem: Players get kicked when backend server is down.

Solution: Always define fallback servers in the try list. Put your lobby first, followed by other servers players can fall back to.

🔌Backend Server Configuration

For Velocity to work properly, backend servers need configuration too:

Paper/Spigot (server.properties)

online-mode=false
server-port=25565  # Different from proxy port
server-ip=0.0.0.0  # Or localhost for security

Paper (config/paper-global.yml)

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "copy-from-forwarding.secret"

Spigot (spigot.yml)

If using legacy forwarding:

settings:
  bungeecord: true

🔒Security Best Practices

1. Always use online-mode: true on the proxy for public servers to enable Mojang authentication.
2. Use modern forwarding mode for best security. It's cryptographically secure and prevents IP spoofing.
3. Protect your forwarding.secret file. Anyone with this file can impersonate your proxy.
4. Set online-mode: false on backend servers. The proxy handles authentication.
5. Never expose backend servers to the internet. Bind them to localhost or internal IPs only.
6. Enable prevent-client-proxy-connections to block players using VPNs to bypass the proxy.
7. Use firewall rules to restrict which IPs can connect to backend servers.
8. Enable log-command-executions on production to audit administrative actions.

🔄Migration from BungeeCord

Switching from BungeeCord/Waterfall to Velocity is straightforward:

1. Download Velocity from PaperMC.
2. Start with player-info-forwarding-mode: legacy for compatibility.
3. Set backend servers to use BungeeCord mode (spigot.yml: bungeecord: true).
4. Copy your server list from BungeeCord's config.yml to Velocity's velocity.toml [servers] section.
5. Test thoroughly before switching players over.
6. Once stable, migrate to modern forwarding by installing Velocity's forwarding plugin on Paper backends.

🔍Troubleshooting

❓Frequently Asked Questions

🔗Related Tools & Resources

ChunkPod Tools

• server.properties Generator - Configure backend Minecraft servers
• JVM Arguments Generator - Optimize Java performance for proxy and servers
• MOTD Generator - Create colorful MOTDs for your proxy

External Resources

• Official Velocity Documentation
• Download Velocity
• Hangar (Velocity Plugin Repository)