Disaster recovery and backup

Persist and back up the data a Virtual Signer stores, so it survives restarts and host loss

The Virtual Signer writes its key shares and other sensitive data to encrypted files in persistent storage. It must be able to read them at all times, including after a restart. Keep this storage on a persistent volume, so that restarting or recreating the containers doesn't delete it.

Storage backends

The Virtual Signer can store its encrypted keys and shares in these backends:

BackendConfigurationUse case
Filesystem(default)Self-hosted deployments
AWS S3IOSIGN_SIGNER_BROKER_STORAGE_BUCKET_URL=s3://bucket?region=us-east-1AWS deployments
Azure BlobIOSIGN_SIGNER_BROKER_STORAGE_BUCKET_URL=azblob://containerAzure deployments

Where data is stored

The storage location is set by IOSIGN_SIGNER_BROKER_STORAGE_BASE_PATH, /var/vsigner by default. It holds the signer's encrypted shares and its disaster recovery (.dr) files. The signer writes new .dr files at every key generation and reshare, and never deletes them, so include this location in your volume backups. See Virtual Signer disaster recovery.

Sign journal

The Virtual Signer keeps a sign journal in the same storage location: a record of every sign request it has committed to. It never signs a recorded request again, even if the backend asks for it. Each record stays for 24 hours after its request expires.

  • Capacity. The journal holds at most 16,384 live records. When it's full, the Virtual Signer refuses new sign requests until older records expire. The Broker publishes vs_broker_sign_journal_entries and vs_broker_sign_journal_capacity on its metrics port, 2113 by default. Alert well before the first reaches the second.
  • Damaged journal. If storage is unreachable, the Broker retries for up to 5 minutes and then stops, so your container platform restarts it. If the journal is damaged, the Broker doesn't start. Stop it, move private-keys/<SIGNER_ID>.sign-journal.json out of the storage location, and start it again.
  • Restores. Restoring the volume from a backup also restores the journal as it was at backup time. After a restore, or after you move the journal aside, the Virtual Signer can sign again a request it signed earlier, for up to 48 hours: a request expires at most 24 hours after it's created. Only a compromised backend would send such a request.

Azure SKR encryption

For Azure deployments, Secure Key Release (SKR) encrypts stored data with keys that Azure releases only to verified confidential containers.

Recovery bundles

Backing up the storage volume protects the running signer. To recover a vault offline, you use a recovery bundle instead. signerctl share backup exports it as a single ZIP containing the signer's .dr files and an integrity manifest.

docker compose exec vs-broker signerctl share backup

signerctl writes bundles to the directory set by IOSIGN_SIGNER_BROKER_BACKUP_BASE_PATH. Export one after the signer joins a new vault, after every reshare, and on a regular schedule. A bundle taken before the latest reshare may not hold enough current shares to recover the vault.

A bundle contains only .dr files. It isn't a complete signer backup, and you can't restore a running Virtual Signer from one. You need both: volume backups restore service, and bundles recover vaults. For the full procedure, see Virtual Signer disaster recovery.

❗️

Volume backups alone can't recover a vault

Backing up this volume isn't enough on its own. Only the ML-KEM-768 private key can decrypt the .dr files it contains. Your Product Owner (Business User) generated that key before the signer was first deployed, and holds it offline. As part of your backup strategy, confirm that you can retrieve it.

Run regular air-gapped disaster recovery drills, so your team can recover a vault if it ever needs to.


Did this page help you?