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.0
• License: MIT
• Minecraft Version: 26.0+ (26.x series)
• Fabric API Version: 0.146.1+

Changelog

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