Backup script for Minecraft servers on Linux.
Supports servers running in screen, tmux, or with RCON enabled. Supports tar
file or restic
backup backends.
- Create backups of your world folder
- Manage deletion of old backups
- "thin" - keep last 24 hourly, last 30 daily, and use remaining space for weekly backups
- "sequential" - delete oldest backup
- Works on vanilla (no plugins required)
- Print backup status to the Minecraft chat
wget https://github.com/nicolaschan/minecraft-backup/releases/latest/download/backup.sh
chmod +x backup.sh
Make sure your system has tar
and your chosen compression algorithm (gzip
by default) installed.
If using RCON, you will also need to have the xxd
command.
# If connecting with RCON:
./backup.sh -c -i /home/user/server/world -o /mnt/storage/backups -s localhost:25575:secret -w rcon
# If running on screen called "minecraft":
./backup.sh -c -i /home/user/server/world -o /mnt/storage/backups -s minecraft
# If running on tmux session 0:
./backup.sh -c -i /home/user/server/world -o /mnt/storage/backups -s 0 -w tmux
# Using restic (and RCON)
export RESTIC_PASSWORD="restic-pass-secret" # your password here
./backup.sh -c -i /home/user/server/world -r /mnt/storage/backups-restic -s localhost:25575:secret -w rcon
# Using Docker and RCON
# You will have to set up networking so that this Docker image can access the RCON server
# In this example, the RCON server hostname is `server-host`
docker run \
-v /home/user/server/world:/mnt/server \
-v /mnt/storage/backups:/mnt/backups \
ghcr.io/nicolaschan/minecraft-backup -c -i /mnt/server -o /mnt/backups -s server-host:25575:secret -w rcon
# Using itzg/docker-minecraft-server container and rcon cli
./backup.sh -c -i /home/user/server/world -o /mnt/storage/backups -s container-name -w docker-rcon
This will show chat messages (-c
) and save a backup of /home/user/server/world
into /mnt/storage/backups
using the default thinning deletion policy for old backups.
Command line options:
-a Compression algorithm (default: gzip)
-c Enable chat messages
-d Delete method: thin (default), sequential, none
-e Compression file extension, exclude leading "." (default: gz)
-f Output file name (default is the timestamp)
-h Shows this help text
-H Set hostname for restic backup (restic only)
-i Input directory (path to world folder, use -i once for each world)
-l Compression level (default: 3)
-m Maximum backups to keep, use -1 for unlimited (default: 128)
-o Output directory
-p Prefix that shows in Minecraft chat (default: Backup)
-q Suppress warnings
-r Restic repo name (if using restic)
-s Screen name, tmux session name, hostname:port:password for RCON or [container name](https://github.com/itzg/docker-minecraft-server) for docker-rcon
-t Enable lock file (lock file not used by default)
-u Lock file timeout seconds (empty = unlimited)
-v Verbose mode
-w Window manager: screen (default), tmux, RCON
- Edit the crontab with
crontab -e
- Example for hourly backups:
00 * * * * /path/to/backup.sh -c -i /home/user/server/world -o /mnt/storage/backups -s minecraft
Always test your backups! Backups are in the tar
format and compressed depending on the option you choose. To restore, first decompress if necessary and then extract using tar. You may be able to do this in one command if tar
supports your compression option, as is the case with gzip
:
Example:
mkdir restored-world
cd restored-world
tar -xzvf /path/to/backups/2019-04-09_02-15-01.tar.gz
The restored worlds should be inside the restored-world
directory, possibly nested under the parent directories. Then you can move your restored world to your Minecraft server folder under the proper name and path so the Minecraft server uses it.
Use restic restore
to restore from backup.
If you use tar
while the server is running, you will likely get an error like this because Minecraft autosaves the world periodically:
tar: /some/path/here/world/region/r.1.11.mca: file changed as we read it
To fix this problem, the backup script disables autosaving with the save-off
Minecraft command before running tar
and then re-enables autosaving after tar
is done.
- Make sure the compression algorithm you specify is installed on your system. (zstd is not installed by default)
- Make sure your compression algorithm is in the crontab's PATH
- Make sure cron has permissions for all the files involved and access to the Minecraft server's GNU Screen
- It's surprising how much space backups can take--make sure you have enough empty space
- Do not put trailing
/
in theSERVER_DIRECTORY
orBACKUP_DIRECTORY
- If "thin" delete method is behaving weirdly, try emptying your backup directory or switch to "sequential"
There is a Minecraft bug MC-217729 in recent Minecraft server versions that cause them to automatically save the world even after receiving the save-off
command. Until this is fixed, there is a chance that the backup will fail because the world files are modified by Minecraft in the process of creating the backup. This script will try to detect and report this problem if it does occur.
Backups are essential to the integrity of your Minecraft world. You should automate regular backups and check that your backups work. It is up to you to make sure that your backups work and that you have a reliable backup policy.
Some backup tips:
- Drives get corrupted or fail! Backup to a different drive than the one your server is running on, so if your main drive fails then you have backups.
- Automate backups so you never lose too much progress.
- Check that your backups work from time to time.
Please refer to the LICENSE (MIT License) for the full legal disclaimer.