CaCl2Backup

中文 | English

A comprehensive Minecraft server backup mod designed for Fabric.

Features

• Three Backup Triggers - Interval, daily schedule, and server stop triggers that can be combined freely
• Multi-threaded Compression - Parallel compression using multiple threads for significantly faster backups
• Automatic Cleanup - Post-backup automatic cleanup of old backups with both count and age limits
• Full Restore - Complete world save restoration from backups
• Label System - Add labels to backups for easy identification (special characters auto-replaced with underscores)
• Index Operations - Quickly select backups by index number without typing full filenames
• Real-time Status - View backup status, configuration, and backup list
• Hot Reload Config - Reload configuration without restarting the server
• Auto-Restart Restore - Optionally auto-restart the server after restoring a backup

Requirements

• Minecraft 26.0+ (26.x series)
• Fabric Loader 0.15.0+
• Fabric API
• Java 25+

Installation

1. Ensure Fabric Loader and Fabric API are installed
2. Place the mod JAR file into your server's mods folder
3. Start the server - the mod will automatically generate the configuration file

Command Reference

All commands require OP privileges and use the /backup prefix.

Basic Commands

Command	Description	Example
/backup create [label]	Create a manual backup (optional label)	/backup create before_update
/backup list	List all available backups (shows index numbers)	/backup list
/backup status	Show current configuration and status	/backup status
/backup reload	Reload configuration file	/backup reload
/backup cleanup	Manually clean up old backups	/backup cleanup

Restore & Delete

Command	Description	Example
/backup restore <index/filename>	Restore world from specified backup	/backup restore 1
/backup delete <index/filename>	Delete specified backup	/backup delete 2

Tip: Use /backup list to view backup index numbers, then use the index directly.

Configuration Commands

Command	Description	Example
/backup config	Show all configuration options	/backup config
/backup config interval [<minutes>]	Show/set backup interval	/backup config interval 60
/backup config maxbackups [<count>]	Show/set maximum backup count	/backup config maxbackups 20
/backup config maxage [<days>]	Show/set maximum backup age	/backup config maxage 14
/backup config autocleanup [<on/off>]	Show/set auto cleanup	/backup config autocleanup on
/backup config threads [<count>]	Show/set compression thread count	/backup config threads 4
/backup config level [<1-9>]	Show/set compression level	/backup config level 6
/backup config autorestart [<on/off>]	Show/set auto-restart after restore	/backup config autorestart on
/backup config restartdelay [<seconds>]	Show/set auto-restart delay	/backup config restartdelay 60
/backup config restartmessage [<message>]	Show/set restart message ({seconds} placeholder)	/backup config restartmessage "Server will restart in {seconds}s..."
/backup config broadcastrestart [<on/off>]	Show/set restart message broadcast	/backup config broadcastrestart on
/backup config trigger	Show all trigger statuses	/backup config trigger
/backup config trigger interval [<on/off>]	Show/set interval trigger	/backup config trigger interval on
/backup config trigger server_stop [<on/off>]	Show/set server stop trigger	/backup config trigger server_stop on
/backup config trigger schedule [<on/off>]	Show/set schedule trigger	/backup config trigger schedule on
/backup config trigger schedule add <HH:mm>	Add a schedule time	/backup config trigger schedule add 03:00
/backup config trigger schedule remove <HH:mm>	Remove a schedule time	/backup config trigger schedule remove 03:00
/backup config trigger schedule clear	Clear all schedule times	/backup config trigger schedule clear

Configuration File

Configuration file location: config/cacl2backup.json

{
  "backupIntervalMinutes": 30,
  "maxBackups": 10,
  "compressionThreads": 8,
  "compressionLevel": 6,
  "autoBackupEnabled": true,
  "autoCleanupEnabled": true,
  "maxBackupAgeDays": 7,
  "backupFolderName": "backups",
  "broadcastBackupMessages": true,
  "saveOnBackup": true,
  "autoRestartAfterRestore": false,
  "restartDelaySeconds": 60,
  "restoreRestartMessage": "Server will restart in {seconds} seconds to complete restore...",
  "broadcastRestoreMessage": true,
  "triggers": {
    "interval": {
      "enabled": true,
      "interval_minutes": 30
    },
    "server_stop": {
      "enabled": false
    },
    "schedule": {
      "enabled": false,
      "times": ["03:00", "15:00"]
    }
  }
}

Configuration Options

Option	Type	Default	Description
backupIntervalMinutes	int	30	Auto-backup interval in minutes (minimum: 1)
maxBackups	int	10	Maximum number of backups to keep
compressionThreads	int	CPU cores	Number of compression threads
compressionLevel	int	6	Compression level (1-9), 1 is fastest with lowest ratio, 9 is slowest with highest ratio
autoBackupEnabled	boolean	true	Enable automatic backups
autoCleanupEnabled	boolean	true	Enable automatic cleanup of old backups
maxBackupAgeDays	int	7	Maximum backup age in days
backupFolderName	String	"backups"	Backup folder name
broadcastBackupMessages	boolean	true	Broadcast backup messages to all players
saveOnBackup	boolean	true	Save world before backup
autoRestartAfterRestore	boolean	false	Auto-restart server after restore
restartDelaySeconds	int	60	Auto-restart delay in seconds (minimum: 10)
restoreRestartMessage	String	"Server will restart in {seconds} seconds..."	Restart message template, {seconds} is replaced with delay
broadcastRestoreMessage	boolean	true	Broadcast restart message
triggers.interval.enabled	boolean	true	Enable interval backup trigger
triggers.interval.interval_minutes	int	30	Interval backup interval in minutes
triggers.server_stop.enabled	boolean	false	Enable server stop backup trigger
triggers.schedule.enabled	boolean	false	Enable daily schedule backup trigger
triggers.schedule.times	list	[]	Daily backup times (HH:mm format, e.g. ["03:00","15:00"])

