Backup and Restore

Documentation for the image tag 1.0.0-rc1.1. See Versions for the documentation of a release.

Backup and Restore

/data holds your CA private key, the database, the encryption key ring and the identity store. There is no other copy. Back it up regularly and keep the archives off the host.

The scripts live in deploy/single-container/ and deploy/multi-container/ in the release you installed. Each has a PowerShell 7 twin (.ps1); Windows PowerShell 5.1 is not supported. They work against a running container whether /data is a bind mount or a named volume.

Take a backup

# single container
./backup.sh ./backups

# multi container
deploy/multi-container/backup.sh ./backups

The container is stopped briefly (a few seconds) so the database and key files are consistent, then restarted. Each backup produces qertum-backup-<timestamp>.tar.gz and a .manifest file listing a checksum for every file.

Schedule it (cron, systemd timer, Task Scheduler) and copy the archives to another machine. A backup on the same disk does not protect against disk failure.

Prove the backup

./restore-test.sh ./backups          # tests the newest archive that has a manifest

It extracts the archive into a scratch volume, compares it with the manifest, then opens the copy offline: it decrypts a stored secret with the restored key ring, signs a probe with each online issuer and builds a CRL. It never stops or changes the running container.

Exit code	Meaning
0	Archive matches what was on /data, and the restored files work
1	A file differs, is missing or was added, or a check failed (named in the output)
2	The test could not run: no Docker, no manifest, a backup from another Qertum version than the image

"Usable" means the restored files work when read by this release. It does not start the whole stack, and it cannot test keys held in a TPM or an external vault. A passing test is not tamper protection: anyone who can change both the archive and its manifest can forge a pass.

Restore

Restoring is a rollback, not a merge. Everything after the backup is gone, including requests, issued certificates and revocations made since.

1. Use the same image release, the same QERTUM_HOST and the same published ports. The authority and ACME URLs are derived from them.

2. If the current volume is still readable, back it up first: ./backup.sh ./before-restore.

3. Prove the archive: ./restore-test.sh ./backups/qertum-backup-<timestamp>.tar.gz.

4. On a new host, copy the archive and compose file and run docker compose up -d once to create an empty container.

5. Restore:

   ./restore.sh ./backups/qertum-backup-<timestamp>.tar.gz [container-name]

   It asks for confirmation, stops the container, clears /data, extracts the archive and restarts.

6. Sign in, and check that Settings, System shows the CA initialised with the issuers you expect. qca doctor runs read-only checks.

What a restore changes

• A certificate issued after the backup is still valid where it was installed, but this CA has no record of it and cannot revoke it.
• A certificate revoked after the backup is no longer revoked; revoke it again.
• CRL numbers roll back. After a restore publish a fresh CRL (qca ca crl reset-base, needs settings.edit) and check the number against what your relying parties last fetched.
• Redis caches start empty and rebuild on first use.
• ACME accounts and EST credentials created after the backup must be registered again.

TPM-sealed keys and moving hardware

If you enabled TPM-backed secret storage, the key ring is sealed to that one TPM. A backup restores only onto the same TPM. Before moving to new hardware, migrate back to the local file key (Settings, Secret Storage), restart, take a fresh backup, and test it. If the TPM is lost or cleared without having done this, what it protected cannot be recovered; restore an older backup taken before TPM storage was enabled.

Do not use key export as a backup

An administrator can export a CA issuer's private key. That is unencrypted key material outside /data, and whoever holds it can sign for your CA. Back up /data; export a key only for an offline copy you will store securely.

Audit log integrity

Audit lines are hash-chained. To make the chain worth something, create a webhook subscribed to AuditCheckpoint that stores every body on another host, then verify a copy of the logs with qca audit verify <dir> --anchor <saved checkpoint>.