Backups

What a backup holds#

Every night the backup container dumps the database to one file and takes one encrypted snapshot of that dump and of every document. Once a month it restores the latest snapshot to scratch space, loads the dump into a scratch database, decrypts twenty documents at random and checks each against its recorded hash. Check backup and restore-test results under Settings → Backups. Investigate failed or missing runs before relying on the backup.

Snapshots are encrypted on the box before they leave it, with a password that only the box and your envelope hold. The backup password is required to read the snapshot. Retention is thirty daily and twelve monthly snapshots.

Three things are deliberately not in a backup:

• The master key and the backup password. That is what the envelope is for. Keep a separate recovery copy of both secrets.
• The live database directory. It is inconsistent while the server runs. The nightly dump is the database, so recovery is limited to the most recent successful snapshot. Failed or missed runs can increase the amount of data you lose.
• Queues and scratch space. Anything that was mid-scan at the moment of loss shows as queued or failed in the Inbox afterwards; open it and add the file again.

Where backups go#

The installer asks and writes the answer into the configuration. Afterwards, harbor config changes it. Choose one of the following targets.

A Backblaze B2 bucket is the recommended offsite option. Make an application key restricted to that one bucket. The repository line looks like b2:your-bucket-name:/harbor, plus the key id and key.

An SFTP host you already have, a NAS or a relative's machine. The line looks like sftp:backup@nas.local:/srv/harbor.

A second disk in the same machine is the no-cloud option. Create the directory and chown 1000:1000 it, since the backup container writes as that user. It survives a dead system disk. It does not survive a fire, a flood, or a burglar who takes the whole machine.

Leave the target unset and the vault runs, Settings says Not configured, and every night records a failed run. Configure a target and complete a successful backup and restore test before relying on recovery.

Restrict deletion of backup history#

With B2, give the backup a key without the permission to delete files and set BACKUP_PRUNE=false. Snapshots then accumulate until you prune from a laptop that holds a full key. This limits deletion through that credential. Review the provider’s retention settings and keep credentials with deletion access off the Harbor server.

Review the monthly restore test#

Harbor runs an automated restore test on the first of each month. Review the result in Settings → Backups, alongside Back up now and Test a restore. If a test fails, read the reported error, check the destination’s credentials and available space, then run the test again.

Both actions are also commands on the box:

harbor backup          # take a snapshot now
harbor restore-test    # restore the latest snapshot to scratch and verify it

The test checks repository access, loading the database dump, and decrypting a sample of documents. It does not verify every document or replace a full recovery exercise. It does not touch the running vault.

The nightly run starts at BACKUP_HOUR, three in the morning by default, in the TZ you set.