Skip to main content
For large networks running multiple BungeeCord or Velocity proxy instances, the Maintenance plugin supports Redis-based synchronization to keep maintenance status and whitelists in sync across all proxies.

​
Overview

Without synchronization, each proxy instance maintains its own maintenance state and whitelist. This means:
  • Enabling maintenance on Proxy A doesn’t affect Proxy B
  • Whitelisting a player on Proxy A doesn’t whitelist them on Proxy B
  • Players could bypass maintenance by connecting through a different proxy
Redis synchronization solves this by providing a central data store that all proxies read from and write to in real-time.

​
What Gets Synchronized

When Redis is enabled, the following data is synchronized across all proxy instances:
  • Global maintenance status (enabled/disabled)
  • Per-server maintenance status (which backend servers are under maintenance)
  • Whitelisted players (UUID and username mappings)
Redis synchronization is only available on BungeeCord and Velocity proxy platforms. It does not apply to Spigot, Paper, or Sponge servers.

​
Configuration

Enable and configure Redis in your config.yml: 
# If you have 2 or more proxy instances, the Redis connection will make sure all proxies
# have the same maintenance status (global as well as per server) and whitelisted players,
# so you won't have to update these on every proxy by hand.
redis:
  enables: false
  # Make sure your Redis instance is properly protected.
  # URI format: redis[s]://[[username][:password]@][host][:port][/db-number]
  # E.g. an SSL connection to a password protected redis could look like this: "rediss://user:[email protected]:6379"
  uri: "redis://localhost:6379"

​
URI Format

The Redis URI follows this structure: 
redis[s]://[[username][:password]@][host][:port][/db-number]

​
Connection Examples

Local Redis without authentication: 
uri: "redis://localhost:6379"
Remote Redis with password: 
uri: "redis://:[email protected]:6379"
SSL connection with authentication: 
uri: "rediss://user:[email protected]:6379"
Specific database number: 
uri: "redis://localhost:6379/2"
Username and password: 
uri: "redis://admin:[email protected]:6379/1"
Always use a password-protected Redis instance when running in production. An open Redis instance can be a serious security vulnerability.

​
Setup Instructions

1

Install Redis

Install Redis on a server accessible by all your proxy instances. This can be:
  • The same machine as one of your proxies
  • A dedicated Redis server
  • A managed Redis service (Redis Cloud, AWS ElastiCache, etc.)
# Example: Install Redis on Ubuntu/Debian
sudo apt update
sudo apt install redis-server

# Enable and start Redis
sudo systemctl enable redis-server
sudo systemctl start redis-server
2

Configure Redis security

Set a strong password in your Redis configuration:
# Edit redis.conf
sudo nano /etc/redis/redis.conf

# Add or modify:
requirepass your_strong_password_here

# Restart Redis
sudo systemctl restart redis-server
3

Configure firewall rules

Ensure your Redis port (default 6379) is only accessible from your proxy servers:
# Example: Allow only specific IPs
sudo ufw allow from 10.0.0.10 to any port 6379
sudo ufw allow from 10.0.0.11 to any port 6379
4

Enable Redis in config.yml

On each proxy instance, update the config:
redis:
  enables: true
  uri: "redis://:your_password@redis-host:6379"
5

Reload all proxies

Reload the Maintenance plugin on all proxy instances:
/maintenance reload
Check the console for:
[Maintenance] Trying to open Redis connection...
[Maintenance] Connected to Redis!
6

Test synchronization

On Proxy A:
/maintenance on
On Proxy B, verify maintenance is enabled:
/maintenance status
The status should show maintenance is enabled across all proxies.

​
How It Works

​
Redis Keys

The plugin uses these Redis keys to store synchronized data:
  • maintenance:status - Global maintenance enabled/disabled state
  • maintenance:servers - Set of server names currently under maintenance
  • maintenance:whitelist - Hash map of whitelisted player UUIDs and usernames
  • maintenance:stream - Stream for real-time update notifications

​
Real-Time Synchronization

When you make a change on one proxy:
  1. Command executed on Proxy A: /maintenance on
  2. Update saved to Redis: maintenance:status set to true
  3. Stream message published: Notifies all proxies of the change
  4. Other proxies receive update: Proxy B, C, D all update their local state
  5. Synchronization complete: All proxies now reflect the new state
