MCSDNotifier

Lets your Minecraft Server make sd_notify(3) calls to support some systemd features:

• Proper detection of when the server is fully started (so dependent units start at the right time)

• Killing the server if startup takes longer than TimeoutStartSec=

• Killing the server if it hangs (no ticks finished) for longer than WatchdogSec=. This is more reliable than the watchdog integrated in Spigot, because it is implemented outside the server process

• Killing the server if stop takes longer than TimeoutStopSec=

• Sending a status string back to the service manager that is displayed in systemctl status:

    $ systemctl status minecraft
    ● minecraft.service - Minecraft Server
    [...]
    Status: "Running Paper git-Paper-280 (MC: 1.20.2) with 0/20 players, TPS avg: 20.00 20.00 20.00"
    Memory: 1.3G
    CPU: 1min 1.049s
  

  This string can be overwritten by other plugins by registering a custom StatusProvider service

Requirements

• Java 9+
• Paper 1.15.2+ (or a fork)
• libsystemd (if you are running systemd you most likely have this already)
• (Only for Servers 1.16 and older) JNA
  • Only if the plugin tells you that JNA is missing when it starts, download a copy of the latest JNA 5.x jar and put it in the classpath of the Server. For technical reasons this dependency cannot be included in the plugin

Paper is required for a number of improvements that Bukkit/Spigot lack:

• Better handling of SIGINT (Ctrl+C) as long as you don't disable the JLine console
• Availability of Server#getTPS() for a more useful status string
• Paper 1.15.2+: Availability of Server#isStopping()
• Paper 1.19.2+: Fixed plugin loggers breaking when server is shut down by signals

Usage

Copy the MCSDNotifier-<VERSION>.jar file of the latest release into your plugins/ directory. This plugin has no configuration and saves no data.

Run your Minecraft Server with a systemd service unit with Type=notify. For a full example, see minecraft.service. Remember to adjust the user/group, working directory, Xms/Xmx and the filename of the server jar. The server console can be accessed by running sudo -u minecraft -- script -c "screen -x minecraft" /dev/null.

Spigot watchdog

Since the systemd watchdog will forcefully kill the server, it is recommended to leave the Spigot watchdog enabled to try and stop the server gracefully first. In spigot.yml configure:

settings:
  timeout-time: 60
  restart-on-crash: true
  restart-script: ./should-not-exist-lksdbgqp390t2q33t3w4uj

Since MCSDNotifier only notifies the watchdog every 10 seconds, the service manager watchdog can trigger early, so make sure that WatchdogSec= is at least 15 seconds higher than spigot.yml timeout-time. Leave restart-on-crash enabled, but set restart-script to a filename that does not exist. This will make the server stop if Spigot watchdog detects a hang. The systemd service will then restart the server automatically; there is no need to fiddle around with shell scripts.

Building

Needs JDK 8+ installed. To build the plugin, run:

./mvnw

This command will download a copy of Maven and use it to build the plugin. Plugin jar file is placed in target/mcsdnotifier-<VERSION>.jar.

Backlog

• Bukkit/Spigot API 1.15+: Upgrade JNA dependency to 5.8.0
• Paper API 1.15+: Use ServerTickBeginEvent for NotifyListener#onTick (?)
• Spigot API 1.16+: Try plugin.yml libraries key for JNA dependency

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see https://www.gnu.org/licenses/.