280 lines
8.8 KiB
Plaintext
280 lines
8.8 KiB
Plaintext
<script type="text/x-handlebars" data-template-name="welcome">
|
||
<p>
|
||
This tutorial is great for getting familiar with the command line
|
||
interface to Vault. As soon as you opened this terminal, you are connected to a real in-memory Vault server.
|
||
Any commands you enter will work as they would with Vault normally, but leaving this page
|
||
will end the session.
|
||
</p>
|
||
<p>
|
||
Please note that this is running in a shared environment, so avoid setting any real secrets.
|
||
</p>
|
||
<p>
|
||
<strong>Use the command "next" to move forward</strong>.
|
||
</p>
|
||
<p>This will work throughout
|
||
the tutorial, along with "previous" to go back a step.
|
||
</p>
|
||
</script>
|
||
|
||
|
||
<script type="text/x-handlebars" data-template-name="steps">
|
||
<p>
|
||
This tutorial will walk you through the following:
|
||
</p>
|
||
<ul>
|
||
<li>- Initializing and unsealing your Vault</li>
|
||
<li>- Authorizing your requests to Vault</li>
|
||
<li>- Reading and writing versioned secrets</li>
|
||
<li>- Updating the stored secrets</li>
|
||
<li>- Deleting the existing secrets</li>
|
||
<li>- Sealing your Vault</li>
|
||
</ul>
|
||
<p>
|
||
<strong>Again, use "next" to move to the first step – initializing your Vault</strong>.
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="init">
|
||
<p>
|
||
To get started, we need to initialize an instance of Vault for you
|
||
to work with.
|
||
</p>
|
||
<p>
|
||
While initializing, you can configure the seal behavior
|
||
of Vault.
|
||
</p>
|
||
<p>
|
||
Initialize Vault now, with 1 unseal key for simplicity, using the command:
|
||
</p>
|
||
<p>
|
||
<code>vault operator init -key-shares=1 -key-threshold=1</code>
|
||
</p>
|
||
<p>
|
||
You'll notice Vault prints out several keys here. Don't clear your terminal,
|
||
as these are needed in the next few steps.
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="unseal">
|
||
<p>
|
||
When a Vault server is started, it starts in a sealed state.
|
||
In this state, Vault is configured to know where and how to access the
|
||
physical storage, but doesn't know how to decrypt any of it.
|
||
</p>
|
||
<p>
|
||
Vault encrypts data with an encryption key. This key is encrypted with the "master key", which
|
||
isn't stored. Decrypting the master key requires a threshold of shards. In this example,
|
||
we use one shard to decrypt this master key.
|
||
</p>
|
||
<p>
|
||
Unseal the Vault:
|
||
</p>
|
||
<p>
|
||
<code>vault operator unseal <key 1></code>
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="auth">
|
||
<p>
|
||
Before performing any operation with Vault, the
|
||
connecting client must be authenticated. Authentication is
|
||
the process of verifying a person or machine is who they say
|
||
they are and assigning an identity to them. This identity is then
|
||
used when making requests with Vault.
|
||
</p>
|
||
<p>
|
||
For simplicity, we'll use the root token we generated on init in Step 2. This
|
||
output should be available in the scrollback.
|
||
</p>
|
||
<p>
|
||
Authorize with a client token:
|
||
</p>
|
||
<p>
|
||
<code>vault login <root token></code>
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="list">
|
||
<p>
|
||
Vault's secrets engines are components which store, generate or encrypt data.
|
||
List which secret engines have been enabled and ready to use.
|
||
</p>
|
||
<p>
|
||
<code>vault secrets list</code>
|
||
</p>
|
||
<p>
|
||
Key/Value Version 2 secret engine is enabled at "secret/" which retains a configurable number of data versions.
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="secrets">
|
||
<p>
|
||
Now we can start reading and writing secrets with the default enabled
|
||
secrets engine. Secrets written to Vault are encrypted and then written
|
||
to the backend storage. The backend storage mechanism never sees the
|
||
unencrypted value and doesn't have the means necessary to decrypt it
|
||
without Vault.
|
||
</p>
|
||
<p>
|
||
<code>vault kv put secret/apikey key="my-test-key"</code>
|
||
</p>
|
||
<p>
|
||
Of course, you can then read this data too:
|
||
</p>
|
||
<p>
|
||
<code>vault kv get secret/apikey</code>
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="update">
|
||
<p>
|
||
Let's update the stored data by running the "put" command again:
|
||
</p>
|
||
<p>
|
||
<code>vault kv put secret/apikey key="my-test-key" owner="dev"</code>
|
||
</p>
|
||
<p>
|
||
This creates version 2 of the data at secret/apikey.
|
||
</p>
|
||
<p>
|
||
What happens if you execute the following command?
|
||
</p>
|
||
<p>
|
||
<code>vault kv put secret/apikey owner="ops"</code>
|
||
</p>
|
||
<p>
|
||
Run the "get" command again to see what values are stored:
|
||
</p>
|
||
<p>
|
||
<code>vault kv get secret/apikey</code>
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="patch">
|
||
<p>
|
||
The "put" operation updates the existing data.
|
||
When you want to partially update the data without overwriting the rest, use the "patch" command.
|
||
</p>
|
||
<p>
|
||
<code>vault kv patch secret/apikey year="2018"</code>
|
||
</p>
|
||
<p>
|
||
Run the "get" command again to verify that the year was simply added to the existing data:
|
||
</p>
|
||
<p>
|
||
<code>vault kv get secret/apikey</code>
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="versions">
|
||
<p>
|
||
The following command retrieves the key metadata at secret/apikey:
|
||
</p>
|
||
<p>
|
||
<code>vault kv metadata get secret/apikey</code>
|
||
</p>
|
||
<p>
|
||
At this point, there are four versions of the data.
|
||
To retrieve the first version of the secret:
|
||
</p>
|
||
<p>
|
||
<code>vault kv get -version=1 secret/apikey</code>
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="delete">
|
||
<p>
|
||
You can delete specific version(s) of the secret:
|
||
</p>
|
||
<p>
|
||
<code>vault kv delete -versions=1 secret/apikey</code>
|
||
</p>
|
||
<p>
|
||
Retrieve the version 1 of the data again. Since the data was deleted, only the metadata gets displayed with data deletion time.
|
||
</p>
|
||
<p>
|
||
<code>vault kv get -version=1 secret/apikey</code>
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="recover">
|
||
<p>
|
||
When the data was deleted unintentionally, you can recover by executing the "undelete" command:
|
||
</p>
|
||
<p>
|
||
<code>vault kv undelete -versions=1 secret/apikey</code>
|
||
</p>
|
||
<p>
|
||
Once the data was recovered, you should be able to retrieve the version 1 of the data successfully:
|
||
</p>
|
||
<p>
|
||
<code>vault kv get -version=1 secret/apikey</code>
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="destroy">
|
||
<p>
|
||
To permanently delete the data version(s), perform the "destroy" operation instead of "delete":
|
||
</p>
|
||
<p>
|
||
<code>vault kv destroy -versions=1 secret/apikey</code>
|
||
</p>
|
||
<p>
|
||
Now, the version 1 of the data is no longer recoverable.
|
||
</p>
|
||
<p>
|
||
The following command deletes all versions and metadata at secret/apikey:
|
||
</p>
|
||
<p>
|
||
<code>vault kv metadata delete secret/apikey</code>
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="help">
|
||
<p>
|
||
At this point, secret/apikey no longer exists. You can verify it by executing the following command:
|
||
</p>
|
||
<p>
|
||
<code>vault kv list secret/</code>
|
||
</p>
|
||
<p>
|
||
To learn more about the K/V command:
|
||
</p>
|
||
<p>
|
||
<code>vault kv -h</code>
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="seal">
|
||
<p>
|
||
There is also an API to seal the Vault. This will throw
|
||
away the encryption key and require another unseal process
|
||
to restore it. Sealing only requires a single operator
|
||
with root privileges. This is typically part of a rare "break glass
|
||
procedure".
|
||
</p>
|
||
<p>
|
||
This way, if there is a detected intrusion, the Vault data can be locked
|
||
quickly to try to minimize damages. It can't be accessed again
|
||
without access to the master key shards.
|
||
</p>
|
||
<p>
|
||
<code>vault operator seal</code>
|
||
</p>
|
||
</script>
|
||
|
||
<script type="text/x-handlebars" data-template-name="finish">
|
||
<p>
|
||
Thanks for trying out the Vault CLI. If you want to keep playing with
|
||
commands, use "fu" to go fullscreen.
|
||
</p>
|
||
<p>
|
||
Note that the Vault CLI uses the HTTP API, which gives you full access to Vault. Every aspect
|
||
of Vault can be controlled via this API.
|
||
</p>
|
||
<p>
|
||
We recommend reading through the <a href="/intro/index.html">intro guide</a> next, which will
|
||
provide more background information, use cases and examples.
|
||
</p>
|
||
</script>
|