Hostname Guard

Running a public Minecraft server comes with a unique set of challenges, especially when you want to control exactly how players connect. If you’ve ever wanted to force players to use your custom domain name instead of a raw IP address, Hostname Guard is the lightweight plugin that makes it effortless. Designed for Bukkit, Spigot, Paper, and Purpur environments, this tool acts as a gatekeeper, verifying the hostname every player uses during the login process. It’s a simple yet powerful way to reinforce your server’s branding, prevent bypass attempts, and maintain a cleaner, more professional community presence.

Why Hostname-Based Access Control Matters

Many server owners invest time in creating a memorable domain like play.myserver.com, only to discover that players can still join through the numeric IP address. This undermines branding efforts and can make it harder to manage traffic, especially if you use a reverse proxy or DDoS protection service that relies on hostname routing. Hostname Guard solves this by inspecting the virtual host header sent by the client during the handshake. If the hostname doesn’t match your approved list, the connection is refused before the player ever loads into the world. The result is a consistent, domain-only experience that aligns with your server’s public identity.

Core Features That Keep Your Server in Check

Hostname Guard doesn’t overcomplicate things. It focuses on a handful of essential features that deliver immediate value without bloating your server’s performance. Here’s what you can expect after you download Hostname Guard and drop it into your plugins folder:

• Strict hostname whitelisting – define one or more allowed domains, and the plugin will reject any connection that doesn’t use them.
• Direct IP blocking – automatically deny players who attempt to join via a raw IP address, even if that IP resolves to your server.
• Wildcard support – optionally use patterns like *.example.com to cover subdomains without listing each one individually.
• Bypass permission – grant trusted staff or test accounts the hostnameguard.bypass node so they can connect freely for maintenance.
• In-game reload and status commands – tweak the configuration without restarting the server, and instantly check which hostnames are currently allowed.
• No NMS or version-specific internals – the plugin works purely at the network handshake level, making it compatible with a wide range of Minecraft versions and server forks.

Compatibility and Requirements

Hostname Guard is built for modern Minecraft server software. It requires Java 21 or newer and runs on any server that implements the Bukkit API, including Spigot, Paper, and Purpur. The recommended Minecraft version is 1.20.5 or higher, but because the plugin avoids NMS code, it often functions on slightly older or newer releases without issues. Always test in a staging environment first if you’re running a non-standard fork. For those who manage multiple servers, the foxygame.net launcher includes Hostname Guard in its curated add-on catalog, letting you install and update the plugin with a single click while automatically matching the correct version to your server’s core.

How to Install Hostname Guard on Your Server

Getting started with Hostname Guard for Minecraft is straightforward, even if you’re new to plugin management. Follow these steps to lock down your server’s hostname access:

Step 1: Download the Plugin

First, download Hostname Guard from a trusted source like Modrinth. You’ll receive a .jar file that’s ready to deploy. Make sure you’re grabbing the latest stable build to benefit from any recent fixes or compatibility improvements.

Step 2: Place the File in Your Plugins Directory

Access your server’s root folder and locate the plugins directory. Drag the downloaded Hostname Guard .jar file into this folder. If your server is currently running, you can either restart it or use a plugin manager to load the new file without downtime.

Step 3: Configure Allowed Hostnames

After the first run, Hostname Guard generates a config.yml file inside plugins/HostnameGuard. Open it with a text editor and add your domain names under the allowed-hostnames list. For example:

• play.yourdomain.com
• mc.yourdomain.com

Set block-direct-ip to true if you want to reject raw IP connections outright. Save the file and use /hostnameguard reload in-game to apply changes instantly.

Step 4: Verify the Setup

Run /hostnameguard status to see the currently enforced hostnames and whether direct IP blocking is active. Try joining your server using the IP address – you should be kicked with a clear message. Then connect via your approved domain to confirm everything works as intended.

Commands and Permissions at a Glance

Hostname Guard keeps administration simple with a minimal set of commands. Both the full and abbreviated forms are supported:

• /hostnameguard reload or /hg reload – reloads the configuration from disk.
• /hostnameguard status or /hg status – displays the current allowed hostnames and whether IP blocking is enabled.

Permissions are equally straightforward. Assign hostnameguard.reload to staff who need to update the config, hostnameguard.status to those who should view the settings, and hostnameguard.bypass to accounts that must be exempt from hostname checks. This granularity ensures that only authorized personnel can alter or circumvent the security rules.

Real-World Use Cases for Hostname Guard

This plugin shines in several common scenarios. If you’re using a TCP shield or Cloudflare Spectrum to protect your server from DDoS attacks, you’ll want players to connect exclusively through the protected domain. Hostname Guard enforces that policy automatically, dropping any direct IP connection that could expose your backend. It’s also invaluable for networks that run multiple servers behind a single BungeeCord or Velocity proxy – you can ensure each sub-server only accepts connections from the correct proxy hostname, preventing unauthorized direct access. Additionally, if you’re migrating your server to a new IP address, you can temporarily allow both the old and new domains while phasing out the old one, all without touching your firewall rules.

Performance and Stability Considerations

Because Hostname Guard operates at the handshake stage, it adds virtually no overhead to gameplay. There are no repeating tasks, no entity checks, and no chunk loading involved. The plugin simply inspects the virtual host field during the login sequence and makes a yes/no decision. This design keeps your server’s TPS unaffected and avoids conflicts with other plugins. The absence of NMS reliance also means you won’t need to scramble for updates every time a new Minecraft version drops – a huge advantage for server admins who value stability.

Final Thoughts on Securing Your Server’s Entry Point

Hostname Guard is one of those plugins that does one thing and does it exceptionally well. It fills a gap that many server owners don’t realize exists until they see players joining through IP addresses, bypassing their carefully configured DNS records. By enforcing domain-only connections, you strengthen your server’s brand, improve compatibility with external protection services, and add a subtle but effective layer of access control. Whether you run a small private server or a large public network, Hostname Guard for Minecraft is a must-have tool that takes only minutes to set up and then quietly does its job in the background. Give it a try, and you’ll wonder how you ever managed without it.