Maintenance

About This Plugin

This plugin lets you activate a maintenance mode on your Paper, Velocity, Bungee, and Sponge server, which will prevent players without a permission to join the server.

Maintenance uses MiniMessage as the component text format. LEGACY TEXT FORMATTING (§a/&a) IS NOT SUPPORTED

• Use https://webui.adventure.kyori.net/ to preview parsed components
• You can find full documentation on the format (including normal colors and formatting, rgb, click/hover events, and more) here: https://docs.adventure.kyori.net/minimessage/format

Features

Its features include:

• A custom motd as well as server icon, that will be shown during maintenance
• Start- and endtimers, which will enable/disable maintenance mode after the time is up (accepts a duration format like 1h5m30s, 5m, or 90s)
• Schedule timers, which will enable maintenance, then disable it after a given amount of time
• A '%TIMER%' variable usable in the pingmessage, to show the time until a running endtimer finishes (other variables and tricks are explained in the configuration file's comments)
• A maintenance whitelist, to grant specific players the ability to join while you're working on your server
• Notifications when players try to join your server during maintenance
• Nearly all messages are editable via the language file, given in a multitude of different languages

Additional features on Velocity/Bungee:

• Only want to enable maintenance on a single server? You can also do so by using the /maintenance <on/off> <servername> command
• Link multiple proxy instances with a MySQL database connection, so you don't have to enable/disable maintenance on each proxy by hand
• Waiting servers during full proxy maintenance, as well as fallback servers to go to when a single proxied server is under maintenance
• Want to have PlaceholderAPI placeholders on Paper? Get the MaintenanceAddon

playercountmessage: "Maintenance                                                                    AAAA"

IMPORTANT: If using the plugin on a Spigot server, the plugin ProtocolLib is required to use Maintenance to its full extent.

Issues/Support

Did you find a bug? Use the issue tracker Other questions or problems? Join the support Discord guild ✨

German Plugin Tutorial
@YouTube

Localization

If you want to join the localization crew, join the Discord to get the proofreader or translator role on Crodwin. All translations are done here: https://crowdin.com/project/maintenance

Commands

Arguments in < > are necessary, those in [ ] aren't (can be omitted).

• /maintenance <on/off> [server] will set the status of the maintenance mode
• /maintenance reload reloads the config and maintenance-icon file
• /maintenance <add/remove> <player/uuid> allows specific players to join on the server when maintenance is enabled
• /maintenance whitelist returns a list of all players on the
• maintenance whitelist
• /maintenance starttimer [server] will enable maintenance mode after the time is up (accepts h/m/s durations, e.g. 1h5m30s or 90s)
• /maintenance endtimer [server] will enable maintenance mode for the given time (accepts h/m/s durations, e.g. 1h5m30s or 90s). After the time is up, it'll be disabled again
• /maintenance schedule [server] will enable maintenance mode after the given time, then disable it according to the second parameter (accepts h/m/s durations, e.g. 1h5m30s or 90s)
• /maintenance aborttimer cancels a running start-/endtimer
• /maintenance setmotd <1/2> sets a motd for maintenance mode
• /maintenance motd lists the currently set maintenance motds
• /maintenance update remotely downloads the newest version of the plugin onto your server
• /maintenance dump dumps some server information, used for bug reports

Permissions

• maintenance.admin - super permission, that grants access to all perms below
• maintenance.bypass - join the server during maintenance
• maintenance.command - use the "/maintenance" command (also required to use the subcommands)
• maintenance.toggle - use the "/maintenance <on/off>" commands
• maintenance.reload - use the "/maintenance reload" command
• maintenance.update - use the "/maintenance <update/forceupdate>" commands
• maintenance.timer - use the "/maintenance <starttimer/endtimer> " and "/maintenance timer abort" commands
• maintenance.whitelist.add - use the "/maintenance add " command
• maintenance.whitelist.remove - use the "/maintenance remove " command
• maintenance.whitelist.list - use the "/maintenance whitelist" command
• maintenance.setmotd - use the "/maintenance setmotd <1/2> " command
• maintenance.motd - use the "/maintenance motd" command
• maintenance.dump - use the "/maintenance dump" command
• maintenance.joinnotification - if enabled: sends a notification to you if a player tries to join the server while maintenance is enabled

Extra permissions for the Velocity/Bungee part:

• maintenance.singleserver.bypass.<server> - join the proxied server during maintenance
• maintenance.singleserver.toggle - use the "/maintenance <on/off> " commands
• maintenance.singleserver.timer - use the "/maintenance <starttimer/endtimer> " and "/maintenance timer abort " commands
• maintenance.singleserver.status - use the "/maintenance status" command

IMPORTANT - If you are using the plugin on your proxyserver: You have to have these permissions on the proxy, not on the backend servers! The best way of doing this is using a proper permissions plugin on the proxy (for example LuckPerms).

Configuration

If you are using Maintenance on Spigot (ew) or a Paper version below 1.12.2 (also ew), you need to have ProtocolLib installed to use the custom server-icon and the playercount-messages! The rest however is also accessible without it.

proxied-maintenance-servers, fallback and mysql section are only for the Velocity/Bungee version.

# Changes the language of command feedback/messages.
# If you find missing translations or want to contribute, see https://crowdin.com/project/maintenance
# Currently available are: en (English), de (German), fr (French), pt (Portuguese), es (Spanish), ru (Russian), zh (Chinese), it (Italian),
#  pl (Polish), tr (Turkish), sv (Swedish), uk (Ukrainian), ja (Japanese), da (Danish), ko (Korean), hu (Hungarian), vi (Vietnamese)
language: en

# Enables maintenance mode.
maintenance-enabled: false

# Enables maintenance on certain servers managed by your proxy instance(s).
proxied-maintenance-servers:
  - PaperServer1
# - AnotherServer

# If maintenance is enabled on a proxied server with players on it, they will be sent to the fallback server instead of being kicked off the network.
# If the fallback server is not reachable/not set, they will just be kicked off the network.
# This can also be set to an array to set multiple fallback servers, in case one server is not always reachable: 'fallback: [s1, s2, s3, ...]'
fallback: lobby

# If maintenance is enabled globally, you can define a "waiting" lobby for players to be sent to instead of being kicked.
# Leave this empty to disable.
waiting-server: ""

# The message (MOTD) shown in the multiplayer server list motd when maintenance is enabled.
# If you put in multiple entries, one of them will be chosen randomly on every ping.
# If running an endtimer, the time left can be displayed by including '%TIMER%' in a ping message.
ping-message:
  enabled: true
  messages:
    - "<red>Currently under maintenance<br><gradient:#fbffc2:#0fffff>We will be back soon!"
  # If set to true and an endtimer is currently running, a message from this pool will be chosen
  # instead of the ones above, so you can have different messages for when an endtimer is running/not running.
  enable-timer-specific-messages: true
  timer-messages:
    - "<red>Currently under maintenance<br><gradient:#fbffc2:#fffff>Come back in:</gradient> <color:#aa55ee>%TIMER%"

# If enabled, the message below will be shown in the top right corner of the server in the server list, where the player count would normally be displayed.
# You can use '%ONLINE%' and '%MAX%' if you want to include the player count in a custom message (e.g. "Maintenance %ONLINE%/%MAX%").
# DOES NOT SUPPORT RGB!
player-count-message:
  enabled: true
  message: "<dark_red>Maintenance"
  # If set to true and an endtimer is currently running, the timer message will be used instead of the normal one.
  enable-timer-specific-message: false
  timer-message: "<dark_red>Come back in: <yellow>%TIMER%"

# Is shown when you move your mouse above the text in the top right corner of the server in the server list, where the player count would normally be displayed.
# DOES NOT SUPPORT RGB!
player-list-hover-message:
  enabled: true
  message: "<red>Currently under<br><red>maintenance"
  # If set to true and an endtimer is currently running, the timer message will be used instead of the normal one.
  enable-timer-specific-message: false
  timer-message: "<red>Come back in:<br><red><yellow>%TIMER%"

# Any extra commands inside the arrays will be executed when maintenance is enabled/disabled.
# Example: commands-on-maintenance-enable: ["say hello!", "stop"]
commands-on-maintenance-enable: []
commands-on-maintenance-disable: []

# Any extra commands inside the "all" array will be executed when maintenance is enabled/disabled on a proxied server.
# You can also add commands for specific servers by adding a new array with the server name as key.
# In the commands, you can use the %SERVER% placeholder to get the server name.
# Example: coolserver: ["say hello", "othercommand %SERVER%"]
commands-on-single-maintenance-enable:
  all: []
commands-on-single-maintenance-disable:
  all: []

# If set to true, the server icon will be changed to the 'maintenance-icon.png' file in the plugin's folder during maintenance.
custom-maintenance-icon: false

# If set to true, players with the 'maintenance.joinnotification' permission will receive a message,
# that a player tried to join the server while maintenance is enabled.
send-join-notification: false

# Set this to false if you do not want players to be kicked when you enable maintenance (new connections will still be blocked).
kick-online-players: true

# When fetched player does not exist then fallback to offline uuid. Only works on proxies like Velocity or BungeeCord
fallback-to-offline-uuid: false

# If enabled and the server is restarted while running an endtimer, the timer will be continued after the restart.
# If the timer ends while the server is offline, maintenance will be disabled as soon as the server starts again.
continue-endtimer-after-restart:
  enabled: false
  # This value is set everytime an endtimer is started, cancelled or ended.
  # Do not manually change this value.
  end: 0

# If using the timer command: In what intervalls before enabling/disabling maintenance there will be a broadcast.
timer-broadcast-for-seconds: [1200, 900, 600, 300, 120, 60, 30, 20, 10, 5, 4, 3, 2, 1]

# If you have 2 or more proxy instances, the database connection will make sure all proxies
# have the same maintenance status, so you won't have to enable/disable it on every proxy by hand.
mysql:
  use-mysql: false
  host: host
  port: 3306
  database: database
  username: username
  password: password
  # Requests to the database will only be made at least x seconds after the last request,
  # so there won't be a request on every single ping on a server with many players.
  #
  # Set this to 0 to make a database request on (almost) every single ping.
  # (0 is not recommended if having more than a hundred concurrent players, then I'd recommend keeping it from 10-60).
  update-interval: 15
  # If you for some reason cannot establish SSL connections to your database, you may disable it here (not recommended).
  use-ssl: true

# If disabled, you will no longer receive any messages if there is an update.
# Not recommended to disable, as new versions generally tend to run better and with fewer bugs.
# However, you can always check for updates manually using the '/maintenance update' command.
update-checks: true

# Used for autoupdating the config, do not change this value.
config-version: 9

#You can use https://webui.adventure.kyori.net/ to edit and preview the formatted text
#For a full list of formats and fancy examples, see https://docs.adventure.kyori.net/minimessage/format.html
#Messages containing the placeholder "<prefix>" will have it replaced with the following string
prefix: "<dark_gray>[<yellow>Maintenance<dark_gray>] "
noPermission: "<red>You do not have the permission to execute that command."
kickmessage: "<red>The server is currently under maintenance!<br>Try again later!"
maintenanceActivated: "<prefix><gold>Maintenance mode is now activated."
maintenanceDeactivated: "<prefix><gold>Maintenance mode is now deactivated."
alreadyEnabled: "<prefix><red>Maintenance is already enabled!"
alreadyDisabled: "<prefix><red>Maintenance is already disabled!"
endtimerBroadcast: "<prefix><gray>Maintenance mode will be disabled in <gold>%TIME%<gray>."
endtimerStarted: "<prefix><green>Started timer: <gray>Maintenance mode will be deactivated in <gold>%TIME%<gray>."
starttimerBroadcast: "<prefix><gray>Maintenance mode will be enabled in <gold>%TIME%<gray>."
starttimerStarted: "<prefix><green>Started timer: <gray>Maintenance mode will be activated in <gold>%TIME%<gray>."
scheduletimerBroadcast: "<prefix><gray>Maintenance mode will be enabled in <gold>%TIME% <gray>and will last for <gold>%DURATION%<gray>."
scheduletimerStarted: "<prefix><green>Started timer: <gray>Maintenance mode will be enabled in <gold>%TIME% <gray>and will last for <gold>%DURATION%<gray>."
timerAlreadyRunning: "<prefix><red>There is already a timer scheduled!"
timerNotRunning: "<prefix><red>There is currently no running timer."
timerCancelled: "<prefix><red>The current timer has been disabled."
timerTooLong: "<prefix><red>The duration has to be less than 28 days!"
timerMotdDisabled: "<prefix><red>You have to set 'enable-timerspecific-messages' in the config to 'true', if you want to use/edit timerspecific motds."
motdTimer: "%HOURS%:%MINUTES%:%SECONDS%"
motdTimerNotRunning: "-"
joinNotification: "<prefix><yellow>%PLAYER% <red>tried to join the server."
motdList: "<prefix><gray>List of your maintenance motds:"
motdListEmpty: "<prefix><red>You don't have any maintenance motds set!"
reload: "<prefix><green>Reloaded config, whitelistedplayers, language file and the maintenance icon."
removedMotd: "<prefix><green>Removed motd number %INDEX%."
removeMotdError: "<prefix><red>You only have one motd, so you cannot remove any!"
setMotd: "<prefix><green>Set line %LINE% of the %INDEX%. maintenance motd to %MOTD%"
setMotdIndexError: "<prefix><red>You currently have %MOTDS% motds, so you have to pick a number between 1 and %NEWAMOUNT%."
setMotdLineError: "<prefix><red>The second argument has to be the line number (1 or 2)!"
updateDownloading: "<prefix><red><bold>Downloading update..."
updateFailed: "<prefix><dark_red><bold>Update failed!"
updateFinished: "<prefix><green><bold>The update was successful! To prevent issues with tasks and to complete the update, you have to restart the server!"
whitelistedPlayers: "<prefix><gold>Whitelisted players for maintenance:"
whitelistedPlayersFormat: "<dark_gray>- <yellow>%NAME% <dark_gray>(<gray>%UUID%<dark_gray>)"
whitelistAdded: "<prefix><green>Added <aqua>%PLAYER% <green>to the maintenance whitelist!"
whitelistAlreadyAdded: "<prefix><aqua>%PLAYER% <red>already is in the maintenance whitelist!"
whitelistRemoved: "<prefix><green>Removed <aqua>%PLAYER% <green>from the maintenance whitelist!"
whitelistNotFound: "<prefix><red>This player is not in the maintenance whitelist!"
whitelistEmpty: "<prefix><red>The maintenance whitelist is empty! Use <yellow>/maintenance add <player/uuid> <red>to add someone!"
playerNotFound: "<prefix><red>No player with this name has played on this server before."
playerNotFoundUuid: "<prefix><red>No player with that uuid could be found."
playerNotOnline: "<prefix><red>There is no player online with that name."
offlinePlayerFetchError: "<prefix><red>There was an error while fetching offline player. Please try again later."
invalidUuid: "<prefix><red>Invalid uuid format!"
#Messages for the Bungee/Velocity part, you can ignore them if you use the plugin on Paper/Sponge
sentToWaitingServer: "<prefix><red>You have been sent to a waiting server!"
forceWaitingServer: "<prefix><red>You cannot leave the waiting server while maintenance is enabled!"
serverNotFound: "<prefix><red>No server with this name is registered on the proxy!"
singleTimerAlreadyRunning: "<prefix><red>There is already a timer scheduled for that server!"
singleTimerCancelled: "<prefix><red>The current timer for server <yellow>%SERVER% <red>has been disabled."
singleTimerNotRunning: "<prefix><red>There is currently no running timer for that server."
singleEndtimerBroadcast: "<prefix><gray>Maintenance mode on server %SERVER% will be disabled in <gold>%TIME%<gray>."
singleEndtimerStarted: "<prefix><green>Started timer: <gray>Maintenance mode on server %SERVER% will be deactivated in <gold>%TIME%<gray>."
singleStarttimerBroadcast: "<prefix><gray>Maintenance mode on server %SERVER% will be enabled in <gold>%TIME%<gray>."
singleStarttimerStarted: "<prefix><green>Started timer: <gray>Maintenance mode on server %SERVER% will be activated in <gold>%TIME%<gray>."
singleScheduletimerBroadcast: "<prefix><gray>Maintenance mode on server %SERVER% will be enabled in <gold>%TIME% <gray>and will last for <gold>%DURATION%<gray>."
singleScheduletimerStarted: "<prefix><green>Started timer: <gray>Maintenance mode on server %SERVER% will be enabled in <gold>%TIME% <gray>and will last for <gold>%DURATION%<gray>."
singleMaintenanceKick: "<prefix><red>The server %SERVER% is currently under maintenance! Try again later!"
singleMaintenanceKickComplete: "<red>The server %SERVER% is under maintenance!<br>You may try to rejoin to go onto another server!"
singleMaintenanceActivated: "<prefix><gold>Maintenance mode is now activated on server <yellow>%SERVER%<gold>."
singleMaintenanceDeactivated: "<prefix><gold>Maintenance mode is now deactivated on server <yellow>%SERVER%<gold>."
singleServerAlreadyEnabled: "<prefix><red>Maintenance is already enabled on server <yellow>%SERVER%<red>!"
singleServerAlreadyDisabled: "<prefix><red>Maintenance is already disabled on server <yellow>%SERVER%<red>!"
singleServerMaintenanceList: "<prefix><gray>Proxied servers, that have maintenance enabled:"
singleServerMaintenanceListEmpty: "<prefix><gray>There are no proxied servers that are under maintenance."
singleServerMaintenanceListEntry: "<dark_grey>- <aqua>%SERVER%"
second: "second"
seconds: "seconds"
minute: "minute"
minutes: "minutes"
hour: "hour"
hours: "hours"
helpHeader: "<dark_gray>========[ <yellow>%NAME% <dark_gray>| <yellow>%PAGE%/%MAX% <dark_gray>]========"
helpPageNotFound: "<prefix><red>There is no page with that number!"
helpNextPage: "<gray>Use <aqua>/maintenance help %PAGE% <gray>to get to the next help window."
helpAbortTimer: "<gold>/maintenance aborttimer <gray>(If running, the current timer will be aborted)"
helpEndtimer: "<gold>/maintenance endtimer <disable in> <gray>(After the given time, e.g. 1h5m, maintenance mode will be disabled)"
helpStarttimer: "<gold>/maintenance starttimer <enable in> <gray>(After the given time, e.g. 1h5m, maintenance mode will be enabled)"
helpScheduleTimer: "<gold>/maintenance scheduletimer <enable in> <maintenance duration> <gray>(After the given time, e.g. 1h5m, maintenance mode will be enabled)"
helpDebug: "<gold>/maintenance debug <gray>(Enables some debug logging)"
helpDump: "<gold>/maintenance dump <gray>(Dumps some server information, used for bug reports)"
helpHelp: "<gold>/maintenance help [page] <gray>(Shows this beautiful help window)"
helpMotd: "<gold>/maintenance motd [timer] <gray>(Lists the currently set maintenance motds. If specifying 'timer', the timer motds are shown)"
helpRemoveMotd: "<gold>/maintenance removemotd [timer] <index> <gray>(Removes a maintenance motd. If using 'timer' as an argument, a timerspecific pingmessage will be removed)"
helpSetMotd: "<gold>/maintenance setmotd [timer] <index> <1/2> <message> <gray>(Sets a motd for maintenance mode. If using 'timer' as an argument, a timerspecific pingmessage will be set)"
helpReload: "<gold>/maintenance reload <gray>(Reloads the config file, whitelist file and the server-icon)"
helpToggle: "<gold>/maintenance <on/off> <gray>(Enables/disables maintenance mode)"
helpUpdate: "<gold>/maintenance update <gray>(Remotely downloads the newest version of the plugin onto your server)"
helpWhitelist: "<gold>/maintenance whitelist <gray>(Shows all whitelisted players for the maintenance mode)"
helpWhitelistAdd: "<gold>/maintenance add <name/uuid> <gray>(Adds the player to the maintenance whitelist, so they can join the server even though maintenance is enabled)"
helpWhitelistRemove: "<gold>/maintenance remove <name/uuid> <gray>(Removes the player from the maintenance whitelist)"
#Messages for the Bungee/Velocity part, you can ignore them if you use the plugin on Paper/Sponge
helpAbortSingleTimer: "<gold>/maintenance aborttimer [server] <gray>(If running, the current timer will be aborted)"
helpSingleEndtimer: "<gold>/maintenance endtimer [server] <disable in> <gray>(After the given time, e.g. 1h5m, maintenance mode will be disabled)"
helpSingleStarttimer: "<gold>/maintenance starttimer [server] <enable in> <gray>(After the given time, e.g. 1h5m, maintenance mode will be enabled)"
helpSingleScheduleTimer: "<gold>/maintenance scheduletimer [server] <enable in> <maintenance duration> <gray>(After the given time, e.g. 1h5m, maintenance mode will be enabled)"
helpSingleToggle: "<gold>/maintenance <on/off> [server] <gray>(Enables/disables maintenance mode)"
helpStatus: "<gold>/maintenance status <gray>(Lists all proxied servers, that are currently under maintenance)"
#Used for autoupdating the language file, do not change this value.
language-version: 2

MySQL/Multi-Proxy Support

Only available in the Bungee/Velocity version! By enabling MySQL in the config, you can even connect multiple proxy-servers to a set value in your database, so you won't have to enable/disable maintenance on each proxy by hand!