Minecraft Server Hibernation

Avoid wasting resources by starting your Minecraft server automatically when a player joins and stopping it when no one is online
(for vanilla/modded on linux/windows/macos)

version: v2.5.0
Copyright (C) 2019-2023 gekigek99

Join our discord server!

RELEASES:

Download the latest releases on github (for linux, windows and macos)

You can download msh from gekware or compile the dev branch to use a more recent version, but note that it may still need to be tested

PROGRAM COMPILATION:

This version was successfully compiled in go version 1.19
Compilation procedure:

git clone https://github.com/gekware/minecraft-server-hibernation.git  
cd minecraft-server-hibernation/  
git submodule update --init
git checkout dev # execute only if you want to compile the dev branch
go build .

INSTRUCTIONS:

1. Install the Minecraft server you want
2. Edit msh-config.json as needed (check definitions):
   • Folder
   • FileName
   • StartServerParam
   • StopServer
   • Whitelist
   • * TimeBeforeStoppingEmptyServer
   • * others...
3. * put the frozen icon you want in path/to/server.jar/folder (must be called server-icon-frozen, supported formats: .png, .jpg)
4. on the router (to which the server is connected): forward port 25555 to server (tutorial)
5. on the server: open port 25555 (example: ufw firewall)
6. run the msh executable
7. You can connect to the server using the port from the configuration file (default 25555).

* = it's not compulsory to modify this parameter

notes

• msh-config.json is not generated automatically. You will need to download it from the releases.
• Automatically run msh at reboot.
• In server.properties set server-ip=0.0.0.0 to avoid errors when msh tries to connect to the minecraft server.
• You must remove all braces from msh-config.json.

DEFINITIONS:

• Some of these parameters can be configured with command-line arguments (msh --help to know more) (user supplied arguments will override config)

Location of server folder and executable. You can find protocol/version here (but msh should set them automatically):

"Server": {
  "Folder": "{path/to/server/folder}"
  "FileName": "{server.jar}"
  "Version": "1.19.2"
  "Protocol": 760
}

Commands to start and stop minecraft server
StopServerAllowKill allows to kill the server after a certain amount of time (in seconds) when it's not responding

"Commands": {
  "StartServer": "java <Commands.StartServerParam> -jar <Server.FileName> nogui"
  "StartServerParam": "-Xmx1024M -Xms1024M"
  "StopServer": "stop"
  "StopServerAllowKill": 10 # set to -1 to disable
}

Set the logging level for debug purposes

"Debug": 1
# 0 - NONE: no log
# 1 - BASE: basic log
# 2 - SERV: minecraft server log
# 3 - DEVE: developement log
# 4 - BYTE: connection bytes log

Ports configuration - MshPort and MshPortQuery must be different from the respective ones in server.properties - query handling is enabled if EnableQuery: true in msh-config.json AND enable-query=true in server.properties

"MshPort": 25555        # port to which players can join
"MshPortQuery": 25555   # port to which stats query requests are performed from clients
"EnableQuery": true     # enable query handling

TimeBeforeStoppingEmptyServer sets the time (after the last player disconnected) that msh waits before hibernating the minecraft server

"TimeBeforeStoppingEmptyServer": 30

SuspendAllow enables msh to suspend minecraft server process when there are no players online
To mitigate ram usage you can set a high swappiness (on linux)
- pro: player wait time to join frozen server is ~0
- cons: ram usage as minecraft server without msh (cpu remains ~0)

SuspendRefresh enables refresh of minecraft server suspension every set seconds (to avoid watchdog crash at unsuspension)
- setting these variables and SuspendRefresh might prevent minecraft server watchdog crash when SuspendAllow is enabled

"SuspendAllow": false
"SuspendRefresh": -1    # set -1 to disable, advised value: 120 (reduce if minecraft server keeps crashing)

Hibernation and Starting server description

"InfoHibernation": "                   §fserver status:\n                   §b§lHIBERNATING"
"InfoStarting": "                   §fserver status:\n                    §6§lWARMING UP"

Set to false if you don't want notifications (every 20 minutes)

"NotifyUpdate": true
"NotifyMessage": true

Whitelist contains IPs and player names that are allowed to start the server (leave empty to allow everyone)
WhitelistImport adds whitelist.json to player names that are allowed to start the server
unknown clients are not allowed to start the server, but can join

"Whitelist": ["127.0.0.1", "gekigek99"]
"WhitelistImport": false

ShowResourceUsage enables the logging of the msh tree process cpu/ram usage percent
for debug purposes (debug level 3 required)

"ShowResourceUsage": false

ShowInternetUsage enables the logging of the msh connection usage
for debug purposes (debug level 3 required)

"ShowInternetUsage": false

CREDITS:

Author: gekigek99

Contributors: najtin, f8ith, Br31zh, someotherotherguy, navidmafi, cromefire, andreblanke, KyleGospo, A-wels, dxomg

Docker branch (outdated): lubocode

Pterodactyl egg: BolverBlitz

If you wish to contribute, please create a pull request using the dev branch as the base for your changes

Give a star to this repository on github!