Usage Guide

Creating Backups

Manual backup (recommended before important operations):

/backup create before_major_update

View backup list:

/backup list

Example output:

[CaCl2Backup] Available backups (5):
1. 2024-02-20 10:30:00 [before_update] - 125.3 MB
2. 2024-02-19 22:00:00 [auto] - 124.8 MB
3. 2024-02-19 10:00:00 - 123.5 MB
...

Restoring World

Warning: Restore operation will overwrite the current world save!

1. View backup list to get index number:

   /backup list
   

2. Restore using index:

   /backup restore 1
   

3. Behavior depends on configuration:

   • autoRestartAfterRestore=false (default): Manually stop the server to complete restore
   • autoRestartAfterRestore=true: Mod auto-restarts server after specified delay

4. World is automatically replaced on next server startup

Configure auto-restart behavior:

/backup config autorestart on          # Enable auto-restart
/backup config restartdelay 60         # Set delay to 60 seconds
/backup config restartmessage "Server will restart in {seconds} seconds..."  # Custom message
/backup config broadcastrestart on     # Enable broadcast

Deleting Backups

Delete using index:

/backup delete 2

Backup Triggers

Three independent triggers that can be combined freely:

Trigger	Default	Description
Interval	On	Auto-backup every N minutes
Schedule	Off	Backup at specific times daily (e.g. 03:00 and 15:00)
Server Stop	Off	Backup when server shuts down normally
Manual Command	—	Run /backup create [label] anytime

Example configuration:

// Only enable server stop + daily 3 AM backup, disable interval
"triggers": {
  "interval":   { "enabled": false },
  "server_stop": { "enabled": true },
  "schedule":   { "enabled": true, "times": ["03:00"] }
}

Backup File Naming

backup_YYYY-MM-DD_HH-mm-ss.zip              # No label
backup_YYYY-MM-DD_HH-mm-ss_label.zip        # With label

Examples:

• backup_2024-02-20_10-30-00.zip
• backup_2024-02-20_10-30-00_before_update.zip

Label naming rules:

• Allowed: letters a-zA-Z, digits 0-9, underscore _, hyphen -
• Other characters (spaces, special symbols, etc.) are auto-replaced with underscore _

Performance

Multi-threaded Compression

The mod uses parallel compression to significantly speed up backups for large worlds:

World Size	1 Thread	4 Threads	8 Threads
500 MB	~45s	~15s	~10s
2 GB	~3min	~1min	~40s
5 GB	~8min	~2.5min	~1.5min

Compression Level Comparison

Level	Ratio	Speed	Use Case
1-3	~40%	Fastest	Frequent backups, SSD storage
4-6	~50%	Balanced	Daily use (recommended)
7-9	~55%	Slower	Limited storage space

Best Practices

1. Regular Backup Checks

   • Run /backup list regularly to confirm backups are created
   • Test restore process periodically to ensure backups are usable

2. Reasonable Retention Policy

   • Both maxBackups and maxBackupAgeDays apply simultaneously
   • Recommended: Keep at least 3-5 valid backups

3. Manual Backup Before Important Operations

   • Before mod updates
   • Before major building projects
   • Before server version upgrades

4. Off-site Backups

   • Periodically copy backup folder to another location
   • Consider cloud storage sync for backups

Troubleshooting

Backup Failed

Problem: Backup failed: World directory not found

Solution: Confirm the server world folder is named world.

World Issues After Restore

Problem: Incomplete world data after restore

Solution:

1. Ensure server is restarted after restore completes
2. Check if backup file is complete (normal file size)
3. Try using a different backup file

Permission Issues

Problem: Cannot execute commands

Solution: Ensure the player has been set as OP (use /op player_name).

Development Info

• Author: CaCl2
• Version: 1.1.1
• License: MIT
• Minecraft Version: 26.0+ (26.x series)
• Fabric API Version: 0.146.1+

Changelog

1.1.1

• Fix — Auto cleanup of old backups not working (Gson deserialization did not validate default values for maxBackups, maxBackupAgeDays, and autoCleanupEnabled, causing auto cleanup to be silently disabled when migrating from older config files)
• Fix — Cleanup logic else if caused count-based and age-based deletion to interfere with each other; rewritten with independent checks to keep exactly maxBackups backups

1.1.0

• Backup trigger refactoring — Three independent triggers: Interval, Schedule, and Server Stop
• Triggers can be combined freely, controlled via triggers config section
• Old config files auto-migrate; existing interval settings are preserved
• New trigger commands: /backup config trigger interval/schedule/server_stop
• Support for multiple daily backup times (e.g. ["03:00","15:00"])
• Sync backup on server shutdown (using createBackupSync)
• Minecraft version support expanded to entire 26.x series (>=26.0 <27.0)
• Removed legacy /backup config autobackup, unified under trigger interval
• Security fixes — Zip Slip path traversal protection, backup name path filtering, TOCTOU race condition fix
• Schedule trigger DST correctness, concurrent list safety, command standardization

1.0.2

• Refactored restore flow: Removed /backup restarter command, auto-restart integrated into /backup restore
• New config options: autoRestartAfterRestore, restartDelaySeconds, restoreRestartMessage, broadcastRestoreMessage
• New config commands: /backup config autorestart, /backup config restartdelay, /backup config restartmessage, /backup config broadcastrestart

1.0.1

• Updated to Minecraft 26.1.2
• Added GitHub Release workflow
• Java version requirement raised to 25+

1.0.0

• Initial release
• Multi-threaded compression
• Scheduled auto-backups
• Automatic cleanup of old backups
• Full restore functionality
• Label system
• Index-based quick selection
• Hot reload configuration