Skip to main content
The Maintenance plugin provides advanced proxy-level maintenance features for BungeeCord networks.

​
Requirements

  • BungeeCord (latest version recommended)
  • Java 17 or higher

​
Installation

  1. Download the latest version from Hangar
  2. Place the JAR file in your BungeeCord plugins/ directory
  3. Restart your proxy
  4. Configure the plugin in plugins/Maintenance/config.yml

​
Proxy-Specific Features

BungeeCord installation unlocks advanced network-wide maintenance capabilities.

​
Global Maintenance

Enable maintenance for the entire proxy network: 
/maintenance on
This prevents all players (without bypass permission) from connecting to any server in your network.

​
Per-Server Maintenance

Enable maintenance for individual backend servers: 
/maintenance on <server>
/maintenance off <server>
Players can still connect to other servers in your network. When trying to connect to a maintenance server:
  • Players with bypass permission receive a notification
  • Other players are redirected to a fallback server (if configured)
  • If no fallback is available, they’re disconnected with a message

​
Fallback Server Configuration

Configure fallback servers for when a specific server is under maintenance: 
fallback:
  enabled: true
  # Define fallback servers for specific servers
  fallback-list:
    survival: lobby    # When survival is in maintenance, send to lobby
    skyblock: hub      # When skyblock is in maintenance, send to hub
Players connecting to a maintenance server will be automatically redirected to the configured fallback.

​
Waiting Server

Send all players to a specific waiting server during global maintenance: 
waiting-server:
  enabled: true
  server: waiting    # Server name to send players to
Use this to create a waiting lobby where players can stay while you perform maintenance. 
/maintenance on
Players will be redirected to the waiting server instead of being kicked.

​
Redis Integration

Sync maintenance status across multiple BungeeCord proxies: 
redis:
  enabled: true
  host: localhost
  port: 6379
  password: ""      # Leave empty if no password
  channel: maintenance
With Redis enabled:
  • Maintenance status is synced across all connected proxies
  • Whitelist changes are propagated instantly
  • No need to run commands on each proxy individually
This is essential for large networks with multiple proxy instances.

​
Plugin Integrations

​
ServerListPlus

Soft dependency - Automatically detected. Integrates with ServerListPlus to provide enhanced server list customization during maintenance.

​
LuckPerms

Soft dependency - Context support. Maintenance registers contexts for:
  • Global maintenance status
  • Per-server maintenance status
Allows you to create conditional permissions based on maintenance state.

​
Configuration

BungeeCord configuration includes proxy-specific options: 
# Global maintenance mode
maintenance: false

# Per-server maintenance
proxied-maintenance-servers:
  survival: false
  skyblock: false

# Fallback configuration
fallback:
  enabled: true
  fallback-list:
    survival: lobby

# Waiting server (alternative to kicking)
waiting-server:
  enabled: false
  server: waiting

# Player count customization
playercountmessage: "Maintenance"

# Timer-specific player count
enable-timerspecific-playercountmessage: false
timer-playercountmessage: "Restarting in %TIMER%"

# Commands to run when enabling/disabling per-server maintenance
commands-on-single-maintenance-enable: []
commands-on-single-maintenance-disable: []

​
Permissions

PermissionDescription
maintenance.commandAccess to /maintenance command
maintenance.bypassJoin during maintenance
maintenance.adminFull administrative access
maintenance.joinnotificationReceive join attempt notifications

​
Commands

BungeeCord includes additional commands for proxy management: 
# Global maintenance
/maintenance on                    # Enable global maintenance
/maintenance off                   # Disable global maintenance

# Per-server maintenance
/maintenance on <server>           # Enable maintenance for specific server
/maintenance off <server>          # Disable maintenance for specific server

# Whitelist management
/maintenance add <player>          # Add player to global whitelist
/maintenance remove <player>       # Remove player from whitelist

# Timers
/maintenance start <time>          # Schedule maintenance start
/maintenance end <time>            # Schedule maintenance end

# Configuration
/maintenance reload                # Reload configuration

​
Server List Customization

​
Custom MOTD

Display different MOTDs for global vs per-server maintenance in your configuration.

​
Player Count Message

Customize what appears in the player count slot: 
playercountmessage: "Under Maintenance"
With timers enabled: 
enable-timerspecific-playercountmessage: true
timer-playercountmessage: "Back in %TIMER%"

​
Use Cases

​
Network-Wide Restart

  1. Enable global maintenance: /maintenance on
  2. Players are kicked (or sent to waiting server)
  3. Perform updates on backend servers
  4. Disable maintenance: /maintenance off

​
Individual Server Update

  1. Enable per-server maintenance: /maintenance on survival
  2. Players on survival are sent to fallback (e.g., lobby)
  3. Update the survival server
  4. Disable maintenance: /maintenance off survival

​
Scheduled Maintenance Window

/maintenance start 1h    # Maintenance begins in 1 hour
Players see countdown in MOTD using %TIMER% placeholder.

​
Multi-Proxy Setup

For networks with multiple BungeeCord proxies:
  1. Install Maintenance on all proxies
  2. Set up Redis server (e.g., using Docker)
  3. Configure Redis in each proxy’s config:
redis:
  enabled: true
  host: redis.yournetwork.com
  port: 6379
  password: "your-secure-password"
  channel: maintenance
  1. Reload all proxies: /maintenance reload
Now all commands executed on one proxy will sync to all others.

​
API Usage

For BungeeCord plugin developers: 
import eu.kennytv.maintenance.api.proxy.MaintenanceProxy;
import eu.kennytv.maintenance.api.MaintenanceProvider;

public class YourPlugin extends Plugin {
    private MaintenanceProxy maintenance;

    @Override
    public void onEnable() {
        maintenance = (MaintenanceProxy) MaintenanceProvider.get();
        
        // Check global maintenance
        boolean globalMaintenance = maintenance.isMaintenance();
        
        // Check server-specific maintenance
        boolean survivalMaintenance = maintenance.isMaintenance("survival");
        
        // Enable maintenance for a server
        maintenance.setMaintenance("survival", true);
    }
}
See the API documentation for complete details.

​
Troubleshooting

​
Players bypass maintenance without permission

Check:
  1. Player isn’t on whitelist: /maintenance remove <player>
  2. Player doesn’t have maintenance.bypass from LuckPerms or another permission plugin
  3. Redis sync is working (if using multi-proxy)

​
Fallback server not working

Ensure:
  1. Fallback server exists in BungeeCord’s config.yml
  2. Fallback server is not also in maintenance
  3. Fallback is properly configured in fallback-list

​
Redis sync not working

Verify:
  1. Redis server is running and accessible
  2. Credentials are correct in config
  3. All proxies use the same Redis channel name
  4. Check proxy logs for Redis connection errors

Build docs developers (and LLMs) love

Get started for freeTalk to us