Complete Documentation

Overview

MAF (Minecraft Application Firewall) is a comprehensive network security plugin designed for Minecraft servers. It provides advanced features for controlling player connections based on geographical location, detecting VPN/Proxy connections, and intelligently routing players to specific worlds based on their region.

Core Features

1. Region-Based Access Control

The plugin allows server administrators to control which countries or regions can connect to the server. This system operates in three modes:

• Disabled Mode: All regions are allowed (default configuration)
• Whitelist Mode: Only specified countries can connect
• Blacklist Mode: All countries except specified ones can connect

Country identification uses ISO 3166-1 alpha-2 codes (US, BR, GB, DE, etc.). The system automatically detects player location using their IP address through the IP-API service.

Configuration Example:
2. VPN & Proxy Detection

Advanced detection system that identifies and blocks suspicious connections:

• VPN Detection: Identifies virtual private network connections
• Proxy Detection: Detects proxy server usage
• Tor Network Detection: Identifies Tor browser connections
• Datacenter/Hosting Detection: Detects connections from hosting providers

Each detection type can be individually enabled or disabled. The system includes intelligent caching to minimize API requests and maintain performance.

Configuration Example:
3. World Routing System

Automatically routes players to specific worlds based on their geographical location. This feature includes two main components:

Spawn Routing: Determines which world players spawn in when they first join
World Access Control: Restricts which worlds players can access based on their country
Players attempting to access restricted worlds are automatically teleported back to their designated spawn world.

4. IP Whitelist System

Administrators can add trusted IP addresses to a whitelist. Whitelisted IPs bypass all firewall checks including:

• Region restrictions
• VPN detection
• All blocking mechanisms

Whitelist management is available through commands or direct configuration file editing.

5. Multi-Language Support

The plugin includes complete translations for six languages:

• English (en): Default language
• Portuguese Brazil (pt_br): Brazilian Portuguese
• Spanish (es): Spanish
• Italian (it): Italian
• Russian (ru): Russian
• Chinese (zh): Simplified Chinese

All messages including kick messages, command responses, and system notifications are fully translatable.

6. Statistics & Monitoring

Comprehensive statistics tracking system that records:

• Total connection attempts
• Allowed connections
• Blocked connections
• Blocked by VPN/Proxy detection
• Blocked by region restriction

Statistics persist across server restarts and can be viewed through the stats command.

Command System

Main Command: /maf or /firewall or /networkfw

Available Subcommands:

/maf help
Displays the help menu with all available commands.
Permission: maf.admin

/maf reload
Reloads all configuration files without requiring a server restart. This includes:

• Main configuration (config.yml)
• World routing configuration (worlds-routing.yml)
• Language files

Permission: maf.admin.reload

/maf stats
Displays detailed connection statistics including total connections, allowed connections, blocked connections, and breakdown by block reason.
Permission: maf.admin.stats

/maf whitelist add <ip>
Adds an IP address to the whitelist, allowing it to bypass all firewall checks.
Permission: maf.admin.whitelist

/maf whitelist remove <ip>
Removes an IP address from the whitelist.
Permission: maf.admin.whitelist

/maf whitelist list
Lists all currently whitelisted IP addresses.
Permission: maf.admin.whitelist

Permission System

Administrative Permissions:

• maf.admin.* - Grants access to all MAF commands (default: op)
• maf.admin.reload - Allows reloading plugin configuration (default: op)
• maf.admin.stats - Allows viewing connection statistics (default: op)
• maf.admin.whitelist - Allows managing IP whitelist (default: op)
• maf.admin.bypass - Bypasses all firewall restrictions (default: op)

User Permissions:

• maf.user.* - Basic user permissions (default: true)

Configuration Files

Main Configuration (configs/config.yml)

Language Settings:
Sets the plugin language. Available options: en, pt_br, es, it, ru, zh

Firewall Settings:

• enabled: Master switch for the entire firewall system
• allow-on-geo-failure: Whether to allow connections when geolocation lookup fails

VPN Detection Settings:

• enabled: Enable/disable VPN detection system
• block-proxy: Block proxy server connections
• block-tor: Block Tor network connections
• block-hosting: Block datacenter/hosting IP addresses

Region Restriction Settings:

• enabled: Enable/disable region restrictions
• mode: Operation mode (disabled, whitelist, or blacklist)
• countries: List of country codes to whitelist or blacklist

World Routing Settings:

• enabled: Enable/disable automatic world routing
• default-world: Default world when no routing rule matches

IP Whitelist:
List of IP addresses that bypass all firewall checks.

Advanced Settings:

• debug-mode: Enable detailed debug logging
• cache-time-minutes: Duration to cache geolocation results
• api-timeout-seconds: Timeout for API requests

World Routing Configuration (configs/worlds-routing.yml)

Spawn Routing:
Maps country codes to spawn worlds. Players from listed countries will spawn in the specified world.

World Access Rules:
Defines which worlds players from specific countries can access. If a country is not listed, players can access all worlds.

Technical Implementation

Architecture

The plugin follows a modular architecture with clear separation of concerns:

Core Components:

• MAF.java: Main plugin class handling initialization and manager coordination
• FirewallManager: Core firewall logic and connection validation
• ConfigManager: Configuration file loading and management
• LanguageManager: Multi-language message system
• WorldRoutingManager: World routing and access control
• StatisticsManager: Connection statistics tracking

Event Handling:

• PlayerConnectionListener: Handles pre-login validation, join events, and world changes

Utility Classes:

• GeoLocationAPI: Manages geolocation lookups with caching
• Logger: Centralized logging with color formatting

