Planning Your Data Protection

SHIELD can perform Vault backups in a few different ways, depending on your network throughput, access control, and personal preferences.

Local Agent

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 address,

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.

Remote Agent

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.

System Prerequisites

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.


Two parameters govern the authentication to your Vault server: Vault URL, and Vault Token.

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 secret/.

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.

Configuration Reference

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 secret/ tree.
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.