RealIP Plugin for Minecraft: Fix Player IPs Behind TCPShield

If you run a Minecraft server behind TCPShield, you have probably noticed something odd in your logs: every player seems to connect from the same IP address. That is not a bug. It is how proxy protection works. The RealIP plugin fixes this by extracting the actual player IP addresses from the connection data TCPShield passes along.

The Problem RealIP Solves

When you put TCPShield in front of your Minecraft server, all player connections route through TCPShield's proxy network. Your server sees the proxy's IP address instead of the real player's IP. This breaks several things that server admins rely on every day.

Bans stop working. You ban one player who is causing problems, but you are actually banning the proxy IP. Everyone behind that proxy gets blocked. You end up punishing innocent players while the actual troublemaker just reconnects through a different route.

Logs become useless. Every connection shows the same IP. You cannot track individual players, investigate griefing incidents, or figure out who was online when something happened. Your server logs turn into a wall of identical entries.

Anti-cheat systems fail. Most anti-cheat plugins rely on IP addresses to identify players and track behavior. With proxy IPs, they cannot tell players apart. The same player with five accounts looks like five different people, or worse, five different players look like one person.

Player tracking breaks. You cannot see where players are coming from, how many accounts they have, or build meaningful statistics. Tools that depend on IP data, like geoIP lookups or VPN detection, stop working entirely.

RealIP sits between TCPShield and your server, reads the connection headers, and rewrites the IP address your server sees. It is a small plugin, but it makes everything else work correctly. If you are setting up a server for the first time, check out our guide to Minecraft server hosting to understand the full picture of what goes into running a protected server.

How RealIP Works

TCPShield adds a special header to each connection that contains the real player's IP address. RealIP reads this header, validates that the connection actually came through TCPShield's network (not someone spoofing it locally), and then tells your server the real IP.

The validation step matters more than most people realize. Without it, someone could connect directly to your backend server and fake the header to impersonate any IP address. RealIP checks that the connection is legitimate before trusting the header data. This prevents IP spoofing attacks that could otherwise bypass your security measures.

The plugin supports three proxy platforms:

• Spigot / CraftBukkit (requires ProtocolLib)
• BungeeCord
• Velocity

You download the version that matches your proxy platform, drop it in your plugins folder, and restart. That is the basic setup. The plugin is lightweight and does not add noticeable overhead to your server.

Installation Steps

Here is the practical installation process that works for most setups. I have tested this on Spigot, Paper, and BungeeCord servers, and the process is similar across all of them.

1. Download the plugin. Get the latest release from the GitHub releases page. Make sure you grab the right version for your proxy platform. The releases are clearly labeled.
2. Install ProtocolLib if needed. If you are running Spigot or CraftBukkit, you need ProtocolLib installed first. RealIP depends on it. Download it from SpigotMC and drop it in your plugins folder. If you are on BungeeCord or Velocity, you can skip this step.
3. Drop the jar in your plugins folder. Place the RealIP jar file in your server's plugins directory. Make sure you are putting it on the right server: if you are running BungeeCord, it goes on the BungeeCord instance, not your backend servers.
4. Restart your server. A full restart is needed. A reload might not work correctly because the plugin hooks into the connection pipeline at startup.
5. Verify it is working. Join your server and check your logs. You should see real player IPs instead of the proxy IP. You can also check your server's latest.log file to confirm.

If you are running BungeeCord, you only need RealIP on your BungeeCord instances, not on your backend servers. The plugin runs on the frontend proxy, not the backend. This is a common mistake: installing it on the wrong server type.

Configuration Tips

RealIP works out of the box with minimal configuration, but there are a few settings worth knowing about. These can save you from security headaches down the line.

only-allow-proxy-connections should be set to true in production. This ensures your server only accepts connections through TCPShield. If this is false, anyone can connect directly to your backend, bypassing TCPShield's protection entirely. This is the most important setting in the plugin.

ProtocolLib version matters. If you are running Paper with an unsupported version of ProtocolLib, you might get errors. The plugin tries to use ProtocolLib over the regular Paper integration because the Paper method exposes MOTDs to direct connect users. Make sure you have ProtocolLib 5.x or newer. If you are on Paper and cannot update ProtocolLib, you can disable the ProtocolLib integration in RealIP's config.

Geyser support. If you are using Geyser to allow Bedrock players, there is a geyser-support config option. Only enable this if you are actually using TCPShield's Geyser tunnel. Enabling it without Geyser can make your backend scannable, which defeats the purpose of using TCPShield in the first place.

Proxy Protocol alternative. If you are having conflicts with other plugins that authenticate players (antiBot, antiVPN, AuthMe), you might want to consider using Proxy Protocol instead of RealIP. This requires a different setup but can be more compatible with certain plugin combinations.

RealIP vs Proxy Protocol: Which Should You Choose?

TCPShield offers two ways to forward real player IPs to your server: the RealIP plugin and Proxy Protocol. Both work, but they have different tradeoffs.

RealIP (plugin-based) is the traditional approach. It is a plugin that runs on your proxy server and reads the connection headers. It is easy to install and configure, but it requires ProtocolLib on Spigot and can conflict with other plugins that authenticate players.

Proxy Protocol is a lower-level approach. It works at the network level, not the plugin level. You enable it in your server's config file and in your TCPShield panel. It does not require ProtocolLib and has fewer plugin conflicts, but it requires more manual configuration and a firewall setup to only accept connections from TCPShield's IP ranges.

Here is a quick comparison:

