BungeeCord

The Maintenance plugin provides advanced proxy-level maintenance features for BungeeCord networks.

Requirements

BungeeCord (latest version recommended)
Java 17 or higher

Installation

Download the latest version from Hangar
Place the JAR file in your BungeeCord plugins/ directory
Restart your proxy
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

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

Individual Server Update

Enable per-server maintenance: /maintenance on survival
Players on survival are sent to fallback (e.g., lobby)
Update the survival server
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:

Install Maintenance on all proxies
Set up Redis server (e.g., using Docker)
Configure Redis in each proxy’s config:

redis:
  enabled: true
  host: redis.yournetwork.com
  port: 6379
  password: "your-secure-password"
  channel: maintenance

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:

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

Fallback server not working

Ensure:

Fallback server exists in BungeeCord’s config.yml
Fallback server is not also in maintenance
Fallback is properly configured in fallback-list

Redis sync not working

Verify:

Redis server is running and accessible
Credentials are correct in config
All proxies use the same Redis channel name
Check proxy logs for Redis connection errors

Get Started

Configuration

Platform Guides

Features

Commands & Permissions

Requirements

Installation

Proxy-Specific Features

Global Maintenance

Per-Server Maintenance

Fallback Server Configuration

Waiting Server

Redis Integration

Plugin Integrations

ServerListPlus

LuckPerms

Configuration

Permissions

Commands

Server List Customization

Custom MOTD

Player Count Message

Use Cases

Network-Wide Restart

Individual Server Update

Scheduled Maintenance Window

Multi-Proxy Setup

API Usage

Troubleshooting

Players bypass maintenance without permission

Fallback server not working

Redis sync not working

​Requirements

​Installation

​Proxy-Specific Features

​Global Maintenance

​Per-Server Maintenance

​Fallback Server Configuration

​Waiting Server

​Redis Integration

​Plugin Integrations

​ServerListPlus

​LuckPerms

​Configuration

​Permissions

​Commands

​Server List Customization

​Custom MOTD

​Player Count Message

​Use Cases

​Network-Wide Restart

​Individual Server Update

​Scheduled Maintenance Window

​Multi-Proxy Setup

​API Usage

​Troubleshooting

​Players bypass maintenance without permission

​Fallback server not working

​Redis sync not working

Requirements

Installation

Proxy-Specific Features

Global Maintenance

Per-Server Maintenance

Fallback Server Configuration

Waiting Server

Redis Integration

Plugin Integrations

ServerListPlus

LuckPerms

Configuration

Permissions

Commands

Server List Customization

Custom MOTD

Player Count Message

Use Cases

Network-Wide Restart

Individual Server Update

Scheduled Maintenance Window

Multi-Proxy Setup

API Usage

Troubleshooting

Players bypass maintenance without permission

Fallback server not working

Redis sync not working