Data Models:

• GeoLocation: Represents player location data
• ValidationResult: Encapsulates connection validation results

Performance Optimization

• Asynchronous Processing: Connection validation runs asynchronously to prevent server lag
• Intelligent Caching: Geolocation results cached for 30 minutes (configurable)
• Efficient Data Structures: Uses ConcurrentHashMap for thread-safe operations
• Lazy Loading: Resources loaded only when needed
• Automatic Cleanup: Periodic cache cleanup prevents memory leaks

API Integration

The plugin uses IP-API for geolocation services:

• Free tier: 45 requests per minute
• No API key required
• Provides country, region, city, and connection type information
• Results are cached to minimize requests

Use Cases & Examples

Example 1: European-Only Server

Configuration to allow only European players:
Example 2: Block Specific Regions

Configuration to block specific countries while allowing all others:
Example 3: VPN-Free Environment

Configuration for strict VPN blocking:
Example 4: Regional Server Network

Configuration for automatic regional routing:
In worlds-routing.yml:
Example 5: Restricted World Access

Configuration to restrict premium worlds by region:
Installation & Setup

Step 1: Installation

1. Download MAF-1.0.0.jar
2. Place in server plugins folder
3. Restart the server
4. Plugin will generate default configuration files

Step 2: Basic Configuration

1. Navigate to plugins/MAF/configs/
2. Edit config.yml according to your needs
3. Edit worlds-routing.yml if using world routing
4. Use /maf reload to apply changes

Step 3: Language Configuration

1. Set desired language in config.yml
2. Optionally customize messages in plugins/MAF/languages/
3. Reload configuration

Step 4: Testing

1. Test with VPN enabled (should be blocked if enabled)
2. Test from different regions
3. Check statistics with /maf stats
4. Verify world routing functionality

Compatibility

Supported Minecraft Versions:

• 1.17.x
• 1.18.x
• 1.19.x
• 1.20.x
• 1.21.x

Server Software:

• Spigot
• Paper
• Purpur
• Any Spigot-based fork

Java Requirements:

• Java 8 or higher
• Recommended: Java 17 or higher for newer Minecraft versions

Troubleshooting

Players Cannot Connect:

• Check region-restriction settings in config.yml
• Verify country codes are correct (ISO 3166-1 alpha-2)
• Add trusted IPs to whitelist
• Check if firewall is enabled
• Review server logs for error messages

VPN Detection Not Working:

• Ensure vpn-detection.enabled is set to true
• Check if API rate limit is reached (45 requests/minute)
• Verify server has internet access
• Check server logs for API errors
• Consider increasing cache time to reduce API calls

World Routing Issues:

• Verify world-routing.enabled is true
• Check that world names match exactly (case-sensitive)
• Ensure target worlds exist on the server
• Review worlds-routing.yml syntax
• Check console for teleportation errors

Configuration Not Applying:

• Use /maf reload after making changes
• Check YAML syntax (indentation must be exact)
• Review console for configuration errors
• Verify file permissions
• Restart server if reload fails

Best Practices

Security:

• Always whitelist your own IP address for administrative access
• Regularly review statistics to identify attack patterns
• Keep whitelist minimal and up-to-date
• Use blacklist mode for most scenarios
• Enable VPN detection for competitive servers

Performance:

• Adjust cache time based on server traffic
• Monitor API rate limits
• Use debug mode only when troubleshooting
• Review logs regularly for performance issues

Configuration:

• Test changes on development server first
• Backup configuration files before major changes
• Document custom configurations
• Use comments in YAML files
• Keep default-world accessible to all regions

Maintenance:

• Regularly check for plugin updates
• Monitor server logs for errors
• Review and clean statistics periodically
• Update country lists as needed
• Test after Minecraft version updates

Country Code Reference

Common ISO 3166-1 alpha-2 country codes:

North America:
US (United States), CA (Canada), MX (Mexico)

South America:
BR (Brazil), AR (Argentina), CL (Chile), CO (Colombia), PE (Peru)

Europe:
GB (United Kingdom), DE (Germany), FR (France), IT (Italy), ES (Spain), PT (Portugal), NL (Netherlands), BE (Belgium), SE (Sweden), NO (Norway), DK (Denmark), FI (Finland), PL (Poland), RU (Russia)

Asia:
CN (China), JP (Japan), KR (South Korea), IN (India), TH (Thailand), VN (Vietnam), PH (Philippines), ID (Indonesia), MY (Malaysia), SG (Singapore)

Oceania:
AU (Australia), NZ (New Zealand)

Middle East:
SA (Saudi Arabia), AE (United Arab Emirates), IL (Israel), TR (Turkey)

Africa:
ZA (South Africa), EG (Egypt), NG (Nigeria), KE (Kenya)

Advanced Features

Custom Kick Messages

All kick messages can be customized in language files. Messages support color codes using the & symbol:

Color codes:
&0-&f for colors, &l for bold, &n for underline, &o for italic, &r for reset

Debug Mode

Enable detailed logging for troubleshooting:
Debug mode logs:

• Geolocation lookup results
• Cache hit/miss information
• Validation decisions
• API response details
• Performance metrics

Statistics Persistence

Statistics are automatically saved to statistics.yml and persist across server restarts. The file includes:

• Total allowed connections
• Total blocked connections
• Breakdown by block reason (VPN, region, etc.)
• Timestamp of last update

Bypass System

Multiple ways to bypass firewall checks:

• IP whitelist (config.yml)
• Permission maf.admin.bypass
• Local/private IP addresses (automatic)