Backup CLI

docsentry-backup is the command-line backup and restore tool, in tools/Docsentry.Backup. It is published self-contained for Windows and Linux. See Backup and restore for what it protects and why.

Usage

docsentry-backup --help | --version | selftest
docsentry-backup backup  --profile <name> [--config <path>] [--dry-run] [--use-app-connection] [--log-json]
docsentry-backup list    [--profile <name>] [--dest <name>] [--config <path>]
docsentry-backup verify  --profile <name> [--set <id>] [--level Manifest|Structure|Content] [--dest <name>] [--config <path>]
docsentry-backup restore --profile <name> --confirm-target <database> [--set <id>] [--dest <name>] [--dry-run] [--config <path>]

--config defaults to backup.config.json beside the executable.

Verbs

backup

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

Option	Required	Purpose
--profile <name>	Yes	The profile to run.
--dry-run	No	Run the preflight checks and report what would happen, without writing anything.
--use-app-connection	No	Take the database connection from the application’s configuration instead of the profile.
--log-json	No	Emit structured JSON log lines, for a scheduler or log collector.

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

list

Lists the backup sets a destination holds. --profile and --dest narrow the listing; with neither it lists everything the configuration can see.

verify

Verifies a backup set.

Option	Required	Purpose
--profile <name>	Yes	The profile whose sets to verify.
--set <id>	No	The set to verify. Defaults to the latest complete set.
--level	No	Manifest (default), Structure, or Content.
--dest <name>	No	Read from a specific destination.

Level	Checks
Manifest	The manifest opens and its signature is valid.
Structure	Every listed part is present at the destination.
Content	Every part decrypts and matches its recorded hash.

restore

Restores a set onto the profile’s target database and storage root.

Option	Required	Purpose
--profile <name>	Yes	The profile describing the target.
--confirm-target <database>	Yes	Must name the target database. A mismatch refuses the restore.
--set <id>	No	The set to restore. Defaults to the latest complete set.
--dest <name>	No	Read from a specific destination.
--dry-run	No	Run the preflight checks only.

A restore places the storage tree and key ring first, then restores the database with automatic file relocation, repairs orphaned database users, clears scheduled job state, and checks the schema ledger. Re-running an interrupted restore skips files already in place.

selftest

Runs the tool’s cryptographic round trips and manifest signing and verification, and reports the result. Run it after installing on a new host and after any change to key provisioning.

Configuration

The tool reads a JSON file defining profiles and destinations. An example ships at tools/Docsentry.Backup/profiles/backup.config.example.json; start from it.

A profile names what to back up and where to send it. A destination names a target and its settings. The current release writes to local and network file-system destinations.

What a set contains

Part	Notes
Database backup	COPY_ONLY full backup, checked with RESTORE VERIFYONLY.
Storage tree	The encrypted content store.
Key ring	The Data Protection keys needed to read the content.
Signed manifest	Canonical JSON listing every part with its hash.
Secret inventory	Which secrets the deployment depends on - not their values.

Every part is written inside an encrypted envelope; the manifest is signed.

Exit codes

Code	Meaning
0	Success.
1	Usage error - wrong verb, missing or conflicting options, invalid configuration.
2	Preflight failed; nothing was written.
3	Partial success - for example, one of several destinations failed.
4	Backup failed.
5	Verification failed.
6	Retention aborted.
7	Cryptographic error.
8	Restore failed.
130	Cancelled.

Treat every non-zero exit as a failure and alert on it.

In a scheduled job

docsentry-backup backup --profile nightly --config /etc/docsentry/backup.config.json --log-json
docsentry-backup verify --profile nightly --level Structure --config /etc/docsentry/backup.config.json

Related

• Backup and restore
• Security hardening - the key ring.