Backup CLI

docsentry-backup is the command-line backup tool, in tools/Docsentry.Backup.

There is no restore verb

The tool creates and lists backup sets. It does not restore them. Restoring is currently a manual procedure using the database backup file inside the set and a file-level copy of the storage tree. Do not treat a successful backup as a tested recovery path - see Backup.

Usage

docsentry-backup [--help] | [--version] | selftest
                 | backup --profile <name> [--config <path>] [--dry-run]
                 | list [--profile <name>] [--dest <name>] [--config <path>]

Verbs

backup

Creates a backup set and writes it to the profile’s destinations.

Option	Required	Purpose
--profile <name>	Yes	The profile to run, from the configuration file.
--config <path>	No	Path to the configuration file. Defaults to the standard location.
--dry-run	No	Evaluate preflight checks and report what would happen, without writing anything.

--dry-run is the right way to validate a new profile. It exercises the preflight checks - credentials, destination reachability, free space, database access - without producing output.

list

Lists the backup sets a destination holds.

Option	Required	Purpose
--profile <name>	No	Restrict to one profile.
--dest <name>	No	Restrict to one destination.
--config <path>	No	Path to the configuration file.

With no options it lists everything the configuration can see.

selftest

Runs the tool’s internal self-test - cryptographic round-trips and manifest signing and verification - and reports the result. Takes no options.

Run it after installing the tool on a new host, and after any change to how keys are provisioned. It confirms the machine can produce and verify a set, which is the part of the pipeline that fails silently if it is going to fail.

--help and --version

Print usage and version respectively. Both take no other arguments.

Configuration

The tool reads a JSON configuration file defining profiles and destinations. An example ships at tools/Docsentry.Backup/profiles/backup.config.example.json - start from it rather than writing one from scratch.

A profile names what to back up and where to send it. A destination names a target and its settings.

What a set contains

Part	Notes
Database backup	Taken with COPY_ONLY, then verified.
Storage tree	The content-addressed blob store.
Signed manifest	Canonical JSON listing every part with its hash, signed.
Secret inventory	A record of which secrets the deployment depends on - not the secret values.

Everything is written inside an encrypted envelope. The manifest is signed separately, so tampering with a set is detectable rather than merely unlikely.

COPY_ONLY is unconditional and deliberate

The database backup is always taken with COPY_ONLY. Omitting it would make this tool a participant in whatever differential or log backup chain the database team already runs, and silently break their restore sequence. This is not configurable, and should not be.

Exit codes

The tool distinguishes usage errors from operational failures, so a script can tell “you invoked it wrongly” from “the backup did not work”. A non-zero exit always means the set was not produced successfully - never treat a non-zero exit as a warning.

In a scheduled job

docsentry-backup backup --profile nightly --config /etc/docsentry/backup.config.json

Check the exit code and alert on non-zero. A backup job whose failures are not surfaced is a backup job that is not running.

Related

• Backup - what to back up, and the restore gap in full.
• Security hardening - the Data Protection key ring, which must be backed up too.