Cloud Backups

PocketMC creates non-corrupting world backups using RCON save-holding, calculates SHA-256 integrity checksums, syncs to cloud storage providers, and performs atomic world restores with automatic rollback.

World Save Synchronization

Copying world region files while a Minecraft server writes to disk causes corrupt chunk boundaries and broken save files. PocketMC coordinates disk synchronization before packaging the world:

1. If RCON is enabled in server.properties, PocketMC connects via loopback RCON and issues save-off, followed by save-all.
2. If RCON is disabled, PocketMC sends save-off and save-all directly to process standard input and monitors console logs for save confirmation output (saved the chunks or all dimensions are saved).
3. Skips transient lock files like session.lock that prevent archive extraction.
4. Compresses the world folder into a timestamped zip archive (world-yyyy-MM-dd-HH-mm-ss.zip).
5. Executes save-on in a guaranteed cleanup block to resume normal background saving.

Checksums & Backup Manifest

Every backup produces a SHA-256 checksum and is logged into the instance manifest (.pocket-mc-backups.json):

• Integrity validation: Checks the hash of each backup file against the recorded checksum before any restore attempt.
• Trigger tracking: Records whether each backup was initiated manually or by the background scheduler.
• Size delta: Calculates byte differences between consecutive backups so you can monitor world growth.
• Local retention: Automatically keeps the configured number of backups (default: 5), deleting older zip files and pruning orphaned manifest entries.

Cloud Storage Providers

Backups can replicate automatically to external storage and cloud providers:

• Google Drive: Uses dedicated application folders with token authorization.
• Dropbox: Streams chunked uploads with version retention.
• Microsoft OneDrive: Connects through Microsoft Graph API.
• External directory replication: If you configure a secondary internal drive or USB disk in settings (ExternalBackupDirectory), backups clone to local disk storage as well.
• Deduplication: PocketMC checks the local SHA-256 against upload history to avoid re-uploading identical archives.
• Cloud retention: Enforces retention counts per target provider, removing older remote files after successful uploads.

Safe Atomic Restore Pipeline

Restoring a world backup uses a staged replacement pipeline to protect against partial extraction failures:

1. Integrity check: Verifies that the backup ZIP is readable and that its SHA-256 matches the manifest.
2. Staged extraction: Unpacks the archive into a temporary staging folder (.restore-stage-{guid}).
3. World validation: Confirms that level.dat is present in the extracted folder to ensure the archive is a valid Minecraft world.
4. Safety backup: Moves the current active world directory to .restore-backup-{timestamp}.
5. Atomic swap: Moves the staged directory into the active world location. If the folder move fails, PocketMC immediately restores your original world from the safety backup.