Understanding VPNGuard for Minecraft Server Security
Running a Minecraft server is all about building a community, but nothing disrupts that faster than spammers, bots, and troublemakers slipping in through anonymizers. VPNGuard is a powerful plugin designed to block players who try to connect behind VPNs, proxies, or other hosting-based IP addresses. By kicking these users before they can cause problems, you keep your server cleaner and your players happier.
How VPNGuard Protects Your Server
When a player attempts to join, VPNGuard instantly sends their IP address to a private, frequently updated database. If the IP belongs to a known VPN or proxy provider, the plugin kicks the player with a customizable message. This real-time check helps prevent ban evasion, spam bots, and griefers from using throwaway connections. The database is refreshed almost daily, so even newly launched anonymizer services are quickly caught.
Core Features at a Glance
- Automatic detection and kicking of VPN and proxy users.
- Privately managed blocklist updated nearly every day.
- In-game notifications when a VPN connection is blocked.
- Detailed reports showing all players who attempted to join via anonymizers.
- Country-based whitelisting or blacklisting to control regional access.
- Subnet bans for entire IP ranges linked to hosting providers.
- Cache system to reduce API calls and speed up repeat checks.
Essential Commands and Permissions
VPNGuard puts control directly in the hands of server administrators with a comprehensive set of commands. Every action can be fine-tuned with granular permissions, so you can delegate tasks to moderators without giving away full control.
Key Commands
- /vpnguard notify – Toggle in-game alerts when a VPN user tries to join.
- /vpnguard report – Generate a report listing all VPN join attempts.
- /vpnguard clearcache – Remove all locally stored cache files.
- /vpnguard clearip <ip> – Delete cache data for a specific IP address.
- /vpnguard country – Manage country blacklist or whitelist settings.
- /vpnguard subnet – Ban or unban entire IP address ranges.
- /vpnguard lookup <player or ip> – View details about any online player or IP.
- /vpnguard about – Display plugin version and information.
Permission Nodes
- vpnguard.permission.bypass – Bypass all VPN checks (for trusted staff).
- vpnguard.command.vpnguard – Access the base command (default: true).
- vpnguard.command.notify – Use the notify toggle (default: OP).
- vpnguard.command.report – Generate reports (default: OP).
- vpnguard.command.clearcache – Clear all cache (default: OP).
- vpnguard.command.clearip – Clear specific IP cache (default: OP).
- vpnguard.command.country – Manage country lists (default: OP).
- vpnguard.command.subnet – Subnet ban management (default: OP).
- vpnguard.command.lookup – Lookup IP or player info (default: OP).
- vpnguard.command.about – View plugin info (default: true).
Setting Up and Configuring VPNGuard
After placing the plugin JAR into your server’s plugins folder and restarting, you can tweak the behavior through a detailed config.yml. You can view an example configuration in the plugin’s documentation. The file lets you define custom kick messages using variables like %p for the player name and %ip for the connecting IP. The country-deny-message also supports %countryname to show the blocked country. If you want to automate actions, the commands section can execute console commands when a VPN user is detected, again using those same variables.
When managing your server, you can simplify plugin installation by using the foxygame.net launcher, a flexible and modern Minecraft launcher that lets you download mods and plugins right from the menu. This makes it easy to keep all your server tools up to date without hunting for files manually.
Understanding the External API and Limits
VPNGuard relies on an external IP validation service hosted at tools.xioax.com. Each time a new player joins, their IP is sent over the internet for a lookup against a private database. To reduce unnecessary requests, the plugin caches results locally. The free API tier allows up to 500 unique player lookups per month. If your server attracts more new faces, you can purchase an API key for a small monthly fee to lift that limit. In the config, the bypass-check option decides what happens when the monthly quota is exhausted—either let unverified players join or kick them as a precaution.
Frequently Asked Questions
How many players can VPNGuard check each month?
The backend provider includes 500 monthly requests for free. With caching enabled, you can easily handle 500 unique new players per month without issue.
What happens when the monthly limit is reached?
The API stops returning data for new users. Depending on your config.yml setting, those players will either be allowed to join unchecked or kicked automatically.
Can I get more than 500 monthly requests?
Yes, you can purchase an API key for a low monthly cost, which removes the request cap entirely.
Where can I learn more about the API?
You can visit the API provider’s homepage for additional details and subscription options.
Why VPNGuard Is a Must-Have for Serious Server Owners
Spam bots and repeat offenders often rely on VPNs to bypass IP bans. VPNGuard slams that door shut. With country controls, you can even restrict access from regions where most malicious traffic originates, or whitelist only your target audience. The report command gives you a clear picture of how many VPN attempts your server faces, helping you adjust your security strategy over time. For a free plugin with such a robust feature set, VPNGuard is an essential layer of defense for any public Minecraft server.