luxolus/open-nomad
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity

merging doc updates

Browse source
This commit is contained in:
Armon Dadgar 2015-09-17 18:00:52 -07:00
parent e293e354c1 9a0d50bdc2
commit 44a711502b
90 changed files with 997 additions and 1075 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
website/LICENSE.md
View file

@ -6,5 +6,5 @@ this should make it clear:
* The text contents of this website are MPL 2.0 licensed.
* The design contents of this website are proprietary and may not be reproduced
or reused in any way other than to run the Vault website locally. The license
or reused in any way other than to run the Nomad website locally. The license
for the design is owned solely by HashiCorp, Inc.

6
website/config.rb
View file

@ -2,12 +2,12 @@
# Configure Middleman
#-------------------------------------------------------------------------
set :base_url, "https://www.vaultproject.io/"
set :base_url, "https://www.nomadproject.io/"
activate :hashicorp do |h|
h.version = ENV["VAULT_VERSION"]
h.version = ENV["NOMAD_VERSION"]
h.bintray_enabled = ENV["BINTRAY_ENABLED"]
h.bintray_repo = "mitchellh/vault"
h.bintray_repo = "mitchellh/nomad"
h.bintray_user = "mitchellh"
h.bintray_key = ENV["BINTRAY_API_KEY"]

BIN
website/source/assets/images/global-arch.png (Stored with Git LFS) Normal file
View file

Binary file not shown.

BIN
website/source/assets/images/region-arch.png (Stored with Git LFS) Normal file
View file

Binary file not shown.

28
website/source/community.html.erb
View file

@ -2,36 +2,36 @@
layout: "inner"
page_title: "Community"
description: |-
Vault is an open source project with a growing community.
Nomad is an open source project with a growing community.
---
<h1>Community</h1>
<p>
Vault is an open source project with a growing community. There are
Nomad is an open source project with a growing community. There are
active, dedicated users willing to help you through various mediums.
</p>
<p>
<strong>IRC:</strong> <code>#vault-tool</code> on Freenode
<strong>IRC:</strong> <code>#nomad-tool</code> on Freenode
</p>
<p>
<strong>Mailing list:</strong>
<a href="https://groups.google.com/group/vault-tool">Vault Google Group</a>
<a href="https://groups.google.com/group/nomad-tool">Nomad Google Group</a>
</p>
<p>
<strong>Bug Tracker:</strong>
<a href="https://github.com/hashicorp/vault/issues">Issue tracker
<a href="https://github.com/hashicorp/nomad/issues">Issue tracker
on GitHub</a>. Please only use this for reporting bugs. Do not ask
for general help here. Use IRC or the mailing list for that.
<h1>People</h1>
<p>
The following people are some of the faces behind Vault. They each
contribute to Vault in some core way. Over time, faces may appear and
The following people are some of the faces behind Nomad. They each
contribute to Nomad in some core way. Over time, faces may appear and
disappear from this list as contributors come and go. In addition to
the faces below, Vault is a project by
the faces below, Nomad is a project by
<a href="https://www.hashicorp.com">HashiCorp</a>, so many HashiCorp
employees actively contribute to Vault.
employees actively contribute to Nomad.
</p>
<div class="people">
<div class="person">
@ -39,8 +39,8 @@ employees actively contribute to Vault.
<div class="bio">
<h3>Mitchell Hashimoto (<a href="https://github.com/mitchellh">@mitchellh</a>)</h3>
<p>
Mitchell Hashimoto is the creator of Vault and works on all
layers of Vault from the core to backends. In addition to Vault,
Mitchell Hashimoto is the creator of Nomad and works on all
layers of Nomad from the core to backends. In addition to Nomad,
Mitchell is the creator of
<a href="https://www.vagrantup.com">Vagrant</a>,
<a href="https://www.packer.io">Packer</a>,
@ -55,7 +55,7 @@ employees actively contribute to Vault.
<div class="bio">
<h3>Armon Dadgar (<a href="https://github.com/armon">@armon</a>)</h3>
<p>
Armon Dadgar is a creator of Vault. He works on all aspects of Vault,
Armon Dadgar is a creator of Nomad. He works on all aspects of Nomad,
focusing on core architecture and security. Armon is also the creator of
<a href="https://www.consul.io">Consul</a>,
<a href="https://www.serfdom.io">Serf</a>,
@ -71,9 +71,9 @@ employees actively contribute to Vault.
<div class="bio">
<h3>Jack Pearkes (<a href="https://github.com/pearkes">@pearkes</a>)</h3>
<p>
Jack Pearkes is the creator of the online interactive demo of Vault.
Jack Pearkes is the creator of the online interactive demo of Nomad.
He maintains this demo as well as the design and interaction of the
Vault website. Jack is an employee of HashiCorp and a primary engineer
Nomad website. Jack is an employee of HashiCorp and a primary engineer
behind <a href="https://atlas.hashicorp.com">Atlas</a>.
He is also a core committer to
<a href="https://www.packer.io">Packer</a>,

28
website/source/docs/audit/index.html.md
View file

@ -3,25 +3,25 @@ layout: "docs"
page_title: "Audit Backends"
sidebar_current: "docs-audit"
description: |-
Audit backends are mountable backends that log requests and responses in Vault.
Audit backends are mountable backends that log requests and responses in Nomad.
---
# Audit Backends
Audit backends are the components in Vault that keep a detailed log
of all requests and response to Vault. Because _every_ operation with
Vault is an API request/response, the audit log contains _every_ interaction
with Vault, including errors.
Audit backends are the components in Nomad that keep a detailed log
of all requests and response to Nomad. Because _every_ operation with
Nomad is an API request/response, the audit log contains _every_ interaction
with Nomad, including errors.
Vault ships with multiple audit backends, depending on the location you want
the logs sent to. Multiple audit backends can be enabled and Vault will send
Nomad ships with multiple audit backends, depending on the location you want
the logs sent to. Multiple audit backends can be enabled and Nomad will send
the audit logs to both. This allows you to not only have a redundant copy,
but also a second copy in case the first is tampered with.
## Sensitive Information
The audit logs contain the full request and response objects for every
interaction with Vault. The data in the request and the data in the
interaction with Nomad. The data in the request and the data in the
response (including secrets and authentication tokens) will be hashed
without a salt using SHA1.
@ -31,7 +31,7 @@ secrets by SHA-ing it yourself.
## Enabling/Disabling Audit Backends
When a Vault server is first initialized, no auditing is enabled. Audit
When a Nomad server is first initialized, no auditing is enabled. Audit
backends must be enabled by a root user using `vault audit-enable`.
When enabling an audit backend, options can be passed to it to configure it.
@ -51,17 +51,17 @@ The existing logs that it did store are untouched.
## Blocked Audit Backends
If there are any audit backends enabled, Vault requires that at least
one be able to persist the log before completing a Vault request.
If there are any audit backends enabled, Nomad requires that at least
one be able to persist the log before completing a Nomad request.
If you have only one audit backend enabled, and it is blocking (network
block, etc.), then Vault will be _unresponsive_. Vault _will not_ complete
block, etc.), then Nomad will be _unresponsive_. Nomad _will not_ complete
any requests until the audit backend can write.
If you have more than one audit backend, then Vault will complete the request
If you have more than one audit backend, then Nomad will complete the request
as long as one audit backend persists the log.
Vault will not respond to requests if audit backends are blocked because
Nomad will not respond to requests if audit backends are blocked because
audit logs are critically important and ignoring blocked requests opens
an avenue for attack. Be absolutely certain that your audit backends cannot
block.

2
website/source/docs/audit/syslog.html.md
View file

@ -14,7 +14,7 @@ The "syslog" audit backend writes audit logs to syslog.
It currently does not support a configurable syslog destination, and
always sends to the local agent. This backend is only supported on Unix systems,
and should not be enabled if any standby Vault instances do not support it.
and should not be enabled if any standby Nomad instances do not support it.
## Options

12
website/source/docs/auth/app-id.html.md
View file

@ -3,7 +3,7 @@ layout: "docs"
page_title: "Auth Backend: App ID"
sidebar_current: "docs-auth-appid"
description: |-
The App ID auth backend is a mechanism for machines to authenticate with Vault.
The App ID auth backend is a mechanism for machines to authenticate with Nomad.
---
# Auth Backend: App ID
@ -11,13 +11,13 @@ description: |-
Name: `app-id`
The App ID auth backend is a mechanism for machines to authenticate with
Vault. It works by requiring two hard-to-guess unique pieces of information:
Nomad. It works by requiring two hard-to-guess unique pieces of information:
a unique app ID, and a unique user ID.
The goal of this credential provider is to allow elastic users
(dynamic machines, containers, etc.) to authenticate with Vault without
having to store passwords outside of Vault. It is a single method of
solving the chicken-and-egg problem of setting up Vault access on a machine.
(dynamic machines, containers, etc.) to authenticate with Nomad without
having to store passwords outside of Nomad. It is a single method of
solving the chicken-and-egg problem of setting up Nomad access on a machine.
With this provider, nobody except the machine itself has access to both
pieces of information necessary to authenticate. For example:
configuration management will have the app IDs, but the machine itself
@ -40,7 +40,7 @@ An example, real world process for using this provider:
4. A new server is provisioned. Configuration management configures the
app ID, the server itself detects its user ID. With both of these
pieces of information, Vault can be accessed according to the policy
pieces of information, Nomad can be accessed according to the policy
set by the app ID.
More details on this process follow:

2
website/source/docs/auth/cert.html.md
View file

@ -3,7 +3,7 @@ layout: "docs"
page_title: "Auth Backend: TLS Certificates"
sidebar_current: "docs-auth-cert"
description: |-
The "cert" auth backend allows users to authenticate with Vault using TLS client certificates.
The "cert" auth backend allows users to authenticate with Nomad using TLS client certificates.
---
# Auth Backend: TLS Certificates

10
website/source/docs/auth/github.html.md
View file

@ -3,17 +3,17 @@ layout: "docs"
page_title: "Auth Backend: GitHub"
sidebar_current: "docs-auth-github"
description: |-
The GitHub auth backend allows authentication with Vault using GitHub.
The GitHub auth backend allows authentication with Nomad using GitHub.
---
# Auth Backend: GitHub
Name: `github`
The GitHub auth backend can be used to authenticate with Vault using
The GitHub auth backend can be used to authenticate with Nomad using
a GitHub personal access token.
This method of authentication is most useful for humans: operators or
developers using Vault directly via the CLI.
developers using Nomad directly via the CLI.
## Authentication
@ -63,7 +63,7 @@ Success! Data written to: auth/github/config
```
After configuring that, you must map the teams of that organization to
policies within Vault. Use the `map/teams/<team>` endpoints to do that.
policies within Nomad. Use the `map/teams/<team>` endpoints to do that.
Example:
```
@ -71,7 +71,7 @@ $ vault write auth/github/map/teams/owners value=root
Success! Data written to: auth/github/map/teams/owners
```
The above would make anyone in the "owners" team a root user in Vault
The above would make anyone in the "owners" team a root user in Nomad
(not recommended).
You can then auth with a user that is a member of the "owners" team using a Personal Access Token with the `read:org` scope.

8
website/source/docs/auth/index.html.md
View file

@ -3,17 +3,17 @@ layout: "docs"
page_title: "Auth Backends"
sidebar_current: "docs-auth"
description: |-
Auth backends are mountable backends that perform authentication for Vault.
Auth backends are mountable backends that perform authentication for Nomad.
---
# Auth Backends
Auth backends are the components in Vault that perform authentication
Auth backends are the components in Nomad that perform authentication
and are responsible for assigning identity and a set of policies to a
user.
Having multiple auth backends enables you to use an auth backend
that makes the sense for your use case of Vault and your organization.
that makes the sense for your use case of Nomad and your organization.
For example, on developer machines, the [GitHub auth backend](/docs/auth/github.html)
is easiest to use. But for servers the [App ID](/docs/auth/app-id.html)
@ -27,7 +27,7 @@ To learn more about authentication, see the
Auth backends can be enabled/disabled using the CLI or the API.
When enabled, auth backends are similar to [secret backends](/docs/secrets/index.html):
they are mounted within the Vault mount table and can be accessed
they are mounted within the Nomad mount table and can be accessed
and configured using the standard read/write API. The only difference
is that all auth backends are mounted underneath the `auth/` prefix.

12
website/source/docs/auth/ldap.html.md
View file

@ -3,7 +3,7 @@ layout: "docs"
page_title: "Auth Backend: LDAP"
sidebar_current: "docs-auth-ldap"
description: |-
The "ldap" auth backend allows users to authenticate with Vault using LDAP credentials.
The "ldap" auth backend allows users to authenticate with Nomad using LDAP credentials.
---
# Auth Backend: LDAP
@ -11,11 +11,11 @@ description: |-
Name: `ldap`
The "ldap" auth backend allows authentication using an existing LDAP
server and user/password credentials. This allows Vault to be integrated
server and user/password credentials. This allows Nomad to be integrated
into environments using LDAP without duplicating the user/pass configuration
in multiple places.
The mapping of groups in LDAP to Vault policies is managed by using the
The mapping of groups in LDAP to Nomad policies is managed by using the
`users/` and `groups/` paths.
## Authentication
@ -100,13 +100,13 @@ $ vault write auth/ldap/config url="ldap://ldap.forumsys.com" \
The above configures the target LDAP server, along with the parameters
specifying how users and groups should be queried from the LDAP server.
Next we want to create a mapping from an LDAP group to a Vault policy:
Next we want to create a mapping from an LDAP group to a Nomad policy:
```
$ vault write auth/ldap/groups/scientists policies=foo,bar
```
This maps the LDAP group "scientists" to the "foo" and "bar" Vault policies.
This maps the LDAP group "scientists" to the "foo" and "bar" Nomad policies.
We can also add specific LDAP users to additional (potentially non-LDAP) groups:
@ -116,7 +116,7 @@ $ vault write auth/ldap/users/tesla groups=engineers
```
This adds the LDAP user "tesla" to the "engineers" group, which maps to
the "foobar" Vault policy.
the "foobar" Nomad policy.
Finally, we can test this by authenticating:

2
website/source/docs/auth/token.html.md
View file

@ -14,7 +14,7 @@ built-in CLI methods such as `vault token-create`. It allows users to
authenticate using a token, as well to create new tokens, revoke
secrets by token, and more.
When any other auth backend returns an identity, Vault core invokes the
When any other auth backend returns an identity, Nomad core invokes the
token backend to create a new unique token for that identity.
The token store can also be used to bypass any other auth backend:

4
website/source/docs/auth/userpass.html.md
View file

@ -3,14 +3,14 @@ layout: "docs"
page_title: "Auth Backend: Username & Password"
sidebar_current: "docs-auth-userpass"
description: |-
The "userpass" auth backend allows users to authenticate with Vault using a username and password.
The "userpass" auth backend allows users to authenticate with Nomad using a username and password.
---
# Auth Backend: Username & Password
Name: `userpass`
The "userpass" auth backend allows users to authenticate with Vault using
The "userpass" auth backend allows users to authenticate with Nomad using
a username and password combination.
The username/password combinations are configured directly to the auth

16
website/source/docs/concepts/auth.html.md
View file

@ -3,23 +3,23 @@ layout: "docs"
page_title: "Authentication"
sidebar_current: "docs-concepts-auth"
description: |-
Before performing any operation with Vault, the connecting client must be authenticated.
Before performing any operation with Nomad, the connecting client must be authenticated.
---
# Authentication
Before performing any operation with Vault, the connecting client must be
Before performing any operation with Nomad, 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.
identity is then used when making requests with Nomad.
Authentication in Vault is pluggable via authentication backends. This
allows you to authenticate with Vault using a method that works best for your
Authentication in Nomad is pluggable via authentication backends. This
allows you to authenticate with Nomad using a method that works best for your
organization. For example, you can authenticate using GitHub, certs, etc.
## Authentication Backends
There are many authentication backends available for Vault. They
There are many authentication backends available for Nomad. They
are enabled using `vault auth-enable`. After they're enabled, you can
learn more about them using `vault path-help auth/<name>`. For example,
if you enable GitHub, you can use `vault path-help auth/github` to learn more
@ -40,7 +40,7 @@ but it is important to understand that authentication works by verifying
your identity and then generating a token to associate with that identity.
For example, even though you may authenticate using something like GitHub,
Vault generates a unique access token for you to use for future requests.
Nomad generates a unique access token for you to use for future requests.
The CLI automatically attaches this token to requests, but if you're using
the API you'll have to do this manually.
@ -88,7 +88,7 @@ be used.
Just like secrets, identities have
[leases](/docs/concepts/lease.html) associated with them. This means that
you must reauthenticate after the given lease period to continue accessing
Vault.
Nomad.
To set the lease associated with an identity, reference the help for
the specific authentication backend in use. It is specific to each backend

18
website/source/docs/concepts/dev-server.html.md
View file

