Zum Hauptinhalt springen

Advanced Backups operation reference

Mit FlammiCraft ausgelieferte Mod-Version: 3.26.0

Diese Detailseite ist derzeit auf Englisch verfügbar.

Handbook overview

Target: Minecraft 1.21.1, NeoForge 21.1.249+, Java 21. The shared core still compiles with --release 8. Imported adapters remain present; the NeoForge target is the validated adapter for this release.

Configuration and migration

Server/world settings live in config/advancedbackups-common.toml; client toast settings live in config/advancedbackups-client.toml. The first successful load migrates config/AdvancedBackups.properties (or the former server-root file) and config/AdvancedBackups-client.properties. Original files remain untouched. Once the TOML exists, it is authoritative. Keep these migration sources until you have reviewed the resulting configuration.

Existing keys lose their config.advancedbackups. prefix. Booleans and numbers are TOML values; blacklist and schedule values are string arrays. Dotted keys and equivalent table sections work. The parser supports TOML 1.0. A bad scalar, unknown key, malformed schedule, invalid profile or overlapping destination rejects the complete update; the active settings stay unchanged. Migration never publishes a TOML with invalid values. A failed first load leaves backups unavailable with an explicit configuration error. Fix the TOML and run /backup reload-config; no stale world destination is reused. Reload is rejected while backup/file work owns the configuration, so an accepted job cannot change halfway through a run. The offline CLI reads TOML using the same parser and retains legacy Properties reads.

type = "incremental"
path = "./backups"
blacklist = ["session.lock", "*_old"]
frequency.schedule = ["0:30", "1:00"]
frequency.uptime = true

[profiles.daily]
type = "zip"
path = "./daily-backups"
frequency.schedule = ["3:00"]
frequency.uptime = false
purge.count = 14

Top-level settings form the default profile. Named profiles inherit them and override individual keys. Each destination receives the world directory name as a suffix. Destinations must be outside the world and must neither overlap nor nest, including resolved aliases. Profiles have separate archives, hash manifests and recovery markers. Their scheduled jobs serialize behind the active operation; an overdue profile waits until the slot is free. Preparation is performed per accepted job rather than sharing live-world snapshots across different points in time.

NeoForge always flushes its native save operations and captured SavedData/region writes; the historical flush flag does not weaken this barrier. savebudget.millis (default 5), savebudget.operations (8) and savebudget.timeoutseconds (1800) bound work between indivisible native save operations. SavedData entries are separate operations and are rechecked against the live cache before saving. The summary identifies the slowest operation. A single mod/chunk callback can exceed that budget. Shutdown retains a synchronous flushed save because regular server ticks have ended.

storage.reservebytes defaults to 256 MiB. For known full backups, the file metadata scan checks that both raw staging and the estimated archive fit before reading any payload. If change detection promotes a partial to a full backup, the check accounts for files already staged. The archive estimate includes the raw payload, a 2% expansion margin and per-entry overhead. Allow roughly twice the selected source bytes for a full backup, plus reserve and overhead, in addition to existing archives. The check does not reserve capacity against other jobs on the same drive. storage.bytespersecond = 0 disables optional archive-transfer throttling. Throttling sleeps in interruptible slices of at most 100 ms. File reads and staged writes remain visible as separate metrics.

Unchanged files in a valid partial chain are hashed without writing staging files. Changed/new files are captured. A later full-backup decision recaptures missing staged files. A stable recapture supplies the authoritative hash for its archived bytes; a change since comparison alone does not invalidate it. Source instability retries remain bounded and do not advance a manifest on failure. Captured SHA-256 and chain MD5 have different roles: SHA-256 verifies payload integrity; MD5 retains existing change-baseline compatibility.

The exact world-relative music_disc_maker/audio/.lock path is excluded independently of profile blacklists. Music Disc Maker uses it only for its process lock and recreates it when the audio store opens. Audio payloads and ownership records remain selected. Other .lock paths and unreadable selected files retain the existing capture and failure rules. This exception does not coordinate concurrent audio and ownership commits into an atomic music snapshot. Restore remains an offline operation with the existing safety archive and world-lock checks.

Jobs, status and administration

