CaCl2Backup

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

Restore & Delete

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

Configuration Commands

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

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:

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:

Compression Level Comparison

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