Skip to content

Backup and restore

PKIFactor offers two complementary backups:

Application backup Appliance backup
Started from System > Backup & Restore (or its schedule) pkifactor-ctl backup on the host
Contains The database, exported and encrypted The database, the data keys, the secrets, the TLS certificate, the license and the configuration
Stored Locally on the platform, or on an SFTP server /opt/pkifactor/data/backups/
Typical use Daily scheduled backups, restore of the data Before an upgrade, migration to a new host, disaster recovery

Application backups

In the Administration workspace, open System > Backup & Restore. The page is reserved for administrators. Its Configuration panel summarizes the storage, retention, schedule and archive encryption; the Database Info panel shows the database size, the total number of backups and the last backup.

Settings

Click Edit in the Configuration panel, then Save Configuration.

Setting Meaning
Storage Type Local (Docker Volume) (a persistent volume of the platform) or SFTP (Host, port, Username, Password, absolute Remote Path, /backups by default). S3 / MinIO is listed but not available in this version. A password left empty keeps the stored one
Local Path Absolute path inside the platform, /app/data/backups by default
Schedule Enabled or Disabled, and a cron expression in UTC (0 2 * * *: every day at 02:00)
Retention Number of backups kept (10 by default), older ones are deleted; 0 keeps them all
Encrypt backups (Fernet) Encrypts the archive with the platform's data key (recommended). Encrypted archives carry the Encrypted badge in the history

Invalid values are refused (a relative path, an unknown storage type, a malformed cron expression).

Back up now, download, restore

  • Backup Now creates a backup, stores it with the configured storage and offers it for download.
  • The Backup History lists each backup with its size, whether it was Scheduled or made by an administrator, and its status. Each completed line can be downloaded (Download), restored (Restore) or deleted.
  • Restore from File restores an archive downloaded earlier (.dump, .backup, .sql, .sql.gz, or .enc for an encrypted archive, which is decrypted with the platform's data keys). The file is limited to 50 MB.

A restore replaces all current data. It asks for confirmation and is recorded in the audit trail. It runs as a single transaction: if any statement fails, or the restore takes more than 10 minutes, nothing is changed and the error is shown.

Via the API 
# Routes without /api prefix: called under /api/v1/
curl -s -b jar https://clm.example.com/api/v1/admin/backup                       # configuration and history
curl -s -b jar -X POST https://clm.example.com/api/v1/admin/backup/create -o backup.dump.enc
curl -s -b jar -X POST https://clm.example.com/api/v1/admin/backup/12/download -o backup.dump.enc
curl -s -b jar -X POST https://clm.example.com/api/v1/admin/backup/12/restore
curl -s -b jar -X POST https://clm.example.com/api/v1/admin/backup/restore -F file=@backup.dump.enc

What an encrypted archive needs

The archive is encrypted with a data key, itself wrapped by the key-encryption service (local key, Vault Transit or HSM). Restoring it on another platform needs the same data keys (data/keys/dek_store.json) and access to the same Vault Transit key or HSM key. Keep the appliance backup, which contains them, in a separate place.

Appliance backups

sudo pkifactor-ctl backup
sudo pkifactor-ctl restore /opt/pkifactor/data/backups/pkifactor_backup_20261026_020000.tar.gz.gpg

The archive (pkifactor_backup_<date>.tar.gz.gpg, mode 600) contains:

  • a dump of the database;
  • data/ (wrapped data keys, license);
  • secrets/ (data encryption key, token keys, KMS credentials);
  • nginx/ssl/ (TLS certificate of the platform);
  • .env and docker-compose.yml.

Since version 1.8.30 the archive is encrypted (gpg, AES-256, with an integrity check) with a passphrase kept outside the archive:

Passphrase source Use
/etc/pkifactor/backup.pass Default. Generated (random, mode 600) by the first backup, which prints a warning
PKIFACTOR_BACKUP_PASSPHRASE_FILE Another file, for example on a mounted secret store
PKIFACTOR_BACKUP_PASSPHRASE The passphrase itself, in the environment of the command

Keep the passphrase off the host

Without the passphrase no archive can be restored, and a lost host takes /etc/pkifactor/backup.pass with it. Copy the passphrase to your password vault right after the first backup. On a high-availability cluster each node has its own file unless you give them the same one.

PKIFACTOR_BACKUP_PLAINTEXT=1 produces an unencrypted tar.gz, as before 1.8.30; it is never the default, because the archive contains every key of the platform. pkifactor-ctl restore accepts both formats, so older archives remain restorable.

pkifactor-ctl upgrade takes such a backup automatically before each upgrade.

Restore on a new host

  1. Install the appliance on the new host with the same version (Appliance installation).
  2. Copy the archive and run sudo pkifactor-ctl restore <archive>. On a new host the passphrase file does not exist: put the passphrase in /etc/pkifactor/backup.pass (mode 600), pass it in PKIFACTOR_BACKUP_PASSPHRASE, or type it when asked. The archive is decrypted and checked before any service is stopped.
  3. If the key-encryption service is Vault Transit or an HSM, make sure the new host can reach it (network, Vault AppRole bound addresses, HSM access lists).
  4. Ask ZetaCert for a license bound to the new installation within the 15-day rebind period (License).
  • Schedule a daily application backup with a retention of at least 7, on SFTP to a different system.
  • Take an appliance backup after every configuration change of the platform (KMS, TLS, secrets) and before every upgrade; keep it off the host, and its passphrase in a different place.
  • Test a restore at least twice a year on a separate host, and check that you can sign in and read a certificate's details.