One operation owns the backup slot from admission through owner-thread completion. Each job has a UUID, trigger, profile and frozen settings. Phases are preflight, world save, pending writes, file capture, archive writing, publication, optional verification and retention. The initial storage preflight runs on the existing file worker; the owner thread starts world saving only after it succeeds. Cancelled/stopping jobs cannot resume saving after a late preflight. Shutdown keeps its synchronous save path. Unknown totals stay unknown. Chat inspection, console progress and client packets derive their phase/files/bytes from the same job. The client protocol is version 2; use matching client/server versions for notifications.

A confirmed storage-capacity failure stops file capture or archive writing immediately. The failed run leaves previously published archives and the chain manifest intact.

Administrative commands retain the existing operator/LAN-owner permission gate:

/backup start
/backup start daily
/backup profile daily status
/backup profile daily history
/backup profile daily verify <archive-filename> full
/backup status
/backup list
/backup info <job-uuid>
/backup history
/backup verify <archive-filename>
/backup verify <archive-filename> full
/backup retention-plan
/backup staging
/backup cleanup-staging <incomplete-staging-name>
/backup snapshot [name]
/backup cancel
/backup reload-config

Commands without a profile qualifier use the default profile. /backup profile <name> provides start, status, list, history, info, verify, retention-plan, staging and cleanup-staging for a named profile. Each profile's files/history are also available in its separate storage root to offline tools. Staging inspection never deletes anything. The explicit cleanup command accepts only a direct incomplete-staging-* directory in that storage root, rejects links and runs while no other job owns the slot.

The bounded history.json contains the last 200 operations, including skipped schedules and preparation failures. It records outcome, settings, phase durations, byte/file counts, staging demand, retry counts and any integration error. Accepted jobs publish a terminal client status on success, failure or cancellation. Reload reports configuration acceptance separately from storage readiness and reports completion only after the owner-thread callback. Status distinguishes latest attempt, successful operation, failure and next default-profile attempt. A saved archive with failed/cancelled retention or temporary cleanup is SUCCESS_WITH_CLEANUP_ERROR; archive creation failure and cancellation remain separate outcomes. Histories are diagnostic metadata, not the source of restore-chain truth.

retry.count defaults to 3 and retry.seconds to 300. Failed automatic jobs receive bounded delayed retries rather than a retry each tick. Normal schedules continue after retries are exhausted. Verification and other maintenance completions preserve pending backup deadlines instead of skipping a schedule crossed by maintenance. Existing local-calendar/DST and rollback-safe archive naming remain in use. The configured maximum backup age is reported by status; operators should monitor histories/events for prolonged failures or activity-based skips.

Verification and integrity

New ZIP and .abchain archives include .advancedbackups-integrity.json, a version-1 SHA-256 map of exactly the member's payload files. It is reserved metadata and never restored/exported as a world file. Its 64 MiB encoded limit is enforced by both writer and reader; oversized output fails before archive/manifest publication. .abchain ancestry/deletion metadata remains format 1. Legacy ZIP/directory chains remain readable. Use the 3.20.0 CLI with new archives; use a materialized ZIP export when handing data to tools that do not understand the metadata conventions.

Differential and incremental archive names carry a chain ID: backup_<time>-c<id>-full.abchain and its backup_<time>-c<id>-partial.abchain members share one ID. Each new full backup starts a new ID. The last issued ID is stored in chain-id.txt beside manifest.json and is also checked against existing names, so IDs are not reused after a restart or after cleanup. An unreadable chain-id.txt fails the full backup before publication. Names without an ID from older versions remain valid for listing, restore and retention, and partials continuing such a chain keep the legacy form. Restore and retention reject a partial whose ID differs from its full backup. Retention reasons name the chain; unrestorable lists partials, with their chain ID, that would stay on disk after their full backup is removed. Older mod and CLI versions reject the new names; use a materialized ZIP export for them.

Quick verification validates recognized metadata, required parents, ordering, payload path sets and safe paths without reading every payload. Full verification additionally reads every payload in every required archive, including superseded files, checks ZIP size/CRC and stored SHA-256 where available. Legacy members explicitly report the absence of stored SHA-256. Neither mode authenticates an archive against deliberate replacement of both data and metadata. No verification repairs or rewrites an archive.

Manual verification writes a dated <archive>.verification.json sidecar. verification.afterbackup enables checking after every published backup. Alternatively, verification.intervalhours schedules verification of the latest point even when no new backup is created. It checks persisted verification time after a restart and uses the same serial operation slot. A newly published point may also satisfy that interval. verification.full selects full (default) or quick checking. The result is also included in the job/event. The mod and both CLI modes coordinate with an exclusive advancedbackups-operation.lock in the storage root; concurrent operations fail clearly rather than reading an archive being changed by another cooperating process. Cross-storage comparisons acquire each distinct canonical storage root once, in a consistent order. Interactive export performs the same full integrity verification as argument export.

