Skip to main content

Preview a config import

POST 
/config/import/preview

Required role: admin. Only an account or token with the admin role can call this operation.

Example request
curl --request POST \
  --header "Authorization: Bearer $HOSERVA_TOKEN" \
  --header "Content-Type: application/json" \
  --data @body.json \
  "https://$HOSERVA_HOST:8008/api/v1/config/import/preview"

Reads the same archive upload as importConfig and reports what an in-place import would change, without changing anything: it writes no database row, no pre-import archive, takes no job hold, and leaves no file behind. blockers lists the refusals importConfig would return for this archive, with the same codes and messages (400 incompatible_archive, 409 archive_other_installation, 409 archive_array_mismatch, 409 restore_path_unsafe); groups compares the archive's database with the live one per category, and lists the custom config files, app templates and app stack files the import would replace, add and remove; it is empty when the archive's schema version differs, since the two cannot be compared. secrets says whether the archive has a passphrase-protected section (status, for secrets.age) and whether the passphrase available opens it and identity.age (identity), and if not, which stacks' .env files would not be restored. The optional passphrase is tried as importConfig tries it: one that does not open the archive's secrets.age, or, for an archive with an identity.age and no secrets.age, its identity.age, is refused as 400 backup_passphrase_incorrect; one that opens secrets.age but not identity.age is not refused, and identity reports passphrase_incorrect. Without a passphrase the configured one is tried, and one that is absent or does not open the files shows only in secrets, never as a refusal; an archive with neither file has nothing to check a passphrase against. An archive that cannot be read is refused as importConfig refuses it (400 invalid_archive, 413 archive_too_large), and a daemon with no config backup wired answers 501 not_configured. Nothing on a data disk is read.

On a fresh install, one with no array configured, bareMetal reports the bare-metal restore (see importConfig): whether the archive's database would be upgraded, and one entry per array disk the archive records, with the attached disk it matched, or none, and a state of matched, absent, replaced or ambiguous. bareMetal.diskMapping is the mapping to confirm, ready to send as importConfig's diskMapping. An archive from a newer schema version is a blocker (archive_newer_version) with no bareMetal. The refusals for another installation's archive or a different array (archive_other_installation, archive_array_mismatch) apply to an installation that has an array only. While no admin account exists this operation is served on the Unix socket only.

Request​

Responses​

What the import would change.