Backup

Incremental world backups for Paper servers. Only the parts of your world that actually changed get copied.

The problem

Most backup plugins zip the whole world folder on a schedule. On a small survival world that's fine. On a 50 GB world it means writing 50 GB every single night — most of it byte-for-byte identical to last night's copy — while competing with the server for disk I/O. Backups become the thing that makes your server stutter, so people turn them off, and then one day they need one.

How this one works

Content-addressed storage. Every file is stored under the SHA-256 of its contents. Two identical region files — in different snapshots, or in different worlds — are stored once and shared.

Genuinely incremental. On each run, a file whose size and modification time match the previous snapshot keeps its existing hash and is never read. An unchanged world costs a directory walk, not a full copy. Only what changed gets written.

Restores are verified. Every file is hash-checked before it is written back. A damaged backup fails loudly instead of quietly handing you a broken world, and /backup verify checks a snapshot is fully restorable before the day you need it.

Stays off the main thread. Auto-save is paused and each world flushed to disk on the main thread — that part is brief and unavoidable — and then all the walking, hashing and copying happens in the background. Auto-save is always turned back on, including when a backup fails.

Files caught mid-write are retried. If the server rewrites a region file while it is being read, the file is captured again rather than stored half-written. A corrupt region file that looks like a perfectly good backup is the worst possible outcome, so it is treated as one.

Commands

Permission: backup.admin (defaults to op).

Restoring

A restore never touches your live world. It rebuilds the snapshot into plugins/Backup/restored/<snapshot>/ and stops there. You then stop the server and swap the folder in yourself.

That is deliberate. A restore that overwrites in place and fails halfway leaves you with neither your old world nor your backup.

Configuration

# How often to back up, in minutes. Set to 0 to only ever back up via /backup now.
interval-minutes: 120

# Take a backup a minute after startup instead of waiting a full interval.
run-on-startup: false

# Which worlds to include. Leave empty to back up every loaded world.
worlds: []

Requirements

• Paper 26.2 or newer
• Java 25

Not in this version

Listed here rather than discovered later:

• No automatic pruning. Old snapshots are kept until you delete them, so the store grows over time.
• No off-site upload. Backups are written to your server's own disk. A disk failure takes the backups with it — copy them somewhere else.
• No single-file or single-chunk restore. Restore is whole-world only.
• Not tested against Folia.

Storage layout

Snapshots are plain text manifests listing a hash, size, timestamp and path per file, next to a store of hash-named blobs. Nothing is in a proprietary container. If this plugin ever stops being maintained, your backups are still ordinary files on disk that you can recover by hand.