@ -3,15 +3,15 @@ layout: "docs"
page_title: "Dev Server Mode"
sidebar_current: "docs-concepts-devserver"
description: |-
The dev server in Vault can be used for development or to experiment with Vault.
The dev server in Nomad can be used for development or to experiment with Nomad.
---
# "Dev" Server Mode
You can start Vault as a server in "dev" mode like so: `vault server -dev`.
You can start Nomad as a server in "dev" mode like so: `vault server -dev`.
This dev-mode server requires no further setup, and your local `vault` CLI will
be authenticated to talk to it. This makes it easy to experiment with Vault or
start a Vault instance for development. Every feature of Vault is available in
be authenticated to talk to it. This makes it easy to experiment with Nomad or
start a Nomad instance for development. Every feature of Nomad is available in
"dev" mode. The `-dev` flag just short-circuits a lot of setup to insecure
defaults.
@ -27,25 +27,25 @@ The properties of the dev server:
and unsealed. You don't need to use `vault unseal`. It is ready for use
immediately.
* **In-memory storage** - All data is stored (encrypted) in-memory. Vault
* **In-memory storage** - All data is stored (encrypted) in-memory. Nomad
server doesn't require any file permissions.
* **Bound to local address without TLS** - The server is listening on
`127.0.0.1:8200` (the default server address) _without_ TLS.
* **Automatically Authenticated** - The server stores your root access
token so `vault` CLI access is ready to go. If you are accessing Vault
token so `vault` CLI access is ready to go. If you are accessing Nomad
via the API, you'll need to authenticate using the token printed out.
* **Single unseal key** - The server is initialized with a single unseal
key. The Vault is already unsealed, but if you want to experiment with
key. The Nomad is already unsealed, but if you want to experiment with
seal/unseal, then only the single outputted key is required.
## Use Case
The dev server should be used for experimentation with Vault features, such
The dev server should be used for experimentation with Nomad features, such
as different authentication backends, secret backends, audit backends, etc.
If you're new to Vault, you may want to pick up with [Your First
If you're new to Nomad, you may want to pick up with [Your First
Secret](http://vaultproject.io/intro/getting-started/first-secret.html) in
our getting started guide.

20
website/source/docs/concepts/ha.html.markdown
View file

@ -3,29 +3,29 @@ layout: "docs"
page_title: "High Availability"
sidebar_current: "docs-concepts-ha"
description: |-
Vault can be highly available, allowing you to run multiple Vaults to protect against outages.
Nomad can be highly available, allowing you to run multiple Nomads to protect against outages.
---
# High Availability Mode (HA)
Vault supports multi-server mode for high availability. This mode protects
against outages by running multiple Vault servers. High availability mode
Nomad supports multi-server mode for high availability. This mode protects
against outages by running multiple Nomad servers. High availability mode
is automatically enabled when using a storage backend that supports it.
You can tell if a backend supports high availability mode ("HA") by
starting the server and seeing if "(HA available)" is outputted next to
the backend information. If it is, then HA will begin happening automatically.
To be highly available, Vault elects a leader and does request forwarding to
To be highly available, Nomad elects a leader and does request forwarding to
the leader. Due to this architecture, HA does not enable increased scalability.
In general, the bottleneck of Vault is the storage backend itself, not
Vault core. For example: to increase scalability of Vault with Consul, you
would scale Consul instead of Vault.
In general, the bottleneck of Nomad is the storage backend itself, not
Nomad core. For example: to increase scalability of Nomad with Consul, you
would scale Consul instead of Nomad.
In addition to using a backend that supports HA, you have to configure
Vault with an _advertise address_. This is the address that Vault advertises
to other Vault servers in the cluster for request forwarding. By default,
Vault will use the first private IP address it finds, but you can override
Nomad with an _advertise address_. This is the address that Nomad advertises
to other Nomad servers in the cluster for request forwarding. By default,
Nomad will use the first private IP address it finds, but you can override
this to any address you want.
## Backend Support

6
website/source/docs/concepts/index.html.md
View file

@ -3,14 +3,14 @@ layout: "docs"
page_title: "Basic Concepts"
sidebar_current: "docs-concepts"
description: |-
Basic concepts that are important to understand for Vault usage.
Basic concepts that are important to understand for Nomad usage.
---
# Basic Concepts
This section covers some high level basic concepts that are important
to understand for day to day Vault usage and operation. Every page in
to understand for day to day Nomad usage and operation. Every page in
this section is recommended reading for anyone consuming or operating
Vault.
Nomad.
Please use the navigation to the left to learn more about a topic.

18
website/source/docs/concepts/lease.html.md
View file

@ -3,22 +3,22 @@ layout: "docs"
page_title: "Lease, Renew, and Revoke"
sidebar_current: "docs-concepts-lease"
description: |-
Vault provides a lease with every secret. When this lease is expired, Vault will revoke that secret.
Nomad provides a lease with every secret. When this lease is expired, Nomad will revoke that secret.
---
# Lease, Renew, and Revoke
With every secret and authentication token, Vault provides a _lease_:
an amount of time that Vault promises that the data will be valid for.
Once the lease is up, Vault can automatically revoke the data, and the
With every secret and authentication token, Nomad provides a _lease_:
an amount of time that Nomad promises that the data will be valid for.
Once the lease is up, Nomad can automatically revoke the data, and the
consumer of the secret can no longer be certain that it is valid.
The benefit should be clear: consumers of secrets need to check in with
Vault routinely to either renew the lease (if allowed) or request a
replacement secret. This makes the Vault audit logs more valuable and
Nomad routinely to either renew the lease (if allowed) or request a
replacement secret. This makes the Nomad audit logs more valuable and
also makes key rolling a lot easier.
All secrets in Vault are required to have a lease. Even if the data is
All secrets in Nomad are required to have a lease. Even if the data is
meant to be valid for eternity, a lease is required to force the consumer
to check in routinely.
@ -33,12 +33,12 @@ be deleted from AWS the moment a secret is revoked. This renders the access
keys invalid from that point forward.
Revocation can happen manually via the API or `vault revoke`, or automatically
by Vault. When a lease is expired, Vault will automatically revoke that
by Nomad. When a lease is expired, Nomad will automatically revoke that
lease.
## Lease IDs
When reading a secret, such as via `vault read`, Vault always returns
When reading a secret, such as via `vault read`, Nomad always returns
a `lease_id`. This is the ID used with commands such as `vault renew` and
`vault revoke` to manage the lease of the secret.

22
website/source/docs/concepts/policies.html.md
View file

@ -3,18 +3,18 @@ layout: "docs"
page_title: "Policies"
sidebar_current: "docs-concepts-policies"
description: |-
Policies are how authorization is done in Vault, allowing you to restrict which parts of Vault a user can access.
Policies are how authorization is done in Nomad, allowing you to restrict which parts of Nomad a user can access.
---
# Access Control Policies
After [authenticating](/docs/concepts/auth.html) with Vault, the
After [authenticating](/docs/concepts/auth.html) with Nomad, the
next step is authorization. This is the process of determining what
a user is allowed to do. Authorization is unified in Vault in the form
a user is allowed to do. Authorization is unified in Nomad in the form
of _policies_.
Policies are [HCL](https://github.com/hashicorp/hcl) or JSON documents
that describe what parts of Vault a user is allowed to access. An example
that describe what parts of Nomad a user is allowed to access. An example
of a policy is shown below:
```javascript
@ -37,8 +37,8 @@ path "secret/super-secret" {
Policies use path based matching to apply rules. A policy may be an exact
match, or might be a glob pattern which uses a prefix. The default policy
is always deny so if a path isn't explicitly allowed, Vault will reject access to it.
This works well due to Vault's architecture of being like a filesystem:
is always deny so if a path isn't explicitly allowed, Nomad will reject access to it.
This works well due to Nomad's architecture of being like a filesystem:
everything has a path associated with it, including the core configuration
mechanism under "sys".
@ -59,7 +59,7 @@ Allowed policies for a path are:
* `read` - Read-only access to a path.
The only non-obvious policy is "sudo". Some routes within Vault and mounted
The only non-obvious policy is "sudo". Some routes within Nomad and mounted
backends are marked as _root_ paths. Clients aren't allowed to access root
paths unless they are a root user (have the special policy "root") or
have access to that path with the "sudo" policy.
@ -71,7 +71,7 @@ Only root or "sudo" privilege users are allowed to do this.
The "root" policy is a special policy that can not be modified or removed.
Any user associated with the "root" policy becomes a root user. A root
user can do _anything_ within Vault.
user can do _anything_ within Nomad.
There always exists at least one root user (associated with the token
when initializing a new server). After this root user, it is recommended
@ -104,7 +104,7 @@ active identity.
## Changes from 0.1
In Vault versions prior to 0.2, the ACL policy language had a slightly
In Nomad versions prior to 0.2, the ACL policy language had a slightly
different specification and semantics. The current specification requires
that glob behavior explicitly be specified by adding the `*` character to
the end of a path. Previously, all paths were glob based matches and no
@ -125,9 +125,9 @@ path "sys/seal" {
```
The merge would previously give the "read" higher precedence. The current
version of Vault prioritizes the explicit deny, so that the "deny" would
version of Nomad prioritizes the explicit deny, so that the "deny" would
take precedence.
To make all Vault 0.1 policies compatible with Vault 0.2, the explicit
To make all Nomad 0.1 policies compatible with Nomad 0.2, the explicit
glob character must be added to all the path prefixes.

32
website/source/docs/concepts/seal.html.md
View file

@ -3,36 +3,36 @@ layout: "docs"
page_title: "Seal/Unseal"
sidebar_current: "docs-concepts-seal"
description: |-
A Vault must be unsealed before it can access its data. Likewise, it can be sealed to lock it down.
A Nomad must be unsealed before it can access its data. Likewise, it can be sealed to lock it down.
---
# Seal/Unseal
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
When a Nomad server is started, it starts in a _sealed_ state. In this
state, Nomad is configured to know where and how to access the physical
storage, but doesn't know how to decrypt any of it.
_Unsealing_ is the process of constructing the master key necessary to
read the decryption key to decrypt the data, allowing access to the Vault.
read the decryption key to decrypt the data, allowing access to the Nomad.
Prior to unsealing, almost no operations are possible with Vault. For
Prior to unsealing, almost no operations are possible with Nomad. For
example authentication, managing the mount tables, etc. are all not possible.
The only possible operations are to unseal the Vault and check the status
The only possible operations are to unseal the Nomad and check the status
of the unseal.
## Why?
The data stored by Vault is stored encrypted. Vault needs the
The data stored by Nomad is stored encrypted. Nomad needs the
_encryption key_ in order to decrypt the data. The encryption key is
also stored with the data, but encrypted with another encryption key
known as the _master key_. The master key isn't stored anywhere.
Therefore, to decrypt the data, Vault must decrypt the encryption key
Therefore, to decrypt the data, Nomad must decrypt the encryption key
which requires the master key. Unsealing is the process of reconstructing
this master key.
Instead of distributing this master key as a single key to an operator,
Vault uses an algorithm known as
Nomad uses an algorithm known as
[Shamir's Secret Sharing](http://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing)
to split the key into shards. A certain threshold of shards is required to
reconstruct the master key.
@ -48,25 +48,25 @@ This process is stateful: each key can be entered via multiple mechanisms
on multiple computers and it will work. This allows each shard of the master
key to be on a distinct machine for better security.
Once a Vault is unsealed, it remains unsealed until one of two things happens:
Once a Nomad is unsealed, it remains unsealed until one of two things happens:
1. It is resealed via the API (see below).
2. The server is restarted.
-> **Note:** Unsealing makes the process of automating a Vault install
difficult. Automated tools can easily install, configure, and start Vault,
-> **Note:** Unsealing makes the process of automating a Nomad install
difficult. Automated tools can easily install, configure, and start Nomad,
but unsealing it is a very manual process. We have plans in the future to
make it easier. For the time being, the best method is to manually unseal
multiple Vault servers in [HA mode](/docs/concepts/ha.html). Use a tool such
as Consul to make sure you only query Vault servers that are unsealed.
multiple Nomad servers in [HA mode](/docs/concepts/ha.html). Use a tool such
as Consul to make sure you only query Nomad servers that are unsealed.
## Sealing
There is also an API to seal the Vault. This will throw away the encryption
There is also an API to seal the Nomad. 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 way, if there is a detected intrusion, the Vault data can be locked
This way, if there is a detected intrusion, the Nomad data can be locked
quickly to try to minimize damages. It can't be accessed again without
access to the master key shards.

8
website/source/docs/concepts/tokens.html.md
View file

@ -3,18 +3,18 @@ layout: "docs"
page_title: "Tokens"
sidebar_current: "docs-concepts-tokens"
description: |-
Tokens are a core authentication method in Vault. Child tokens, token-based revocation, and more.
Tokens are a core authentication method in Nomad. Child tokens, token-based revocation, and more.
---
# Tokens
Tokens are the core method for _authentication_ within Vault. Tokens
Tokens are the core method for _authentication_ within Nomad. Tokens
can be used directly or [authentication backends](/docs/concepts/auth.html)
can be used to dynamically generate tokens based on external identities.
If you've gone through the getting started guide, you probably noticed that
`vault server -dev` (or `vault init` for a non-dev server) outputs an
initial "root token." This is the first method of authentication for Vault.
initial "root token." This is the first method of authentication for Nomad.
It is also the only authentication backend that cannot be disabled.
As stated in the [authentication concepts](/docs/concepts/auth.html),
@ -47,7 +47,7 @@ with the token. Learn more about policies on the
Every token has a lease associated with it. These leases behave in much
the same way as [leases for secrets](/docs/concepts/lease.html). After
the lease period is up, the token will no longer function. In addition
to no longer functioning, Vault will revoke it.
to no longer functioning, Nomad will revoke it.
In order to avoid your token being revoked, the `vault token-renew`
command should be used to renew the lease on the token periodically.

24
website/source/docs/config/index.html.md
View file

@ -3,12 +3,12 @@ layout: "docs"
page_title: "Server Configuration"
sidebar_current: "docs-config"
description: |-
Vault server configuration reference.
Nomad server configuration reference.
---
# Server Configuration
Outside of development mode, Vault servers are configured using a file.
Outside of development mode, Nomad servers are configured using a file.
The format of this file is [HCL](https://github.com/hashicorp/hcl) or JSON.
An example configuration is shown below:
@ -34,11 +34,11 @@ to specify where the configuration is.
## Reference
* `backend` (required) - Configures the storage backend where Vault data
* `backend` (required) - Configures the storage backend where Nomad data
is stored. There are multiple options available for storage backends,
and they're documented below.
* `listener` (required) - Configures how Vault is listening for API requests.
* `listener` (required) - Configures how Nomad is listening for API requests.
"tcp" is currently the only option available. A full reference for the
inner syntax is below.
@ -59,9 +59,9 @@ to specify where the configuration is.
In production, you should only consider setting the `disable_mlock` option
on Linux systems that only use encrypted swap or do not use swap at all.
Vault does not currently support memory locking on Mac OS X and Windows
Nomad does not currently support memory locking on Mac OS X and Windows
and so the feature is automatically disabled on those platforms. To give
the Vault executable access to the `mlock` syscall on Linux systems:
the Nomad executable access to the `mlock` syscall on Linux systems:
```shell
sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault))
@ -70,11 +70,11 @@ sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault))
## Backend Reference
For the `backend` section, the supported backends are shown below.
Vault requires that the backend itself will be responsible for backups,
Nomad requires that the backend itself will be responsible for backups,
durability, etc.
* `consul` - Store data within [Consul](http://www.consul.io). This
backend supports HA. It is the most recommended backend for Vault
backend supports HA. It is the most recommended backend for Nomad
and has been shown to work at high scale under heavy load.
* `etcd` - Store data within [etcd](https://coreos.com/etcd/).
@ -89,7 +89,7 @@ durability, etc.
* `mysql` - Store data within MySQL. This backend does not support HA.
* `inmem` - Store data in-memory. This is only really useful for
development and experimentation. Data is lost whenever Vault is
development and experimentation. Data is lost whenever Nomad is
restarted.
* `file` - Store data on the filesystem using a directory structure.
@ -100,7 +100,7 @@ durability, etc.
All backends support the following options:
* `advertise_addr` (optional) - For backends that support HA, this
is the address to advertise to other Vault servers in the cluster
is the address to advertise to other Nomad servers in the cluster
for request forwarding. Most HA backends will attempt to determine
the advertise address if not provided.
@ -213,7 +213,7 @@ The supported options are:
defaults to "127.0.0.1:8200".
* `tls_disable` (optional) - If non-empty, then TLS will be disabled.
This is an opt-in; Vault assumes by default that TLS will be used.
This is an opt-in; Nomad assumes by default that TLS will be used.
* `tls_cert_file` (required unless disabled) - The path to the certificate
for TLS.
@ -221,7 +221,7 @@ The supported options are:
* `tls_key_file` (required unless disabled) - The path to the private key
for the certificate.
* `tls_min_version` (optional) - **(Vault > 0.2)** If provided, specifies
* `tls_min_version` (optional) - **(Nomad > 0.2)** If provided, specifies
the minimum supported version of TLS. Accepted values are "tls10", "tls11"
or "tls12". This defaults to "tls12". WARNING: TLS 1.1 and lower
are generally considered less secure; avoid using these if

28
website/source/docs/http/index.html.md
View file

@ -3,14 +3,14 @@ layout: "http"
page_title: "HTTP API"
sidebar_current: "docs-http-overview"
description: |-
Vault has an HTTP API that can be used to control every aspect of Vault.
Nomad has an HTTP API that can be used to control every aspect of Nomad.
---
# HTTP API
The Vault HTTP API gives you full access to Vault via HTTP. Every
aspect of Vault can be controlled via this API. The Vault CLI uses
the HTTP API to access Vault.
The Nomad HTTP API gives you full access to Nomad via HTTP. Every
aspect of Nomad can be controlled via this API. The Nomad CLI uses
the HTTP API to access Nomad.
## Version Prefix
@ -18,10 +18,10 @@ All API routes are prefixed with `/v1/`.
This documentation is only for the v1 API.
~> **Backwards compatibility:** At the current version, Vault does
~> **Backwards compatibility:** At the current version, Nomad does
not yet promise backwards compatibility even with the v1 prefix. We'll
remove this warning when this policy changes. We expect we'll reach API
stability by Vault 0.3.
stability by Nomad 0.3.
## Transport
@ -33,10 +33,10 @@ depending on user settings.
## Authentication
Once the Vault is unsealed, every other operation requires
Once the Nomad is unsealed, every other operation requires
a _client token_. A user may have a client token explicitly.
The client token must be sent as the `token` cookie or the
`X-Vault-Token` HTTP header.
`X-Nomad-Token` HTTP header.
Otherwise, a client token can be retrieved via
[authentication backends](/docs/auth/index.html).
@ -49,7 +49,7 @@ to each authentication backend.
Login endpoints for authentication backends that generate an identity
will be sent down with a `Set-Cookie` header as well as via JSON. If you have a
well-behaved HTTP client, then authentication information will
automatically be saved and sent to the Vault API.
automatically be saved and sent to the Nomad API.
## Reading and Writing Secrets
@ -66,7 +66,7 @@ Here is an example of reading a secret using cURL:
```shell
curl \
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-H "X-Nomad-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-X GET \
http://127.0.0.1:8200/v1/secret/foo
```
@ -89,18 +89,18 @@ Here is an example of writing a secret using cURL:
```shell
curl \
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-H "X-Nomad-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-H "Content-Type: application/json" \
-X POST \
-d '{"value":"bar"}' \
http://127.0.0.1:8200/v1/secret/baz
```
For more examples, please look at the Vault API client.
For more examples, please look at the Nomad API client.
## Help
To retrieve the help for any API within Vault, including mounted
To retrieve the help for any API within Nomad, including mounted
backends, credential providers, etc. then append `?help=1` to any
URL. If you have valid permission to access the path, then the help text
will be returned with the following structure:
@ -144,5 +144,5 @@ The following HTTP status codes are used throughout the API.
of time.
- `500` - Internal server error. An internal error has occurred,
try again later. If the error persists, report a bug.
- `503` - Vault is down for maintenance or is currently sealed.
- `503` - Nomad is down for maintenance or is currently sealed.
Try again later.

6
website/source/docs/http/libraries.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: Libraries"
sidebar_current: "docs-http-libraries"
description: |-
List of official and community contributed libraries for interacting with the Vault HTTP API.
List of official and community contributed libraries for interacting with the Nomad HTTP API.
---
# Libraries
@ -13,11 +13,11 @@ Some are officially maintained while others are provided by the community.
## Go
* [Vault Go Client](https://github.com/hashicorp/vault/tree/master/api) (official)
* [Nomad Go Client](https://github.com/hashicorp/vault/tree/master/api) (official)
## Ruby
* [Vault Ruby Client](https://github.com/hashicorp/vault-ruby) (official)
* [Nomad Ruby Client](https://github.com/hashicorp/vault-ruby) (official)
## Python

2
website/source/docs/http/sys-auth.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/auth"
sidebar_current: "docs-http-auth-auth"
description: |-
The `/sys/auth` endpoint is used to manage auth backends in Vault.
The `/sys/auth` endpoint is used to manage auth backends in Nomad.
---
# /sys/auth

6
website/source/docs/http/sys-health.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/health"
sidebar_current: "docs-http-debug-health"
description: |-
The '/sys/health' endpoint is used to check the health status of Vault.
The '/sys/health' endpoint is used to check the health status of Nomad.
---
# /sys/health
@ -11,8 +11,8 @@ description: |-
<dl>
<dt>Description</dt>
<dd>
Returns the health status of Vault. This matches the semantics of a Consul HTTP health
check and provides a simple way to monitor the health of a Vault instance.
Returns the health status of Nomad. This matches the semantics of a Consul HTTP health
check and provides a simple way to monitor the health of a Nomad instance.
</dd>
<dt>Method</dt>

6
website/source/docs/http/sys-init.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/init"
sidebar_current: "docs-http-sys-init"
description: |-
The '/sys/init' endpoint is used to initialize a new Vault.
The '/sys/init' endpoint is used to initialize a new Nomad.
---
# /sys/init
@ -13,7 +13,7 @@ description: |-
<dl>
<dt>Description</dt>
<dd>
Return the initialization status of a Vault.
Return the initialization status of a Nomad.
</dd>
<dt>Method</dt>
@ -39,7 +39,7 @@ description: |-
<dl>
<dt>Description</dt>
<dd>
Initializes a new Vault. The Vault must've not been previously
Initializes a new Nomad. The Nomad must've not been previously
initialized.
</dd>

4
website/source/docs/http/sys-key-status.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/key-status"
sidebar_current: "docs-http-rotate-key-status"
description: |-
The '/sys/key-status' endpoint is used to query info about the current encryption key of Vault.
The '/sys/key-status' endpoint is used to query info about the current encryption key of Nomad.
---
# /sys/key-status
@ -11,7 +11,7 @@ description: |-
<dl>
<dt>Description</dt>
<dd>
Returns information about the current encryption key used by Vault.
Returns information about the current encryption key used by Nomad.
</dd>
<dt>Method</dt>

4
website/source/docs/http/sys-leader.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/leader"
sidebar_current: "docs-http-ha-leader"
description: |-
The '/sys/leader' endpoint is used to check the high availability status and current leader of Vault.
The '/sys/leader' endpoint is used to check the high availability status and current leader of Nomad.
---
# /sys/leader
@ -11,7 +11,7 @@ description: |-
<dl>
<dt>Description</dt>
<dd>
Returns the high availability status and current leader instance of Vault.
Returns the high availability status and current leader instance of Nomad.
</dd>
<dt>Method</dt>

2
website/source/docs/http/sys-mounts.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/mounts"
sidebar_current: "docs-http-mounts-mounts"
description: |-
The '/sys/mounts' endpoint is used manage secret backends in Vault.
The '/sys/mounts' endpoint is used manage secret backends in Nomad.
---
# /sys/mounts

2
website/source/docs/http/sys-policy.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/policy"
sidebar_current: "docs-http-auth-policy"
description: |-
The `/sys/policy` endpoint is used to manage ACL policies in Vault.
The `/sys/policy` endpoint is used to manage ACL policies in Nomad.
---
# /sys/policy

2
website/source/docs/http/sys-raw.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/raw"
sidebar_current: "docs-http-debug-raw"
description: |-
The `/sys/raw` endpoint is access the raw underlying store in Vault.
The `/sys/raw` endpoint is access the raw underlying store in Nomad.
---
# /sys/raw

6
website/source/docs/http/sys-rekey.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/rekey/"
sidebar_current: "docs-http-rotate-rekey"
description: |-
The `/sys/rekey/` endpoints are used to rekey the unseal keys for Vault.
The `/sys/rekey/` endpoints are used to rekey the unseal keys for Nomad.
---
# /sys/rekey/init
@ -116,8 +116,8 @@ description: |-
<dl>
<dt>Description</dt>
<dd>
Enter a single master key share to progress the rekey of the Vault.
If the threshold number of master key shares is reached, Vault
Enter a single master key share to progress the rekey of the Nomad.
If the threshold number of master key shares is reached, Nomad
will complete the rekey. Otherwise, this API must be called multiple
times until that threshold is met.
</dd>

4
website/source/docs/http/sys-seal-status.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/seal-status"
sidebar_current: "docs-http-seal-status"
description: |-
The '/sys/seal-status' endpoint is used to check the seal status of a Vault.
The '/sys/seal-status' endpoint is used to check the seal status of a Nomad.
---
# /sys/seal-status
@ -11,7 +11,7 @@ description: |-
<dl>
<dt>Description</dt>
<dd>
Returns the seal status of the Vault.
Returns the seal status of the Nomad.
</dd>
<dt>Method</dt>

4
website/source/docs/http/sys-seal.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/seal"
sidebar_current: "docs-http-seal-seal"
description: |-
The '/sys/seal' endpoint seals the Vault.
The '/sys/seal' endpoint seals the Nomad.
---
# /sys/seal
@ -11,7 +11,7 @@ description: |-
<dl>
<dt>Description</dt>
<dd>
Seals the Vault.
Seals the Nomad.
</dd>
<dt>Method</dt>

8
website/source/docs/http/sys-unseal.html.md
View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/seal-unseal"
sidebar_current: "docs-http-seal-unseal"
description: |-
The '/sys/seal-unseal' endpoint is used to unseal the Vault.
The '/sys/seal-unseal' endpoint is used to unseal the Nomad.
---
# /sys/unseal
@ -11,9 +11,9 @@ description: |-
<dl>
<dt>Description</dt>
<dd>
Enter a single master key share to progress the unsealing of the Vault.
If the threshold number of master key shares is reached, Vault
will attempt to unseal the Vault. Otherwise, this API must be
Enter a single master key share to progress the unsealing of the Nomad.
If the threshold number of master key shares is reached, Nomad
will attempt to unseal the Nomad. Otherwise, this API must be
called multiple times until that threshold is met.
</dd>

10
website/source/docs/index.html.markdown
View file

@ -3,12 +3,12 @@ layout: "docs"
page_title: "Documentation"
sidebar_current: "docs-home"
description: |-
Welcome to the Vault documentation! This documentation is more of a reference guide for all available features and options of Vault. If you're just getting started with Vault, please start with the introduction and getting started guide instead.
Welcome to the Nomad documentation! This documentation is more of a reference guide for all available features and options of Nomad. If you're just getting started with Nomad, please start with the introduction and getting started guide instead.
---
# Vault Documentation
# Nomad Documentation
Welcome to the Vault documentation! This documentation is more of a reference
guide for all available features and options of Vault. If you're just getting
started with Vault, please start with the
Welcome to the Nomad documentation! This documentation is more of a reference
guide for all available features and options of Nomad. If you're just getting
started with Nomad, please start with the
[introduction and getting started guide](/intro/index.html) instead.

28
website/source/docs/install/index.html.md
View file

@ -1,24 +1,24 @@
---
layout: "docs"
page_title: "Install Vault"
page_title: "Install Nomad"
sidebar_current: "docs-install"
description: |-
Learn how to install Vault.
Learn how to install Nomad.
---
# Install Vault
# Install Nomad
Installing Vault is simple. There are two approaches to installing Vault:
Installing Nomad is simple. There are two approaches to installing Nomad:
downloading a precompiled binary for your system, or installing from source.
Downloading a precompiled binary is easiest, and we provide downloads over
TLS along with SHA256 sums to verify the binary is what we say it is. We
also distribute a PGP signature with the SHA256 sums that can be verified.
However, we use a 3rd party storage host, and some people feel that
due to the importance of security with Vault, they'd rather compile it
due to the importance of security with Nomad, they'd rather compile it
from source.
For this reason, we also document on this page how to compile Vault
For this reason, we also document on this page how to compile Nomad
from source, from the same versions of all dependent libraries that
we used for the official builds.
@ -26,13 +26,13 @@ we used for the official builds.
To install the precompiled binary,
[download](/downloads.html) the appropriate package for your system.
Vault is currently packaged as a zip file. We don't have any near term
Nomad is currently packaged as a zip file. We don't have any near term
plans to provide system packages.
Once the zip is downloaded, unzip it into any directory. The
`vault` binary inside is all that is necessary to run Vault (or
`vault` binary inside is all that is necessary to run Nomad (or
`vault.exe` for Windows). Any additional files, if any, aren't
required to run Vault.
required to run Nomad.
Copy the binary to anywhere on your system. If you intend to access it
from the command-line, make sure to place it somewhere on your `PATH`.
@ -42,22 +42,22 @@ from the command-line, make sure to place it somewhere on your `PATH`.
To compile from source, you'll need [Go](https://golang.org) installed
and configured properly. You'll also need Git.
1. Clone the Vault repository into your GOPATH: https://github.com/hashicorp/vault
1. Clone the Nomad repository into your GOPATH: https://github.com/hashicorp/vault
1. Verify that the file `$GOPATH/src/github.com/hashicorp/vault/main.go`
exists. If it doesn't, then you didn't clone Vault into the proper
exists. If it doesn't, then you didn't clone Nomad into the proper
path.
1. Run `make dev`. This will build Vault for your current system
1. Run `make dev`. This will build Nomad for your current system
and put the binary in `bin` (relative to the git checkout).
~> **Note:** All the dependencies of Vault are vendored and the command
~> **Note:** All the dependencies of Nomad are vendored and the command
above will use these vendored binaries. This is to avoid malicious
upstream dependencies if possible.
## Verifying the Installation
To verify Vault is properly installed, execute the `vault` binary on
To verify Nomad is properly installed, execute the `vault` binary on
your system. You should see help output. If you are executing it from
the command line, make sure it is on your PATH or you may get an error
about `vault` not being found.

203
website/source/docs/internals/architecture.html.md
View file

@ -3,155 +3,130 @@ layout: "docs"
page_title: "Architecture"
sidebar_current: "docs-internals-architecture"
description: |-
Learn about the internal architecture of Vault.
Learn about the internal architecture of Nomad.
---
# Architecture
Vault is a complex system that has many different pieces. To help both users and developers of Vault
Nomad is a complex system that has many different pieces. To help both users and developers of Nomad
build a mental model of how it works, this page documents the system architecture.
~> **Advanced Topic!** This page covers technical details
of Vault. You don't need to understand these details to
effectively use Vault. The details are documented here for
of Nomad. You don't need to understand these details to
effectively use Nomad. The details are documented here for
those who wish to learn about them without having to go
spelunking through the source code. However, if you're an
operator of Vault, we recommend learning about the architecture
due to the importance of Vault in an environment.
spelunking through the source code.
# Glossary
Before describing the architecture, we provide a glossary of terms to help
clarify what is being discussed:
* **Storage Backend** - A storage backend is responsible for durable storage of _encrypted_ data.
Backends are not trusted by Vault and are only expected to provide durability. The storage
backend is configured when starting the Vault server.
* **Job** - A Job is a specification provided by users that declares a workload for
Nomad. A Job is a form of _desired state_, the user is expressing that the job should
be running, but not where it should be run. The responsibility of Nomad is to make sure
the _actual state_ matches the user desired state. A Job is composed of one or more
task groups.
* **Barrier** - The barrier is cryptographic steel and concrete around the Vault. All data that
flows between Vault and the Storage Backend passes through the barrier. The barrier ensures
that only encrypted data is written out, and that data is verified and decrypted on the way
in. Much like a bank vault, the barrier must be "unsealed" before anything inside can be accessed.
* **Task Group** - A Task Group is a set of tasks that must be run together. For example, a
web server may require that a log shipping co-process is always running as well. A task
group is the unit of scheduling, meaning the entire group must run on a client node and
cannot be split.
* **Secret Backend** - A secret backend is responsible for managing secrets. Simple secret backends
like the "generic" backend simply return the same secret when queried. Some backends support
using policies to dynamically generate a secret each time they are queried. This allows for
unique secrets to be used which allows Vault to do fine-grained revocation and policy updates.
As an example, a MySQL backend could be configured with a "web" policy. When the "web" secret
is read, a new MySQL user/password pair will be generated with a limited set of privileges
for the web server.
* **Task** - A Task is the smallest unit of work in Nomad. Tasks are executed by drivers,
which allow Nomad to be flexible in the types of tasks it supports. Examples include Docker,
Qemu, Java and static binaries. Tasks specify their driver, configuration for the driver,
constraints, and resources required.
* **Audit Backend** - An audit backend is responsible for managing audit logs. Every request to Vault
and response from Vault goes through the configured audit backends. This provides a simple
way to integrate Vault with multiple audit logging destinations of different types.
* **Client** - A Client of Nomad is a machine that tasks can be run on. All clients run the
Nomad agent. The agent is responsible for registering with the servers, watching for any
work to be assigned and executing tasks. The Nomad agent is a long lived process which
interfaces with the servers.
* **Credential Backend** - A credential backend is used to authenticate users or applications which
are connecting to Vault. Once authenticated, the backend returns the list of applicable policies
which should be applied. Vault takes an authenticated user and returns a client token that can
be used for future requests. As an example, the `user-password` backend uses a username and password
to authenticate the user. Alternatively, the `github` backend allows users to authenticate
via GitHub.
* **Server** - Nomad servers are the brains of the cluster. There is a cluster of servers
per region and they manage all jobs and clients, run evalutations and create task allocations.
The servers replicate data between each other and perform leader election to ensure high
availability. Servers federate across regions to make Nomad globally aware.
* **Client Token** - A client token is a conceptually similar to a session cookie on a web site.
Once a user authenticates, Vault returns a client token which is used for future requests.
The token is used by Vault to verify the identity of the client and to enforce the applicable
ACL policies.
* **Regions and Datacenters** - Nomad models infrastructure as regions and datacenters.
Regions may contain multiple datacenters. Servers are assigned to regions and manage
all state for the region and make scheduling decisions within that region. Requests that
are made between regions are forwarded to the appropriate servers. As an example, you may
have a "US" region with the "us-east-1" and "us-west-1" datacenters, connected to the
"EU" region with the "eu-fr-1" and "eu-uk-1" datacenters.
* **Secret** - A secret is the term for anything returned by Vault which contains confidential
or cryptographic material. Not everything returned by Vault is a secret, for example
system configuration, status information, or backend policies are not considered Secrets.
Secrets always have an associated lease. This means clients cannot assume that the secret
contents can be used indefinitely. Vault will revoke a secret at the end of the lease, and
an operator may intervene to revoke the secret before the lease is over. This contract
between Vault and its clients is critical, as it allows for changes in keys and policies
without manual intervention.
* **Evaluation** - Evaluations are the mechanism by which Nomad makes scheduling decisions.
When either the _desired state_ (jobs) or _actual state_ (clients) changes, Nomad creates
a new evaluation to determine if any actions must be taken. An evaluation may result
in changes to allocations if necessary.
* **Server** - Vault depends on a long-running instance which operates as a server.
The Vault server provides an API which clients interact with and manages the
interaction between all the backends, ACL enforcement, and secret lease revocation.
Having a server based architecture decouples clients from the security keys and policies,
enables centralized audit logging and simplifies administration for operators.
* **Allocation** - An Allocation is a mapping between a task group in a job, and a client
node. A single job may have hundreds or thousands of task groups, meaning an equivalent
number of allocations must exist to map the work to client machines. Allocations are created
by the Nomad servers as part of scheduling decisions made during an evaluation.
* **Bin Packing** - Bin Packing is the process of filling bins with items in a way that
maximizes the utilization of bins. This extends to Nomad, where the clients are "bins"
and the items are task groups. Nomad optimizes resources by efficiently bin packing
tasks onto client machines.
# High-Level Overview
A very high level overview of Vault looks like this:
Looking at only a single region, at a high level Nomad looks like:
![Architecture Overview](/assets/images/layers.png)
![Regional Architecture](/assets/images/region-arch.png)
Let's begin to break down this picture. There is a clear separation of components
that are inside or outside of the security barrier. Only the storage backend and
the HTTP API are outside, all other components are inside the barrier.
Within each region, we have both clients and servers. Servers are responsible for
accepting jobs from users, managing clients, and computing task placements. Each
region may have clients from multiple datacenters, allowing a small number of servers
to handle very large clusters.
The storage backend is untrusted and is used to durably store encrypted data. When
the Vault server is started, it must be provided with a storage backend so that data
is available across restarts. The HTTP API similarly must be started by the Vault server
on start so that clients can interact with it.
In some cases, for either availability or scalability, you may need to run multiple
regions. Nomad supports federating multiple regions together into a single cluster.
At a high level, this looks like:
Once started, the Vault is in a _sealed_ state. Before any operation can be performed
on the Vault it must be unsealed. This is done by providing the unseal keys. When
the Vault is initialized it generates an encryption key which is used to protect all the
data. That key is protected by a master key. By default, Vault uses a technique known
as [Shamir's secret sharing algorithm](http://en.wikipedia.org/wiki/Shamir's_Secret_Sharing)
to split the master key into 5 shares, any 3 of which are required to reconstruct the master
key.
![Global Architecture](/assets/images/global-arch.png)
![Keys](/assets/images/keys.png)
Regions are fully independent from each other, and do not share jobs, clients or
state. They are loosely-coupled using a gossip protocol, which allows users to
submit jobs to any region or query the state of any region transparently. Requests
are forwarded to the appropriate server to be processed and the results returned.
The number of shares and the minimum threshold required can both be specified. Shamir's
technique can be disabled, and the master key used directly for unsealing. Once Vault
retrieves the encryption key, it is able to decrypt the data in the storage backend,
and enters the _unsealed_ state. Once unsealed, Vault loads all of the configured
audit, credential and secret backends.
The servers in each datacenter are all part of a single consensus group. This means
that they work together to elect a single leader which has extra duties. The leader
is responsible for processing all queries and transactions. Nomad is an optimistically
concurrent, meaning all servers participate in making scheduling decisions in parallel.
The leader provides the additional coordination necessary to do this safely and
to ensure clients are not oversubscribed.
The configuration of those backends must be stored in Vault since they are security
sensitive. Only users with the correct permissions should be able to modify them,
meaning they cannot be specified outside of the barrier. By storing them in Vault,
any changes to them are protected by the ACL system and tracked by audit logs.
Each region is expected to have either three or five servers. This strikes a balance
between availability in the case of failure and performance, as consensus gets
progressively slower as more servers are added. However, there is no limit to the number
of clients per region.
After the Vault is unsealed, requests can be processed from the HTTP API to the Core.
The core is used to manage the flow of requests through the system, enforce ACLs,
and ensure audit logging is done.
Clients are configured to communicate with their regional servers and communicate
using remote procedure calls (RPC) to register themselves, heartbeat for liveness,
wait for new allocations, and update the status of allocations. A client registers
with the servers to provide the resources available, attributes, and installed drivers.
Servers use this information for scheduling decisions and create allocations to assign
work to clients.
When a client first connects to Vault, it needs to authenticate. Vault provides
configurable credential backends providing flexibility in the authentication mechanism
used. Human friendly mechanisms such as username/password or GitHub might be
used for operators, while applications may use public/private keys or tokens to authenticate.
An authentication request flows through core and into a credential backend, which determines
if the request is valid and returns a list of associated policies.
Policies are just a named ACL rule. For example, the "root" policy is builtin and
permits access to all resources. You can create any number of named policies with
fine-grained control over paths. Vault operates exclusively in a blacklist mode, meaning
unless access is explicitly granted via a policy the action is not allowed.
Since a user may have multiple policies associated, an action is allowed if any policy
permits it. Policies are stored and managed by an internal policy store. This internal store
is manipulated through the system backend, which is always mounted at `sys/`.
Once authentication takes place and a credential backend provides a set of applicable
policies, a new client token is generated and managed by the token store. This client token
is sent back to the client, and is used to make future requests. This is similar to
a cookie sent by a website after a user logs in. The client token may have a lease associated
with it depending on the credential backend configuration. This means the client token
may need to be periodically renewed to avoid invalidation.
Once authenticated, requests are made providing the client token. The token is used
to verify the client is authorized and to load the relevant policies. The policies
are used to authorize the client request. The request is then routed to the secret backend,
which is processed depending on the type of backend. If the backend returns a secret,
the core registers it with the expiration manager and attaches a lease ID.
The lease ID is used by clients to renew or revoke their secret. If a client allows the
lease to expire, the expiration manager automatically revokes the secret.
The core handles logging of requests and responses to the audit broker, which fans the
request out to all the configured audit backends. Outside of the request flow, the core
performs certain background activity. Lease management is critical, as it allows
expired client tokens or secrets to be revoked automatically. Additionally, Vault handles
certain partial failure cases by using write ahead logging with a rollback manager.
This is managed transparently within the core and is not user visible.
Users make use of the Nomad CLI or API to submit jobs to the servers. A job represents
a desired state, providing the set of tasks that should be run. The servers are
responsible for scheduling the tasks, which is done by finding an optimial placement for
each task such that resource utilization is maximized while satisfying all constraints
specified by the job. Resource utilization is maximized by bin packing, in which
the scheduling tries to make use of all the resources of a machine without
exhausing any dimension. Job constraints can be used to ensure an application is
running in an appropriate environment. Constraints can be technical requirements based
on hardware features such as architecture, availability of GPUs, or software features
like operating system and kernel version, or they can be business constraints like
ensuring PCI compliant workloads run on appropriate servers.
# Getting in Depth
This has been a brief high-level overview of the architecture of Vault. There
are more details available for each of the sub-systems.
This has been a brief high-level overview of the architecture of Nomad. There
are more details available for each of the sub-systems. The [consensus protocol](/docs/internals/consensus.html) is
documented in detail as is the [gossip protocol](/docs/internals/gossip.html).
For other details, either consult the code, ask in IRC or reach out to the mailing list.

205
website/source/docs/internals/consensus.html.md Normal file
View file

@ -0,0 +1,205 @@
---
layout: "docs"
page_title: "Consensus Protocol"
sidebar_current: "docs-internals-consensus"
description: |-
Nomad uses a consensus protocol to provide Consistency as defined by CAP. The consensus protocol is based on Raft: In search of an Understandable Consensus Algorithm. For a visual explanation of Raft, see The Secret Lives of Data.
---
# Consensus Protocol
Nomad uses a [consensus protocol](http://en.wikipedia.org/wiki/Consensus_(computer_science))
to provide [Consistency (as defined by CAP)](http://en.wikipedia.org/wiki/CAP_theorem).
The consensus protocol is based on
["Raft: In search of an Understandable Consensus Algorithm"](https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf).
For a visual explanation of Raft, see [The Secret Lives of Data](http://thesecretlivesofdata.com/raft).
~> **Advanced Topic!** This page covers technical details of
the internals of Nomad. You don't need to know these details to effectively
operate and use Nomad. These details are documented here for those who wish
to learn about them without having to go spelunking through the source code.
## Raft Protocol Overview
Raft is a consensus algorithm that is based on
[Paxos](http://en.wikipedia.org/wiki/Paxos_%28computer_science%29). Compared
to Paxos, Raft is designed to have fewer states and a simpler, more
understandable algorithm.
There are a few key terms to know when discussing Raft:
* Log - The primary unit of work in a Raft system is a log entry. The problem
of consistency can be decomposed into a *replicated log*. A log is an ordered
sequence of entries. We consider the log consistent if all members agree on
the entries and their order.
* FSM - [Finite State Machine](http://en.wikipedia.org/wiki/Finite-state_machine).
An FSM is a collection of finite states with transitions between them. As new logs
are applied, the FSM is allowed to transition between states. Application of the
same sequence of logs must result in the same state, meaning behavior must be deterministic.
* Peer set - The peer set is the set of all members participating in log replication.
For Nomad's purposes, all server nodes are in the peer set of the local region.
* Quorum - A quorum is a majority of members from a peer set: for a set of size `n`,
quorum requires at least `(n/2)+1` members.
For example, if there are 5 members in the peer set, we would need 3 nodes
to form a quorum. If a quorum of nodes is unavailable for any reason, the
cluster becomes *unavailable* and no new logs can be committed.
* Committed Entry - An entry is considered *committed* when it is durably stored
on a quorum of nodes. Once an entry is committed it can be applied.
* Leader - At any given time, the peer set elects a single node to be the leader.
The leader is responsible for ingesting new log entries, replicating to followers,
and managing when an entry is considered committed.
Raft is a complex protocol and will not be covered here in detail (for those who
desire a more comprehensive treatment, the full specification is available in this
[paper](https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf)).
We will, however, attempt to provide a high level description which may be useful
for building a mental model.
Raft nodes are always in one of three states: follower, candidate, or leader. All
nodes initially start out as a follower. In this state, nodes can accept log entries
from a leader and cast votes. If no entries are received for some time, nodes
self-promote to the candidate state. In the candidate state, nodes request votes from
their peers. If a candidate receives a quorum of votes, then it is promoted to a leader.
The leader must accept new log entries and replicate to all the other followers.
In addition, if stale reads are not acceptable, all queries must also be performed on
the leader.
Once a cluster has a leader, it is able to accept new log entries. A client can
request that a leader append a new log entry (from Raft's perspective, a log entry
is an opaque binary blob). The leader then writes the entry to durable storage and
attempts to replicate to a quorum of followers. Once the log entry is considered
*committed*, it can be *applied* to a finite state machine. The finite state machine
is application specific; in Nomad's case, we use
[MemDB](https://github.com/hashicorp/go-memdb) to maintain cluster state.
Obviously, it would be undesirable to allow a replicated log to grow in an unbounded
fashion. Raft provides a mechanism by which the current state is snapshotted and the
log is compacted. Because of the FSM abstraction, restoring the state of the FSM must
result in the same state as a replay of old logs. This allows Raft to capture the FSM
state at a point in time and then remove all the logs that were used to reach that
state. This is performed automatically without user intervention and prevents unbounded
disk usage while also minimizing time spent replaying logs. One of the advantages of
using MemDB is that it allows Nomad to continue accepting new transactions even while
old state is being snapshotted, preventing any availability issues.
Consensus is fault-tolerant up to the point where quorum is available.
If a quorum of nodes is unavailable, it is impossible to process log entries or reason
about peer membership. For example, suppose there are only 2 peers: A and B. The quorum
size is also 2, meaning both nodes must agree to commit a log entry. If either A or B
fails, it is now impossible to reach quorum. This means the cluster is unable to add
or remove a node or to commit any additional log entries. This results in
*unavailability*. At this point, manual intervention would be required to remove
either A or B and to restart the remaining node in bootstrap mode.
A Raft cluster of 3 nodes can tolerate a single node failure while a cluster
of 5 can tolerate 2 node failures. The recommended configuration is to either
run 3 or 5 Nomad servers per region. This maximizes availability without
greatly sacrificing performance. The [deployment table](#deployment_table) below
summarizes the potential cluster size options and the fault tolerance of each.
In terms of performance, Raft is comparable to Paxos. Assuming stable leadership,
committing a log entry requires a single round trip to half of the cluster.
Thus, performance is bound by disk I/O and network latency.
## Raft in Nomad
Only Nomad server nodes participate in Raft and are part of the peer set. All
client nodes forward requests to servers. The clients in Nomad only need to know
about their allocations and query that information from the servers, while the
servers need to maintain the global state of the cluster.
Since all servers participate as part of the peer set, they all know the current
leader. When an RPC request arrives at a non-leader server, the request is
forwarded to the leader. If the RPC is a *query* type, meaning it is read-only,
the leader generates the result based on the current state of the FSM. If
the RPC is a *transaction* type, meaning it modifies state, the leader
generates a new log entry and applies it using Raft. Once the log entry is committed
and applied to the FSM, the transaction is complete.
Because of the nature of Raft's replication, performance is sensitive to network
latency. For this reason, each region elects an independent leader and maintains
a disjoint peer set. Data is partitioned by region, so each leader is responsible
only for data in their region. When a request is received for a remote region,
the request is forwarded to the correct leader. This design allows for lower latency
transactions and higher availability without sacrificing consistency.
## Consistency Modes
Although all writes to the replicated log go through Raft, reads are more
flexible. To support various trade-offs that developers may want, Nomad
supports 2 different consistency modes for reads.
The two read modes are:
* `default` - Raft makes use of leader leasing, providing a time window
in which the leader assumes its role is stable. However, if a leader
is partitioned from the remaining peers, a new leader may be elected
while the old leader is holding the lease. This means there are 2 leader
nodes. There is no risk of a split-brain since the old leader will be
unable to commit new logs. However, if the old leader services any reads,
the values are potentially stale. The default consistency mode relies only
on leader leasing, exposing clients to potentially stale values. We make
this trade-off because reads are fast, usually strongly consistent, and
only stale in a hard-to-trigger situation. The time window of stale reads
is also bounded since the leader will step down due to the partition.
* `stale` - This mode allows any server to service the read regardless of if
it is the leader. This means reads can be arbitrarily stale but are generally
within 50 milliseconds of the leader. The trade-off is very fast and scalable
reads but with stale values. This mode allows reads without a leader meaning
a cluster that is unavailable will still be able to respond.
## <a name="deployment_table"></a>Deployment Table
Below is a table that shows quorum size and failure tolerance for various
cluster sizes. The recommended deployment is either 3 or 5 servers. A single
server deployment is _**highly**_ discouraged as data loss is inevitable in a
failure scenario.
<table class="table table-bordered table-striped">
<tr>
<th>Servers</th>
<th>Quorum Size</th>
<th>Failure Tolerance</th>
</tr>
<tr>
<td>1</td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td>2</td>
<td>2</td>
<td>0</td>
</tr>
<tr class="warning">
<td>3</td>
<td>2</td>
<td>1</td>
</tr>
<tr>
<td>4</td>
<td>3</td>
<td>1</td>
</tr>
<tr class="warning">
<td>5</td>
<td>3</td>
<td>2</td>
</tr>
<tr>
<td>6</td>
<td>4</td>
<td>2</td>
</tr>
<tr>
<td>7</td>
<td>4</td>
<td>3</td>
</tr>
</table>

34
website/source/docs/internals/gossip.html.md Normal file
View file

@ -0,0 +1,34 @@
---
layout: "docs"
page_title: "Gossip Protocol"
sidebar_current: "docs-internals-gossip"
description: |-
Nomad uses a gossip protocol to manage membership. All of this is provided through the use of the Serf library.
---
# Gossip Protocol
Nomad uses a [gossip protocol](http://en.wikipedia.org/wiki/Gossip_protocol)
to manage membership. This is provided through the use of the [Serf library](https://www.serfdom.io/).
The gossip protocol used by Serf is based on
["SWIM: Scalable Weakly-consistent Infection-style Process Group Membership Protocol"](http://www.cs.cornell.edu/~asdas/research/dsn02-swim.pdf),
with a few minor adaptations. There are more details about [Serf's protocol here](https://www.serfdom.io/docs/internals/gossip.html).
~> **Advanced Topic!** This page covers technical details of
the internals of Nomad. You don't need to know these details to effectively
operate and use Nomad. These details are documented here for those who wish
to learn about them without having to go spelunking through the source code.
## Gossip in Nomad
Named makes use of a single global WAN gossip pool that all servers participate in.
Membership information provided by the gossip pool allows servers to perform cross region
requests. The integrated failure detection allows Nomad to gracefully handle an entire region
losing connectivity, or just a single server in a remote region. The gossip protocol
is also used to detect servers in the same region to perform automatic clustering
via the [consensus protocol](/docs/internals/consensus.html).
All of these features are provided by leveraging [Serf](https://www.serfdom.io/). It
is used as an embedded library to provide these features. From a user perspective,
this is not important, since the abstraction should be masked by Nomad. It can be useful
however as a developer to understand how this library is leveraged.

49
website/source/docs/internals/high-availability.html.md
View file

@ -1,49 +0,0 @@
---
layout: "docs"
page_title: "High Availability"
sidebar_current: "docs-internals-ha"
description: |-
Learn about the high availability design of Vault.
---
# High Availability
Vault is primarily used in production environments to manage secrets.
As a result, any downtime of the Vault service can affect downstream clients.
Vault is designed to support a highly available deploy to ensure a machine
or process failure is minimally disruptive.
~> **Advanced Topic!** This page covers technical details
of Vault. You don't need to understand these details to
effectively use Vault. The details are documented here for
those who wish to learn about them without having to go
spelunking through the source code. However, if you're an
operator of Vault, we recommend learning about the architecture
due to the importance of Vault in an environment.
# Design Overview
The primary design goal in making Vault highly availability (HA) was to
minimize downtime and not horizontal scalability. Vault is typically
bound by the IO limits of the storage backend rather than the compute
requirements. This simplifies the HA approach and allows more complex
coordination to be avoided.
Certain storage backends, such as Consul, provide additional coordination
functions that enable Vault to run in an HA configuration. When supported
by the backend, Vault will automatically run in HA mode without additional
configuration.
When running in HA mode, Vault servers have two additional states they
can be in: standby and active. For multiple Vault servers sharing a storage
backend, only a single instance will be active at any time while all other
instances are hot standbys.
The active server operates in a standard fashion and processes all requests.
The standby servers do not process requests, and instead redirect to the active
Vault. Meanwhile, if the active server is sealed, fails, or loses network connectivity
then one of the standbys will take over and become the active instance.
It is important to note that only _unsealed_ servers act as a standby.
If a server is still in the sealed state, then it cannot act as a standby
as it would be unable to serve any requests should the active server fail.

14
website/source/docs/internals/index.html.md
View file

@ -3,15 +3,15 @@ layout: "docs"
page_title: "Internals"
sidebar_current: "docs-internals"
description: |-
This section covers the internals of Vault and explains technical details of Vaults operation.
This section covers the internals of Nomad and explains technical details of Nomads operation.
---
# Vault Internals
# Nomad Internals
This section covers the internals of Vault and explains the technical
details of how Vault functions, its architecture and security properties.
This section covers the internals of Nomad and explains the technical
details of how Nomad functions, its architecture and sub-systems.
-> **Note:** Knowledge of Vault internals is not
required to use Vault. If you aren't interested in the internals
of Vault, you may safely skip this section. If you're operating Vault,
-> **Note:** Knowledge of Nomad internals is not
required to use Nomad. If you aren't interested in the internals
of Nomad, you may safely skip this section. If you're operating Nomad,
we recommend understanding the internals.

58
website/source/docs/internals/rotation.html.md
View file

@ -1,58 +0,0 @@
---
layout: "docs"
page_title: "Key Rotation"
sidebar_current: "docs-internals-rotation"
description: |-
Learn about the details of key rotation within Vault.
---
# Key Rotation
Vault has multiple encryption keys that are used for various purposes. These keys support
rotation so that they can be periodically changed or in response to a potential leak or
compromise. It is useful to first understand the
[high-level architecture](/docs/internals/architecture.html) before learning about key rotation.
As a review, Vault starts in a _sealed_ state. Vault is unsealed by providing the unseal keys.
By default, Vault uses a technique known as [Shamir's secret sharing algorithm](http://en.wikipedia.org/wiki/Shamir's_Secret_Sharing)
to split the master key into 5 shares, any 3 of which are required to reconstruct the master
key. The master key is used to protect the encryption key, which is ultimately used to protect
data written to the storage backend.
![Keys](/assets/images/keys.png)
To support key rotation, we need to support changing the unseal keys, master key, and the
backend encryption key. We split this into two seperate operations, `rekey` and `rotate`.
The `rekey` operation is used to generate a new master key. When this is being done,
it is possible to change the parameters of the key splitting, so that the number of shares
and the threshold required to unseal can be changed. To perform a rekey a threshold of the
current unseal keys must be provided. This is to prevent a single malicious operator from
performing a rekey and invaliding the existing master key.
Performing a rekey is fairly straightforward. The rekey operation must be initialized with
the new parameters for the split and threshold. Once initialized, the current unseal keys
must be provided until the threshold is met. Once met, Vault will generate the new master
key, perform the splitting, and re-encrypt the encryption key with the new master key.
The new unseal keys are then provided to the operator, and the old unseal keys are no
longer usable.
The `rotate` operation is used to change the encryption key used to protect data written
to the storage backend. This key is never provided or visible to operators, who only
have unseal keys. This simplifies the rotation, as it does not require the current key
holders unlike the `rekey` operation. When `rotate` is triggered, a new encryption key
is generated and added to a keyring. All new values written to the storage backend are
encrypted with the new key. Old values written with previous encryption keys can still
be decrypted since older keys are saved in the keyring. This allows key rotation to be
done online, without an expensive re-encryption process.
Both the `rekey` and `rotate` operations can be done online and in a highly available
configuration. Only the active Vault instance can perform either of the operations
but standby instances can still assume an active role after either operation. This is
done by providing an online upgrade path for standby instances. If the current encryption
key is `N` and a rotation installs `N+1`, Vault creates a special "upgrade" key, which
provides the `N+1` encryption key protected by the `N` key. This upgrade key is only available
for a few minutes enabling standby instances do a periodic check for upgrades.
This allows standby instances to update their keys and stay in-sync with the active Vault
without requiring operators to perform another unseal.

148
website/source/docs/internals/security.html.md
View file

@ -1,148 +0,0 @@
---
layout: "docs"
page_title: "Security Model"
sidebar_current: "docs-internals-security"
description: |-
Learn about the security model of Vault.
---
# Security Model
Due to the nature of Vault and the confidentiality of data it is managing,
the Vault security model is very critical. The overall goal of Vault's security
model is to provide [confidentiality, integrity, availability, accountability,
authentication](http://en.wikipedia.org/wiki/Information_security).
This means that data at rest and in transit must be secure from eavesdropping
or tampering. Clients must be appropriately authenticated and authorized
to access data or modify policy. All interactions must be auditable and traced
uniquely back to the origin entity. The system must be robust against intentional
attempts to bypass any of its access controls.
# Threat Model
The following are the various parts of the Vault threat model:
* Eavesdropping on any Vault communication. Client communication with Vault
should be secure from eavesdropping as well as communication from Vault to
its storage backend.
* Tampering with data at rest or in transit. Any tampering should be detectable
and cause Vault to abort processing of the transaction.
* Access to data or controls without authentication or authorization. All requests
must be proceeded by the applicable security policies.
* Access to data or controls without accountability. If audit logging
is enabled, requests and responses must be logged before the client receives
any secret material.
* Confidentiality of stored secrets. Any data that leaves Vault to rest in the
storage backend must be safe from eavesdropping. In practice, this means all
data at rest must be encrypted.
* Availability of secret material in the face of failure. Vault supports
running in a highly available configuration to avoid loss of availability.
The following are not parts of the Vault threat model:
* Protecting against arbitrary control of the storage backend. An attacker
that can perform arbitrary operations against the storage backend can
undermine security in any number of ways that are difficult or impossible to protect
against. As an example, an attacker could delete or corrupt all the contents
of the storage backend causing total data loss for Vault. The ability to control
reads would allow an attacker to snapshot in a well-known state and rollback state
changes if that would be beneficial to them.
* Protecting against the leakage of the existence of secret material. An attacker
that can read from the storage backend may observe that secret material exists
and is stored, even if it is kept confidential.
* Protecting against memory analysis of a running Vault. If an attacker is able
to inspect the memory state of a running Vault instance then the confidentiality
of data may be compromised.
# External Threat Overview
Given the architecture of Vault, there are 3 distinct systems we are concerned with
for Vault. There is the client, which is speaking to Vault over an API. There is Vault
or the server more accurately, which is providing an API and serving requests. Lastly,
there is the storage backend, which the server is utilizing to read and write data.
There is no mutual trust between the Vault client and server. Clients use
[TLS](http://en.wikipedia.org/wiki/Transport_Layer_Security) to verify the identity
of the server and to establish a secure communication channel. Servers require that
a client provides a client token for every request which is used to identify the client.
A client that does not provide their token is only permitted to make login requests.
The storage backends used by Vault are also untrusted by design. Vault uses a security
barrier for all requests made to the backend. The security barrier automatically encrypts
all data leaving Vault using the [Advanced Encryption Standard (AES)](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard)
cipher in the [Galois Counter Mode (GCM)](http://en.wikipedia.org/wiki/Galois/Counter_Mode).
The nonce is randomly generated for every encrypted object. When data is read from the
security barrier the GCM authentication tag is verified prior to decryption to detect
any tampering.
Depending on the backend used, Vault may communicate with the backend over TLS
to provide an added layer of security. In some cases, such as a file backend this
is not applicable. Because storage backends are untrusted, an eavesdropper would
only gain access to encrypted data even if communication with the backend was intercepted.
# Internal Threat Overview
Within the Vault system, a critical security concern is an attacker attempting
to gain access to secret material they are not authorized to. This is an internal
threat if the attacker is already permitted some level of access to Vault and is
able to authenticate.
When a client first authenticates with Vault, a credential backend is used to
verify the identity of the client and to return a list of associated ACL policies.
This association is configured by operators of Vault ahead of time. For example,
GitHub users in the "engineering" team may be mapped to the "engineering" and "ops"
Vault policies. Vault then generates a client token which is a randomly generated
UUID and maps it to the policy list. This client token is then returned to the client.
On each request a client provides this token. Vault then uses it to check that the token
is valid and has not been revoked or expired, and generates an ACL based on the associated
policies. Vault uses a strict default deny or whitelist enforcement. This means unless
an associated policy allows for a given action, it will be denied. Each policy specifies
a level of access granted to a path in Vault. When the policies are merged (if multiple
policies are associated with a client), the highest access level permitted is used.
For example, if the "engineering" policy permits read/write access to the "eng/" path,
and the "ops" policy permits read access to the "ops/" path, then the user gets the
union of those. Policy is matched using the most specific defined policy, which may be
an exact match or the longest-prefix match glob pattern.
Certain operations are only permitted by "root" users, which is a distinguished
policy built into Vault. This is similar to the concept of a root user on a Unix system
or an Administrator on Windows. Although clients could be provided with root tokens
or associated with the root policy, instead Vault supports the notion of "sudo" privilege.
As part of a policy, users may be granted "sudo" privileges to certain paths, so that
they can still perform security sensitive operations without being granted global
root access to Vault.
Lastly, Vault supports using a [Two-man rule](http://en.wikipedia.org/wiki/Two-man_rule) for
unsealing using [Shamir's Secret Sharing technique](http://en.wikipedia.org/wiki/Shamir's_Secret_Sharing).
When Vault is started, it starts in an _sealed_ state. This means that the encryption key
needed to read and write from the storage backend is not yet known. The process of unsealing
requires providing the master key so that the encryption key can be retrieved. The risk of distributing
the master key is that a single malicious actor with access to it can decrypt the entire
Vault. Instead, Shamir's technique allows us to split the master key into multiple shares or parts.
The number of shares and the threshold needed is configurable, but by default Vault generates
5 shares, any 3 of which must be provided to reconstruct the master key.
By using a secret sharing technique, we avoid the need to place absolute trust in the holder
of the master key, and avoid storing the master key at all. The master key is only
retrievable by reconstructing the shares. The shares are not useful for making any requests
to Vault, and can only be used for unsealing. Once unsealed the standard ACL mechanisms
are used for all requests.
To make an analogy, a bank puts security deposit boxes inside of a vault.
Each security deposit box has a key, while the vault door has both a combination and a key.
The vault is encased in steel and concrete so that the door is the only practical entrance.
The analogy to Vault, is that the cryptosystem is the steel and concrete protecting the data.
While you could tunnel through the concrete or brute force the encryption keys, it would be
prohibitively time consuming. Opening the bank vault requires two-factors: the key and the combination.
Similarly, Vault requires multiple shares be provided to reconstruct the master key.
Once unsealed, each security deposit boxes still requires the owner provide a key, and similarly
the Vault ACL system protects all the secrets stored.

65
website/source/docs/internals/telemetry.html.md
View file

@ -3,21 +3,21 @@ layout: "docs"
page_title: "Telemetry"
sidebar_current: "docs-internals-telemetry"
description: |-
Learn about the telemetry data available in Vault.
Learn about the telemetry data available in Nomad.
---
# Telemetry
The Vault agent collects various runtime metrics about the performance of
The Nomad agent collects various runtime metrics about the performance of
different libraries and subsystems. These metrics are aggregated on a ten
second interval and are retained for one minute.
To view this data, you must send a signal to the Vault process: on Unix,
this is `USR1` while on Windows it is `BREAK`. Once Vault receives the signal,
To view this data, you must send a signal to the Nomad process: on Unix,
this is `USR1` while on Windows it is `BREAK`. Once Nomad receives the signal,
it will dump the current telemetry information to the agent's `stderr`.
This telemetry information can be used for debugging or otherwise
getting a better view of what Vault is doing.
getting a better view of what Nomad is doing.
Telemetry information can be streamed to both [statsite](http://github.com/armon/statsite)
as well as statsd based on providing the appropriate configuration options.
@ -25,24 +25,39 @@ as well as statsd based on providing the appropriate configuration options.
Below is sample output of a telemetry dump:
```text
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.num_goroutines': 12.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.free_count': 11882.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.total_gc_runs': 9.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.expire.num_leases': 1.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.alloc_bytes': 502992.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.sys_bytes': 3999992.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.malloc_count': 17315.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.heap_objects': 5433.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.total_gc_pause_ns': 3794124.000
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.audit.log_response': Count: 2 Min: 0.001 Mean: 0.001 Max: 0.001 Stddev: 0.000 Sum: 0.002
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.route.read.secret-': Count: 1 Sum: 0.036
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.barrier.get': Count: 3 Min: 0.004 Mean: 0.021 Max: 0.050 Stddev: 0.025 Sum: 0.064
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.token.lookup': Count: 2 Min: 0.040 Mean: 0.074 Max: 0.108 Stddev: 0.048 Sum: 0.148
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.policy.get_policy': Count: 2 Min: 0.003 Mean: 0.004 Max: 0.005 Stddev: 0.001 Sum: 0.009
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.core.check_token': Count: 2 Min: 0.053 Mean: 0.087 Max: 0.121 Stddev: 0.048 Sum: 0.174
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.audit.log_request': Count: 2 Min: 0.001 Mean: 0.001 Max: 0.001 Stddev: 0.000 Sum: 0.002
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.barrier.put': Count: 3 Min: 0.004 Mean: 0.010 Max: 0.019 Stddev: 0.008 Sum: 0.029
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.route.write.secret-': Count: 1 Sum: 0.035
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.core.handle_request': Count: 2 Min: 0.097 Mean: 0.228 Max: 0.359 Stddev: 0.186 Sum: 0.457
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.expire.register': Count: 1 Sum: 0.18
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.broker.total_blocked': 0.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.plan.queue_depth': 0.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.malloc_count': 7568.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.total_gc_runs': 8.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.broker.total_ready': 0.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.num_goroutines': 56.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.sys_bytes': 3999992.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.heap_objects': 4135.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.heartbeat.active': 1.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.broker.total_unacked': 0.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.broker.total_waiting': 0.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.alloc_bytes': 634056.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.free_count': 3433.000
[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.total_gc_pause_ns': 6572135.000
[2015-09-17 16:59:40 -0700 PDT][C] 'nomad.memberlist.msg.alive': Count: 1 Sum: 1.000
[2015-09-17 16:59:40 -0700 PDT][C] 'nomad.serf.member.join': Count: 1 Sum: 1.000
[2015-09-17 16:59:40 -0700 PDT][C] 'nomad.raft.barrier': Count: 1 Sum: 1.000
[2015-09-17 16:59:40 -0700 PDT][C] 'nomad.raft.apply': Count: 1 Sum: 1.000
[2015-09-17 16:59:40 -0700 PDT][C] 'nomad.nomad.rpc.query': Count: 2 Sum: 2.000
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.serf.queue.Query': Count: 6 Sum: 0.000
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.fsm.register_node': Count: 1 Sum: 1.296
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.serf.queue.Intent': Count: 6 Sum: 0.000
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.runtime.gc_pause_ns': Count: 8 Min: 126492.000 Mean: 821516.875 Max: 3126670.000 Stddev: 1139250.294 Sum: 6572135.000
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.raft.leader.dispatchLog': Count: 3 Min: 0.007 Mean: 0.018 Max: 0.039 Stddev: 0.018 Sum: 0.054
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.leader.reconcileMember': Count: 1 Sum: 0.007
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.leader.reconcile': Count: 1 Sum: 0.025
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.raft.fsm.apply': Count: 1 Sum: 1.306
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.client.get_allocs': Count: 1 Sum: 0.110
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.worker.dequeue_eval': Count: 29 Min: 0.003 Mean: 363.426 Max: 503.377 Stddev: 228.126 Sum: 10539.354
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.serf.queue.Event': Count: 6 Sum: 0.000
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.raft.commitTime': Count: 3 Min: 0.013 Mean: 0.037 Max: 0.079 Stddev: 0.037 Sum: 0.110
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.leader.barrier': Count: 1 Sum: 0.071
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.client.register': Count: 1 Sum: 1.626
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.eval.dequeue': Count: 21 Min: 500.610 Mean: 501.753 Max: 503.361 Stddev: 1.030 Sum: 10536.813
[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.memberlist.gossip': Count: 12 Min: 0.009 Mean: 0.017 Max: 0.025 Stddev: 0.005 Sum: 0.204
```

53
website/source/docs/internals/token.html.md
View file

@ -1,53 +0,0 @@
---
layout: "docs"
page_title: "Token Authentication"
sidebar_current: "docs-internals-token"
description: |-
Learn about the client token authentication in Vault.
---
# Token Authentication
The `token` authentication backend is built-in and is at the core of
client authentication. Other authentication backends may be used to
authenticate a client, but they eventually result in the generation of a client
token managed by the `token` backend.
Every token has a number of properties:
* ID - The primary ID of a token is a randomly generated UUID
* Display Name - Optionally, a human readable display name
* Metadata - Metadata used for audit logging
* Number of Uses - Optionally, a restricted use count
* Parent ID - Optionally, a parent token which created this child token
* Policies - An associated list of ACL policies
* Source Path - The path at which the token was generated (e.g. `auth/github/login`)
The properties of a token are immutable once created. The exception to this
is the number of uses, which is decremented on each request. Each of these
properties enable Vault to do a number of interesting things.
Each token maintains the source path, or the login path, that was used
to create the token. This is used to allow source based revocation. For example,
if we believe our GitHub organization was compromised, we may want to revoke
all tokens generated via `auth/github/login`. This would be done by using the
`auth/token/revoke-prefix/` API with the `auth/github/` prefix. Revoking the
prefix will revoke all client tokens generated at that path, as well as all
dynamic secrets generated by those tokens. This provides a powerful "break glass"
procedure during a potential compromise.
If a token is created by another authentication backend, they do not have
a parent token. However, any tokens created by the `auth/token/create` API
have a parent token, namely the token used to make that request. By maintaining
this parent-child relationship, Vault models token trees. Child tokens can
be created with a subset of the parent policies, allowing for dropping of
privileges. When a token is revoked, the entire sub-tree of tokens is revoked
with it. This allows clients to safely generate child tokens and then revoke
them all along with the root.
Child tokens are very useful, especially when combined with limited use tokens.
When a token is created, its use count can be optionally specified. Providing
a use count of one makes a _one time token_. This means the token can be used
for a single request before being automatically revoked. This can be generalized
to any number of uses. Limited use tokens cannot be used to create sub-tokens,
but they can be a powerful way to allow extremely limited access to Vault.

8
website/source/docs/secrets/aws/index.html.md
View file

@ -3,16 +3,16 @@ layout: "docs"
page_title: "Secret Backend: AWS"
sidebar_current: "docs-secrets-aws"
description: |-
The AWS secret backend for Vault generates access keys dynamically based on IAM policies.
The AWS secret backend for Nomad generates access keys dynamically based on IAM policies.
---
# AWS Secret Backend
Name: `aws`
The AWS secret backend for Vault generates AWS access credentials dynamically
The AWS secret backend for Nomad generates AWS access credentials dynamically
based on IAM policies. This makes IAM much easier to use: credentials could
be generated on the fly, and are automatically revoked when the Vault
be generated on the fly, and are automatically revoked when the Nomad
lease is expired.
This page will show a quick start for this backend. For detailed documentation
@ -59,7 +59,7 @@ This path will create a named role along with the IAM policy used
to restrict permissions for it. This is used to dynamically create
a new pair of IAM credentials when needed.
The `@` tells Vault to load the policy from the file named `policy.json`. Here
The `@` tells Nomad to load the policy from the file named `policy.json`. Here
is an example IAM policy to get started:
```javascript

18
website/source/docs/secrets/cassandra/index.html.md
View file

@ -3,17 +3,17 @@ layout: "docs"
page_title: "Secret Backend: Cassandra"
sidebar_current: "docs-secrets-cassandra"
description: |-
The Cassandra secret backend for Vault generates database credentials to access Cassandra.
The Cassandra secret backend for Nomad generates database credentials to access Cassandra.
---
# Cassandra Secret Backend
Name: `cassandra`
The Cassandra secret backend for Vault generates database credentials
The Cassandra secret backend for Nomad generates database credentials
dynamically based on configured roles. This means that services that need
to access a database no longer need to hardcode credentials: they can request
them from Vault, and use Vault's leasing mechanism to more easily roll keys.
them from Nomad, and use Nomad's leasing mechanism to more easily roll keys.
Additionally, it introduces a new ability: with every service accessing
the database with unique credentials, it makes auditing much easier when
@ -33,7 +33,7 @@ $ vault mount cassandra
Successfully mounted 'cassandra' at 'cassandra'!
```
Next, Vault must be configured to connect to Cassandra. This is done by
Next, Nomad must be configured to connect to Cassandra. This is done by
writing one or more hosts, a username, and a password:
```text
@ -41,8 +41,8 @@ $ vault write cassandra/config/connection \
hosts=localhost username=cassandra password=cassandra
```
In this case, we've configured Vault with the user "cassandra" and password "cassandra",
It is important that the Vault user is a superuser, in order to manage other user accounts.
In this case, we've configured Nomad with the user "cassandra" and password "cassandra",
It is important that the Nomad user is a superuser, in order to manage other user accounts.
The next step is to configure a role. A role is a logical name that maps
to a policy used to generated those credentials. For example, lets create
@ -58,14 +58,14 @@ Success! Data written to: cassandra/roles/readonly
By writing to the `roles/readonly` path we are defining the `readonly` role.
This role will be created by evaluating the given `creation_cql` statements. By
default, the `{{username}}` and `{{password}}` fields will be populated by
Vault with dynamically generated values. This CQL statement is creating
Nomad with dynamically generated values. This CQL statement is creating
the named user, and then granting it `SELECT` or read-only privileges
to keyspaces. More complex `GRANT` queries can be used to
customize the privileges of the role. See the [CQL Reference Manual](http://docs.datastax.com/en/cql/3.1/cql/cql_reference/grant_r.html)
for more information.
To generate a new set of credentials, we simply read from that role:
Vault is now configured to create and manage credentials for Cassandra!
Nomad is now configured to create and manage credentials for Cassandra!
```text
$ vault read cassandra/creds/readonly
@ -77,7 +77,7 @@ password dfa80eea-ccbe-b228-ebf7-e2f62b245e71
username vault-root-1434647667-9313
```
By reading from the `creds/readonly` path, Vault has generated a new
By reading from the `creds/readonly` path, Nomad has generated a new
set of credentials using the `readonly` role configuration. Here we
see the dynamically generated username and password, along with a one
hour lease.

12
website/source/docs/secrets/consul/index.html.md
View file

@ -3,14 +3,14 @@ layout: "docs"
page_title: "Secret Backend: Consul"
sidebar_current: "docs-secrets-consul"
description: |-
The Consul secret backend for Vault generates tokens for Consul dynamically.
The Consul secret backend for Nomad generates tokens for Consul dynamically.
---
# Consul Secret Backend
Name: `consul`
The Consul secret backend for Vault generates
The Consul secret backend for Nomad generates
[Consul](http://consul.io)
API tokens dynamically based on Consul ACL policies.
@ -27,7 +27,7 @@ $ vault mount consul
Successfully mounted 'consul' at 'consul'!
```
Next, we must configure Vault to know how to contact Consul.
Next, we must configure Nomad to know how to contact Consul.
This is done by writing the access information:
```
@ -35,9 +35,9 @@ $ vault write consul/config/access address=127.0.0.1:8500 token=root
Success! Data written to: consul/config/access
```
In this case, we've configured Vault to connect to Consul
In this case, we've configured Nomad to connect to Consul
on the default port with the loopback address. We've also provided
an ACL token to use with the `token` parameter. Vault must have a management
an ACL token to use with the `token` parameter. Nomad must have a management
type token so that it can create and revoke ACL tokens.
The next step is to configure a role. A role is a logical name that maps
@ -64,7 +64,7 @@ lease_duration 3600
token 973a31ea-1ec4-c2de-0f63-623f477c2510
```
Here we can see that Vault has generated a new Consul ACL token for us.
Here we can see that Nomad has generated a new Consul ACL token for us.
We can test this token out, and verify that it is read-only:
```

6
website/source/docs/secrets/custom.html.md
View file

@ -3,13 +3,13 @@ layout: "docs"
page_title: "Secret Backend: Custom"
sidebar_current: "docs-secrets-custom"
description: |-
Create custom secret backends for Vault.
Create custom secret backends for Nomad.
---
# Custom Secret Backends
Vault doesn't currently support the creation of custom secret backends.
The primary reason is because we want to ensure the core of Vault is
Nomad doesn't currently support the creation of custom secret backends.
The primary reason is because we want to ensure the core of Nomad is
secure before attempting any sort of plug-in system. We're interested
in supporting custom secret backends, but don't yet have a clear strategy
or timeline to do.

4
website/source/docs/secrets/generic/index.html.md
View file

@ -11,9 +11,9 @@ description: |-
Name: `generic`
The generic secret backend is used to store arbitrary secrets within
the configured physical storage for Vault. If you followed along with
the configured physical storage for Nomad. If you followed along with
the getting started guide, you interacted with a generic secret backend
via the `secret/` prefix that Vault mounts by default.
via the `secret/` prefix that Nomad mounts by default.
Writing to a key in the `secret/` backend will replace the old value,
the sub-fields are not merged together.

14
website/source/docs/secrets/index.html.md
View file

@ -3,12 +3,12 @@ layout: "docs"
page_title: "Secret Backends"
sidebar_current: "docs-secrets"
description: |-
Secret backends are mountable backends that store or generate secrets in Vault.
Secret backends are mountable backends that store or generate secrets in Nomad.
---
# Secret Backends
Secret backends are the components in Vault which store and generate
Secret backends are the components in Nomad which store and generate
secrets.
Some secret backends, such as "generic", simply store and read
@ -17,12 +17,12 @@ secrets_: secrets that are made on demand.
Secret backends are part of the
[mount system](#)
in Vault. They behave very similarly to a virtual filesystem:
in Nomad. They behave very similarly to a virtual filesystem:
any read/write/delete is sent to the secret backend, and the secret
backend can choose to react to that operation however it sees fit.
For example, the "generic" backend passes through any operation back
to the configured storage backend for Vault. A "read" turns into a
to the configured storage backend for Nomad. A "read" turns into a
"read" of the storage backend at the same path, a "write" turns into
a write, etc. This is a lot like a normal filesystem.
@ -62,14 +62,14 @@ system to determine the paths it responds to.
## Barrier View
An important concept around secret backends is that they receive a
_barrier view_ to the configured Vault physical storage. This is a lot
_barrier view_ to the configured Nomad physical storage. This is a lot
like a [chroot](http://en.wikipedia.org/wiki/Chroot).
Whenever a secret backend is mounted, a random UUID is generated. This
becomes the data root for that backend. Whenever that backend writes to
the physical storage layer, it is prefixed with that UUID folder. Since
the Vault storage layer doesn't support relative access (such as `..`),
the Nomad storage layer doesn't support relative access (such as `..`),
this makes it impossible for a mounted backend to access any other data.
This is an important security feature in Vault: even a malicious backend
This is an important security feature in Nomad: even a malicious backend
can't access the data from any other backend.

6
website/source/docs/secrets/jwt/index.html.md
View file

@ -2,7 +2,7 @@
Name: `jwt`
The JWT secret backend for Vault generates JSON Web Tokens dynamically based on configured roles. This means services can get tokens needed for authentication without going through the usual manual process of generating a private key and signing the token and maintaining the private key's security. Vault's built-in authentication and authorization mechanisms provide the verification functionality.
The JWT secret backend for Nomad generates JSON Web Tokens dynamically based on configured roles. This means services can get tokens needed for authentication without going through the usual manual process of generating a private key and signing the token and maintaining the private key's security. Nomad's built-in authentication and authorization mechanisms provide the verification functionality.
This page will show a quick start for this backend. For detailed documentation on every path, use `vault path-help` after mounting the backend.
@ -62,8 +62,8 @@ Generating a token requires passing of additional information so we use the
```text
$ vault write jwt/issue/webauth \
issuer="Vault" \
audience="Vault Client" \
issuer="Nomad" \
audience="Nomad Client" \
expiration="1538096292" \
claims=@extra.json
```

20
website/source/docs/secrets/mysql/index.html.md
View file

@ -3,24 +3,24 @@ layout: "docs"
page_title: "Secret Backend: MySQL"
sidebar_current: "docs-secrets-mysql"
description: |-
The MySQL secret backend for Vault generates database credentials to access MySQL.
The MySQL secret backend for Nomad generates database credentials to access MySQL.
---
# MySQL Secret Backend
Name: `mysql`
The MySQL secret backend for Vault generates database credentials
The MySQL secret backend for Nomad generates database credentials
dynamically based on configured roles. This means that services that need
to access a database no longer need to hardcode credentials: they can request
them from Vault, and use Vault's leasing mechanism to more easily roll keys.
them from Nomad, and use Nomad's leasing mechanism to more easily roll keys.
Additionally, it introduces a new ability: with every service accessing
the database with unique credentials, it makes auditing much easier when
questionable data access is discovered: you can track it down to the specific
instance of a service based on the SQL username.
Vault makes use of its own internal revocation system to ensure that users
Nomad makes use of its own internal revocation system to ensure that users
become invalid within a reasonable time of the lease expiring.
This page will show a quick start for this backend. For detailed documentation
@ -36,7 +36,7 @@ $ vault mount mysql
Successfully mounted 'mysql' at 'mysql'!
```
Next, we must configure Vault to know how to connect to the MySQL
Next, we must configure Nomad to know how to connect to the MySQL
instance. This is done by providing a DSN (Data Source Name):
```
@ -44,13 +44,13 @@ $ vault write mysql/config/connection value="root:root@tcp(192.168.33.10:3306)/"
Success! Data written to: mysql/config/connection
```
In this case, we've configured Vault with the user "root" and password "root,
In this case, we've configured Nomad with the user "root" and password "root,
connecting to an instance at "192.168.33.10" on port 3306. It is not necessary
that Vault has the root user, but the user must have privileges to create
that Nomad has the root user, but the user must have privileges to create
other users, namely the `GRANT OPTION` privilege.
Optionally, we can configure the lease settings for credentials generated
by Vault. This is done by writing to the `config/lease` key:
by Nomad. This is done by writing to the `config/lease` key:
```
$ vault write mysql/config/lease lease=1h lease_max=24h
@ -74,7 +74,7 @@ Success! Data written to: mysql/roles/readonly
By writing to the `roles/readonly` path we are defining the `readonly` role.
This role will be created by evaluating the given `sql` statements. By
default, the `{{name}}` and `{{password}}` fields will be populated by
Vault with dynamically generated values. This SQL statement is creating
Nomad with dynamically generated values. This SQL statement is creating
the named user, and then granting it `SELECT` or read-only privileges
to tables in the database. More complex `GRANT` queries can be used to
customize the privileges of the role. See the [MySQL manual](https://dev.mysql.com/doc/refman/5.7/en/grant.html)
@ -91,7 +91,7 @@ password 132ae3ef-5a64-7499-351e-bfe59f3a2a21
username root-aefa635a-18
```
By reading from the `creds/readonly` path, Vault has generated a new
By reading from the `creds/readonly` path, Nomad has generated a new
set of credentials using the `readonly` role configuration. Here we
see the dynamically generated username and password, along with a one
hour lease.

32
website/source/docs/secrets/pki/index.html.md
View file

@ -3,14 +3,14 @@ layout: "docs"
page_title: "Secret Backend: PKI"
sidebar_current: "docs-secrets-pki"
description: |-
The PKI secret backend for Vault generates TLS certificates.
The PKI secret backend for Nomad generates TLS certificates.
---
# PKI Secret Backend
Name: `pki`
The PKI secret backend for Vault generates X.509 certificates dynamically based on configured roles. This means services can get certificates needed for both client and server authentication without going through the usual manual process of generating a private key and CSR, submitting to a CA, and waiting for a verification and signing process to complete. Vault's built-in authentication and authorization mechanisms provide the verification functionality.
The PKI secret backend for Nomad generates X.509 certificates dynamically based on configured roles. This means services can get certificates needed for both client and server authentication without going through the usual manual process of generating a private key and CSR, submitting to a CA, and waiting for a verification and signing process to complete. Nomad's built-in authentication and authorization mechanisms provide the verification functionality.
By keeping leases relatively short, revocations are less likely to be needed, keeping CRLs short and helping the backend scale to large workloads. This in turn allows each instance of a running application to have a unique certificate, eliminating sharing and the accompanying pain of revocation and rollover.
@ -24,7 +24,7 @@ To successfully deploy this backend, there are a number of important considerati
### Never use root CAs
Vault storage is secure, but not as secure as a piece of paper in a bank vault. It is, after all, networked software. Your long-lived self-signed root CA's private key should instead be used to issue a shorter-lived intermediate CA certificate, and this is what you should put into Vault. This aligns with industry best practices.
Nomad storage is secure, but not as secure as a piece of paper in a bank vault. It is, after all, networked software. Your long-lived self-signed root CA's private key should instead be used to issue a shorter-lived intermediate CA certificate, and this is what you should put into Nomad. This aligns with industry best practices.
### One CA Certificate, One Backend
@ -34,13 +34,13 @@ This also provides a convenient method of switching to a new CA certificate whil
### Keep certificate lifetimes short, for CRL's sake
This backend aligns with Vault's philosophy of short-lived secrets. As such it is not expected that CRLs will grow large; the only place a private key is ever returned is to the requesting client (this backend does *not* store generated private keys). In most cases, if the key is lost, the certificate can simply be ignored, as it will expire shortly.
This backend aligns with Nomad's philosophy of short-lived secrets. As such it is not expected that CRLs will grow large; the only place a private key is ever returned is to the requesting client (this backend does *not* store generated private keys). In most cases, if the key is lost, the certificate can simply be ignored, as it will expire shortly.
If a certificate must truly be revoked, the normal Vault revocation function can be used; alternately a root token can be used to revoke the certificate using the certificate's serial number. Any revocation action will cause the CRL to be regenerated. When the CRL is regenerated, any expired certificates are removed from the CRL (and any revoked, expired certificate are removed from backend storage).
If a certificate must truly be revoked, the normal Nomad revocation function can be used; alternately a root token can be used to revoke the certificate using the certificate's serial number. Any revocation action will cause the CRL to be regenerated. When the CRL is regenerated, any expired certificates are removed from the CRL (and any revoked, expired certificate are removed from backend storage).
This backend does not support multiple CRL endpoints with sliding date windows; often such mechanisms will have the transition point a few days apart, but this gets into the expected realm of the actual certificate validity periods issued from this backend. A good rule of thumb for this backend would be to simply not issue certificates with a validity period greater than your maximum comfortable CRL lifetime. Alternately, you can control CRL caching behavior on the client to ensure that checks happen more often.
Often multiple endpoints are used in case a single CRL endpoint is down so that clients don't have to figure out what to do with a lack of response. Run Vault in HA mode, and the CRL endpoint should be available even if a particular node is down.
Often multiple endpoints are used in case a single CRL endpoint is down so that clients don't have to figure out what to do with a lack of response. Run Nomad in HA mode, and the CRL endpoint should be available even if a particular node is down.
### You must configure CRL information *in advance*
@ -48,7 +48,7 @@ This backend serves CRLs from a predictable location. That location must be enco
### No OCSP support, yet
Vault's architecture does not currently allow for a binary protocol such as OCSP to be supported by a backend. As such, you should configure your software to use CRLs for revocation information, with a caching lifetime that feels good to you. Since you are following the advice above about keeping lifetimes short (right?), CRLs should not grow too large.
Nomad's architecture does not currently allow for a binary protocol such as OCSP to be supported by a backend. As such, you should configure your software to use CRLs for revocation information, with a caching lifetime that feels good to you. Since you are following the advice above about keeping lifetimes short (right?), CRLs should not grow too large.
## Quick Start
@ -62,7 +62,7 @@ crlDistributionPoints = URI:https://vault.example.com:8200/v1/pki/crl
Adjust the URI as appropriate.
### Vault
### Nomad
The first step to using the PKI backend is to mount it. Unlike the `generic` backend, the `pki` backend is not mounted by default.
@ -71,7 +71,7 @@ $ vault mount pki
Successfully mounted 'pki' at 'pki'!
```
Next, Vault must be configured with a root certificate and associated private key. This is done by writing the contents of a file or *stdin*:
Next, Nomad must be configured with a root certificate and associated private key. This is done by writing the contents of a file or *stdin*:
```text
$ vault write pki/config/ca pem_bundle="@ca_bundle.pem"
@ -85,7 +85,7 @@ $ cat bundle.pem | vault write pki/config/ca pem_bundle="-"
Success! Data written to: pki/config/ca
```
Although in this example the value being piped into *stdin* could be passed directly into the Vault CLI command, a more complex usage might be to use [Ansible](http://www.ansible.com) to securely store the certificate and private key in an `ansible-vault` file, then have an `ansible-playbook` command decrypt this value and pass it in to Vault.
Although in this example the value being piped into *stdin* could be passed directly into the Nomad CLI command, a more complex usage might be to use [Ansible](http://www.ansible.com) to securely store the certificate and private key in an `ansible-vault` file, then have an `ansible-playbook` command decrypt this value and pass it in to Nomad.
The next step is to configure a role. A role is a logical name that maps to a policy used to generated those credentials. For example, let's create an "example-dot-com" role:
@ -96,7 +96,7 @@ $ vault write pki/roles/example-dot-com \
Success! Data written to: pki/roles/example-dot-com
```
By writing to the `roles/example-dot-com` path we are defining the `example-dot-com` role. To generate a new set of credentials, we simply write to the `issue` endpoint with that role name: Vault is now configured to create and manage certificates!
By writing to the `roles/example-dot-com` path we are defining the `example-dot-com` role. To generate a new set of credentials, we simply write to the `issue` endpoint with that role name: Nomad is now configured to create and manage certificates!
```text
$ vault write pki/issue/example-dot-com common_name=blah.example.com
@ -123,7 +123,7 @@ serial 5e:62:eb:2e:44:dd:04:83:8e:21:88:36:fc:15:ce:ed:da:1c:29:f5
Note that this is a write, not a read, to allow values to be passed in at request time.
Vault has now generated a new set of credentials using the `example-dot-com` role configuration. Here we see the dynamically generated private key and certificate. The issuing CA certificate is returned as well.
Nomad has now generated a new set of credentials using the `example-dot-com` role configuration. Here we see the dynamically generated private key and certificate. The issuing CA certificate is returned as well.
Using ACLs, it is possible to restrict using the pki backend such that trusted operators can manage the role definitions, and both users and applications are restricted in the credentials they are allowed to read.
@ -139,7 +139,7 @@ If you get stuck at any time, simply run `vault path-help pki` or with a subpath
<dd>
Retrieves the CA certificate *in raw DER-encoded form*.
This is a bare endpoint that does not return a
standard Vault data structure. If `/pem` is added to the
standard Nomad data structure. If `/pem` is added to the
endpoint, the CA certificate is returned in PEM format.
<br /><br />This is an unauthenticated endpoint.
</dd>
@ -218,7 +218,7 @@ If you get stuck at any time, simply run `vault path-help pki` or with a subpath
command similar to the following:<br/>
```text
curl -X POST --data "@cabundle.json" http://127.0.0.1:8200/v1/pki/config/ca -H X-Vault-Token:06b9d...
curl -X POST --data "@cabundle.json" http://127.0.0.1:8200/v1/pki/config/ca -H X-Nomad-Token:06b9d...
```
Note that if you provide the data through the HTTP API it must be
@ -261,7 +261,7 @@ If you get stuck at any time, simply run `vault path-help pki` or with a subpath
Retrieves the current CRL *in raw DER-encoded form*. This endpoint
is suitable for usage in the CRL Distribution Points extension in a
CA certificate. This is a bare endpoint that does not return a
standard Vault data structure. If `/pem` is added to the endpoint,
standard Nomad data structure. If `/pem` is added to the endpoint,
the CRL is returned in PEM format.
<br /><br />This is an unauthenticated endpoint.
</dd>
@ -408,7 +408,7 @@ If you get stuck at any time, simply run `vault path-help pki` or with a subpath
<dd>
Revokes a certificate using its serial number. This is an
alternative option to the standard method of revoking
using Vault lease IDs. A successful revocation will
using Nomad lease IDs. A successful revocation will
rotate the CRL.
<br /><br />This is a root-protected endpoint.
</dd>

22
website/source/docs/secrets/postgresql/index.html.md
View file

@ -3,24 +3,24 @@ layout: "docs"
page_title: "Secret Backend: PostgreSQL"
sidebar_current: "docs-secrets-postgresql"
description: |-
The PostgreSQL secret backend for Vault generates database credentials to access PostgreSQL.
The PostgreSQL secret backend for Nomad generates database credentials to access PostgreSQL.
---
# PostgreSQL Secret Backend
Name: `postgresql`
The PostgreSQL secret backend for Vault generates database credentials
The PostgreSQL secret backend for Nomad generates database credentials
dynamically based on configured roles. This means that services that need
to access a database no longer need to hardcode credentials: they can request
them from Vault, and use Vault's leasing mechanism to more easily roll keys.
them from Nomad, and use Nomad's leasing mechanism to more easily roll keys.
Additionally, it introduces a new ability: with every service accessing
the database with unique credentials, it makes auditing much easier when
questionable data access is discovered: you can track it down to the specific
instance of a service based on the SQL username.
Vault makes use both of its own internal revocation system as well as the
Nomad makes use both of its own internal revocation system as well as the
`VALID UNTIL` setting when creating PostgreSQL users to ensure that users
become invalid within a reasonable time of the lease expiring.
@ -37,7 +37,7 @@ $ vault mount postgresql
Successfully mounted 'postgresql' at 'postgresql'!
```
Next, Vault must be configured to connect to the PostgreSQL. This is done by
Next, Nomad must be configured to connect to the PostgreSQL. This is done by
writing either a PostgreSQL URL or PG connection string:
```text
@ -45,12 +45,12 @@ $ vault write postgresql/config/connection \
value="postgresql://root:vaulttest@vaulttest.ciuvljjni7uo.us-west-1.rds.amazonaws.com:5432/postgres"
```
In this case, we've configured Vault with the user "root" and password "vaulttest",
In this case, we've configured Nomad with the user "root" and password "vaulttest",
connecting to a PostgreSQL instance in AWS RDS. The "postgres" database name is being used.
It is important that the Vault user have the `GRANT OPTION` privilege to manage users.
It is important that the Nomad user have the `GRANT OPTION` privilege to manage users.
Optionally, we can configure the lease settings for credentials generated
by Vault. This is done by writing to the `config/lease` key:
by Nomad. This is done by writing to the `config/lease` key:
```
$ vault write postgresql/config/lease lease=1h lease_max=24h
@ -76,14 +76,14 @@ Success! Data written to: postgresql/roles/readonly
By writing to the `roles/readonly` path we are defining the `readonly` role.
This role will be created by evaluating the given `sql` statements. By
default, the `{{name}}`, `{{password}}` and `{{expiration}}` fields will be populated by
Vault with dynamically generated values. This SQL statement is creating
Nomad with dynamically generated values. This SQL statement is creating
the named user, and then granting it `SELECT` or read-only privileges
to tables in the database. More complex `GRANT` queries can be used to
customize the privileges of the role. See the [PostgreSQL manual](http://www.postgresql.org/docs/9.4/static/sql-grant.html)
for more information.
To generate a new set of credentials, we simply read from that role:
Vault is now configured to create and manage credentials for Postgres!
Nomad is now configured to create and manage credentials for Postgres!
```text
$ vault read postgresql/creds/readonly
@ -94,7 +94,7 @@ password 34205e88-0de1-68b7-6267-72d8e32c5d3d
username vault-root-1430162075-7887
```
By reading from the `creds/readonly` path, Vault has generated a new
By reading from the `creds/readonly` path, Nomad has generated a new
set of credentials using the `readonly` role configuration. Here we
see the dynamically generated username and password, along with a one
hour lease.

42
website/source/docs/secrets/ssh/index.html.md
View file

@ -3,14 +3,14 @@ layout: "docs"
page_title: "Secret Backend: SSH"
sidebar_current: "docs-secrets-ssh"
description: |-
The SSH secret backend for Vault generates dynamic SSH keys or One-Time-Passwords.
The SSH secret backend for Nomad generates dynamic SSH keys or One-Time-Passwords.
---
# SSH Secret Backend
Name: `ssh`
Vault SSH backend generates SSH credentials for remote hosts dynamically. This
Nomad SSH backend generates SSH credentials for remote hosts dynamically. This
backend increases the security by removing the need to share the private key to
everyone who needs access to infrastructures. It also solves the problem of
management and distribution of keys belonging to remote hosts.
@ -27,14 +27,14 @@ on every path, use `vault path-help` after mounting the backend.
----------------------------------------------------
## I. Dynamic Type
Register the shared secret key (having super user privileges) with Vault and let
Vault take care of issuing a dynamic secret key every time a client wants to SSH
Register the shared secret key (having super user privileges) with Nomad and let
Nomad take care of issuing a dynamic secret key every time a client wants to SSH
into the remote host.
When a Vault authenticated client requests for a dynamic credential, Vault server
When a Nomad authenticated client requests for a dynamic credential, Nomad server
creates a key-pair, uses the previously shared secret key to login to the remote
host and appends the newly generated public key to `~/.ssh/authorized_keys` file for
the desired username. Vault uses an install script (configurable) to achieve this.
the desired username. Nomad uses an install script (configurable) to achieve this.
To run this script in super user mode without password prompts, `NOPASSWD` option
for sudoers should be enabled at all remote hosts.
@ -45,8 +45,8 @@ File: `/etc/sudoers`
```
The private key returned to the user will be leased and can be renewed if desired.
Once the key is given to the user, Vault will not know when it gets used or how many
time it gets used. Therefore, Vault **WILL NOT** and cannot audit the SSH session
Once the key is given to the user, Nomad will not know when it gets used or how many
time it gets used. Therefore, Nomad **WILL NOT** and cannot audit the SSH session
establishments. An alternative is to use OTP type, which audits every SSH request
(see below).
@ -60,7 +60,7 @@ $ vault mount ssh
Successfully mounted 'ssh' at 'ssh'!
```
Next, we must register infrastructures with Vault. This is done by writing the role
Next, we must register infrastructures with Nomad. This is done by writing the role
information. The type of credentials created are determined by the `key_type` option.
To do this, first create a named key and then create a role.
@ -95,7 +95,7 @@ are explained in the comments.
# $1: "install" or "uninstall"
#
# $2: File name containing public key to be installed. Vault server uses UUID
# $2: File name containing public key to be installed. Nomad server uses UUID
# as file name to avoid collisions with public keys generated for requests.
#
# $3: Absolute path of the authorized_keys file.
@ -175,7 +175,7 @@ username@ip:~$
### Automate it!
Creation of new key, saving it in a file and establishing an SSH session will all be done
via a single Vault CLI.
via a single Nomad CLI.
```shell
$ vault ssh -role dynamic_key_role username@ip
@ -184,18 +184,18 @@ username@ip:~$
----------------------------------------------------
## II. One-Time-Password (OTP) Type
Install Vault SSH Agent in remote hosts and let Vault server issue an OTP every time
Install Nomad SSH Agent in remote hosts and let Nomad server issue an OTP every time
a client wants to SSH into remote hosts.
Vault authenticated clients request for a credential from Vault server and get an OTP
Nomad authenticated clients request for a credential from Nomad server and get an OTP
issued. When clients try to establish SSH connection with the remote host, OTP typed
in at the password prompt will be received by the Vault agent and gets validated
by the Vault server. Vault server deletes the OTP after validating it once (hence one-time).
in at the password prompt will be received by the Nomad agent and gets validated
by the Nomad server. Nomad server deletes the OTP after validating it once (hence one-time).
Since Vault server is contacted for every successful connection establishment, unlike
Since Nomad server is contacted for every successful connection establishment, unlike
Dynamic type, every login attempt **WILL** be audited.
See [Vault-SSH-Agent](https://github.com/hashicorp/vault-ssh-agent) for details
See [Nomad-SSH-Agent](https://github.com/hashicorp/vault-ssh-agent) for details
on how to configure the agent.
### Mounting SSH
@ -212,7 +212,7 @@ Successfully mounted 'ssh' at 'ssh'!
Create a role, say `otp_key_role` for key type `otp`. All the machines represented
by CIDR block should have agent installed in them and have their SSH configuration
modified to support Vault SSH Agent client authentication.
modified to support Nomad SSH Agent client authentication.
```shell
$ vault write ssh/roles/otp_key_role key_type=otp default_user=username cidr_list=x.x.x.x/y,m.m.m.m/n
@ -411,7 +411,7 @@ username@ip:~$
<span class="param">key</span>
<span class="param-flags">required for Dynamic type, NA for OTP type</span>
(String)
Name of the registered key in Vault. Before creating the role, use
Name of the registered key in Nomad. Before creating the role, use
the `keys/` endpoint to create a named key.
</li>
<li>
@ -420,7 +420,7 @@ username@ip:~$
(String)
Admin user at remote host. The shared key being registered should be
for this user and should have root privileges. Everytime a dynamic
credential is being generated for other users, Vault uses this admin
credential is being generated for other users, Nomad uses this admin
username to login to remote host and install the generated credential
for the other user.
</li>
@ -446,7 +446,7 @@ username@ip:~$
Port number for SSH connection. Default is '22'. Port number does not
play any role in creation of OTP. For 'otp' type, this is just a way
to inform client about the port number to use. Port number will be
returned to client by Vault server along with OTP.
returned to client by Nomad server along with OTP.
</li>
<li>
<span class="param">key_type</span>

12
website/source/docs/secrets/transit/index.html.md
View file

@ -3,25 +3,25 @@ layout: "docs"
page_title: "Secret Backend: Transit"
sidebar_current: "docs-secrets-transit"
description: |-
The transit secret backend for Vault encrypts/decrypts data in-transit. It doesn't store any secrets.
The transit secret backend for Nomad encrypts/decrypts data in-transit. It doesn't store any secrets.
---
# Transit Secret Backend
Name: `transit`
The transit secret backend is used to encrypt/data in-transit. Vault doesn't
The transit secret backend is used to encrypt/data in-transit. Nomad doesn't
store the data sent to the backend. It can also be viewed as "encryption as
a service."
The primary use case for the transit backend is to encrypt data from
applications while still storing that encrypted data in some primary data
store. This relieves the burden of proper encryption/decryption from
application developers and pushes the burden onto the operators of Vault.
Operators of Vault generally include the security team at an organization,
application developers and pushes the burden onto the operators of Nomad.
Operators of Nomad generally include the security team at an organization,
which means they can ensure that data is encrypted/decrypted properly.
As of Vault 0.2, the transit backend also supports doing key derivation. This
As of Nomad 0.2, the transit backend also supports doing key derivation. This
allows data to be encrypted within a context such that the same context must be
used for decryption. This can be used to enable per transaction unique keys which
further increase the security of data at rest.
@ -87,7 +87,7 @@ ciphertext vault:v0:czEwyKqGZY/limnuzDCUUe5AK0tbBObWqeZgFqxCuIqq7A84SeiOq3sKD0Y/
```
The encryption endpoint expects the plaintext to be provided as a base64 encoded
strings, so we must first convert it. Vault does not store the plaintext or the
strings, so we must first convert it. Nomad does not store the plaintext or the
ciphertext, but only handles it _in transit_ for processing. The application
is free to store the ciphertext in a database or file at rest.

8
website/source/downloads.html.erb
View file

@ -1,18 +1,18 @@
---
layout: "downloads"
page_title: "Download Vault"
page_title: "Download Nomad"
sidebar_current: "downloads-vault"
description: |-
Download Vault
Download Nomad
---
<h1>Download Vault</h1>
<h1>Download Nomad</h1>
<section class="downloads">
<div class="description row">
<div class="col-md-12">
<p>
Below are all available downloads for the latest version of Vault
Below are all available downloads for the latest version of Nomad
(<%= latest_version %>). Please download the proper package for your
operating system and architecture. You can find SHA256 checksums
for packages <a href="https://dl.bintray.com/mitchellh/vault/vault_<%= latest_version %>_SHA256SUMS?direct">here</a>. You can verify the SHA256 checksums using <a href="https://hashicorp.com/security.html">our PGP public key</a> and the <a href="https://dl.bintray.com/mitchellh/vault/vault_<%= latest_version %>_SHA256SUMS.sig?direct">SHA256SUMs signature file</a>.

13
website/source/index.html.erb
View file

@ -15,8 +15,8 @@
<div id="hero-logotype"></div>
</div>
<div id="hero-text">
<h1>Applications on a global fleet.</h1>
<h3>As simple as a Single Machine.</h3>
<h1>Easily deploy applications at any scale</h1>
<h3>Any App. Any OS. Any Cloud.</h3>
<div id="hero-btns">
<a class="h-btn light lrg has-caret intro" href="/intro">Learn More<span class="h-caret"></span></a>
<a class="h-btn green lrg has-caret has-border try" href="">Try Nomad<span class="h-caret"></span></a>
@ -47,10 +47,13 @@
<div id="deploy" class="feature">
<div class="feature-header">
<h3>Deploy to any cloud</h3>
<p>Deploy Applications and Docker containers across datacenters to any cloud</p>
<p>
Nomad supports multi-datacenter and multi-region clusters. Deploy applications that
span multiple geographic locations or cloud providers.
</p>
</div>
<div class="feature-footer">
<p>Phasellus quis arcu nec turpis aliquet malesuada. Pellentesque auctor fermentum cursus.</p>
<p>Applications containerized with Docker can be quickly deployed, making it easy to scale.</p>
<span class="docker-outline-logo"></span>
</div>
</div> <!-- .feature -->
@ -106,7 +109,7 @@
<div id="density" class="feature">
<div class="feature-header">
<h3>Increase density and reduce cost</h3>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque hendrerit nulla ut orci ultricies viverra.</p>
<p>Nomad automatically bin packs tasks to maximize efficency, increase density and reduce costs.</p>
</div>
<div class="feature-graphic"></div>
</div> <!-- .feature -->

30
website/source/intro/getting-started/acl.html.md
View file

@ -3,28 +3,28 @@ layout: "intro"
page_title: "Access Control Policies"
sidebar_current: "gettingstarted-acl"
description: |-
Access control policies in Vault control what a user can access.
Access control policies in Nomad control what a user can access.
---
# Access Control Policies (ACLs)
Access control policies in Vault control what a user can access. In
Access control policies in Nomad control what a user can access. In
the last section, we learned about _authentication_. This section is
about _authorization_.
Whereas for authentication Vault has multiple options or backends that
can be enabled and used, the authorization or policies of Vault are always
Whereas for authentication Nomad has multiple options or backends that
can be enabled and used, the authorization or policies of Nomad are always
the same format. All authentication backends must map identities back to
the core policies that are configured with Vault.
the core policies that are configured with Nomad.
When initializing Vault, there is always one special policy created
When initializing Nomad, there is always one special policy created
that can't be removed: the "root" policy. This policy is a special policy
that gives superuser access to everything in Vault. An identity mapped to
that gives superuser access to everything in Nomad. An identity mapped to
the root policy can do anything.
## Policy Format
Policies in Vault are formatted with
Policies in Nomad are formatted with
[HCL](https://github.com/hashicorp/hcl). HCL is a human-readable configuration
format that is also JSON-compatible, so you can use JSON as well. An example
policy is shown below:
@ -42,13 +42,13 @@ path "secret/foo" {
The policy format uses a prefix matching system on the API path
to determine access control. The most specific defined policy is used,
either an exact match or the longest-prefix glob match. Since everything
in Vault must be accessed via the API, this gives strict control over every
aspect of Vault, including mounting backends, authenticating, as well as secret access.
in Nomad must be accessed via the API, this gives strict control over every
aspect of Nomad, including mounting backends, authenticating, as well as secret access.
In the policy above, a user could write any secret to `secret/`, except
to `secret/foo`, where only read access is allowed. Policies default to
deny, so any access to an unspecified path is not allowed. The policy
language changed slightly in Vault 0.2, [see this page for details](/docs/concepts/policies.html).
language changed slightly in Nomad 0.2, [see this page for details](/docs/concepts/policies.html).
Save the above policy as `acl.hcl`.
@ -103,7 +103,7 @@ such as `vault mounts` will not work either.
## Mapping Policies to Auth Backends
Vault is the single policy authority, unlike auth where you can mount
Nomad is the single policy authority, unlike auth where you can mount
multiple backends. Any mounted auth backend must map identities to these
core policies.
@ -124,12 +124,12 @@ mapping policies to identity.
## Next
Policies are an important part of Vault. While using the root token
Policies are an important part of Nomad. While using the root token
is easiest to get up and running, you'll want to restrict access to
Vault very quickly, and the policy system is the way to do this.
Nomad very quickly, and the policy system is the way to do this.
The syntax and function of policies is easy to understand and work
with, and because auth backends all must map to the central policy system,
you only have to learn this policy system.
Next, we'll cover how to [deploy Vault](/intro/getting-started/deploy.html).
Next, we'll cover how to [deploy Nomad](/intro/getting-started/deploy.html).

40
website/source/intro/getting-started/apis.html.md
View file

@ -7,9 +7,9 @@ description: |-
---
# Using the HTTP APIs with Authentication
All of Vault's capabilities are accessible via the HTTP API in addition to the CLI. In fact, most calls from the CLI actually invoke the HTTP API. In some cases, Vault features are not available via the CLI and can only be accessed via the HTTP API.
All of Nomad's capabilities are accessible via the HTTP API in addition to the CLI. In fact, most calls from the CLI actually invoke the HTTP API. In some cases, Nomad features are not available via the CLI and can only be accessed via the HTTP API.
Once you have started the Vault server, you can use `curl` or any other http client to make API calls. For example, if you started the Vault server in [development mode](/docs/concepts/dev-server.html), you could validate the initialization status like this:
Once you have started the Nomad server, you can use `curl` or any other http client to make API calls. For example, if you started the Nomad server in [development mode](/docs/concepts/dev-server.html), you could validate the initialization status like this:
```
$ curl http://127.0.0.1:8200/v1/sys/init
@ -22,7 +22,7 @@ This will return a JSON response:
```
## Accessing Secrets via the REST APIs
Machines that need access to information stored in Vault will most likely access Vault via its REST API. For example, if a machine were using [app-id](/docs/auth/app-id.html) for authentication, the application would first authenticate to Vault which would return a Vault API token. The application would use that token for future communication with Vault.
Machines that need access to information stored in Nomad will most likely access Nomad via its REST API. For example, if a machine were using [app-id](/docs/auth/app-id.html) for authentication, the application would first authenticate to Nomad which would return a Nomad API token. The application would use that token for future communication with Nomad.
For the purpose of this guide, we will use the following configuration which disables TLS and uses a file-based backend. You should never disable TLS in production, but it is okay for the purposes of this tutorial.
@ -36,13 +36,13 @@ listener "tcp" {
}
```
Save this file on disk and then start the Vault server with this command:
Save this file on disk and then start the Nomad server with this command:
```
$ vault server -config=/etc/vault.conf
```
At this point, we can use Vault's API for all our interactions. For example, we can initialize Vault like this:
At this point, we can use Nomad's API for all our interactions. For example, we can initialize Nomad like this:
```
$ curl \
@ -60,15 +60,15 @@ The response should be JSON and look something like this:
}
```
This response contains our initial root token. It also includes the unseal key. You can use the uneal key to unseal the Vault and use the root token perform other requests in Vault that require authentication.
This response contains our initial root token. It also includes the unseal key. You can use the uneal key to unseal the Nomad and use the root token perform other requests in Nomad that require authentication.
To make this guide easy to copy-and-paste, we will be using the environment variable `$VAULT_TOKEN` to store the root token. You can export this Vault token in your current shell like this:
To make this guide easy to copy-and-paste, we will be using the environment variable `$VAULT_TOKEN` to store the root token. You can export this Nomad token in your current shell like this:
```
$ export VAULT_TOKEN=0e2ede5a-6664-a49e-ca33-8f204d1cdb95
```
Using the unseal key (not the root token) from above, you can unseal the Vault via the HTTP API:
Using the unseal key (not the root token) from above, you can unseal the Nomad via the HTTP API:
```
$ curl \
@ -95,38 +95,38 @@ We can enable an authentication backend with the following `curl` command:
```
$ curl \
-X POST \
-H "X-Vault-Token:$VAULT_TOKEN" \
-H "X-Nomad-Token:$VAULT_TOKEN" \
-d '{"type":"app-id"}' \
http://127.0.0.1:8200/v1/sys/auth/app-id
```
Notice that the request to the app-id endpoint needed an authentication token. In this case we are passing the root token generated when we started the Vault server. We could also generate tokens using any other authentication mechanisms, but we will use the root token for simplicity.
Notice that the request to the app-id endpoint needed an authentication token. In this case we are passing the root token generated when we started the Nomad server. We could also generate tokens using any other authentication mechanisms, but we will use the root token for simplicity.
The last thing we need to do before using our App ID endpoint is writing the data to the store to associate an app id with a user id. For more information on this process, see the documentation on the [app-id auth backend](/docs/auth/app-id.html).
First, we need to associate the application with a particular [ACL policy](/docs/concepts/policies.html) in Vault. In the following command, we are going to associate the created tokens with the `root` policy. You would not want to do this in a real production scenario because the root policy allows complete read, write, and administrator access to Vault. For a production application, you should create an ACL policy (which is also possible via the HTTP API), but is not covered in this guide for simplicity.
First, we need to associate the application with a particular [ACL policy](/docs/concepts/policies.html) in Nomad. In the following command, we are going to associate the created tokens with the `root` policy. You would not want to do this in a real production scenario because the root policy allows complete read, write, and administrator access to Nomad. For a production application, you should create an ACL policy (which is also possible via the HTTP API), but is not covered in this guide for simplicity.
```
$ curl \
-X POST \
-H "X-Vault-Token:$VAULT_TOKEN" \
-H "X-Nomad-Token:$VAULT_TOKEN" \
-d '{"value":"root", "display_name":"demo"}' \
http://localhost:8200/v1/auth/app-id/map/app-id/152AEA38-85FB-47A8-9CBD-612D645BFACA
```
Note that `152AEA38-85FB-47A8-9CBD-612D645BFACA` is a randomly generated UUID. You can use any tool to generate a UUID, but make sure it is unique.
Next we need to map the application to a particular "user". In Vault, this is actually a particular application:
Next we need to map the application to a particular "user". In Nomad, this is actually a particular application:
```
$ curl \
-X POST \
-H "X-Vault-Token:$VAULT_TOKEN" \
-H "X-Nomad-Token:$VAULT_TOKEN" \
-d '{"value":"152AEA38-85FB-47A8-9CBD-612D645BFACA"}' \
http://localhost:8200/v1/auth/app-id/map/user-id/5ADF8218-D7FB-4089-9E38-287465DBF37E
```
Now your app can identify itself via the app-id and user-id and get access to Vault. The first step is to authenticate:
Now your app can identify itself via the app-id and user-id and get access to Nomad. The first step is to authenticate:
```
$ curl \
@ -156,7 +156,7 @@ This will return a response that looks like the following:
}
```
The returned client token (`7a25c58b-9bad-5750-b579-edbb9f10a5ef`) can now be used to authenticate with Vault. As you can see from the returned payload, the App ID backend does not currently support lease expiration or renewal. If you authenticate with backend that does support leases, your application will have to track expiration and handle renewal, but that is a topic for another guide.
The returned client token (`7a25c58b-9bad-5750-b579-edbb9f10a5ef`) can now be used to authenticate with Nomad. As you can see from the returned payload, the App ID backend does not currently support lease expiration or renewal. If you authenticate with backend that does support leases, your application will have to track expiration and handle renewal, but that is a topic for another guide.
We can export this new token as our new `VAULT_TOKEN`:
@ -164,12 +164,12 @@ We can export this new token as our new `VAULT_TOKEN`:
$ export VAULT_TOKEN="7a25c58b-9bad-5750-b579-edbb9f10a5ef"
```
Be sure to replace this with the value returned from your API response. We can now use this token to authentication requests to Vault:
Be sure to replace this with the value returned from your API response. We can now use this token to authentication requests to Nomad:
```
$ curl \
-X POST \
-H "X-Vault-Token:$VAULT_TOKEN" \
-H "X-Nomad-Token:$VAULT_TOKEN" \
-H 'Content-type: application/json' \
-d '{"bar":"baz"}' \
http://127.0.0.1:8200/v1/secret/foo
@ -179,7 +179,7 @@ This will create a new secret named "foo" with the given JSON contents. We can r
```
$ curl \
-H "X-Vault-Token:$VAULT_TOKEN" \
-H "X-Nomad-Token:$VAULT_TOKEN" \
http://127.0.0.1:8200/v1/secret/foo
```
@ -199,7 +199,7 @@ This should return a response like this:
You can see the documentation on the [HTTP APIs](/docs/http/index.html) for more details on other available endpoints.
Congratulations! You now know all the basics to get started with Vault.
Congratulations! You now know all the basics to get started with Nomad.
## Next

34
website/source/intro/getting-started/authentication.html.md
View file

@ -3,36 +3,36 @@ layout: "intro"
page_title: "Authentication"
sidebar_current: "gettingstarted-auth"
description: |-
Authentication to Vault gives a user access to use Vault. Vault can authenticate using multiple methods.
Authentication to Nomad gives a user access to use Nomad. Nomad can authenticate using multiple methods.
---
# Authentication
Now that we know how to use the basics of Vault, it is important to understand
how to authenticate to Vault itself. Up to this point, we haven't had to
authenticate because starting the Vault server in dev mode automatically logs
Now that we know how to use the basics of Nomad, it is important to understand
how to authenticate to Nomad itself. Up to this point, we haven't had to
authenticate because starting the Nomad server in dev mode automatically logs
us in as root. In practice, you'll almost always have to manually authenticate.
On this page, we'll talk specifically about _authentication_. On the next
page, we talk about _authorization_.
Authentication is the mechanism of assigning an identity to a Vault user.
Authentication is the mechanism of assigning an identity to a Nomad user.
The access control and permissions associated with an identity are
authorization, and will not be covered on this page.
Vault has pluggable authentication backends, making it easy to authenticate
with Vault using whatever form works best for your organization. On this page
Nomad has pluggable authentication backends, making it easy to authenticate
with Nomad using whatever form works best for your organization. On this page
we'll use the token backend as well as the GitHub backend.
## Tokens
We'll first explain token authentication before going over any other
authentication backends. Token authentication is enabled by default in
Vault and cannot be disabled. It is also what we've been using up to this
Nomad and cannot be disabled. It is also what we've been using up to this
point.
When you start a dev server with `vault server -dev`, it outputs your
_root token_. The root token is the initial access token to configure Vault.
It has root privileges, so it can perform any operation within Vault.
_root token_. The root token is the initial access token to configure Nomad.
It has root privileges, so it can perform any operation within Nomad.
We'll cover how to limit privileges in the next section.
You can create more tokens using `vault token-create`:
@ -70,17 +70,17 @@ with this token are listed below:
root
```
This authenticates with Vault. It will verify your token and let you know
This authenticates with Nomad. It will verify your token and let you know
what access policies the token is associated with. If you want to test
`vault auth`, make sure you create a new token first.
## Auth Backends
In addition to tokens, other authentication backends can be enabled.
Authentication backends enable alternate methods of identifying with Vault.
Authentication backends enable alternate methods of identifying with Nomad.
These identities are tied back to a set of access policies, just like tokens.
Vault supports other authentication backends in order to make authentication
Nomad supports other authentication backends in order to make authentication
easiest for your environment. For example, for desktop environments,
private key or GitHub based authentication may be easiest. For server
environments, some shared secret may be best. Auth backends give you
@ -148,19 +148,19 @@ $ vault auth-disable github
Disabled auth provider at path 'github'!
```
If you ran the above, you'll probably find you can't access your Vault
If you ran the above, you'll probably find you can't access your Nomad
anymore unless you have another root token, since it invalidated your
own session since we authenticated with GitHub above. Since we're still
operating in development mode, just restart the dev server to fix this.
## Next
In this page you learned about how Vault authenticates users. You learned
In this page you learned about how Nomad authenticates users. You learned
about the built-in token system as well as enabling other authentication
backends. At this point you know how Vault assigns an _identity_ to
backends. At this point you know how Nomad assigns an _identity_ to
a user.
The multiple authentication backends Vault provides let you choose the
The multiple authentication backends Nomad provides let you choose the
most appropriate authentication mechanism for your organization.
In this next section, we'll learn about

106
website/source/intro/getting-started/deploy.html.md
View file

@ -1,26 +1,26 @@
---
layout: "intro"
page_title: "Deploy Vault"
page_title: "Deploy Nomad"
sidebar_current: "gettingstarted-deploy"
description: |-
Learn how to deploy Vault into production, how to initialize it, configure it, etc.
Learn how to deploy Nomad into production, how to initialize it, configure it, etc.
---
# Deploy Vault
# Deploy Nomad
Up to this point, we've been working with the dev server, which
automatically authenticated us, setup in-memory storage, etc. Now that
you know the basics of Vault, it is important to learn how to deploy
Vault into a real environment.
you know the basics of Nomad, it is important to learn how to deploy
Nomad into a real environment.
On this page, we'll cover how to configure Vault, start Vault, the
seal/unseal process, and scaling Vault.
On this page, we'll cover how to configure Nomad, start Nomad, the
seal/unseal process, and scaling Nomad.
## Configuring Vault
## Configuring Nomad
Vault is configured using [HCL](https://github.com/hashicorp/hcl) files.
Nomad is configured using [HCL](https://github.com/hashicorp/hcl) files.
As a reminder, these files are also JSON-compatible. The configuration
file for Vault is relatively simple. An example is shown below:
file for Nomad is relatively simple. An example is shown below:
```javascript
backend "consul" {
@ -36,17 +36,17 @@ listener "tcp" {
Within the configuration file, there are two primary configurations:
* `backend` - This is the physical backend that Vault uses for
* `backend` - This is the physical backend that Nomad uses for
storage. Up to this point the dev server has used "inmem" (in memory),
but in the example above we're using [Consul](http://www.consul.io),
a much more production-ready backend.
* `listener` - One or more listeners determine how Vault listens for
* `listener` - One or more listeners determine how Nomad listens for
API requests. In the example above we're listening on localhost port
8200 without TLS.
For now, copy and paste the configuration above to `example.hcl`. It will
configure Vault to expect an instance of Consul running locally.
configure Nomad to expect an instance of Consul running locally.
Starting a local Consul instance takes only a few minutes. Just follow the
[Consul Getting Started Guide](https://www.consul.io/intro/getting-started/install.html)
@ -64,34 +64,34 @@ where you saved the configuration above.
```
$ vault server -config=example.hcl
==> Vault server configuration:
==> Nomad server configuration:
Log Level: info
Backend: consul
Listener 1: tcp (addr: "127.0.0.1:8200", tls: "disabled")
==> Vault server started! Log data will stream in below:
==> Nomad server started! Log data will stream in below:
```
Vault outputs some information about its configuration, and then blocks.
Nomad outputs some information about its configuration, and then blocks.
This process should be run using a resource manager such as systemd or
upstart.
You'll notice that you can't execute any commands. We don't have any
auth information! When you first setup a Vault server, you have to start
auth information! When you first setup a Nomad server, you have to start
by _initializing_ it.
On Linux, Vault may fail to start with the following error:
On Linux, Nomad may fail to start with the following error:
```shell
$ vault server -config=example.hcl
Error initializing core: Failed to lock memory: cannot allocate memory
This usually means that the mlock syscall is not available.
Vault uses mlock to prevent memory from being swapped to
Nomad uses mlock to prevent memory from being swapped to
disk. This requires root privileges as well as a machine
that supports mlock. Please enable mlock on your system or
disable Vault from using it. To disable Vault from using it,
disable Nomad from using it. To disable Nomad from using it,
set the `disable_mlock` configuration option in your configuration
file.
```
@ -99,16 +99,16 @@ file.
For guidance on dealing with this issue, see the discussion of
`disable_mlock` in [Server Configuration](/docs/config/index.html).
## Initializing the Vault
## Initializing the Nomad
Initialization is the process of first configuring the Vault. This
Initialization is the process of first configuring the Nomad. This
only happens once when the server is started against a new backend that
has never been used with Vault before.
has never been used with Nomad before.
During initialization, the encryption keys are generated, unseal keys
are created, and the initial root token is setup. To initialize Vault
are created, and the initial root token is setup. To initialize Nomad
use `vault init`. This is an _unauthenticated_ request, but it only works
on brand new Vaults with no data:
on brand new Nomads with no data:
```
$ vault init
@ -119,21 +119,21 @@ Key 4: 8dd72fd7d1af254de5f82d1270fd87ab04
Key 5: b47fdeb7dda82dbe92d88d3c860f605005
Initial Root Token: eaf5cc32-b48f-7785-5c94-90b5ce300e9b
Vault initialized with 5 keys and a key threshold of 3!
Nomad initialized with 5 keys and a key threshold of 3!
Please securely distribute the above keys. Whenever a Vault server
Please securely distribute the above keys. Whenever a Nomad server
is started, it must be unsealed with 3 (the threshold)
of the keys above (any of the keys, as long as the total number equals
the threshold).
Vault does not store the original master key. If you lose the keys
Nomad does not store the original master key. If you lose the keys
above such that you no longer have the minimum number (the
threshold), then your Vault will not be able to be unsealed.
threshold), then your Nomad will not be able to be unsealed.
```
Initialization outputs two incredibly important pieces of information:
the _unseal keys_ and the _initial root token_. This is the
**only time ever** that all of this data is known by Vault, and also the
**only time ever** that all of this data is known by Nomad, and also the
only time that the unseal keys should ever be so close together.
For the purpose of this getting started guide, save all these keys
@ -142,25 +142,25 @@ save these keys together.
## Seal/Unseal
Every initialized Vault server starts in the _sealed_ state. From
the configuration, Vault can access the physical storage, but it can't
Every initialized Nomad server starts in the _sealed_ state. From
the configuration, Nomad can access the physical storage, but it can't
read any of it because it doesn't know how to decrypt it. The process
of teaching Vault how to decrypt the data is known as _unsealing_ the
Vault.
of teaching Nomad how to decrypt the data is known as _unsealing_ the
Nomad.
Unsealing has to happen every time Vault starts. It can be done via
the API and via the command line. To unseal the Vault, you
Unsealing has to happen every time Nomad starts. It can be done via
the API and via the command line. To unseal the Nomad, you
must have the _threshold_ number of unseal keys. In the output above,
notice that the "key threshold" is 3. This means that to unseal
the Vault, you need 3 of the 5 keys that were generated.
the Nomad, you need 3 of the 5 keys that were generated.
-> **Note:** Vault does not store any of the unseal key shards. Vault
-> **Note:** Nomad does not store any of the unseal key shards. Nomad
uses an algorithm known as
[Shamir's Secret Sharing](http://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing)
to split the master key into shards. Only with the threshold number of keys
can it be reconstructed and your data finally accessed.
Begin unsealing the Vault with `vault unseal`:
Begin unsealing the Nomad with `vault unseal`:
```
$ vault unseal
@ -171,20 +171,20 @@ Key Threshold: 3
Unseal Progress: 1
```
After pasting in a valid key and confirming, you'll see that the Vault
is still sealed, but progress is made. Vault knows it has 1 key out of 3.
Due to the nature of the algorithm, Vault doesn't know if it has the
After pasting in a valid key and confirming, you'll see that the Nomad
is still sealed, but progress is made. Nomad knows it has 1 key out of 3.
Due to the nature of the algorithm, Nomad doesn't know if it has the
_correct_ key until the threshold is reached.
Also notice that the unseal process is stateful. You can go to another
computer, use `vault unseal`, and as long as it's pointing to the same server,
that other computer can continue the unseal process. This is incredibly
important to the design of the unseal process: multiple people with multiple
keys are required to unseal the Vault. The Vault can be unsealed from
keys are required to unseal the Nomad. The Nomad can be unsealed from
multiple computers and the keys should never be together. A single malicious
operator does not have enough keys to be malicious.
Continue with `vault unseal` to complete unsealing the Vault. Note that
Continue with `vault unseal` to complete unsealing the Nomad. Note that
all 3 keys must be different, but they can be any other keys. As long as
they're correct, you should soon see output like this:
@ -197,26 +197,26 @@ Key Threshold: 3
Unseal Progress: 0
```
The `Sealed: false` means the Vault is unsealed!
The `Sealed: false` means the Nomad is unsealed!
Feel free to play around with entering invalid keys, keys in different
orders, etc. in order to understand the unseal process. It is very important.
Once you're ready to move on, use `vault auth` to authenticate with
the root token.
As a root user, you can reseal the Vault with `vault seal`. A single
As a root user, you can reseal the Nomad with `vault seal`. A single
operator is allowed to do this. This lets a single operator lock down
the Vault in an emergency without consulting other operators.
the Nomad in an emergency without consulting other operators.
When the Vault is sealed again, it clears all of its state (including
the encryption key) from memory. The Vault is secure and locked down
When the Nomad is sealed again, it clears all of its state (including
the encryption key) from memory. The Nomad is secure and locked down
from access.
## Next
You now know how to configure, initialize, and unseal/seal Vault.
This is the basic knowledge necessary to deploy Vault into a real
environment. Once the Vault is unsealed, you access it as you have
throughout this getting started guide (which worked with an unsealed Vault).
You now know how to configure, initialize, and unseal/seal Nomad.
This is the basic knowledge necessary to deploy Nomad into a real
environment. Once the Nomad is unsealed, you access it as you have
throughout this getting started guide (which worked with an unsealed Nomad).
Next, we have a [short tutorial](/intro/getting-started/apis.html) on using the HTTP APIs to authenticate and access secrets.

40
website/source/intro/getting-started/dev-server.html.md
View file

@ -3,51 +3,51 @@ layout: "intro"
page_title: "Starting the Server"
sidebar_current: "gettingstarted-devserver"
description: |-
After installing Vault, the next step is to start the server.
After installing Nomad, the next step is to start the server.
---
# Starting the Vault Server
# Starting the Nomad Server
With Vault installed, the next step is to start a Vault server.
With Nomad installed, the next step is to start a Nomad server.
Vault operates as a client/server application. The Vault server is the
only piece of the Vault architecture that interacts with the data
storage and backends. All operations done via the Vault CLI interact
Nomad operates as a client/server application. The Nomad server is the
only piece of the Nomad architecture that interacts with the data
storage and backends. All operations done via the Nomad CLI interact
with the server over a TLS connection.
In this page, we'll start and interact with the Vault server to understand
In this page, we'll start and interact with the Nomad server to understand
how the server is started, and understanding the seal/unseal process.
## Starting the Dev Server
To start, we're going to start the Vault _dev server_. The dev server
To start, we're going to start the Nomad _dev server_. The dev server
is a built-in flag to start a pre-configured server that is not very
secure but useful for playing with Vault locally. Later in the getting
secure but useful for playing with Nomad locally. Later in the getting
started guide we'll configure and start a real server.
To start the Vault dev server, run `vault server -dev`:
To start the Nomad dev server, run `vault server -dev`:
```
$ vault server -dev
WARNING: Dev mode is enabled!
In this mode, Vault is completely in-memory and unsealed.
Vault is configured to only have a single unseal key. The root
In this mode, Nomad is completely in-memory and unsealed.
Nomad is configured to only have a single unseal key. The root
token has already been authenticated with the CLI, so you can
immediately begin using the Vault CLI.
immediately begin using the Nomad CLI.
The only step you need to take is to set the following
environment variable since Vault will be talking without TLS:
environment variable since Nomad will be talking without TLS:
export VAULT_ADDR='http://127.0.0.1:8200'
The unseal key and root token are reproduced below in case you
want to seal/unseal the Vault or play with authentication.
want to seal/unseal the Nomad or play with authentication.
Unseal Key: 2252546b1a8551e8411502501719c4b3
Root Token: 79bd8011-af5a-f147-557e-c58be4fedf6c
==> Vault server configuration:
==> Nomad server configuration:
Log Level: info
Backend: inmem
@ -57,7 +57,7 @@ Root Token: 79bd8011-af5a-f147-557e-c58be4fedf6c
```
You should see output similar to that above. As you can see, when you
start a dev server, Vault warns you loudly. The dev server stores all
start a dev server, Nomad warns you loudly. The dev server stores all
its data in-memory (but still encrypted), listens on localhost without TLS, and
automatically unseals and shows you the unseal key and root access key.
We'll go over what all this means shortly.
@ -71,7 +71,7 @@ With the dev server running, do the following three things before anything
else:
1. Copy and run the `export VAULT_ADDR ...` command from your terminal
output. This will configure the Vault client to talk to our dev server.
output. This will configure the Nomad client to talk to our dev server.
2. Save the unseal key somewhere. Don't worry about _how_ to save this
securely. For now, just save it anywhere.
@ -98,7 +98,7 @@ High-Availability Enabled: false
```
If the output looks different, especially if the numbers are different
or the Vault is sealed, then restart the dev server and try again. The
or the Nomad is sealed, then restart the dev server and try again. The
only reason these would ever be different is if you're running a dev
server from going through this guide previously.
@ -106,7 +106,7 @@ We'll cover what this output means later in the guide.
## Next
Congratulations! You've started your first Vault server. We haven't stored
Congratulations! You've started your first Nomad server. We haven't stored
any secrets yet, but we'll do that in the next section.
Next, we're going to

16
website/source/intro/getting-started/dynamic-secrets.html.md
View file

@ -3,14 +3,14 @@ layout: "intro"
page_title: "Dynamic Secrets"
sidebar_current: "gettingstarted-dynamicsecrets"
description: |-
On this page we introduce dynamic secrets by showing you how to create AWS access keys with Vault.
On this page we introduce dynamic secrets by showing you how to create AWS access keys with Nomad.
---
# Dynamic Secrets
Now that we've written basic secrets to Vault and we have an understanding
Now that we've written basic secrets to Nomad and we have an understanding
of the mount system, we're going to move on to the next core feature of
Vault: _dynamic secrets_.
Nomad: _dynamic secrets_.
Dynamic secrets are secrets that are generated when they're accessed,
and aren't statically written like we did in
@ -20,7 +20,7 @@ generate AWS access keys.
The power of dynamic secrets is that they simply don't exist before
they're read, so there is no risk of someone stealing them or another
client using the same secrets. And because Vault has built-in revocation
client using the same secrets. And because Nomad has built-in revocation
mechanisms (covered later), the dynamic secret can be revoked right after
use, minimizing the amount of time the secret existed.
@ -105,7 +105,7 @@ many policies with the backend. Save a file named "policy.json" with the followi
```
This is a basic IAM policy that lets the user perform any action within
Amazon EC2. With the policy saved, write it to Vault and create a new role:
Amazon EC2. With the policy saved, write it to Nomad and create a new role:
```
$ vault write aws/roles/deploy policy=@policy.json
@ -113,7 +113,7 @@ Success! Data written to: aws/roles/deploy
```
Again, we're using a special path here `aws/roles/<NAME>` to write
an IAM policy to Vault. We also used the special syntax `@filename` with
an IAM policy to Nomad. We also used the special syntax `@filename` with
`vault write` to write the contents of a file.
## Generating the Secret
@ -134,7 +134,7 @@ Success! The access and secret key can now be used to perform any EC2
operations within AWS. You can verify they work, if you want. Also notice
that these keys are new, they're not the keys you entered earlier.
The `lease_id` above is a special ID used for Vault for renewal,
The `lease_id` above is a special ID used for Nomad for renewal,
revocation, etc. Copy and save your Lease ID now.
## Revoking the Secret
@ -164,7 +164,7 @@ exist for the duration that they're needed.
On this page we experienced our first dynamic secret, and we also saw
the revocation system in action. Dynamic secrets are incredibly powerful.
As time goes on, we expect that more systems will support some sort of
API to create access credentials, and Vault will be ready to get the
API to create access credentials, and Nomad will be ready to get the
most value out of this practice.
Before going further, we're going to take a quick detour to learn

16
website/source/intro/getting-started/first-secret.html.md
View file

@ -3,7 +3,7 @@ layout: "intro"
page_title: "Your First Secret"
sidebar_current: "gettingstarted-firstsecret"
description: |-
With the Vault server running, let's read and write our first secret.
With the Nomad server running, let's read and write our first secret.
---
# Your First Secret
@ -11,18 +11,18 @@ description: |-
Now that the dev server is up and running, let's get straight to it and
read and write our first secret.
One of the core features of Vault is the ability to read and write
One of the core features of Nomad is the ability to read and write
arbitrary secrets securely. On this page, we'll do this using the CLI,
but there is also a complete
[HTTP API](/docs/http/index.html)
that can be used to programmatically do anything with Vault.
that can be used to programmatically do anything with Nomad.
Secrets written to Vault are encrypted and then written to the backend
Secrets written to Nomad are encrypted and then written to the backend
storage. For our dev server, backend storage is in-memory, but in production
this would more likely be on disk or in [Consul](https://www.consul.io).
Vault encrypts the value before it is ever handed to the storage driver.
Nomad encrypts the value before it is ever handed to the storage driver.
The backend storage mechanism _never_ sees the unencrypted value and doesn't
have the means necessary to decrypt it without Vault.
have the means necessary to decrypt it without Nomad.
## Writing a Secret
@ -69,7 +69,7 @@ excited yes
value world
```
As you can see, the values we wrote are given back to us. Vault read
As you can see, the values we wrote are given back to us. Nomad read
the data from storage and decrypted it.
The output format is purposefully whitespace separated to make it easy
to pipe into a tool like `awk`.
@ -112,7 +112,7 @@ Success! Deleted 'secret/hello'
## Next
In this section we learned how to use the powerful CRUD features of
Vault to store arbitrary secrets. On its own this is already a useful
Nomad to store arbitrary secrets. On its own this is already a useful
but basic feature.
Next, we'll learn the basics about [secret backends](/intro/getting-started/secret-backends.html).

12
website/source/intro/getting-started/help.html.md
View file

@ -3,7 +3,7 @@ layout: "intro"
page_title: "Built-in Help"
sidebar_current: "gettingstarted-help"
description: |-
Vault has a built-in help system to learn about the available paths in Vault and how to use them.
Nomad has a built-in help system to learn about the available paths in Nomad and how to use them.
---
# Built-in Help
@ -16,11 +16,11 @@ the paths to use differed. AWS in particular had special paths like
Instead of having to memorize or reference documentation constantly
to determine what paths to use, we built a help system directly into
Vault. This help system can be accessed via the API or the command-line and
Nomad. This help system can be accessed via the API or the command-line and
generates human-readable help for any mounted backend.
On this page, we'll learn how to use this help system. It is an invaluable
tool as you continue to work with Vault.
tool as you continue to work with Nomad.
## Backend Overview
@ -112,9 +112,9 @@ generic `secret/` path.
## Next
The help system may not be the most exciting feature of Vault, but it
is indispensable in day-to-day usage of Vault. The help system lets you
learn about how to use any backend within Vault without leaving the command
The help system may not be the most exciting feature of Nomad, but it
is indispensable in day-to-day usage of Nomad. The help system lets you
learn about how to use any backend within Nomad without leaving the command
line.
Next, we'll learn about

50
website/source/intro/getting-started/install.html.md
View file

@ -1,28 +1,28 @@
---
layout: "intro"
page_title: "Install Vault"
page_title: "Install Nomad"
sidebar_current: "gettingstarted-install"
description: |-
The first step to using Vault is to get it installed.
The first step to using Nomad is to get it installed.
---
# Install Vault
# Install Nomad
Vault must first be installed on your machine. Vault is distributed as
Nomad must first be installed on your machine. Nomad is distributed as
a [binary package](/downloads.html) for all supported platforms and
architectures. This page will not cover how to compile Vault from source,
architectures. This page will not cover how to compile Nomad from source,
but compiling from source is covered in the [documentation](/docs/install/index.html)
for those who want to be sure they're compiling source they trust into
the final binary.
## Installing Vault
## Installing Nomad
To install Vault, find the [appropriate package](/downloads.html) for
your system and download it. Vault is packaged as a zip archive.
To install Nomad, find the [appropriate package](/downloads.html) for
your system and download it. Nomad is packaged as a zip archive.
After downloading Vault, unzip the package. Vault runs as a single binary
After downloading Nomad, unzip the package. Nomad runs as a single binary
named `vault`. Any other files in the package can be safely removed and
Vault will still function.
Nomad will still function.
The final step is to make sure that `vault` is available on the PATH.
See [this page](http://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux)
@ -32,7 +32,7 @@ contains instructions for setting the PATH on Windows.
## Verifying the Installation
After installing Vault, verify the installation worked by opening a new
After installing Nomad, verify the installation worked by opening a new
terminal session and checking that `vault` is available. By executing
`vault`, you should see help output similar to the following:
@ -41,30 +41,30 @@ $ vault
usage: vault [-version] [-help] <command> [args]
Common commands:
delete Delete operation on secrets in Vault
delete Delete operation on secrets in Nomad
path-help Look up the help for a path
read Read data or secrets from Vault
read Read data or secrets from Nomad
renew Renew the lease of a secret
revoke Revoke a secret.
server Start a Vault server
status Outputs status of whether Vault is sealed and if HA mode is enabled
write Write secrets or configuration into Vault
server Start a Nomad server
status Outputs status of whether Nomad is sealed and if HA mode is enabled
write Write secrets or configuration into Nomad
All other commands:
audit-disable Disable an audit backend
audit-enable Enable an audit backend
audit-list Lists enabled audit backends in Vault
auth Prints information about how to authenticate with Vault
audit-list Lists enabled audit backends in Nomad
auth Prints information about how to authenticate with Nomad
auth-disable Disable an auth provider
auth-enable Enable a new auth provider
init Initialize a new Vault server
init Initialize a new Nomad server
key-status Provides information about the active encryption key
mount Mount a logical backend
mounts Lists mounted backends in Vault
mounts Lists mounted backends in Nomad
policies List the policies on the server
policy-delete Delete a policy from the server
policy-write Write a policy to the server
rekey Rekeys Vault to generate new unseal keys
rekey Rekeys Nomad to generate new unseal keys
remount Remount a secret backend to a new path
rotate Rotates the backend encryption key used to persist data
seal Seals the vault server
@ -73,11 +73,11 @@ All other commands:
token-revoke Revoke one or more auth tokens
unmount Unmount a secret backend
unseal Unseals the vault server
version Prints the Vault version
version Prints the Nomad version
```
If you get an error that Vault could not be found, then your PATH environment
If you get an error that Nomad could not be found, then your PATH environment
variable was not setup properly. Please go back and ensure that your PATH
variable contains the directory where Vault was installed.
variable contains the directory where Nomad was installed.
Otherwise, Vault is installed and ready to go!
Otherwise, Nomad is installed and ready to go!

10
website/source/intro/getting-started/next-steps.html.md
View file

@ -3,18 +3,18 @@ layout: "intro"
page_title: "Next Steps"
sidebar_current: "gettingstarted-nextsteps"
description: |-
After completing the getting started guide, learn about what to do next with Vault.
After completing the getting started guide, learn about what to do next with Nomad.
---
# Next Steps
That concludes the getting started guide for Vault. Hopefully you're
excited about the possibilities of Vault and ready to put this knowledge
That concludes the getting started guide for Nomad. Hopefully you're
excited about the possibilities of Nomad and ready to put this knowledge
to use to improve your environment.
We've covered the basics of all the core features of Vault in this guide.
We've covered the basics of all the core features of Nomad in this guide.
Due to the importance of securing secrets, we recommend reading the following
as next steps.
* [Documentation](/docs/index.html) - The documentation is an in-depth
reference guide to all the features of Vault.
reference guide to all the features of Nomad.

22
website/source/intro/getting-started/secret-backends.html.md
View file

@ -8,21 +8,21 @@ description: |-
# Secret Backends
Previously, we saw how to read and write arbitrary secrets to Vault.
Previously, we saw how to read and write arbitrary secrets to Nomad.
To do this, we used the `secret/` prefix. This prefix specifies the
_secret backend_ to use, and Vault defaults to mounting the _generic_
_secret backend_ to use, and Nomad defaults to mounting the _generic_
backend to `secret/`. The generic backend reads and writes raw data to
the backend storage.
Vault supports other backends in addition to "generic", and this feature
in particular is what makes Vault unique. For example, the "aws" backend
Nomad supports other backends in addition to "generic", and this feature
in particular is what makes Nomad unique. For example, the "aws" backend
generates AWS access keys dynamically, on demand. Another example --
this type of backend does not yet exist -- is a backend that
reads and writes data directly to an
[HSM](http://en.wikipedia.org/wiki/Hardware_security_module).
As Vault matures, more and more backends will be added.
As Nomad matures, more and more backends will be added.
To represent backends, Vault behaves much like a filesystem: backends
To represent backends, Nomad behaves much like a filesystem: backends
are _mounted_ at specific paths. For example, the "generic" backend is
_mounted_ at the `secret/` prefix.
@ -33,7 +33,7 @@ to the next page, where we'll create dynamic secrets.
## Mount a Backend
To start, let's mount another "generic" backend. Just like a normal
filesystem, Vault can mount a backend multiple times at different
filesystem, Nomad can mount a backend multiple times at different
mount points. This is useful if you want different access control policies
(covered later) or configurations for different paths.
@ -61,7 +61,7 @@ sys/ system system endpoints used for control, policy and debugging
You can see the `generic/` path we just mounted, as well as the built-in
secret path. You can also see the `sys/` path. We won't cover this in the
getting started guide, but this mount point is used to interact with
the Vault core system.
the Nomad core system.
Spend some time reading and writing secrets to the new mount point to
convince yourself it works. As a bonus, write to the `secret/` endpoint
@ -92,7 +92,7 @@ closely tied to their mount paths.
Now that you've mounted and unmounted a backend, you might wonder:
"what is a secret backend? what is the point of this mounting system?"
Vault behaves a lot like a [virtual filesystem](http://en.wikipedia.org/wiki/Virtual_file_system).
Nomad behaves a lot like a [virtual filesystem](http://en.wikipedia.org/wiki/Virtual_file_system).
The read/write/delete operations are forwarded to the backend, and the
backend can choose to react to these operations however it wishes.
For example, the "generic" backend simply passes this through to the
@ -103,9 +103,9 @@ policies and access tokens. So, while you might do a `vault read aws/deploy`,
this isn't reading from any _physical_ path "aws/deploy". Instead, the AWS
backend is dynamically generating an access key based on the "deploy" policy.
This abstraction is incredibly powerful. It lets Vault interface directly
This abstraction is incredibly powerful. It lets Nomad interface directly
with physical systems such as the backend as well as things such as SQL
databases, HSMs, etc. But in addition to these physical systems, Vault
databases, HSMs, etc. But in addition to these physical systems, Nomad
can interact with more unique environments: AWS IAM, dynamic SQL user creation,
etc. all using the same read/write interface.

50
website/source/intro/index.html.markdown
View file

@ -3,25 +3,25 @@ layout: "intro"
page_title: "Introduction"
sidebar_current: "what"
description: |-
Welcome to the intro guide to Vault! This guide is the best place to start with Vault. We cover what Vault is, what problems it can solve, how it compares to existing software, and contains a quick start for using Vault.
Welcome to the intro guide to Nomad! This guide is the best place to start with Nomad. We cover what Nomad is, what problems it can solve, how it compares to existing software, and contains a quick start for using Nomad.
---
# Introduction to Vault
# Introduction to Nomad
Welcome to the intro guide to Vault! This guide is the best
place to start with Vault. We cover what Vault is, what
Welcome to the intro guide to Nomad! This guide is the best
place to start with Nomad. We cover what Nomad is, what
problems it can solve, how it compares to existing software,
and contains a quick start for using Vault.
and contains a quick start for using Nomad.
If you are already familiar with the basics of Vault, the
If you are already familiar with the basics of Nomad, the
[documentation](/docs/index.html) provides a better reference
guide for all available features as well as internals.
## What is Vault?
## What is Nomad?
Vault is a tool for securely accessing _secrets_. A secret is anything
Nomad is a tool for securely accessing _secrets_. A secret is anything
that you want to tightly control access to, such as API keys, passwords,
certificates, and more. Vault provides a unified interface to any
certificates, and more. Nomad provides a unified interface to any
secret, while providing tight access control and recording a detailed
audit log.
@ -30,36 +30,36 @@ credentials, API keys for external services, credentials for
service-oriented architecture communication, etc. Understanding who is
accessing what secrets is already very difficult and platform-specific.
Adding on key rolling, secure storage, and detailed audit logs is almost
impossible without a custom solution. This is where Vault steps in.
impossible without a custom solution. This is where Nomad steps in.
Examples work best to showcase Vault. Please see the
Examples work best to showcase Nomad. Please see the
[use cases](/intro/use-cases.html).
The key features of Vault are:
The key features of Nomad are:
* **Secure Secret Storage**: Arbitrary key/value secrets can be stored
in Vault. Vault encrypts these secrets prior to writing them to persistent
in Nomad. Nomad encrypts these secrets prior to writing them to persistent
storage, so gaining access to the raw storage isn't enough to access
your secrets. Vault can write to disk, [Consul](http://www.consul.io),
your secrets. Nomad can write to disk, [Consul](http://www.consul.io),
and more.
* **Dynamic Secrets**: Vault can generate secrets on-demand for some
* **Dynamic Secrets**: Nomad can generate secrets on-demand for some
systems, such as AWS or SQL databases. For example, when an application
needs to access an S3 bucket, it asks Vault for credentials, and Vault
needs to access an S3 bucket, it asks Nomad for credentials, and Nomad
will generate an AWS keypair with valid permissions on demand. After
creating these dynamic secrets, Vault will also automatically revoke them
creating these dynamic secrets, Nomad will also automatically revoke them
after the lease is up.
* **Data Encryption**: Vault can encrypt and decrypt data without storing
* **Data Encryption**: Nomad can encrypt and decrypt data without storing
it. This allows security teams to define encryption parameters and
developers to store encrypted data in a location such as SQL without
having to design their own encryption methods.
* **Leasing and Renewal**: All secrets in Vault have a _lease_ associated
with it. At the end of the lease, Vault will automatically revoke that
* **Leasing and Renewal**: All secrets in Nomad have a _lease_ associated
with it. At the end of the lease, Nomad will automatically revoke that
secret. Clients are able to renew leases via built-in renew APIs.
* **Revocation**: Vault has built-in support for secret revocation. Vault
* **Revocation**: Nomad has built-in support for secret revocation. Nomad
can revoke not only single secrets, but a tree of secrets, for example
all secrets read by a specific user, or all secrets of a particular type.
Revocation assists in key rolling as well as locking down systems in the
@ -67,9 +67,9 @@ The key features of Vault are:
## Next Steps
See the page on [Vault use cases](/intro/use-cases.html) to see the
multiple ways Vault can be used. Then see
[how Vault compares to other software](/intro/vs/index.html)
See the page on [Nomad use cases](/intro/use-cases.html) to see the
multiple ways Nomad can be used. Then see
[how Nomad compares to other software](/intro/vs/index.html)
to see how it fits into your existing infrastructure. Finally, continue onwards with
the [getting started guide](/intro/getting-started/install.html) to use
Vault to read, write, and create real secrets and see how it works in practice.
Nomad to read, write, and create real secrets and see how it works in practice.

20
website/source/intro/use-cases.html.markdown
View file

@ -3,30 +3,30 @@ layout: "intro"
page_title: "Use Cases"
sidebar_current: "use-cases"
description: |-
This page lists some concrete use cases for Vault, but the possible use cases are much broader than what we cover.
This page lists some concrete use cases for Nomad, but the possible use cases are much broader than what we cover.
---
# Use Cases
Before understanding use cases, it's useful to know [what Vault is](/intro/index.html).
This page lists some concrete use cases for Vault, but the possible use cases are
Before understanding use cases, it's useful to know [what Nomad is](/intro/index.html).
This page lists some concrete use cases for Nomad, but the possible use cases are
much broader than what we cover.
#### General Secret Storage
At a bare minimum, Vault can be used for the storage of any secrets. For
example, Vault would be a fantastic way to store sensitive environment variables,
At a bare minimum, Nomad can be used for the storage of any secrets. For
example, Nomad would be a fantastic way to store sensitive environment variables,
database credentials, API keys, etc.
Compare this with the current way to store these which might be
plaintext in files, configuration management, a database, etc. It would be
much safer to query these using `vault read` or the API. This protects
the plaintext version of these secrets as well as records access in the Vault
the plaintext version of these secrets as well as records access in the Nomad
audit log.
#### Employee Credential Storage
While this overlaps with "General Secret Storage", Vault is a good mechanism
While this overlaps with "General Secret Storage", Nomad is a good mechanism
for storing credentials that employees share to access web services. The
audit log mechanism lets you know what secrets an employee accessed and
when an employee leaves, it is easier to roll keys and understand which keys
@ -34,7 +34,7 @@ have and haven't been rolled.
#### API Key Generation for Scripts
The "dynamic secrets" feature of Vault is ideal for scripts: an AWS
The "dynamic secrets" feature of Nomad is ideal for scripts: an AWS
access key can be generated for the duration of a script, then revoked.
The keypair will not exist before or after the script runs, and the
creation of the keys are completely logged.
@ -44,12 +44,12 @@ effectively hardcoding limited-access access tokens in various places.
#### Data Encryption
In addition to being able to store secrets, Vault can be used to
In addition to being able to store secrets, Nomad can be used to
encrypt/decrypt data that is stored elsewhere. The primary use of this is
to allow applications to encrypt their data while still storing it in the
primary data store.
The benefit of this is that developers do not need to worry about how to
properly encrypt data. The responsibility of encryption is on Vault
properly encrypt data. The responsibility of encryption is on Nomad
and the security team managing it, and developers just encrypt/decrypt
data as needed.

16
website/source/intro/vs/chef-puppet-etc.html.md
View file

@ -1,12 +1,12 @@
---
layout: "intro"
page_title: "Vault vs. Chef, Puppet, etc."
page_title: "Nomad vs. Chef, Puppet, etc."
sidebar_current: "vs-other-chef"
description: |-
Comparison between Vault and configuration management solutions such as Chef, Puppet, etc.
Comparison between Nomad and configuration management solutions such as Chef, Puppet, etc.
---
# Vault vs. Chef, Puppet, etc.
# Nomad vs. Chef, Puppet, etc.
A big part of configuring software is setting up secrets: configuring a
web application to talk to a service, configuring the credentials of a
@ -22,19 +22,19 @@ to somehow get this secret to decrypt the data. Additionally, access to
the encrypted data isn't always logged, so if there is an intrusion, it
isn't clear what data has been accessed and by who.
Vault is not tied to any specific configuration management system. You can
Nomad is not tied to any specific configuration management system. You can
read secrets from configuration management, but you can also use the API
directly to read secrets from applications. This means that configuration
management requires less secrets, and in many cases doesn't ever have to
persist them to disk.
Vault encrypts the data onto physical storage and requires multiple
Nomad encrypts the data onto physical storage and requires multiple
keys to even read it. If an attacker were to gain access to the physical
encrypted storage, it couldn't be read without multiple keys which are generally
distributed to multiple individuals. This is known as _unsealing_, and happens
once whenever Vault starts.
once whenever Nomad starts.
For an unsealed Vault, every interaction is logged in via the audit backends.
For an unsealed Nomad, every interaction is logged in via the audit backends.
Even erroneous requests (invalid access tokens, for example) are logged.
To access any data, an access token is required. This token is usually
associated with an identity coming from a system such as GitHub, LDAP, etc.
@ -42,4 +42,4 @@ This identity is also written to the audit log.
Access tokens can be given fine-grained control over what secrets can be
accessed. It is rare to have a single key that can access all secrets. This
makes it easier to have fine-grained access for consumers of Vault.
makes it easier to have fine-grained access for consumers of Nomad.

14
website/source/intro/vs/consul.html.md
View file

@ -1,12 +1,12 @@
---
layout: "intro"
page_title: "Vault vs. Consul"
page_title: "Nomad vs. Consul"
sidebar_current: "vs-other-consul"
description: |-
Comparison between Vault and attempting to store secrets with Consul.
Comparison between Nomad and attempting to store secrets with Consul.
---
# Vault vs. Consul
# Nomad vs. Consul
[Consul](https://consul.io) is system for service discovery, monitoring,
and configuration that is distributed and highly available. Consul also
@ -17,16 +17,16 @@ ACLs, it is not designed for that purpose. As such, data is not encrypted
in transit nor at rest, it does not have pluggable authentication mechanisms,
and there is no per-request auditing mechanism.
Vault is designed from the ground up as a secret management solution. As such,
Nomad is designed from the ground up as a secret management solution. As such,
it protects secrets in transit and at rest. It provides multiple authentication
and audit logging mechanisms. Dynamic secret generation allows Vault to avoid
and audit logging mechanisms. Dynamic secret generation allows Nomad to avoid
providing clients with root privileges to underlying systems and makes
it possible to do key rolling and revocation.
The strength of Consul is that it is fault tolerant and highly scalable.
By using Consul as a backend to Vault, you get the best of both. Consul
By using Consul as a backend to Nomad, you get the best of both. Consul
is used for durable storage of encrypted data at rest and provides coordination
so that Vault can be highly available and fault tolerant. Vault provides
so that Nomad can be highly available and fault tolerant. Nomad provides
the higher level policy management, secret leasing, audit logging, and automatic
revocation.

12
website/source/intro/vs/custom.html.markdown
View file

@ -1,12 +1,12 @@
---
layout: "intro"
page_title: "Vault vs. Custom Solutions"
page_title: "Nomad vs. Custom Solutions"
sidebar_current: "vs-other-custom"
description: |-
Comparison between Vault and writing a custom solution.
Comparison between Nomad and writing a custom solution.
---
# Vault vs. Custom Solutions
# Nomad vs. Custom Solutions
Many organizations resort to custom solutions for storing secrets,
whether that be Dropbox, encrypted disk images, encrypted SQL columns,
@ -17,12 +17,12 @@ Storing secrets is also an incredibly important piece of infrastructure
that must be done correctly. This increases the pressure to maintain
the internal systems.
Vault is designed for secret storage. It provides a simple interface
Nomad is designed for secret storage. It provides a simple interface
on top of a strong security model to meet your secret storage needs.
Furthermore, Vault is an open source tool. This means that the tool is
Furthermore, Nomad is an open source tool. This means that the tool is
as good as the entire community working together to improve it. This
isn't just features and bug fixes, but finding potential security holes.
Additionally, since it is an open source, your own security teams can
review and contribute to Vault and verify it meets your standards
review and contribute to Nomad and verify it meets your standards
for security.

8
website/source/intro/vs/dropbox.html.md
View file

@ -1,12 +1,12 @@
---
layout: "intro"
page_title: "Vault vs. Dropbox"
page_title: "Nomad vs. Dropbox"
sidebar_current: "vs-other-dropbox"
description: |-
Comparison between Vault and attempting to store secrets with Dropbox.
Comparison between Nomad and attempting to store secrets with Dropbox.
---
# Vault vs. Dropbox
# Nomad vs. Dropbox
It is an unfortunate truth that many organizations, big and small,
often use Dropbox as a mechanism for storing secrets. It is so common
@ -17,7 +17,7 @@ Dropbox is not made for storing secrets. Even if you're using something
such as an encrypted disk image within Dropbox, it is subpar versus a
real secret storage server.
A real secret management tool such as Vault has a stronger security
A real secret management tool such as Nomad has a stronger security
model, integrates with many different authentication services, stores
audit logs, can generate dynamic secrets, and more.

22
website/source/intro/vs/hsm.html.md
View file

@ -1,12 +1,12 @@
---
layout: "intro"
page_title: "Vault vs. HSMs"
page_title: "Nomad vs. HSMs"
sidebar_current: "vs-other-hsm"
description: |-
Comparison between Vault and HSM systems.
Comparison between Nomad and HSM systems.
---
# Vault vs. HSMs
# Nomad vs. HSMs
A [hardware security module (HSM)](http://en.wikipedia.org/wiki/Hardware_security_module)
is a hardware device that is meant to secure various secrets. They generally
@ -21,19 +21,19 @@ and the "API" to request secrets is also difficult to use. Example: CloudHSM
requires SSH and setting up various keypairs manually. It is difficult to
automate.
Vault **doesn't replace an HSM**. There are many benefits to an HSM if
Nomad **doesn't replace an HSM**. There are many benefits to an HSM if
you can afford it. Instead, an HSM is a fantastic potential secret backend
for Vault. This would allow Vault to access the HSM data via the Vault API,
for Nomad. This would allow Nomad to access the HSM data via the Nomad API,
making it significantly easier to use an HSM, while also retaining all the
audit logs. In fact, you'd have multiple audit logs: requests to Vault
audit logs. In fact, you'd have multiple audit logs: requests to Nomad
as well as to the HSM.
Vault can also do many things that HSMs cannot currently do, such
Nomad can also do many things that HSMs cannot currently do, such
as generating _dynamic secrets_. Instead of storing AWS access keys directly
within Vault, Vault can generate access keys according to a specific
policy on the fly. Vault has the potential of doing this for any
within Nomad, Nomad can generate access keys according to a specific
policy on the fly. Nomad has the potential of doing this for any
system through its mountable secret backend system.
For most companies, an HSM is overkill, and Vault is enough. For companies
that can afford an HSM, it can be used with Vault to get the best of both
For most companies, an HSM is overkill, and Nomad is enough. For companies
that can afford an HSM, it can be used with Nomad to get the best of both
worlds.

12
website/source/intro/vs/index.html.markdown
View file

@ -1,22 +1,22 @@
---
layout: "intro"
page_title: "Vault vs. Other Software"
page_title: "Nomad vs. Other Software"
sidebar_current: "vs-other"
description: |-
Comparisons between Vault and other software that claim to store secrets in some capacity.
Comparisons between Nomad and other software that claim to store secrets in some capacity.
---
# Vault vs. Other Software
# Nomad vs. Other Software
There are a number of other options in the market currently that claim
to store secrets in some capacity. This section compares Vault to these
to store secrets in some capacity. This section compares Nomad to these
other software choices.
Due to the bias of the comparisons being on the Vault website, we attempt
Due to the bias of the comparisons being on the Nomad website, we attempt
to only use facts. If you find something that is invalid or out of date
in the comparisons, please
[open an issue](https://github.com/hashicorp/vault/issues) and we'll
address it as soon as possible.
Use the navigation on the left to read comparisons of Vault versus other
Use the navigation on the left to read comparisons of Nomad versus other
systems.

26
website/source/intro/vs/keywhiz.html.md
View file

@ -1,12 +1,12 @@
---
layout: "intro"
page_title: "Vault vs. Keywhiz"
page_title: "Nomad vs. Keywhiz"
sidebar_current: "vs-other-keywhiz"
description: |-
Comparison between Vault and Keywhiz.
Comparison between Nomad and Keywhiz.
---
# Vault vs. Keywhiz
# Nomad vs. Keywhiz
Keywhiz is a secret management solution built by Square. Keywhiz
has a client/server architecture based on a RESTful API. Clients of
@ -17,30 +17,30 @@ as files on disk, and use Unix file permissions for access control. Human
operators may authenticate using a cookie-based authentication either via command
line utilities or through a management web interface.
Vault similarly is designed as a comprehensive secret management
solution. The client interaction with Vault is flexible
both for authentication and usage of secrets. Vault supports [mTLS
Nomad similarly is designed as a comprehensive secret management
solution. The client interaction with Nomad is flexible
both for authentication and usage of secrets. Nomad supports [mTLS
authentication](/docs/auth/cert.html) along with many [other
mechanisms](/docs/auth/index.html). The goal being to make it easy to
authenticate as a machine for programmatic access and as a human for
operator usage.
Vault and Keywhiz expose secrets via an API. The Vault
Nomad and Keywhiz expose secrets via an API. The Nomad
[ACL system](/docs/concepts/policies.html) is used
to protect secrets and gate access, similarly to the
Keywhiz ACL system. With Vault, All auditing is done
Keywhiz ACL system. With Nomad, All auditing is done
server side using [audit backends](/docs/audit/index.html).
Keywhiz focuses on storage and distribution of secrets and supports
rotation through secret versioning, which is possible in the Keywhiz UI and
command-line utilities. Vault also supports dynamic secrets and generating credentials
command-line utilities. Nomad also supports dynamic secrets and generating credentials
on-demand for fine-grained security controls, but adds first class support
for non-repudiation. Key rotation is a first class concern for Keywhiz and Vault, so
for non-repudiation. Key rotation is a first class concern for Keywhiz and Nomad, so
that no external systems need to be used.
Lastly Vault forces a mandatory lease contract with clients. All secrets read
from Vault have an associated lease which enables operators to audit key usage,
perform key rolling, and ensure automatic revocation. Vault provides multiple
Lastly Nomad forces a mandatory lease contract with clients. All secrets read
from Nomad have an associated lease which enables operators to audit key usage,
perform key rolling, and ensure automatic revocation. Nomad provides multiple
revocation mechanisms to give operators a clear "break glass" procedure after
a potential compromise.

24
website/source/intro/vs/kms.html.md
View file

@ -1,40 +1,40 @@
---
layout: "intro"
page_title: "Vault vs. Amazon Key Management Service"
page_title: "Nomad vs. Amazon Key Management Service"
sidebar_current: "vs-other-kms"
description: |-
Comparison between Vault and Amazon Key Management Service.
Comparison between Nomad and Amazon Key Management Service.
---
# Vault vs. Amazon KMS
# Nomad vs. Amazon KMS
Amazon Key Management Service (KMS) is a service provided in the AWS
ecosystem for encryption key management. It is backed by Hardware Security
Modules (HSM) for physical security.
Vault and KMS differ in the scope of problems they are trying to solve.
Nomad and KMS differ in the scope of problems they are trying to solve.
The KMS service is focused on securely storing encryption keys and supporting
cryptographic operations (encrypt and decrypt) using those keys. It supports
access controls and auditing as well.
In contrast, Vault provides a comprehensive secret management solution.
In contrast, Nomad provides a comprehensive secret management solution.
The [`transit` backend](/docs/secrets/transit/index.html)
provides similar capabilities as the KMS service, allowing for encryption keys
to be stored and cryptographic operations to be performed. However, Vault goes
to be stored and cryptographic operations to be performed. However, Nomad goes
much futher than just key management.
The flexible secret backends allow Vault to handle any type of secret data,
The flexible secret backends allow Nomad to handle any type of secret data,
including database credentials, API keys, PKI keys, and encryption keys.
Vault also supports dynamic secrets, generating credentials on-demand for
Nomad also supports dynamic secrets, generating credentials on-demand for
fine-grained security controls, auditing, and non-repudiation.
Lastly Vault forces a mandatory lease contract with clients. All secrets read
from Vault have an associated lease which enables operations to audit key usage,
perform key rolling, and ensure automatic revocation. Vault provides multiple
Lastly Nomad forces a mandatory lease contract with clients. All secrets read
from Nomad have an associated lease which enables operations to audit key usage,
perform key rolling, and ensure automatic revocation. Nomad provides multiple
revocation mechansims to give operators a clear "break glass" procedure after
a potential compromise.
Vault is an open source tool that can be deployed to any environment,
Nomad is an open source tool that can be deployed to any environment,
and does not require any special hardware. This makes it well suited for cloud
environments where HSMs are not available or are cost prohibitive.

2
website/source/layouts/_header.erb
View file

@ -22,7 +22,7 @@
<nav role="navigation">
<ul class="nav navbar-nav navbar-right">
<li class="first download"><a href="/downloads.html">Download</a></li>
<li class="github"><a href="https://github.com/hashicorp/vault">GitHub</a></li>
<li class="github"><a href="https://github.com/hashicorp/nomad">GitHub</a></li>
</ul>
</nav>
</div>

2
website/source/layouts/_meta.erb
View file

@ -7,7 +7,7 @@
<link rel="shortcut icon" href="<%= image_path('favicon.png') %>">
<title><%= [current_page.data.page_title, "Vault by HashiCorp"].compact.join(" - ") %></title>
<title><%= [current_page.data.page_title, "Nomad by HashiCorp"].compact.join(" - ") %></title>
<%= stylesheet_link_tag "application" %>

2
website/source/layouts/_sidebar.erb
View file

@ -21,6 +21,6 @@
<!-- Sidebar navigation 2-->
<ul class="buttons-nav">
<li class="first"><a class="v-btn gray sml" href="/downloads.html">Download</a></li>
<li class=""><a class="v-btn gray sml" href="https://github.com/hashicorp/vault">GitHub</a></li>
<li class=""><a class="v-btn gray sml" href="https://github.com/hashicorp/nomad">GitHub</a></li>
</ul>
</aside>

18
website/source/layouts/docs.erb
View file

@ -13,25 +13,17 @@
<a href="/docs/internals/architecture.html">Architecture</a>
</li>
<li<%= sidebar_current("docs-internals-ha") %>>
<a href="/docs/internals/high-availability.html">High Availability</a>
</li>
<li<%= sidebar_current("docs-internals-consensus") %>>
<a href="/docs/internals/consensus.html">Consensus Protocol</a>
</li>
<li<%= sidebar_current("docs-internals-security") %>>
<a href="/docs/internals/security.html">Security Model</a>
<li<%= sidebar_current("docs-internals-gossip") %>>
<a href="/docs/internals/gossip.html">Gossip Protocol</a>
</li>
<li<%= sidebar_current("docs-internals-telemetry") %>>
<a href="/docs/internals/telemetry.html">Telemetry</a>
</li>
<li<%= sidebar_current("docs-internals-token") %>>
<a href="/docs/internals/token.html">Token Authentication</a>
</li>
<li<%= sidebar_current("docs-internals-rotation") %>>
<a href="/docs/internals/rotation.html">Key Rotation</a>
</li>
</ul>
</li>

2
website/source/layouts/downloads.erb
View file

@ -3,7 +3,7 @@
<div class="docs-sidebar hidden-print affix-top" role="complementary">
<ul class="nav docs-sidenav">
<li<%= sidebar_current("downloads-vault") %>>
<a href="/downloads.html">Download Vault</a>
<a href="/downloads.html">Download Nomad</a>
</li>
<li>

8
website/source/layouts/intro.erb
View file

@ -3,7 +3,7 @@
<div class="docs-sidebar hidden-print affix-top" role="complementary">
<ul class="nav docs-sidenav">
<li<%= sidebar_current("what") %>>
<a href="/intro/index.html">What is Vault?</a>
<a href="/intro/index.html">What is Nomad?</a>
</li>
<li<%= sidebar_current("use-cases") %>>
@ -11,7 +11,7 @@
</li>
<li<%= sidebar_current("vs-other") %>>
<a href="/intro/vs/index.html">Vault vs. Other Software</a>
<a href="/intro/vs/index.html">Nomad vs. Other Software</a>
<ul class="nav">
<li<%= sidebar_current("vs-other-chef") %>>
<a href="/intro/vs/chef-puppet-etc.html">Chef, Puppet, etc.</a>
@ -47,7 +47,7 @@
<a href="/intro/getting-started/install.html">Getting Started</a>
<ul class="nav">
<li<%= sidebar_current("gettingstarted-install") %>>
<a href="/intro/getting-started/install.html">Install Vault</a>
<a href="/intro/getting-started/install.html">Install Nomad</a>
</li>
<li<%= sidebar_current("gettingstarted-devserver") %>>
@ -79,7 +79,7 @@
</li>
<li<%= sidebar_current("gettingstarted-deploy") %>>
<a href="/intro/getting-started/deploy.html">Deploy Vault</a>
<a href="/intro/getting-started/deploy.html">Deploy Nomad</a>
</li>
<li<%= sidebar_current("getting-started-apis") %>>

4
website/source/security.html.erb
View file

@ -2,7 +2,7 @@
layout: "inner"
page_title: "Security"
description: |-
Vault takes security very seriously. Please responsibly disclose any security vulnerabilities found and we'll handle it quickly.
Nomad takes security very seriously. Please responsibly disclose any security vulnerabilities found and we'll handle it quickly.
---
<h1>Security</h1>
@ -22,6 +22,6 @@ which has the proper email to communicate with as well as our PGP key.
</p>
<p>
If you aren't reporting a security sensitive vulnerability, please
open an issue on the standard <a href="https://github.com/hashicorp/vault">GitHub</a>
open an issue on the standard <a href="https://github.com/hashicorp/nomad">GitHub</a>
repository.
</p>