Forwarding Bypass
Configure SoulFire's forwarding-bypass plugin, including Modern, BungeeGuard, legacy forwarding, and SoulFireBypass for online-mode proxy networks.
What this is for
Use the built-in forwarding-bypass plugin when your target server sits behind a proxy setup that expects forwarded player data instead of a normal direct join.
This is mainly relevant for:
- BungeeCord-style legacy forwarding
- BungeeGuard-protected legacy forwarding
- Velocity modern forwarding
- the external
SoulFireBypassproxy plugin for allowing SoulFire bots onto an online-mode proxy network without disabling online mode globally
If your target is a normal standalone server with no proxy forwarding in front of it, leave this plugin off.
What the built-in plugin supports
SoulFire ships forwarding-bypass as a built-in plugin.
It exposes these modes:
| Mode | Use this when | Needs a secret | Uses player-address |
|---|---|---|---|
LEGACY | The backend expects classic BungeeCord IP forwarding | No | Yes |
BUNGEE_GUARD | The backend uses BungeeGuard on top of legacy forwarding | Yes | Yes |
MODERN | The proxy/backend uses Velocity modern forwarding | Yes | Yes |
SF_BYPASS | You installed the separate SoulFireBypass plugin on the proxy | Yes | No |
The related CLI flags are:
--forwarding-bypass-enabled--forwarding-bypass-forwarding-mode--forwarding-bypass-secret--forwarding-bypass-player-address
Forwarding is trust-sensitive infrastructure. If you configure the wrong mode or leak the secret, you are not just causing login bugs, you may be creating an authentication bypass.
Enable forwarding-bypass in SoulFire
Open the instance
Open the SoulFire instance that will run the bots.
Enable the plugin
Open Plugins and enable Forwarding Bypass.
Select the forwarding mode
Open Plugin Settings and choose the mode that matches your proxy/backend setup.
Fill in the shared values
Set the secret if your selected mode needs one.
Set player-address if your selected mode uses it and you want the backend to see a specific player IP.
Start a small test first
Start with one bot and verify that the backend accepts the connection before scaling up.
How each mode behaves
Legacy
LEGACY rewrites the handshake hostname with classic BungeeCord forwarding data.
Use it only if your target actually expects that older forwarding format.
BungeeGuard
BUNGEE_GUARD uses the legacy forwarding format and appends the BungeeGuard token inside the forwarded profile properties.
Use the same token configured on your network.
Modern
MODERN answers Velocity's velocity:player_info forwarding request during login.
Use the same forwarding secret configured between your Velocity proxy and backend servers.
SoulFire Bypass
SF_BYPASS is different from standard proxy forwarding.
Instead of imitating normal forwarded player data, SoulFire appends a marker containing your shared key to the handshake hostname.
The external proxy plugin reads that marker and forces offline-mode login only for connections carrying a valid key.
That is what allows SoulFire offline-mode bots to join your online-mode proxy network without switching the whole proxy to offline mode.
Set up SoulFireBypass
SoulFireBypass on Modrinth is a separate proxy plugin. Its published description says it allows SoulFire to bypass online-mode auth on your server. The source code is published at AlexProgrammerDE/SoulFireBypass.
Use it when:
- your public network still needs normal online-mode authentication for real players
- you want a controlled exception for SoulFire bots
- you do not want to disable online mode globally just to run tests
Anyone who knows a valid SoulFireBypass key can impersonate a player through the proxy path protected by that plugin. Treat the key like a password and rotate it if it is exposed.
Proxy-side setup
Install the plugin on the proxy
Download SoulFireBypass from Modrinth and place it on your proxy.
The Modrinth listing currently advertises Velocity, BungeeCord, and Waterfall compatibility.
Start the proxy once
Start the proxy so the plugin creates its data folder and config.yml.
Configure allowed keys
Edit the generated config.yml and replace the placeholder value under allowed-keys with a strong secret.
allowed-keys:
- replace_this_with_a_long_random_keyRestart the proxy
Restart after saving the config so the new key is loaded.
SoulFire-side setup
Enable Forwarding Bypass
In SoulFire, enable the built-in Forwarding Bypass plugin.
Select SoulFire Bypass mode
Set forwarding-mode to SF_BYPASS.
Use the same key
Set the plugin secret in SoulFire to the same value you added to allowed-keys on the proxy.
Join through the proxy entry point
Point SoulFire at the normal proxy address, not a backend server.
What SoulFireBypass actually changes
With standard online-mode proxy auth, the proxy expects a normal authenticated player login flow. SoulFireBypass changes only one narrow part of that decision:
- if the incoming handshake contains a valid
SF_<key>marker, the proxy plugin forces offline-mode handling for that connection - if the key is missing or wrong, the connection stays on the normal online-mode path
- this lets you keep normal auth for regular players while granting SoulFire a controlled bypass path
This is not a general replacement for Velocity modern forwarding or BungeeGuard. It is a separate opt-in bypass path specifically for SoulFire.
Recommended usage
- Use
MODERNif you are connecting through a standard Velocity modern-forwarding setup and do not need SoulFireBypass. - Use
BUNGEE_GUARDif you are testing against an older Bungee-style network protected by BungeeGuard. - Use
SF_BYPASSif you specifically want SoulFire offline-mode bots to reach an otherwise online-mode proxy network. - Do not enable
forwarding-bypassunless the server architecture actually requires it.
Related pages
How is this page?
Last updated on