If you are just starting out and want the simplest setup, go with RealIP. If you are running a complex setup with many authentication plugins, Proxy Protocol might be the better choice.

Common Issues and Fixes

After installing RealIP, you might run into a few common issues. Here is how to fix them based on real server admin experience.

Plugin will not load. The most common cause is missing ProtocolLib on Spigot. Install ProtocolLib first, then restart. Check your startup log for specific error messages. If you see a "NoClassDefFoundError" or similar, it is almost always ProtocolLib.

Players still show proxy IP. Make sure TCPShield is actually configured on your network. RealIP only works if your connection is routed through TCPShield's protection. If TCPShield is not set up on their end, the plugin will have nothing to parse. Check your TCPShield panel to make sure your domain is properly configured.

ProtocolLib errors on startup. You might have an outdated ProtocolLib version. Update to the latest version. If you are on Paper and cannot update ProtocolLib, you can disable the ProtocolLib integration in RealIP's config. Look for the use-protocollib option and set it to false.

Conflicts with other plugins. Some plugins that authenticate players (antiBot, antiVPN, AuthMe) can conflict with RealIP. If you are using these, consider setting up Proxy Protocol instead of using RealIP. You will need to enable proxy-protocol in your server's config and in your TCPShield panel.

Backend IP leaked. If your backend IP is visible to the internet, scanners can find it and attack it directly, bypassing TCPShield. Make sure only-allow-proxy-connections is set to true and that your firewall only allows connections from TCPShield's IP ranges.

Performance Impact and Server Resources

RealIP is designed to be lightweight. It does not add significant CPU or memory overhead to your server. The plugin only processes connection headers at the moment a player joins, not during gameplay. Once the connection is established and the IP is rewritten, RealIP steps back and does nothing until the next player joins.

In practice, you will not notice any performance difference. The plugin uses minimal memory (a few megabytes) and negligible CPU time. It does not run background tasks or scheduled jobs. It is purely event-driven, responding only to player join events.

This is one of the reasons RealIP has become the standard for TCPShield-protected servers. It solves a critical problem without adding any meaningful resource cost. You can run it on even the smallest server hardware without concern.

RealIP and Anti-Cheat Compatibility

One of the most important benefits of RealIP is that it makes anti-cheat plugins work correctly again. Without real IPs, anti-cheat systems cannot properly identify and track players. Here is how RealIP helps specific anti-cheat categories:

Movement anti-cheat. These plugins track player movement patterns to detect fly hacks, speed hacks, and other movement cheats. With proxy IPs, they cannot distinguish between players, leading to false positives or missed cheats. RealIP restores their ability to track individual players.

Combat anti-cheat. Killaura, aimbot, and other combat cheats are detected by analyzing player combat behavior. Anti-cheat plugins use IP addresses to correlate combat events with specific players. Without real IPs, this correlation breaks down.

Account linking. Some anti-cheat systems link multiple accounts from the same IP to detect ban evasion. With proxy IPs, all players appear to be from the same IP, making account linking useless. RealIP restores this capability.

VPN and proxy detection. Many servers use VPN detection to block players who try to hide their real IP. With proxy IPs, VPN detection sees the same IP for everyone and cannot function. RealIP fixes this by providing the actual player IP.

When You Do Not Need RealIP

If you are not using TCPShield, you do not need RealIP. It only works with that specific service. There is no point installing it on a server that is not behind TCPShield's proxy network. The plugin will load but will not do anything useful.

If you are using a different DDoS protection service, check if they have their own IP forwarding plugin. Most proxy-based protection services need some way to pass real IPs to your server. TCPShield is just one option among many.

If you are running a small private server for friends, you probably do not need DDoS protection or RealIP at all. These tools are for public servers that are actual targets. A private server with a whitelist does not need this level of protection.

Practical Tips for Server Admins

After running RealIP on multiple servers over the past few years, here are some practical tips that are not obvious from the documentation.

Test after every update. When either RealIP, ProtocolLib, or your server software updates, test that IP forwarding still works. Updates can sometimes break compatibility in subtle ways. A quick check of your logs after each update can save you from hours of debugging later.

Monitor your logs regularly. Even with RealIP working correctly, it is worth checking your logs occasionally. Look for patterns: are there connections that do not have the TCPShield header? Are there IPs that seem unusual? This can help you spot configuration issues or potential security problems early.

Keep ProtocolLib updated. ProtocolLib updates frequently, and staying current prevents compatibility issues. If you are on Paper, be aware that Paper's built-in IP forwarding can sometimes conflict with ProtocolLib. Test thoroughly after any ProtocolLib update.

Document your setup. If you are running a server with multiple admins, make sure everyone knows that RealIP is installed and why it matters. Document the configuration, especially the only-allow-proxy-connections setting. This prevents well-meaning admins from accidentally disabling it.

Have a backup plan. If RealIP stops working or you need to troubleshoot TCPShield issues, know how to temporarily disable it. You can set only-allow-proxy-connections to false to allow direct connections while you debug. Just remember to set it back to true when you are done.

Check your ban list periodically. Even with RealIP working, it is worth reviewing your ban list occasionally. Make sure you are not accidentally banning proxy IPs or ranges that include innocent players. A quick audit every few weeks can prevent support headaches.

Educate your moderators. Make sure your moderation team understands how RealIP works and why it matters. If they see all players with the same IP in logs, they need to know that RealIP is not working correctly. Provide them with a quick guide on how to verify IP forwarding is active. For more on managing your server, our Minecraft commands guide covers the essentials every admin should know.