Offline CLI, plans and comparison

Run the built mod JAR using Java 21. No arguments retain the interactive menus. Argument mode provides stable exit codes: 0 success, 2 invalid usage/options, 3 I/O, validation or reconstruction failure. --json emits compact machine-readable JSON; the default prints indented reports.

java -jar AdvancedBackups-neoforge-1.21.1-3.20.0.jar help
java -jar <jar> list <archive-directory> --json
java -jar <jar> inspect <archive>
java -jar <jar> verify <archive> --full --json
java -jar <jar> compare <before-archive> <after-archive> --path=region --json
java -jar <jar> export <archive> --target=<new.zip>
java -jar <jar> plan <archive> --target=<offline-world>
java -jar <jar> restore <archive> --target=<offline-world> --safety=<existing-external-directory>
java -jar <jar> restore <archive> --target=<offline-world> --safety=<existing-external-directory> --apply
java -jar <jar> restore <archive> --target=<offline-world> --safety=<existing-external-directory> --path=region --apply
java -jar <jar> drill <archive> --target=<new-separate-directory>

restore without --apply is a preview. Flags --apply, --full and --json never take values; forms such as --apply=false are rejected before file operations. Preview and execution share RestorePlan: added/replaced/removed files, target and selection are identical. Applying verifies the archives, takes the target's world lock, checks for a changed file selection, creates a complete external safety archive, then replaces only the selected files/directories. The root world session.lock is preserved and omitted from the safety archive. Nested files named session.lock are included in that safety archive before removal or replacement. Equal-name replacements keep the original until their staged replacement succeeds; removals and file/directory transitions still require changes protected by the safety archive. Root world links are preserved while internal traversal uses the canonical world path. Failures after changes name the incomplete target and safety-copy path. Restore is not an atomic whole-world transaction; use the safety archive after a partial failure.

drill refuses an existing target and refuses targets nested in the source storage. It reconstructs into a fresh separate directory, leaving the original world untouched. --path selects a single file or complete directory subtree for comparison/restore. Comparisons use the same resolved overlay as restore and report added/changed/deleted files, sizes and source members. Renames appear as deletion plus addition. Old chains cannot recover deletions that were never recorded.

Retention and integrations

Retention first creates a plan, then executes its exact ordered selection after checking selected archive sizes/timestamps. Plans expose reasons, estimated freed bytes, protected points/snapshots and unmet limits. Existing size/count/age rules still apply. purge.hourlyhours, purge.dailydays and purge.weeklyweeks add one retained point per corresponding time bucket within those windows; all default to zero. Required ancestry, the latest point and minimum incremental chains are protected even when a limit cannot be met. Dependency protection can retain more points than the nominal tier/count setting. Snapshots stay outside automatic deletion. Deletion hides an archive before removing contents, and stops on failure/interruption.

last-event.json is a version-1 report containing job id, trigger, profile, terminal outcome, archive, required members, verification result, finish time and error. It is replaced atomically after local archive/manifest publication (or after a failed/cancelled operation). External tools can consume it using their existing transfer mechanisms. Integrations can register a bounded local BackupEvents.listen(Consumer<Event>) callback and close its returned registration to unsubscribe. Listener/report failures are separate integrationError values in history and never change a published local archive's outcome. No cloud client or shell command execution is built in.

Acceptance boundary

The last 200 individual event reports remain in events/<job-uuid>.json, allowing consumers to catch up after missing a last-event.json update. Unresolvable ancestry on a failed check has an explicit ancestryError.

Automated checks use isolated synthetic directories, including legacy/current chains, deletions and file/directory transitions, corrupt payloads, invalid configuration, world locks, cancellation, owner-thread callbacks, profile isolation, retention plans and staging measurements. Plain JVM NeoForge fixtures inspect actual dependency targets and save-write barriers. They do not load the whole game or establish Mixin compatibility with the complete modpack. The user performs final client/modpack testing, including backup under load, snapshots, shutdown and restore into a disposable world copy. No deployment, existing-backup purge, live-world restore or database operation is part of implementation verification.