Installation backups API¶
Endpoint paths below are backend-native. Add /api when using the dashboard gateway, for example http://localhost:3005/api/process/capabilities.
Preview, acknowledge and track an archive job
This is the reviewed-preview backup path. Direct start and restore have separate admission rules below; an accepted job still needs its final verification result.
flowchart TD
Preview["Preview coverage, destination, capacity and downtime"] --> Review["Review exclusions and required acknowledgements"]
Review --> Start["Start the backup using the reviewed preview"]
Start --> Poll["Poll the retained job"]
Poll --> Result{"Terminal result"}
Result -->|Verified| Catalog["Inspect the verified archive catalog"]
Result -->|Failed or interrupted| Recovery["Inspect retained operation and recovery state"]
Routes and admission¶
These routes require installation_backup=true and numeric
installation_backup_protocol=1. They follow the normal DUMB authentication
policy. The frontend exposes them under Settings → Backups and restore.
Paths below are relative to the API; browser requests use its /api proxy.
| Method | Route | Purpose |
|---|---|---|
GET |
/process/installation-backups/status |
Schedule, preparation, operation/recovery state and current job |
GET |
/process/installation-backups/catalog |
Verified installation archives from the selected destination |
POST |
/process/installation-backups/preview |
Review coverage, exclusions, destination, capacity and downtime |
GET |
/process/installation-backups/preview/status |
Reconnect to the current or selected tracked backup preview when supported |
POST |
/process/installation-backups/preview/{preview_id}/cancel |
Request cooperative cancellation of that tracked backup preview when supported |
POST |
/process/installation-backups/start |
Start the reviewed backup after explicit acknowledgement |
POST |
/process/installation-backups/start-direct |
Admit an acknowledged backup without a live preview when supported |
GET |
/process/installation-backups/jobs/{job_id} |
Poll a retained backup or restore job |
POST |
/process/installation-backups/jobs/{job_id}/cancel |
Request cooperative cancellation of an active backup when supported |
PUT |
/process/installation-backups/schedule |
Save an explicitly enabled/disabled schedule, destination, compression and retention |
POST |
/process/installation-backups/restore/preview |
Verify a selected archive and preview compatible restore targets |
POST |
/process/installation-backups/restore/start |
Start the reviewed restore with its required confirmations |
POST |
/process/installation-backups/jobs/{job_id}/rollback |
Recover the exact retained operation after its typed rollback confirmation |
Compression¶
Backends advertising installation_backup_compression=true accept
compression in POST /preview and PUT /schedule: "none" selects the default
uncompressed .tar; "zstd" selects .tar.zst and additionally requires
installation_backup_zstd=true. The schema capability is independent of runtime
codec availability: with schema support and Zstandard unavailable, clients can
still explicitly save "none" to replace a schedule's previous "zstd" choice.
A preview response and its tracked operation report the reviewed compression
choice, which is bound to the preview token. Changing it requires another
preview. An omitted schedule field preserves its saved compression choice; a
newly configured schedule defaults to "none". Clients lacking the schema
capability omit the field and keep the legacy uncompressed flow.
The catalog reports each archive's compression. Restore detects the actual
format from its bytes rather than trusting the extension, so legacy .tar
archives continue to work. Both formats are complete standalone archives.
Compression streams directly to the destination; capacity admission uses a
conservative uncompressed estimate plus overhead, not an assumed ratio.
Direct start and request retries¶
Backends advertising installation_backup_direct_start=true support
POST /start-direct. The status response advertises direct_start with
confirmation_text and required_acknowledgements. Send:
{
"request_id": "0123456789abcdef0123456789abcdef",
"destination_id": "registered_destination",
"compression": "none",
"confirmation": "BACK UP DUMB INSTALLATION",
"acknowledgements": {
"downtime": true,
"secrets": true,
"external_state": true
}
}
Use a fresh random 32-character lowercase hexadecimal request identity for each
intended backup. Retries of the same identity and options return the original
durable job; different options with a spent identity are refused. The job
exposes its request_id for transport-loss reconciliation. A direct start skips
the live census and does not provide a reviewed size estimate. Its worker checks
coverage and destination, stops managed writers, and checks capacity from the
cold census before emitting archive payload. If it fails, poll the job for its
reason and service-resume outcome.
The job may include capacity with from_census: true, measured source totals
and filesystem-role free/required/shortfall byte counts. Failed admitted
scheduled jobs keep the normal interval; pre-admission blockers retain the
five-minute retry without stopping services.
On these backends, reviewed POST /start also admits a job without repeating
the preview's full census. Scheduled backups use direct admission. Both retain
configuration/destination identity checks and final source/archive verification.
The legacy preparation field remains null; older backends may expose
checking_capacity before admission. Clients must gate direct start by its
capability and keep polling status while a start response is pending or uncertain.
Never treat an older completed job as confirmation of a new request, and do not
automatically submit a fresh operation after a proxy timeout.
Job status and progress¶
Job created_at / updated_at and preparation started_at values use Unix
seconds and can contain fractional seconds. Newer backends can include a progress object with optional
entries, logical_bytes and bytes_processed counters. These are relative to
the current stage and reset at a phase change: inventorying is a metadata
census, archiving is archive streaming, checking_source hashes source file
contents again, and verifying reads back the archive. In archive streaming
and verification, bytes_processed counts actual stored stream bytes, including
the stream containing headers, padding and manifest data; for Zstandard these
are compressed bytes. logical_bytes remains an uncompressed source measure.
In source checking, bytes_processed counts source file bytes hashed.
Consumers must tolerate omitted counters and must not infer an overall
percentage or advancement merely from a successful status request.
Archive verification and publication¶
For an installation backup, archive_verified=true reports a persisted
result.complete=true with a verified archive receipt and its nonempty
reference in result.archive. This proof is saved before service resume. The
overall job can still be recovery_required because applications could not
resume; that status does not invalidate the published archive. Backup recovery
preserves the archive result and merges restart fields into it. Restore rollback
keeps its separate existing semantics.
The flag describes verification and publication at backup time, not a new full-file integrity check on every status poll. Do not derive it from copied bytes, elapsed time, a finished phase or a filename. A publication-stage failure without a recorded receipt has an unconfirmed outcome: retain recovery evidence and review the archive catalogue rather than declaring a verified backup or assuming that publication never happened.
archive_publication_uncertain=true identifies that recorded publication
uncertainty. Its persistent marker survives a controller restart that changes
the job stage to interrupted; clients must not rely on the stage alone.
During service recovery, keep the archive receipt visible separately from the
overall job status. For scheduled backups, last_success_at records accepted
archive publication and the normal next interval is retained even when services
need recovery. Publication uncertainty also avoids an immediate heavy retry,
but does not create a successful-backup timestamp or verified-archive claim.
Measured phase percentages¶
Backends advertising installation_backup_phase_progress=true can include measured
phase totals. When a phase has a measured total, progress can include total_entries,
total_logical_bytes or total_bytes, together with percent and
percent_basis ("entries" or "bytes"). These fields describe only the current
phase. Omit the progress bar when its measured percentage is absent; a finished
phase does not establish that the archive has passed later checks or been
published. Do not mix compressed stream bytes with logical source totals.
Service state during the operation¶
Job services_stopped and stopped_process_names, when present, report the
exact retained service names whose complete quiescence was verified. Clients
must invalidate stale running/health data when an installation hold begins,
show an unknown or transitioning state while stopping/resuming, and only label
named services stopped when the backend supplies that evidence. The API and
frontend remain control-plane services. A cached green badge is not proof that
an application stayed running through a cold backup.
Cancel an active backup¶
installation_backup_cancellation=true enables POST /jobs/{job_id}/cancel
with an empty request body. Public job fields can_cancel and
cancel_requested advertise whether the worker can accept the request and
whether cancellation is pending. This operation is only for an active
installation_backup, including a scheduled run; it does not cancel restores
or invoke rollback. Keep polling: the worker must leave its current I/O, remove
its own unpublished output and safely resume the retained service set before
reporting cancelled. Resume failure remains recovery_required. Cancellation
acceptance closes before verified archive publication; clients must respect
can_cancel rather than infer eligibility from a running status alone.
Track or cancel a preview¶
Backends advertising installation_backup_preview_status=true track the
backup preview while the existing synchronous POST /preview is running.
Poll GET /preview/status; optional query parameter preview_id pins a selected
operation. The response contains protocol, controller_session and preview
(null when no current preview is retained). An explicitly queried unknown or
expired ID returns 409; it does not start another scan. The operation reports preview_id,
status, stage, message, start/update/completion and last-progress timestamps,
elapsed_seconds, entries, logical_bytes, completed/total root counts,
current_root and destination_id. Statuses are running, cancelling,
completed, failed and cancelled; scan counters do not imply a known total or
an archive write. A completed operation supplies its original review result
and expiry. A completed scan can still return blockers and requires a separate
explicit /start request before a backup begins.
POST /preview/{preview_id}/cancel requests a stop; it does not claim immediate
completion. Wait for cancelled after the worker cleans its temporary ledger
and releases its preview lock. Preview never stops managed writers. Status is
held in controller memory, so a changed controller_session or a missing result
after a restart requires an explicitly requested new preview, not automatic
replay. Confirmation expiry begins after scanning completes. The capability
adds no fixed scan deadline and does not change restore-preview behavior.
Restore and recovery¶
Preview authorization is short-lived and bound to the reviewed source, targets
and storage identity. A restore can select an owned catalog reference or a
container-visible archive path, allowing recovery without the original local
catalog. Backends advertising installation_backup_shared_permissions=true
accept the strict boolean allow_shared_permissions (default false) for that
mounted-file choice. Set it to true only with archive_path after explicit
consent to the source's shared access controls; true with an owned reference is
rejected because its registered profile supplies the policy. The choice is
bound into the reviewed source. Archive integrity, paths and file types are
validated before replacement. The operation preserves rollback evidence and
leaves a successful restore stopped with a container restart required to reload configuration and auth.
The preview states the actual inventory and exclusions. These archives cover managed installation state, not host deployment files, media or external systems. Failed admission, capacity, storage or compatibility checks do not authorize a partial success. See Installation backup and restore for the operating and recovery procedure.
An installation-recovery hold continues to allow normal login/refresh and the
stateless POST /auth/verify session check under their ordinary authentication
rules. This exception does not allow other HTTP methods or unrelated mutations.
A held service/setup request's 409 is not an instruction to clear credentials;
clients retain the session unless authentication itself establishes its expiry.