myena/consul-backinator repository overview

⁠consul-backinator

⁠Summary

Flexible Consul KV pair backup and restore tool with a few unique features including ACL token and prepared query backup and restoration.

⁠Key Features

• Written in Golang using the official Consul API
• No limits on the number of keys that can be backed up or restored
• Backup files are written as gzip compressed and AES256 encrypted JSON data
• Data integrity validation via HMAC-SHA256 signature of the raw data
• Optional path transformation (path replacement) on key backup and/or restore
• Clean well documented code that's simple to follow
• Direct AWS/S3 support for backup and restoration of KVs, ACLs and queries
• Node auto discovery in cloud environments via go-discover⁠

⁠Installing

OS X/macOS Homebrew users ...

brew install consul-backinator

Users with a proper Go environment (1.8+ required) ...

go get -u github.com/myENA/consul-backinator

Developers that wish to take advantage of vendoring and other options ...

git clone https://github.com/myENA/consul-backinator.git
cd consul-backinator
make

To build as a Docker container ...

git clone https://github.com/myENA/consul-backinator.git
cd consul-backinator
make docker

To use the latest container from Docker Hub ...

docker pull myena/consul-backinator
docker run myena/consul-backinator

See DOCKER.md⁠ for some Docker use cases.

To run on Nomad ...

git clone https://github.com/myENA/consul-backinator.git
cd consul-backinator

Edit the job specification file consul-backinator.nomad to suit your environment. It uses S3 by default and must be configured with the correct bucket URI, access key, and secret key. It's recommended to use a dedicated consul-backinator user with IAM permissions to just this bucket for security purposes. The job runs every 15 minutes by default and logs to STDERR and STDOUT.

⁠Security

Releases after 1.4 will be accompanied by a GPG signed SHA256SUM file.

Releases from 1.6.6 will use this GPG key:

Education Networks of America (ENA github code signing key) <[email protected]>

The public key 720E001BD902187F83763C62C924F0AC9DA36FEB⁠ is available via public servers and gpg/[email protected]⁠ in this repository.

For previous releases, they are signed by this key:

ENA R&D Team (ENA R&D code signing key) <r&[email protected]> 73F17750

This old key is still available at 62859FAD5BAEA13C3839D5053CA59EE673F17750⁠ via public servers.

When verifying releases please note that only the SHA256SUM file is signed with the GPG key. The following process should be more than satisfactory to verify the authenticity of any release.

⁠Verifying Releases

Using the key downloaded from the public server or contained in this repository you should import the gpg key into your local key store.

gpg --import "[email protected]"

Next, with the release archive, shasum and signature file downloaded you should verify integrity of the checksum file using the GPG signature.

gpg --verify consul-backinator-1.6.6-SHA256SUMS.sig consul-backinator-1.6.6-SHA256SUMS

Finally, ensure the downloaded archive matches the verified checksums file. Only downloaded archives in the current directory will be checked.

shasum -a 256 -c consul-backinator-1.5-SHA256SUMS

If the above steps completed without error you have a verified release!

⁠Usage

⁠Summary

ahurt$ ./consul-backinator --help
usage: consul-backinator [--version] [--help] <command> [<args>]

Available commands are:
    backup     Perform a backup operation
    dump       Dump a backup file
    restore    Perform a restore operation

⁠Backup Options

⁠Restore Options

⁠Shared Consul Options (backup/restore)

⁠Dump Options

⁠Transformations

Transformations are simple string operations and will affect the path anywhere there is a match. For example, passing -transform="foo,bar" would rewrite /apple/foo/key => /apple/bar/key as well as /orange/thing/foo/key => /orange/thing/bar/key. To avoid potential errors in transformations you should always use the most exact path possible. Using the previous example if you only wanted to affect keys under apple you should pass -transform="apple/foo,apple/bar" to prevent other paths from being modified inadvertently.

⁠S3 Support

Support for S3 is implemented by passing an S3 URI to the standard -file option. The full format for the URI is as follows:

s3://access-key:secret-key@my-bucket/path/to/object?region=us-east-1&endpoint=my-s3gw:9000&secure=false

The minimal URI when using environment variables would be: s3://my-bucket/path/object

The current URI parsing accepts s3:// and s3n:// scheme prefixes.

This table describes all the S3 URI options and corresponding environment variables.

⁠Example

ahurt$ ./consul-backinator backup -key=superSecretStuff
2016/05/09 17:14:11 [Success] Backed up 289 keys from / to consul.bak
Keep your backup (consul.bak) and signature (consul.bak.sig) files in a safe place.
You will need both to restore your data.

ahurt$ ls -la *.sig *.bak
-rw-------  1 ahurt  staff  11167 May  9 17:14 consul.bak
-rw-------  1 ahurt  staff     44 May  9 17:14 consul.bak.sig

⁠Thanks

• The HashiCorp⁠ folks for the excellent Consul service discovery daemon and the excellent embedded API and golang package. In addition to some very nice references back to this utility in a few issues.
• Adam Avilla⁠ for his time and contributions to the Docker portions of the build.
• All the other contributors, testers and stargazers.