This happens in real-time (typically within milliseconds) with no manual intervention required.

​
Architecture Example

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Proxy A   │────▶│    Redis    │◀────│   Proxy B   │
│  (US East)  │     │   Server    │     │  (US West)  │
└─────────────┘     └─────────────┘     └─────────────┘
                           ▲
                           │
                           │
                    ┌──────┴──────┐
                    │   Proxy C   │
                    │   (Europe)  │
                    └─────────────┘

All proxies synchronize maintenance status, per-server
maintenance, and whitelisted players through Redis

​
Synchronized Operations

​
Global Maintenance

# Run on any proxy - affects all proxies
/maintenance on
/maintenance off

​
Per-Server Maintenance

# Run on any proxy - affects the backend server across all proxies
/maintenance on survival
/maintenance off creative

​
Whitelist Management

# Add player on Proxy A - whitelisted on all proxies
/maintenance whitelist add Notch

# Remove player on Proxy B - removed from all proxies
/maintenance whitelist remove Notch

​
Timers

# Start timer on any proxy - broadcasts to all proxies
/maintenance endtimer 30m
Timers are synchronized, but timer broadcasts will be sent from each proxy independently. This is expected behavior and ensures all players on all proxies receive notifications.

​
Troubleshooting

​
Connection Failed

Error: Error while trying to open Redis connection! Solutions:
  • Verify Redis is running: redis-cli ping (should return PONG)
  • Check the URI format is correct
  • Ensure the password is correct
  • Verify network connectivity between proxy and Redis
  • Check firewall rules allow the connection

​
Authentication Failed

Error: NOAUTH Authentication required Solutions:
  • Add password to URI: redis://:password@host:6379
  • Verify the password matches your Redis configuration
  • Check Redis requirepass setting in redis.conf

​
Synchronization Delays

Symptom: Changes take several seconds to propagate Solutions:
  • Check network latency between proxies and Redis
  • Monitor Redis server load and memory
  • Ensure Redis server has adequate resources
  • Consider using a faster network or dedicated Redis instance

​
Inconsistent State

Symptom: Different proxies show different maintenance status Solutions:
  1. Reload all proxies: /maintenance reload
  2. Verify all proxies have the same Redis URI configured
  3. Check Redis logs for errors
  4. Restart all proxy instances if issues persist

​
Best Practices

​
Security

  • Always use authentication: Never run Redis without a password in production
  • Use SSL/TLS: For connections over the internet, use rediss:// (Redis over SSL)
  • Restrict access: Configure firewall rules to only allow proxy servers
  • Regular updates: Keep Redis updated to the latest stable version

​
Performance

  • Dedicated Redis instance: For large networks, use a dedicated Redis server
  • Monitor Redis: Track memory usage, connection count, and latency
  • Use persistence: Enable Redis persistence (RDB or AOF) to prevent data loss
  • Connection pooling: The plugin automatically manages connection pools

​
High Availability

  • Redis Sentinel: For automatic failover, consider Redis Sentinel
  • Redis Cluster: For horizontal scaling, use Redis Cluster
  • Backup strategy: Regularly backup your Redis data
  • Health monitoring: Monitor Redis availability and alert on failures

​
Example Production Setup

# Production Redis configuration
redis:
  enables: true
  uri: "rediss://maintenance-user:[email protected]:6380/0"

# Use:
# - rediss:// for SSL/TLS encryption
# - Strong random password
# - Internal network hostname
# - Non-default port (6380) for additional security
# - Dedicated database number (0)

​
Monitoring

Check Redis connection status in your proxy logs: 
[Maintenance] Trying to open Redis connection...
[Maintenance] Connected to Redis!
Monitor Redis operations: 
# Connect to Redis CLI
redis-cli -a your_password

# Monitor real-time commands
MONITOR

# Check key values
GET maintenance:status
SMEMBERS maintenance:servers
HGETALL maintenance:whitelist

# View stream entries
XRANGE maintenance:stream - +

Build docs developers (and LLMs) love

Get started for freeTalk to us