Skip to main content

Backups

Every node on Treasury creates its own encrypted snapshots periodically, which you can freely backup and use to independently restore nodes (using decryption key).

There are two main processes that carry data.

  • Engine: manages all of the state needed to control policies: access controls, addresses, users, transfer rules, consensus information, etc.
  • Signer: manages key material.

The data exported by engine isn't sensitive and thus doesn't need to be encrypted.

Whereas the data exported by signer is always encrypted.

Backup or restore everything​

info

cord backup snapshot command is only available on Treasury v24.3.1 or after.

You can create a complete backup of a node by running the following.

cord backup snapshot --home path/to/treasury_home --bak AGE_BACKUP_KEY --output snapshot.tar

Similarly, you can then import the snapshot by running the following.

# you will be prompted to enter in the backup phrase.
cord backup restore --home path/to/treasury_home --snapshot snapshot.tar

A treasury appliance will periodically create it's own snapshots in it's configured backup directly. Any key material is encrypted to the configured bak, so the snapshot.tar does not reveal any secret information by itself.

What is a bak or mnemonic?​

bak is short for Backup key. We use age for backup encryption. A the public componment of a backup key looks something like age1lkdk8m4whnyngxj5y4q6hvfsmzrgllek469ggt3gee37qms7pcjq6selk3, and the secret component is a 12 word mnemonic, to make it easy to write down.

You can generate a new bak and mnemonic by running the following.

cord backup bak

Manual backup and restore​

If you run into a situation where you only want to restore engine state, or manage keys directly, you can do so. Perhaps you want to export a key for external use, or to import new keys.

Signer​

Key material (part of signer) is part of the whole Treasury backup, but can be managed separately for backup and restore if needed.

Overview​

After deployment, Signer should be configured with two things:

  • A public key of an age credential, which looks something like age1lkdk8m4whnyngxj5y4q6hvfsmzrgllek469ggt3gee37qms7pcjq6selk3.
  • A "backup directory", where to store all encrypted resources/snapshots.

You can see the currently configured backup key on a node by running signer init-node --db path/to/signer.db.

The signer will automatically export "snapshots", and "resources", both encrypted to the age public key.

Use signer backup subcommand to manage backups.

Manage backups and recovery

Usage: signer backup [OPTIONS] <COMMAND>

Commands:
  decrypt        Decrypt an encrypted age file to plaintext
  encrypt        Encrypt an input file
  import         Import an JSON files bearing encrypted resources
  export         Encrypt and export resources individually
  legacy         Legacy commands for managing backup material
  restore        Restore from an encrypted snapshot
  snapshot       Create an encrypted snapshot of a signer.db
  compare-keys   Compare keys in treasury against contents of signer database
  recover-key    Recover a key from combining encrypted shares
  verify-phrase  Verifications of the backup phrase
  help           Print this message or the help of the given subcommand(s)

Options:
  -c, --config <CONFIG>
  -v, --verbose...       Increase logging verbosity
  -q, --quiet...         Decrease logging verbosity
  -h, --help             Print help
  -V, --version          Print version

Snapshots​

A snapshot is everything contained by signer. All keys, identity information, etc. You can manually decrypt the snapshot using age (or signer) and visually inspect it -- it's JSON. You can restore a signer node using only this snapshot (and the decryption key). A snapshot is taken only periodically (or manually), about every hour. This snapshot is also what is used when you snapshot all of Treasury.

Exported resources​

A resource is an individual key-share, or key, exported by signer. While all resources are always included in a snapshot, snapshot is not taken every time a resource is created.

An encrypted resource is exported immediately after it's created, and it's also gossiped to all other signer nodes for them to store in their backup directories.

In the event that a snapshot does not capture new keys created before a total failure, the encrypted resources (either from the failed node, or other nodes) can be imported after restoring from the last known snapshot.

Exported resources are JSON files that include an age-encrypted base64 blob.

Take a snapshot​

A snapshot is everything contained by signer. All keys, identity information, and credentials.

signer backup snapshot --db $TREASURY_HOME/signer.db --output snapshot.json.age

The snapshot is an encrypted JSON file. We can decrypt it and manually inspect it (WARNING: this reveals key material)1.

 export SIGNER_BAK_PHRASE="<your-12-word-mnemonic-phrase>"
signer backup decrypt snapshot.json.age
cat snapshot.json

Restore from a snapshot​

You can restore all signer information and key material from a snaphshot. Here we'll restore to a temporary directory, but in production you should restore to $TREASURY_HOME/signer.db1.

 export SIGNER_BAK_PHRASE="<your-12-word-mnemonic-phrase>"
mkdir restored
signer backup restore --snapshot snapshot.json.age --db ./restored/signer.db

By default, keys are not overwritten if there's any conflict restoring to an existing signer.db. Pass --overwrite to overwrite any existing data. You can encrypt to a different backup key by passing --bak.

Individual keys​

You can manually export and import individual key shares. They will be exported as encrypted blobs in JSON files with metadata.

To export:

signer backup export --db $TREASURY_HOME/signer.db --output-dir ./key-shares "keys/356"

You can export to a new decryption key by passing --bak.

To import:

signer backup import --db $TREASURY_HOME/signer.db key-shares/participants/1/shares/keys-356@1.json

Verifying​

You can verify that a mnemonic phrase is correct (as explicitly expected, or as configured in the signer database), or that a snapshot file decrypts1. In any case, the following command outputs the derived bak key.

 export SIGNER_BAK_PHRASE="<your-12-word-mnemonic-phrase>"

signer backup verify-phrase --bak "<your-expected-bak>"
# or
signer backup verify-phrase --db $TREASURY_HOME/signer.db
# or
signer backup verify-phrase --file "<your-snapshot-or-encrypted-file>"

After the node is restored, you can test that all the keys in Treasury have key shares present in the local signer.db.

signer backup compare-keys --api http://localhost:8777 --db $TREASURY_HOME/signer.db

Use signer list-keys --db $TREASURY_HOME/signer.db to further manually inspect as needed. This does not expose any key material.

Footnotes​

  1. Note that a leading space before the export of an environment variable prevents the command from being stored in shell history. ↩ ↩2 ↩3 ↩4