BungeeCord

Install and configure Maintenance on BungeeCord proxy servers

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

Permission	Description
maintenance.command	Access to /maintenance command
maintenance.bypass	Join during maintenance
maintenance.admin	Full administrative access
maintenance.joinnotification	Receive 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

4. 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