Planning Your Data Protection
SHIELD can perform Vault backups in a few different ways, depending on your network throughput, access control, and personal preferences.
The simplest method is to run the SHIELD agent on the same box as the
vaule server process, and connect to it over the loopback
If you want to protect more than one Vault, you can install the agent on each. They will all then register with the SHIELD instance, with different identities, and you can configure backup jobs for each of them.
You can also run the SHIELD agent somewhere else, and configure your backup jobs to connect to the Vault host(s) over TCP, using either their public IPs, or (if you have configured them) internal Linode IPs.
This can be useful if you'd rather not load additional software on your Vault host(s). You can also reuse the external agent to protect multiple Vault instances, since your backup jobs will specify the IP address of each.
SHIELD uses the Vault HTTP REST/JSON API for both snapshots and restoration, so there is no dependency on other installed software.
Configuring Backup Jobs
With Vault, you can constrain how much or how little of the full set of stored secrets you protect. For most use cases, you'll want to backup all of them, but you can limit your export to a subset of the Vault hierarchy.
It's entirely up to you.
This plugin currently only supports token authentication. Since non-root tokens in Vault are time-scoped for security purposes, and because SHIELD doesn't regularly communicate with data systems when it is not doing data protection operations, these types of tokens will eventually expire and render your backup configuration unusable.
For this reason, you must currently use a root Vault authentication token for configuring backups.
TLS Certificate Verification
Vault is a sensitive system, by its very nature. In all but the most
trivial cases, you're going to want to connect to it over TLS to prevent
would-be network sniffers in the dark. This is as simple as supplying a
https:// URL during plugin configuration.
The Vault SHIELD plugin will validate the X.509 TLS certificate it receives from the Vault cluster, to ensure that it is signed by a known authority, is valid for the identity we are connect to, and that it has not expired.
It is, however, not unusual to find live Vault installations that are wholly disconnected from the traditional web-of-trust of the Internet Public Key Infrastructure (PKI). Such clusters either use self-signed certificates, or a custom X.509 Certificate Authority to issue their Vault certificates.
To support these scenarios, the Vault SHIELD data protection plugin has a parameter, Skip SSL Validation that will countermand the default validation logic, and accept any correct X.509 certificate.
While this can be useful, and does help work around expired but otherwise valid X.509 certificates, it does open up your data protection setup to server masquerades, impersonation, and other such attacks.
Backing up All Secrets
The default configuration of the Vault backup plugin is to
protect all secrets found in the kv v1 or v2 backend mounted at
You dont' have to do anything — just make sure to leave the Vault Subtree parameter blank (its default value)!
Backing up Some Secrets
If you only want to back up a subset of the Vault path hierarchy, specify the path to that subtree's root in the Vault Subtree parameter when you configure your data system. The plugin will then start its secrets traversal there, instead of at the root.
Note: this parameter has no bearing on restores; SHIELD will restore all secrets found in the snapshot archive, regardless of what you set for Vault Subtree.
Restoring Vault from a Snapshot
When the Vault SHIELD plugin snapshots a Vault, it does a recursive walk of the selected mount (optionall constrained by the subtree parameter, and dumps the found secrets.
Restoration works this process in reverse; as keys and values are read in from the snapshot, they are PUT to the backing Vault cluster, overriding any pre-existing secrets, and creating any missing ones.
Note: this is an additive process. If you restore a snapshot to a non-empty Vault, any secrets that were not present when the snapshot was taken will continue to exist after the restore completes.
It is also worth noting that this plugin only protects kv v1 and v2 mountpoints. It does not extract configuration from other Vault backend mounts, nor does it snapshot policies, or userauth configurations.
This section details all available configuration parameters for the Vault data protection plugin.
- Vault URL
- The url address of your Vault server, including the protocol.
- Auth Token
- The auth token for a user with privileges to read and write the entire
- Vault Path Subtree
- A subtree to limit the backup operation to.
- Skip SSL Validation
- If your Vault certificate is invalid, expired, or signed by an unknown Certificate Authority, you can disable SSL validation. This is not recommended from a security standpoint, however.