cwhitelist
Running a Minecraft server comes with its fair share of responsibilities, and managing who gets to join is often at the top of the list. Basic whitelists work, but they quickly become a headache when you're juggling multiple servers, dealing with player name changes, or trying to keep out unwanted guests. That's where cwhitelist steps in. This isn't just another whitelist mod; it's a comprehensive management system designed for modern servers that need flexibility, security, and centralized control.
Whether you're running a small community server or a large network, cwhitelist offers a level of sophistication that standard tools just can't match. It moves beyond simple username checks, offering a multi-layered approach to authentication that keeps your server safe and your community curated.
Why Choose cwhitelist for Minecraft?
Traditional whitelists are static. You add a name, and that's it. But what happens when a player changes their username? What if you want to restrict access by IP address for extra security? What if you need to manage whitelists across five different servers without logging into each one? cwhitelist for Minecraft answers all these questions and more. It provides a robust, feature-rich solution that adapts to your server's needs, not the other way around.
Multi-Dimensional Authentication
The core of cwhitelist lies in its ability to verify players using multiple methods. You're not locked into just one way of doing things. You can enable or disable each check independently, giving you granular control over your security posture.
- Player Name: The classic method, checking the username against your list.
- UUID: A more secure method that ties the whitelist entry to the player's unique identifier, immune to name changes.
- IP Address: Restrict access to specific IPs, with wildcard support (like
192.168.*.*) for flexibility.
This modular system means you can require just a name, just a UUID, or a combination of all three for maximum security. It's your call.
Centralized Management with API Integration
For server networks, managing whitelists on each individual server is a nightmare. cwhitelist solves this with its powerful API integration. It operates in a dual-mode system: API-first with a local fallback. This means if your central API server is reachable, it uses that as the single source of truth. If the API goes down, it gracefully falls back to a local cache, ensuring your server never locks players out due to a network hiccup.
This setup provides real-time synchronization across all connected servers. Add a player on one server, and they're instantly whitelisted on all of them. Token-based authentication ensures that only authorized servers can communicate with your API, and built-in health checks keep an eye on the connection's status.
How to Install and Get Started
Getting cwhitelist up and running is straightforward. The mod is built for Minecraft 1.21.x and requires the NeoForge loader. You'll need Java 17 or higher to run it. The process is simple:
- Download cwhitelist: Grab the latest
cwhitelist-x.x-NeoForge-1.21.x.jarfile from the official releases page. - Install: Place the downloaded
.jarfile into your server'smodsfolder. - Configure: Start the server once to generate the default configuration file, then stop it. You'll find
config/cwhitelist-common.tomlready for editing. - Restart: After you've made your changes, restart the server to apply them.
For players looking for a more streamlined experience, the foxygame.net launcher offers a one-click install for mods, including cwhitelist, and its add-on catalog automatically checks version compatibility, making the setup process even less of a hassle. It's a great way to get your mods sorted without having to manually track down files.
Understanding the Configuration
The configuration file is well-documented and easy to navigate. It's split into logical sections so you can find what you need quickly.
Basic and Check Settings
The [basic] section controls your logging preferences. You can enable or disable local file logging, set how long to retain logs (1-365 days), and cap the size of individual log files. The [checks] section is where you toggle the authentication methods we mentioned earlier.
API Settings
If you're ready to set up centralized management, the [api] section is your control panel. Here you'll set the baseUrl for your API server, provide your secure token, and configure timeouts and cache durations. You can also decide whether to sync on startup and whether to send login events back to the API for central logging.
Command Reference for Admins
cwhitelist doesn't clutter the player experience with commands; all management is admin-focused. The commands are intuitive and give you full control.
Basic Management
/cwhitelist add name <username>- Add a player by name./cwhitelist add uuid <uuid>- Add a player by UUID./cwhitelist add ip <ip-address>- Add an IP address./cwhitelist remove name <username>- Remove a player by name./cwhitelist list- View all whitelist entries./cwhitelist reload- Reload the configuration without restarting.
API Management
/cwhitelist api status- Check the current API connection status./cwhitelist api verify- Test if your API token is valid./cwhitelist api health- Perform a health check on the API server./cwhitelist api sync- Manually trigger a sync from the API./cwhitelist api clearcache- Force a refresh of the local cache.
Intelligent Logging and Security
Knowing who tried to join and when is crucial for server security. cwhitelist provides a comprehensive audit trail, logging every login attempt with timestamps. The logging system is smart, with automatic rotation to prevent disk space issues and configurable retention policies. For those using the API, you can even enable remote logging, sending events to your central system for a unified view.
Security is a top priority. The mod uses token-based authentication for API communication, supports HTTPS for secure connections, and has built-in timeout and retry logic to handle network issues gracefully. All sensitive data is stored in the config file, not hardcoded, and admin commands are protected by permission levels.
Performance and Troubleshooting
cwhitelist is designed with performance in mind. All API calls and file operations are asynchronous, meaning they won't block the main server thread. Smart caching reduces the load on your API server, and the mod gracefully degrades to local-only mode if the API becomes unavailable.
If you run into issues, the mod provides clear error messages. Common problems like API connection failures, token verification errors, or permission issues all have straightforward solutions. Detailed logs are written to logs/cwhitelist/ and can help you diagnose almost any problem.
Conclusion
If you're serious about server management, cwhitelist is an invaluable tool. It transforms a simple whitelist into a powerful, centralized security system. Its flexibility, robust API, and intelligent features make it perfect for both single servers and large networks. Whether you need simple name-based whitelisting or complex multi-server synchronization, cwhitelist for Minecraft delivers a professional-grade solution that's easy to install and configure. Take control of your server's access today and experience the difference a dedicated whitelist management mod can make.