merging doc updates

This commit is contained in:
Armon Dadgar 2015-09-17 18:00:52 -07:00
commit 44a711502b
90 changed files with 997 additions and 1075 deletions

View file

@ -6,5 +6,5 @@ this should make it clear:
* The text contents of this website are MPL 2.0 licensed. * The text contents of this website are MPL 2.0 licensed.
* The design contents of this website are proprietary and may not be reproduced * 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. for the design is owned solely by HashiCorp, Inc.

View file

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

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

Binary file not shown.

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

Binary file not shown.

View file

@ -2,36 +2,36 @@
layout: "inner" layout: "inner"
page_title: "Community" page_title: "Community"
description: |- description: |-
Vault is an open source project with a growing community. Nomad is an open source project with a growing community.
--- ---
<h1>Community</h1> <h1>Community</h1>
<p> <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. active, dedicated users willing to help you through various mediums.
</p> </p>
<p> <p>
<strong>IRC:</strong> <code>#vault-tool</code> on Freenode <strong>IRC:</strong> <code>#nomad-tool</code> on Freenode
</p> </p>
<p> <p>
<strong>Mailing list:</strong> <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>
<p> <p>
<strong>Bug Tracker:</strong> <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 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. for general help here. Use IRC or the mailing list for that.
<h1>People</h1> <h1>People</h1>
<p> <p>
The following people are some of the faces behind Vault. They each The following people are some of the faces behind Nomad. They each
contribute to Vault in some core way. Over time, faces may appear and 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 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 <a href="https://www.hashicorp.com">HashiCorp</a>, so many HashiCorp
employees actively contribute to Vault. employees actively contribute to Nomad.
</p> </p>
<div class="people"> <div class="people">
<div class="person"> <div class="person">
@ -39,8 +39,8 @@ employees actively contribute to Vault.
<div class="bio"> <div class="bio">
<h3>Mitchell Hashimoto (<a href="https://github.com/mitchellh">@mitchellh</a>)</h3> <h3>Mitchell Hashimoto (<a href="https://github.com/mitchellh">@mitchellh</a>)</h3>
<p> <p>
Mitchell Hashimoto is the creator of Vault and works on all Mitchell Hashimoto is the creator of Nomad and works on all
layers of Vault from the core to backends. In addition to Vault, layers of Nomad from the core to backends. In addition to Nomad,
Mitchell is the creator of Mitchell is the creator of
<a href="https://www.vagrantup.com">Vagrant</a>, <a href="https://www.vagrantup.com">Vagrant</a>,
<a href="https://www.packer.io">Packer</a>, <a href="https://www.packer.io">Packer</a>,
@ -55,7 +55,7 @@ employees actively contribute to Vault.
<div class="bio"> <div class="bio">
<h3>Armon Dadgar (<a href="https://github.com/armon">@armon</a>)</h3> <h3>Armon Dadgar (<a href="https://github.com/armon">@armon</a>)</h3>
<p> <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 focusing on core architecture and security. Armon is also the creator of
<a href="https://www.consul.io">Consul</a>, <a href="https://www.consul.io">Consul</a>,
<a href="https://www.serfdom.io">Serf</a>, <a href="https://www.serfdom.io">Serf</a>,
@ -71,9 +71,9 @@ employees actively contribute to Vault.
<div class="bio"> <div class="bio">
<h3>Jack Pearkes (<a href="https://github.com/pearkes">@pearkes</a>)</h3> <h3>Jack Pearkes (<a href="https://github.com/pearkes">@pearkes</a>)</h3>
<p> <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 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>. behind <a href="https://atlas.hashicorp.com">Atlas</a>.
He is also a core committer to He is also a core committer to
<a href="https://www.packer.io">Packer</a>, <a href="https://www.packer.io">Packer</a>,

View file

@ -3,25 +3,25 @@ layout: "docs"
page_title: "Audit Backends" page_title: "Audit Backends"
sidebar_current: "docs-audit" sidebar_current: "docs-audit"
description: |- 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
Audit backends are the components in Vault that keep a detailed log Audit backends are the components in Nomad that keep a detailed log
of all requests and response to Vault. Because _every_ operation with of all requests and response to Nomad. Because _every_ operation with
Vault is an API request/response, the audit log contains _every_ interaction Nomad is an API request/response, the audit log contains _every_ interaction
with Vault, including errors. with Nomad, including errors.
Vault ships with multiple audit backends, depending on the location you want Nomad 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 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, 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. but also a second copy in case the first is tampered with.
## Sensitive Information ## Sensitive Information
The audit logs contain the full request and response objects for every 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 response (including secrets and authentication tokens) will be hashed
without a salt using SHA1. without a salt using SHA1.
@ -31,7 +31,7 @@ secrets by SHA-ing it yourself.
## Enabling/Disabling Audit Backends ## 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`. 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. 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 ## Blocked Audit Backends
If there are any audit backends enabled, Vault requires that at least If there are any audit backends enabled, Nomad requires that at least
one be able to persist the log before completing a Vault request. 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 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. 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. 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 audit logs are critically important and ignoring blocked requests opens
an avenue for attack. Be absolutely certain that your audit backends cannot an avenue for attack. Be absolutely certain that your audit backends cannot
block. block.

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 It currently does not support a configurable syslog destination, and
always sends to the local agent. This backend is only supported on Unix systems, 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 ## Options

View file

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

View file

@ -3,7 +3,7 @@ layout: "docs"
page_title: "Auth Backend: TLS Certificates" page_title: "Auth Backend: TLS Certificates"
sidebar_current: "docs-auth-cert" sidebar_current: "docs-auth-cert"
description: |- 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 # Auth Backend: TLS Certificates

View file

@ -3,17 +3,17 @@ layout: "docs"
page_title: "Auth Backend: GitHub" page_title: "Auth Backend: GitHub"
sidebar_current: "docs-auth-github" sidebar_current: "docs-auth-github"
description: |- description: |-
The GitHub auth backend allows authentication with Vault using GitHub. The GitHub auth backend allows authentication with Nomad using GitHub.
--- ---
# Auth Backend: GitHub # Auth Backend: GitHub
Name: `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. a GitHub personal access token.
This method of authentication is most useful for humans: operators or 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 ## Authentication
@ -63,7 +63,7 @@ Success! Data written to: auth/github/config
``` ```
After configuring that, you must map the teams of that organization to 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: Example:
``` ```
@ -71,7 +71,7 @@ $ vault write auth/github/map/teams/owners value=root
Success! Data written to: auth/github/map/teams/owners 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). (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. 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.

View file

@ -3,17 +3,17 @@ layout: "docs"
page_title: "Auth Backends" page_title: "Auth Backends"
sidebar_current: "docs-auth" sidebar_current: "docs-auth"
description: |- 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
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 and are responsible for assigning identity and a set of policies to a
user. user.
Having multiple auth backends enables you to use an auth backend 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) 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) 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. 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): 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 and configured using the standard read/write API. The only difference
is that all auth backends are mounted underneath the `auth/` prefix. is that all auth backends are mounted underneath the `auth/` prefix.

View file

@ -3,7 +3,7 @@ layout: "docs"
page_title: "Auth Backend: LDAP" page_title: "Auth Backend: LDAP"
sidebar_current: "docs-auth-ldap" sidebar_current: "docs-auth-ldap"
description: |- 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 # Auth Backend: LDAP
@ -11,11 +11,11 @@ description: |-
Name: `ldap` Name: `ldap`
The "ldap" auth backend allows authentication using an existing 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 into environments using LDAP without duplicating the user/pass configuration
in multiple places. 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. `users/` and `groups/` paths.
## Authentication ## 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 The above configures the target LDAP server, along with the parameters
specifying how users and groups should be queried from the LDAP server. 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 $ 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: 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 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: Finally, we can test this by authenticating:

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 authenticate using a token, as well to create new tokens, revoke
secrets by token, and more. 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. token backend to create a new unique token for that identity.
The token store can also be used to bypass any other auth backend: The token store can also be used to bypass any other auth backend:

View file

@ -3,14 +3,14 @@ layout: "docs"
page_title: "Auth Backend: Username & Password" page_title: "Auth Backend: Username & Password"
sidebar_current: "docs-auth-userpass" sidebar_current: "docs-auth-userpass"
description: |- 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 # Auth Backend: Username & Password
Name: `userpass` 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. a username and password combination.
The username/password combinations are configured directly to the auth The username/password combinations are configured directly to the auth

View file

@ -3,23 +3,23 @@ layout: "docs"
page_title: "Authentication" page_title: "Authentication"
sidebar_current: "docs-concepts-auth" sidebar_current: "docs-concepts-auth"
description: |- 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 # 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 _authenticated_. Authentication is the process of verifying a person or
machine is who they say they are and assigning an identity to them. This 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 Authentication in Nomad is pluggable via authentication backends. This
allows you to authenticate with Vault using a method that works best for your allows you to authenticate with Nomad using a method that works best for your
organization. For example, you can authenticate using GitHub, certs, etc. organization. For example, you can authenticate using GitHub, certs, etc.
## Authentication Backends ## 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 are enabled using `vault auth-enable`. After they're enabled, you can
learn more about them using `vault path-help auth/<name>`. For example, 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 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. your identity and then generating a token to associate with that identity.
For example, even though you may authenticate using something like GitHub, 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 CLI automatically attaches this token to requests, but if you're using
the API you'll have to do this manually. the API you'll have to do this manually.
@ -88,7 +88,7 @@ be used.
Just like secrets, identities have Just like secrets, identities have
[leases](/docs/concepts/lease.html) associated with them. This means that [leases](/docs/concepts/lease.html) associated with them. This means that
you must reauthenticate after the given lease period to continue accessing 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 To set the lease associated with an identity, reference the help for
the specific authentication backend in use. It is specific to each backend the specific authentication backend in use. It is specific to each backend

View file

@ -3,15 +3,15 @@ layout: "docs"
page_title: "Dev Server Mode" page_title: "Dev Server Mode"
sidebar_current: "docs-concepts-devserver" sidebar_current: "docs-concepts-devserver"
description: |- 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 # "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 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 be authenticated to talk to it. This makes it easy to experiment with Nomad or
start a Vault instance for development. Every feature of Vault is available in 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 "dev" mode. The `-dev` flag just short-circuits a lot of setup to insecure
defaults. 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 and unsealed. You don't need to use `vault unseal`. It is ready for use
immediately. 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. server doesn't require any file permissions.
* **Bound to local address without TLS** - The server is listening on * **Bound to local address without TLS** - The server is listening on
`127.0.0.1:8200` (the default server address) _without_ TLS. `127.0.0.1:8200` (the default server address) _without_ TLS.
* **Automatically Authenticated** - The server stores your root access * **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. via the API, you'll need to authenticate using the token printed out.
* **Single unseal key** - The server is initialized with a single unseal * **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. seal/unseal, then only the single outputted key is required.
## Use Case ## 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. 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 Secret](http://vaultproject.io/intro/getting-started/first-secret.html) in
our getting started guide. our getting started guide.

View file

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

View file

@ -3,14 +3,14 @@ layout: "docs"
page_title: "Basic Concepts" page_title: "Basic Concepts"
sidebar_current: "docs-concepts" sidebar_current: "docs-concepts"
description: |- description: |-
Basic concepts that are important to understand for Vault usage. Basic concepts that are important to understand for Nomad usage.
--- ---
# Basic Concepts # Basic Concepts
This section covers some high level basic concepts that are important 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 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. Please use the navigation to the left to learn more about a topic.

View file

@ -3,22 +3,22 @@ layout: "docs"
page_title: "Lease, Renew, and Revoke" page_title: "Lease, Renew, and Revoke"
sidebar_current: "docs-concepts-lease" sidebar_current: "docs-concepts-lease"
description: |- 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 # Lease, Renew, and Revoke
With every secret and authentication token, Vault provides a _lease_: With every secret and authentication token, Nomad provides a _lease_:
an amount of time that Vault promises that the data will be valid for. an amount of time that Nomad promises that the data will be valid for.
Once the lease is up, Vault can automatically revoke the data, and the 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. 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 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 Nomad routinely to either renew the lease (if allowed) or request a
replacement secret. This makes the Vault audit logs more valuable and replacement secret. This makes the Nomad audit logs more valuable and
also makes key rolling a lot easier. 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 meant to be valid for eternity, a lease is required to force the consumer
to check in routinely. 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. keys invalid from that point forward.
Revocation can happen manually via the API or `vault revoke`, or automatically 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.
## Lease IDs ## 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 a `lease_id`. This is the ID used with commands such as `vault renew` and
`vault revoke` to manage the lease of the secret. `vault revoke` to manage the lease of the secret.

View file

@ -3,18 +3,18 @@ layout: "docs"
page_title: "Policies" page_title: "Policies"
sidebar_current: "docs-concepts-policies" sidebar_current: "docs-concepts-policies"
description: |- 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 # 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 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_. of _policies_.
Policies are [HCL](https://github.com/hashicorp/hcl) or JSON documents 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: of a policy is shown below:
```javascript ```javascript
@ -37,8 +37,8 @@ path "secret/super-secret" {
Policies use path based matching to apply rules. A policy may be an exact 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 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. is always deny so if a path isn't explicitly allowed, Nomad will reject access to it.
This works well due to Vault's architecture of being like a filesystem: This works well due to Nomad's architecture of being like a filesystem:
everything has a path associated with it, including the core configuration everything has a path associated with it, including the core configuration
mechanism under "sys". mechanism under "sys".
@ -59,7 +59,7 @@ Allowed policies for a path are:
* `read` - Read-only access to a path. * `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 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 paths unless they are a root user (have the special policy "root") or
have access to that path with the "sudo" policy. 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. 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 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 There always exists at least one root user (associated with the token
when initializing a new server). After this root user, it is recommended when initializing a new server). After this root user, it is recommended
@ -104,7 +104,7 @@ active identity.
## Changes from 0.1 ## 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 different specification and semantics. The current specification requires
that glob behavior explicitly be specified by adding the `*` character to 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 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 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. 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. glob character must be added to all the path prefixes.

View file

@ -3,36 +3,36 @@ layout: "docs"
page_title: "Seal/Unseal" page_title: "Seal/Unseal"
sidebar_current: "docs-concepts-seal" sidebar_current: "docs-concepts-seal"
description: |- 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 # Seal/Unseal
When a Vault server is started, it starts in a _sealed_ state. In this When a Nomad server is started, it starts in a _sealed_ state. In this
state, Vault is configured to know where and how to access the physical state, Nomad is configured to know where and how to access the physical
storage, but doesn't know how to decrypt any of it. storage, but doesn't know how to decrypt any of it.
_Unsealing_ is the process of constructing the master key necessary to _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. 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. of the unseal.
## Why? ## 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 _encryption key_ in order to decrypt the data. The encryption key is
also stored with the data, but encrypted with another encryption key also stored with the data, but encrypted with another encryption key
known as the _master key_. The master key isn't stored anywhere. 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 which requires the master key. Unsealing is the process of reconstructing
this master key. this master key.
Instead of distributing this master key as a single key to an operator, 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) [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 to split the key into shards. A certain threshold of shards is required to
reconstruct the master key. 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 on multiple computers and it will work. This allows each shard of the master
key to be on a distinct machine for better security. 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). 1. It is resealed via the API (see below).
2. The server is restarted. 2. The server is restarted.
-> **Note:** Unsealing makes the process of automating a Vault install -> **Note:** Unsealing makes the process of automating a Nomad install
difficult. Automated tools can easily install, configure, and start Vault, 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 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 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 multiple Nomad 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. as Consul to make sure you only query Nomad servers that are unsealed.
## Sealing ## 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 key and require another unseal process to restore it. Sealing only requires
a single operator with root privileges. 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 quickly to try to minimize damages. It can't be accessed again without
access to the master key shards. access to the master key shards.

View file

@ -3,18 +3,18 @@ layout: "docs"
page_title: "Tokens" page_title: "Tokens"
sidebar_current: "docs-concepts-tokens" sidebar_current: "docs-concepts-tokens"
description: |- 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
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 directly or [authentication backends](/docs/concepts/auth.html)
can be used to dynamically generate tokens based on external identities. can be used to dynamically generate tokens based on external identities.
If you've gone through the getting started guide, you probably noticed that 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 `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. It is also the only authentication backend that cannot be disabled.
As stated in the [authentication concepts](/docs/concepts/auth.html), 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 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 same way as [leases for secrets](/docs/concepts/lease.html). After
the lease period is up, the token will no longer function. In addition 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` In order to avoid your token being revoked, the `vault token-renew`
command should be used to renew the lease on the token periodically. command should be used to renew the lease on the token periodically.

View file

@ -3,12 +3,12 @@ layout: "docs"
page_title: "Server Configuration" page_title: "Server Configuration"
sidebar_current: "docs-config" sidebar_current: "docs-config"
description: |- description: |-
Vault server configuration reference. Nomad server configuration reference.
--- ---
# Server Configuration # 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. The format of this file is [HCL](https://github.com/hashicorp/hcl) or JSON.
An example configuration is shown below: An example configuration is shown below:
@ -34,11 +34,11 @@ to specify where the configuration is.
## Reference ## 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, is stored. There are multiple options available for storage backends,
and they're documented below. 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 "tcp" is currently the only option available. A full reference for the
inner syntax is below. 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 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. 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 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 ```shell
sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault)) 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 ## Backend Reference
For the `backend` section, the supported backends are shown below. 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. durability, etc.
* `consul` - Store data within [Consul](http://www.consul.io). This * `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. and has been shown to work at high scale under heavy load.
* `etcd` - Store data within [etcd](https://coreos.com/etcd/). * `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. * `mysql` - Store data within MySQL. This backend does not support HA.
* `inmem` - Store data in-memory. This is only really useful for * `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. restarted.
* `file` - Store data on the filesystem using a directory structure. * `file` - Store data on the filesystem using a directory structure.
@ -100,7 +100,7 @@ durability, etc.
All backends support the following options: All backends support the following options:
* `advertise_addr` (optional) - For backends that support HA, this * `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 for request forwarding. Most HA backends will attempt to determine
the advertise address if not provided. the advertise address if not provided.
@ -213,7 +213,7 @@ The supported options are:
defaults to "127.0.0.1:8200". defaults to "127.0.0.1:8200".
* `tls_disable` (optional) - If non-empty, then TLS will be disabled. * `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 * `tls_cert_file` (required unless disabled) - The path to the certificate
for TLS. for TLS.
@ -221,7 +221,7 @@ The supported options are:
* `tls_key_file` (required unless disabled) - The path to the private key * `tls_key_file` (required unless disabled) - The path to the private key
for the certificate. 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" the minimum supported version of TLS. Accepted values are "tls10", "tls11"
or "tls12". This defaults to "tls12". WARNING: TLS 1.1 and lower or "tls12". This defaults to "tls12". WARNING: TLS 1.1 and lower
are generally considered less secure; avoid using these if are generally considered less secure; avoid using these if

View file

@ -3,14 +3,14 @@ layout: "http"
page_title: "HTTP API" page_title: "HTTP API"
sidebar_current: "docs-http-overview" sidebar_current: "docs-http-overview"
description: |- 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 # HTTP API
The Vault HTTP API gives you full access to Vault via HTTP. Every The Nomad HTTP API gives you full access to Nomad via HTTP. Every
aspect of Vault can be controlled via this API. The Vault CLI uses aspect of Nomad can be controlled via this API. The Nomad CLI uses
the HTTP API to access Vault. the HTTP API to access Nomad.
## Version Prefix ## Version Prefix
@ -18,10 +18,10 @@ All API routes are prefixed with `/v1/`.
This documentation is only for the v1 API. 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 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 remove this warning when this policy changes. We expect we'll reach API
stability by Vault 0.3. stability by Nomad 0.3.
## Transport ## Transport
@ -33,10 +33,10 @@ depending on user settings.
## Authentication ## 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. a _client token_. A user may have a client token explicitly.
The client token must be sent as the `token` cookie or the 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 Otherwise, a client token can be retrieved via
[authentication backends](/docs/auth/index.html). [authentication backends](/docs/auth/index.html).
@ -49,7 +49,7 @@ to each authentication backend.
Login endpoints for authentication backends that generate an identity 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 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 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 ## Reading and Writing Secrets
@ -66,7 +66,7 @@ Here is an example of reading a secret using cURL:
```shell ```shell
curl \ curl \
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ -H "X-Nomad-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-X GET \ -X GET \
http://127.0.0.1:8200/v1/secret/foo http://127.0.0.1:8200/v1/secret/foo
``` ```
@ -89,18 +89,18 @@ Here is an example of writing a secret using cURL:
```shell ```shell
curl \ curl \
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ -H "X-Nomad-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-X POST \ -X POST \
-d '{"value":"bar"}' \ -d '{"value":"bar"}' \
http://127.0.0.1:8200/v1/secret/baz 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 ## 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 backends, credential providers, etc. then append `?help=1` to any
URL. If you have valid permission to access the path, then the help text URL. If you have valid permission to access the path, then the help text
will be returned with the following structure: will be returned with the following structure:
@ -144,5 +144,5 @@ The following HTTP status codes are used throughout the API.
of time. of time.
- `500` - Internal server error. An internal error has occurred, - `500` - Internal server error. An internal error has occurred,
try again later. If the error persists, report a bug. 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. Try again later.

View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: Libraries" page_title: "HTTP API: Libraries"
sidebar_current: "docs-http-libraries" sidebar_current: "docs-http-libraries"
description: |- 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 # Libraries
@ -13,11 +13,11 @@ Some are officially maintained while others are provided by the community.
## Go ## 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 ## Ruby
* [Vault Ruby Client](https://github.com/hashicorp/vault-ruby) (official) * [Nomad Ruby Client](https://github.com/hashicorp/vault-ruby) (official)
## Python ## Python

View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/auth" page_title: "HTTP API: /sys/auth"
sidebar_current: "docs-http-auth-auth" sidebar_current: "docs-http-auth-auth"
description: |- 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 # /sys/auth

View file

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

View file

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

View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/key-status" page_title: "HTTP API: /sys/key-status"
sidebar_current: "docs-http-rotate-key-status" sidebar_current: "docs-http-rotate-key-status"
description: |- 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 # /sys/key-status
@ -11,7 +11,7 @@ description: |-
<dl> <dl>
<dt>Description</dt> <dt>Description</dt>
<dd> <dd>
Returns information about the current encryption key used by Vault. Returns information about the current encryption key used by Nomad.
</dd> </dd>
<dt>Method</dt> <dt>Method</dt>

View file

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

View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/mounts" page_title: "HTTP API: /sys/mounts"
sidebar_current: "docs-http-mounts-mounts" sidebar_current: "docs-http-mounts-mounts"
description: |- 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 # /sys/mounts

View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/policy" page_title: "HTTP API: /sys/policy"
sidebar_current: "docs-http-auth-policy" sidebar_current: "docs-http-auth-policy"
description: |- 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 # /sys/policy

View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/raw" page_title: "HTTP API: /sys/raw"
sidebar_current: "docs-http-debug-raw" sidebar_current: "docs-http-debug-raw"
description: |- 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 # /sys/raw

View file

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

View file

@ -3,7 +3,7 @@ layout: "http"
page_title: "HTTP API: /sys/seal-status" page_title: "HTTP API: /sys/seal-status"
sidebar_current: "docs-http-seal-status" sidebar_current: "docs-http-seal-status"
description: |- 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 # /sys/seal-status
@ -11,7 +11,7 @@ description: |-
<dl> <dl>
<dt>Description</dt> <dt>Description</dt>
<dd> <dd>
Returns the seal status of the Vault. Returns the seal status of the Nomad.
</dd> </dd>
<dt>Method</dt> <dt>Method</dt>

View file

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

View file

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

View file

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

View file

@ -1,24 +1,24 @@
--- ---
layout: "docs" layout: "docs"
page_title: "Install Vault" page_title: "Install Nomad"
sidebar_current: "docs-install" sidebar_current: "docs-install"
description: |- 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 for your system, or installing from source.
Downloading a precompiled binary is easiest, and we provide downloads over 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 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. 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 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. 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 from source, from the same versions of all dependent libraries that
we used for the official builds. we used for the official builds.
@ -26,13 +26,13 @@ we used for the official builds.
To install the precompiled binary, To install the precompiled binary,
[download](/downloads.html) the appropriate package for your system. [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. plans to provide system packages.
Once the zip is downloaded, unzip it into any directory. The 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 `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 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`. 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 To compile from source, you'll need [Go](https://golang.org) installed
and configured properly. You'll also need Git. 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` 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. 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). 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 above will use these vendored binaries. This is to avoid malicious
upstream dependencies if possible. upstream dependencies if possible.
## Verifying the Installation ## 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 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 the command line, make sure it is on your PATH or you may get an error
about `vault` not being found. about `vault` not being found.

View file

@ -3,155 +3,130 @@ layout: "docs"
page_title: "Architecture" page_title: "Architecture"
sidebar_current: "docs-internals-architecture" sidebar_current: "docs-internals-architecture"
description: |- description: |-
Learn about the internal architecture of Vault. Learn about the internal architecture of Nomad.
--- ---
# Architecture # 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. build a mental model of how it works, this page documents the system architecture.
~> **Advanced Topic!** This page covers technical details ~> **Advanced Topic!** This page covers technical details
of Vault. You don't need to understand these details to of Nomad. You don't need to understand these details to
effectively use Vault. The details are documented here for effectively use Nomad. The details are documented here for
those who wish to learn about them without having to go those who wish to learn about them without having to go
spelunking through the source code. However, if you're an spelunking through the source code.
operator of Vault, we recommend learning about the architecture
due to the importance of Vault in an environment.
# Glossary # Glossary
Before describing the architecture, we provide a glossary of terms to help Before describing the architecture, we provide a glossary of terms to help
clarify what is being discussed: clarify what is being discussed:
* **Storage Backend** - A storage backend is responsible for durable storage of _encrypted_ data. * **Job** - A Job is a specification provided by users that declares a workload for
Backends are not trusted by Vault and are only expected to provide durability. The storage Nomad. A Job is a form of _desired state_, the user is expressing that the job should
backend is configured when starting the Vault server. 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 * **Task Group** - A Task Group is a set of tasks that must be run together. For example, a
flows between Vault and the Storage Backend passes through the barrier. The barrier ensures web server may require that a log shipping co-process is always running as well. A task
that only encrypted data is written out, and that data is verified and decrypted on the way group is the unit of scheduling, meaning the entire group must run on a client node and
in. Much like a bank vault, the barrier must be "unsealed" before anything inside can be accessed. cannot be split.
* **Secret Backend** - A secret backend is responsible for managing secrets. Simple secret backends * **Task** - A Task is the smallest unit of work in Nomad. Tasks are executed by drivers,
like the "generic" backend simply return the same secret when queried. Some backends support which allow Nomad to be flexible in the types of tasks it supports. Examples include Docker,
using policies to dynamically generate a secret each time they are queried. This allows for Qemu, Java and static binaries. Tasks specify their driver, configuration for the driver,
unique secrets to be used which allows Vault to do fine-grained revocation and policy updates. constraints, and resources required.
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.
* **Audit Backend** - An audit backend is responsible for managing audit logs. Every request to Vault * **Client** - A Client of Nomad is a machine that tasks can be run on. All clients run the
and response from Vault goes through the configured audit backends. This provides a simple Nomad agent. The agent is responsible for registering with the servers, watching for any
way to integrate Vault with multiple audit logging destinations of different types. 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 * **Server** - Nomad servers are the brains of the cluster. There is a cluster of servers
are connecting to Vault. Once authenticated, the backend returns the list of applicable policies per region and they manage all jobs and clients, run evalutations and create task allocations.
which should be applied. Vault takes an authenticated user and returns a client token that can The servers replicate data between each other and perform leader election to ensure high
be used for future requests. As an example, the `user-password` backend uses a username and password availability. Servers federate across regions to make Nomad globally aware.
to authenticate the user. Alternatively, the `github` backend allows users to authenticate
via GitHub.
* **Client Token** - A client token is a conceptually similar to a session cookie on a web site. * **Regions and Datacenters** - Nomad models infrastructure as regions and datacenters.
Once a user authenticates, Vault returns a client token which is used for future requests. Regions may contain multiple datacenters. Servers are assigned to regions and manage
The token is used by Vault to verify the identity of the client and to enforce the applicable all state for the region and make scheduling decisions within that region. Requests that
ACL policies. 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 * **Evaluation** - Evaluations are the mechanism by which Nomad makes scheduling decisions.
or cryptographic material. Not everything returned by Vault is a secret, for example When either the _desired state_ (jobs) or _actual state_ (clients) changes, Nomad creates
system configuration, status information, or backend policies are not considered Secrets. a new evaluation to determine if any actions must be taken. An evaluation may result
Secrets always have an associated lease. This means clients cannot assume that the secret in changes to allocations if necessary.
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.
* **Server** - Vault depends on a long-running instance which operates as a server. * **Allocation** - An Allocation is a mapping between a task group in a job, and a client
The Vault server provides an API which clients interact with and manages the node. A single job may have hundreds or thousands of task groups, meaning an equivalent
interaction between all the backends, ACL enforcement, and secret lease revocation. number of allocations must exist to map the work to client machines. Allocations are created
Having a server based architecture decouples clients from the security keys and policies, by the Nomad servers as part of scheduling decisions made during an evaluation.
enables centralized audit logging and simplifies administration for operators.
* **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 # 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 Within each region, we have both clients and servers. Servers are responsible for
that are inside or outside of the security barrier. Only the storage backend and accepting jobs from users, managing clients, and computing task placements. Each
the HTTP API are outside, all other components are inside the barrier. 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 In some cases, for either availability or scalability, you may need to run multiple
the Vault server is started, it must be provided with a storage backend so that data regions. Nomad supports federating multiple regions together into a single cluster.
is available across restarts. The HTTP API similarly must be started by the Vault server At a high level, this looks like:
on start so that clients can interact with it.
Once started, the Vault is in a _sealed_ state. Before any operation can be performed ![Global Architecture](/assets/images/global-arch.png)
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.
![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 The servers in each datacenter are all part of a single consensus group. This means
technique can be disabled, and the master key used directly for unsealing. Once Vault that they work together to elect a single leader which has extra duties. The leader
retrieves the encryption key, it is able to decrypt the data in the storage backend, is responsible for processing all queries and transactions. Nomad is an optimistically
and enters the _unsealed_ state. Once unsealed, Vault loads all of the configured concurrent, meaning all servers participate in making scheduling decisions in parallel.
audit, credential and secret backends. 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 Each region is expected to have either three or five servers. This strikes a balance
sensitive. Only users with the correct permissions should be able to modify them, between availability in the case of failure and performance, as consensus gets
meaning they cannot be specified outside of the barrier. By storing them in Vault, progressively slower as more servers are added. However, there is no limit to the number
any changes to them are protected by the ACL system and tracked by audit logs. of clients per region.
After the Vault is unsealed, requests can be processed from the HTTP API to the Core. Clients are configured to communicate with their regional servers and communicate
The core is used to manage the flow of requests through the system, enforce ACLs, using remote procedure calls (RPC) to register themselves, heartbeat for liveness,
and ensure audit logging is done. 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 Users make use of the Nomad CLI or API to submit jobs to the servers. A job represents
configurable credential backends providing flexibility in the authentication mechanism a desired state, providing the set of tasks that should be run. The servers are
used. Human friendly mechanisms such as username/password or GitHub might be responsible for scheduling the tasks, which is done by finding an optimial placement for
used for operators, while applications may use public/private keys or tokens to authenticate. each task such that resource utilization is maximized while satisfying all constraints
An authentication request flows through core and into a credential backend, which determines specified by the job. Resource utilization is maximized by bin packing, in which
if the request is valid and returns a list of associated policies. 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
Policies are just a named ACL rule. For example, the "root" policy is builtin and running in an appropriate environment. Constraints can be technical requirements based
permits access to all resources. You can create any number of named policies with on hardware features such as architecture, availability of GPUs, or software features
fine-grained control over paths. Vault operates exclusively in a blacklist mode, meaning like operating system and kernel version, or they can be business constraints like
unless access is explicitly granted via a policy the action is not allowed. ensuring PCI compliant workloads run on appropriate servers.
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.
# Getting in Depth # Getting in Depth
This has been a brief high-level overview of the architecture of Vault. There This has been a brief high-level overview of the architecture of Nomad. There
are more details available for each of the sub-systems. 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. For other details, either consult the code, ask in IRC or reach out to the mailing list.

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>

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.

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.

View file

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

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.

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.

View file

@ -3,21 +3,21 @@ layout: "docs"
page_title: "Telemetry" page_title: "Telemetry"
sidebar_current: "docs-internals-telemetry" sidebar_current: "docs-internals-telemetry"
description: |- description: |-
Learn about the telemetry data available in Vault. Learn about the telemetry data available in Nomad.
--- ---
# Telemetry # 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 different libraries and subsystems. These metrics are aggregated on a ten
second interval and are retained for one minute. second interval and are retained for one minute.
To view this data, you must send a signal to the Vault process: on Unix, 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 Vault receives the signal, 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`. it will dump the current telemetry information to the agent's `stderr`.
This telemetry information can be used for debugging or otherwise 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) Telemetry information can be streamed to both [statsite](http://github.com/armon/statsite)
as well as statsd based on providing the appropriate configuration options. 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: Below is sample output of a telemetry dump:
```text ```text
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.num_goroutines': 12.000 [2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.broker.total_blocked': 0.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.free_count': 11882.000 [2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.plan.queue_depth': 0.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.total_gc_runs': 9.000 [2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.malloc_count': 7568.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.expire.num_leases': 1.000 [2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.total_gc_runs': 8.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.alloc_bytes': 502992.000 [2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.broker.total_ready': 0.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.sys_bytes': 3999992.000 [2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.num_goroutines': 56.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.malloc_count': 17315.000 [2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.sys_bytes': 3999992.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.heap_objects': 5433.000 [2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.heap_objects': 4135.000
[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.total_gc_pause_ns': 3794124.000 [2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.heartbeat.active': 1.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-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.broker.total_unacked': 0.000
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.route.read.secret-': Count: 1 Sum: 0.036 [2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.broker.total_waiting': 0.000
[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-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.alloc_bytes': 634056.000
[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-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.free_count': 3433.000
[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-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.total_gc_pause_ns': 6572135.000
[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-09-17 16:59:40 -0700 PDT][C] 'nomad.memberlist.msg.alive': Count: 1 Sum: 1.000
[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-09-17 16:59:40 -0700 PDT][C] 'nomad.serf.member.join': Count: 1 Sum: 1.000
[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-09-17 16:59:40 -0700 PDT][C] 'nomad.raft.barrier': Count: 1 Sum: 1.000
[2015-04-20 12:24:30 -0700 PDT][S] 'vault.route.write.secret-': Count: 1 Sum: 0.035 [2015-09-17 16:59:40 -0700 PDT][C] 'nomad.raft.apply': Count: 1 Sum: 1.000
[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-09-17 16:59:40 -0700 PDT][C] 'nomad.nomad.rpc.query': Count: 2 Sum: 2.000
[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][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
``` ```

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.

View file

@ -3,16 +3,16 @@ layout: "docs"
page_title: "Secret Backend: AWS" page_title: "Secret Backend: AWS"
sidebar_current: "docs-secrets-aws" sidebar_current: "docs-secrets-aws"
description: |- 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 # AWS Secret Backend
Name: `aws` 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 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. lease is expired.
This page will show a quick start for this backend. For detailed documentation 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 to restrict permissions for it. This is used to dynamically create
a new pair of IAM credentials when needed. 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: is an example IAM policy to get started:
```javascript ```javascript

View file

@ -3,17 +3,17 @@ layout: "docs"
page_title: "Secret Backend: Cassandra" page_title: "Secret Backend: Cassandra"
sidebar_current: "docs-secrets-cassandra" sidebar_current: "docs-secrets-cassandra"
description: |- 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 # Cassandra Secret Backend
Name: `cassandra` 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 dynamically based on configured roles. This means that services that need
to access a database no longer need to hardcode credentials: they can request 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 Additionally, it introduces a new ability: with every service accessing
the database with unique credentials, it makes auditing much easier when the database with unique credentials, it makes auditing much easier when
@ -33,7 +33,7 @@ $ vault mount cassandra
Successfully mounted 'cassandra' at '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: writing one or more hosts, a username, and a password:
```text ```text
@ -41,8 +41,8 @@ $ vault write cassandra/config/connection \
hosts=localhost username=cassandra password=cassandra hosts=localhost username=cassandra password=cassandra
``` ```
In this case, we've configured Vault with the user "cassandra" and password "cassandra", In this case, we've configured Nomad with the user "cassandra" and password "cassandra",
It is important that the Vault user is a superuser, in order to manage other user accounts. 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 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 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. 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 This role will be created by evaluating the given `creation_cql` statements. By
default, the `{{username}}` and `{{password}}` fields will be populated 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 the named user, and then granting it `SELECT` or read-only privileges
to keyspaces. More complex `GRANT` queries can be used to 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) 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. for more information.
To generate a new set of credentials, we simply read from that role: 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 ```text
$ vault read cassandra/creds/readonly $ vault read cassandra/creds/readonly
@ -77,7 +77,7 @@ password dfa80eea-ccbe-b228-ebf7-e2f62b245e71
username vault-root-1434647667-9313 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 set of credentials using the `readonly` role configuration. Here we
see the dynamically generated username and password, along with a one see the dynamically generated username and password, along with a one
hour lease. hour lease.

View file

@ -3,14 +3,14 @@ layout: "docs"
page_title: "Secret Backend: Consul" page_title: "Secret Backend: Consul"
sidebar_current: "docs-secrets-consul" sidebar_current: "docs-secrets-consul"
description: |- 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 # Consul Secret Backend
Name: `consul` Name: `consul`
The Consul secret backend for Vault generates The Consul secret backend for Nomad generates
[Consul](http://consul.io) [Consul](http://consul.io)
API tokens dynamically based on Consul ACL policies. API tokens dynamically based on Consul ACL policies.
@ -27,7 +27,7 @@ $ vault mount consul
Successfully mounted 'consul' at '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: 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 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 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. 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 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 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: We can test this token out, and verify that it is read-only:
``` ```

View file

@ -3,13 +3,13 @@ layout: "docs"
page_title: "Secret Backend: Custom" page_title: "Secret Backend: Custom"
sidebar_current: "docs-secrets-custom" sidebar_current: "docs-secrets-custom"
description: |- description: |-
Create custom secret backends for Vault. Create custom secret backends for Nomad.
--- ---
# Custom Secret Backends # Custom Secret Backends
Vault doesn't currently support the creation of custom secret backends. Nomad doesn't currently support the creation of custom secret backends.
The primary reason is because we want to ensure the core of Vault is 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 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 in supporting custom secret backends, but don't yet have a clear strategy
or timeline to do. or timeline to do.

View file

@ -11,9 +11,9 @@ description: |-
Name: `generic` Name: `generic`
The generic secret backend is used to store arbitrary secrets within 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 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, Writing to a key in the `secret/` backend will replace the old value,
the sub-fields are not merged together. the sub-fields are not merged together.

View file

@ -3,12 +3,12 @@ layout: "docs"
page_title: "Secret Backends" page_title: "Secret Backends"
sidebar_current: "docs-secrets" sidebar_current: "docs-secrets"
description: |- 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
Secret backends are the components in Vault which store and generate Secret backends are the components in Nomad which store and generate
secrets. secrets.
Some secret backends, such as "generic", simply store and read 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 Secret backends are part of the
[mount system](#) [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 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. backend can choose to react to that operation however it sees fit.
For example, the "generic" backend passes through any operation back 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 "read" of the storage backend at the same path, a "write" turns into
a write, etc. This is a lot like a normal filesystem. 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 ## Barrier View
An important concept around secret backends is that they receive a 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). like a [chroot](http://en.wikipedia.org/wiki/Chroot).
Whenever a secret backend is mounted, a random UUID is generated. This Whenever a secret backend is mounted, a random UUID is generated. This
becomes the data root for that backend. Whenever that backend writes to 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 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 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. can't access the data from any other backend.

View file

@ -2,7 +2,7 @@
Name: `jwt` 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. 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 ```text
$ vault write jwt/issue/webauth \ $ vault write jwt/issue/webauth \
issuer="Vault" \ issuer="Nomad" \
audience="Vault Client" \ audience="Nomad Client" \
expiration="1538096292" \ expiration="1538096292" \
claims=@extra.json claims=@extra.json
``` ```

View file

@ -3,24 +3,24 @@ layout: "docs"
page_title: "Secret Backend: MySQL" page_title: "Secret Backend: MySQL"
sidebar_current: "docs-secrets-mysql" sidebar_current: "docs-secrets-mysql"
description: |- 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 # MySQL Secret Backend
Name: `mysql` 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 dynamically based on configured roles. This means that services that need
to access a database no longer need to hardcode credentials: they can request 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 Additionally, it introduces a new ability: with every service accessing
the database with unique credentials, it makes auditing much easier when the database with unique credentials, it makes auditing much easier when
questionable data access is discovered: you can track it down to the specific questionable data access is discovered: you can track it down to the specific
instance of a service based on the SQL username. 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. become invalid within a reasonable time of the lease expiring.
This page will show a quick start for this backend. For detailed documentation 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'! 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): 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 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 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. other users, namely the `GRANT OPTION` privilege.
Optionally, we can configure the lease settings for credentials generated 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 $ 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. 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 This role will be created by evaluating the given `sql` statements. By
default, the `{{name}}` and `{{password}}` fields will be populated 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 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 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) 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 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 set of credentials using the `readonly` role configuration. Here we
see the dynamically generated username and password, along with a one see the dynamically generated username and password, along with a one
hour lease. hour lease.

View file

@ -3,14 +3,14 @@ layout: "docs"
page_title: "Secret Backend: PKI" page_title: "Secret Backend: PKI"
sidebar_current: "docs-secrets-pki" sidebar_current: "docs-secrets-pki"
description: |- description: |-
The PKI secret backend for Vault generates TLS certificates. The PKI secret backend for Nomad generates TLS certificates.
--- ---
# PKI Secret Backend # PKI Secret Backend
Name: `pki` 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. 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 ### 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 ### 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 ### 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. 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* ### 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 ### 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 ## Quick Start
@ -62,7 +62,7 @@ crlDistributionPoints = URI:https://vault.example.com:8200/v1/pki/crl
Adjust the URI as appropriate. 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. 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'! 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 ```text
$ vault write pki/config/ca pem_bundle="@ca_bundle.pem" $ 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 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: 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 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 ```text
$ vault write pki/issue/example-dot-com common_name=blah.example.com $ 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. 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. 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> <dd>
Retrieves the CA certificate *in raw DER-encoded form*. Retrieves the CA certificate *in raw DER-encoded form*.
This is a bare endpoint that does not return a 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. endpoint, the CA certificate is returned in PEM format.
<br /><br />This is an unauthenticated endpoint. <br /><br />This is an unauthenticated endpoint.
</dd> </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/> command similar to the following:<br/>
```text ```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 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 Retrieves the current CRL *in raw DER-encoded form*. This endpoint
is suitable for usage in the CRL Distribution Points extension in a is suitable for usage in the CRL Distribution Points extension in a
CA certificate. This is a bare endpoint that does not return 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. the CRL is returned in PEM format.
<br /><br />This is an unauthenticated endpoint. <br /><br />This is an unauthenticated endpoint.
</dd> </dd>
@ -408,7 +408,7 @@ If you get stuck at any time, simply run `vault path-help pki` or with a subpath
<dd> <dd>
Revokes a certificate using its serial number. This is an Revokes a certificate using its serial number. This is an
alternative option to the standard method of revoking 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. rotate the CRL.
<br /><br />This is a root-protected endpoint. <br /><br />This is a root-protected endpoint.
</dd> </dd>

View file

@ -3,24 +3,24 @@ layout: "docs"
page_title: "Secret Backend: PostgreSQL" page_title: "Secret Backend: PostgreSQL"
sidebar_current: "docs-secrets-postgresql" sidebar_current: "docs-secrets-postgresql"
description: |- 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 # PostgreSQL Secret Backend
Name: `postgresql` 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 dynamically based on configured roles. This means that services that need
to access a database no longer need to hardcode credentials: they can request 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 Additionally, it introduces a new ability: with every service accessing
the database with unique credentials, it makes auditing much easier when the database with unique credentials, it makes auditing much easier when
questionable data access is discovered: you can track it down to the specific questionable data access is discovered: you can track it down to the specific
instance of a service based on the SQL username. 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 `VALID UNTIL` setting when creating PostgreSQL users to ensure that users
become invalid within a reasonable time of the lease expiring. become invalid within a reasonable time of the lease expiring.
@ -37,7 +37,7 @@ $ vault mount postgresql
Successfully mounted 'postgresql' at '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: writing either a PostgreSQL URL or PG connection string:
```text ```text
@ -45,12 +45,12 @@ $ vault write postgresql/config/connection \
value="postgresql://root:vaulttest@vaulttest.ciuvljjni7uo.us-west-1.rds.amazonaws.com:5432/postgres" 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. 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 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 $ 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. 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 This role will be created by evaluating the given `sql` statements. By
default, the `{{name}}`, `{{password}}` and `{{expiration}}` fields will be populated 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 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 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) customize the privileges of the role. See the [PostgreSQL manual](http://www.postgresql.org/docs/9.4/static/sql-grant.html)
for more information. for more information.
To generate a new set of credentials, we simply read from that role: 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 ```text
$ vault read postgresql/creds/readonly $ vault read postgresql/creds/readonly
@ -94,7 +94,7 @@ password 34205e88-0de1-68b7-6267-72d8e32c5d3d
username vault-root-1430162075-7887 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 set of credentials using the `readonly` role configuration. Here we
see the dynamically generated username and password, along with a one see the dynamically generated username and password, along with a one
hour lease. hour lease.

View file

@ -3,14 +3,14 @@ layout: "docs"
page_title: "Secret Backend: SSH" page_title: "Secret Backend: SSH"
sidebar_current: "docs-secrets-ssh" sidebar_current: "docs-secrets-ssh"
description: |- 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 # SSH Secret Backend
Name: `ssh` 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 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 everyone who needs access to infrastructures. It also solves the problem of
management and distribution of keys belonging to remote hosts. 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 ## I. Dynamic Type
Register the shared secret key (having super user privileges) with Vault and let Register the shared secret key (having super user privileges) with Nomad and let
Vault take care of issuing a dynamic secret key every time a client wants to SSH Nomad take care of issuing a dynamic secret key every time a client wants to SSH
into the remote host. 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 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 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 To run this script in super user mode without password prompts, `NOPASSWD` option
for sudoers should be enabled at all remote hosts. 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. 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 Once the key is given to the user, Nomad will not know when it gets used or how many
time it gets used. Therefore, Vault **WILL NOT** and cannot audit the SSH session 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 establishments. An alternative is to use OTP type, which audits every SSH request
(see below). (see below).
@ -60,7 +60,7 @@ $ vault mount ssh
Successfully mounted 'ssh' at '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. 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. 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" # $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. # as file name to avoid collisions with public keys generated for requests.
# #
# $3: Absolute path of the authorized_keys file. # $3: Absolute path of the authorized_keys file.
@ -175,7 +175,7 @@ username@ip:~$
### Automate it! ### Automate it!
Creation of new key, saving it in a file and establishing an SSH session will all be done 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 ```shell
$ vault ssh -role dynamic_key_role username@ip $ vault ssh -role dynamic_key_role username@ip
@ -184,18 +184,18 @@ username@ip:~$
---------------------------------------------------- ----------------------------------------------------
## II. One-Time-Password (OTP) Type ## 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. 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 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 in at the password prompt will be received by the Nomad agent and gets validated
by the Vault server. Vault server deletes the OTP after validating it once (hence one-time). 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. 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. on how to configure the agent.
### Mounting SSH ### 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 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 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 ```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 $ 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">key</span>
<span class="param-flags">required for Dynamic type, NA for OTP type</span> <span class="param-flags">required for Dynamic type, NA for OTP type</span>
(String) (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. the `keys/` endpoint to create a named key.
</li> </li>
<li> <li>
@ -420,7 +420,7 @@ username@ip:~$
(String) (String)
Admin user at remote host. The shared key being registered should be Admin user at remote host. The shared key being registered should be
for this user and should have root privileges. Everytime a dynamic 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 username to login to remote host and install the generated credential
for the other user. for the other user.
</li> </li>
@ -446,7 +446,7 @@ username@ip:~$
Port number for SSH connection. Default is '22'. Port number does not 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 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 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>
<li> <li>
<span class="param">key_type</span> <span class="param">key_type</span>

View file

@ -3,25 +3,25 @@ layout: "docs"
page_title: "Secret Backend: Transit" page_title: "Secret Backend: Transit"
sidebar_current: "docs-secrets-transit" sidebar_current: "docs-secrets-transit"
description: |- 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 # Transit Secret Backend
Name: `transit` 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 store the data sent to the backend. It can also be viewed as "encryption as
a service." a service."
The primary use case for the transit backend is to encrypt data from The primary use case for the transit backend is to encrypt data from
applications while still storing that encrypted data in some primary data applications while still storing that encrypted data in some primary data
store. This relieves the burden of proper encryption/decryption from store. This relieves the burden of proper encryption/decryption from
application developers and pushes the burden onto the operators of Vault. application developers and pushes the burden onto the operators of Nomad.
Operators of Vault generally include the security team at an organization, Operators of Nomad generally include the security team at an organization,
which means they can ensure that data is encrypted/decrypted properly. 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 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 used for decryption. This can be used to enable per transaction unique keys which
further increase the security of data at rest. 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 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 ciphertext, but only handles it _in transit_ for processing. The application
is free to store the ciphertext in a database or file at rest. is free to store the ciphertext in a database or file at rest.

View file

@ -1,18 +1,18 @@
--- ---
layout: "downloads" layout: "downloads"
page_title: "Download Vault" page_title: "Download Nomad"
sidebar_current: "downloads-vault" sidebar_current: "downloads-vault"
description: |- description: |-
Download Vault Download Nomad
--- ---
<h1>Download Vault</h1> <h1>Download Nomad</h1>
<section class="downloads"> <section class="downloads">
<div class="description row"> <div class="description row">
<div class="col-md-12"> <div class="col-md-12">
<p> <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 (<%= latest_version %>). Please download the proper package for your
operating system and architecture. You can find SHA256 checksums 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>. 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>.

View file

@ -15,8 +15,8 @@
<div id="hero-logotype"></div> <div id="hero-logotype"></div>
</div> </div>
<div id="hero-text"> <div id="hero-text">
<h1>Applications on a global fleet.</h1> <h1>Easily deploy applications at any scale</h1>
<h3>As simple as a Single Machine.</h3> <h3>Any App. Any OS. Any Cloud.</h3>
<div id="hero-btns"> <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 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> <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 id="deploy" class="feature">
<div class="feature-header"> <div class="feature-header">
<h3>Deploy to any cloud</h3> <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>
<div class="feature-footer"> <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> <span class="docker-outline-logo"></span>
</div> </div>
</div> <!-- .feature --> </div> <!-- .feature -->
@ -106,7 +109,7 @@
<div id="density" class="feature"> <div id="density" class="feature">
<div class="feature-header"> <div class="feature-header">
<h3>Increase density and reduce cost</h3> <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>
<div class="feature-graphic"></div> <div class="feature-graphic"></div>
</div> <!-- .feature --> </div> <!-- .feature -->

View file

@ -3,28 +3,28 @@ layout: "intro"
page_title: "Access Control Policies" page_title: "Access Control Policies"
sidebar_current: "gettingstarted-acl" sidebar_current: "gettingstarted-acl"
description: |- 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 (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 the last section, we learned about _authentication_. This section is
about _authorization_. about _authorization_.
Whereas for authentication Vault has multiple options or backends that Whereas for authentication Nomad has multiple options or backends that
can be enabled and used, the authorization or policies of Vault are always 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 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 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. the root policy can do anything.
## Policy Format ## 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 [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 format that is also JSON-compatible, so you can use JSON as well. An example
policy is shown below: policy is shown below:
@ -42,13 +42,13 @@ path "secret/foo" {
The policy format uses a prefix matching system on the API path The policy format uses a prefix matching system on the API path
to determine access control. The most specific defined policy is used, to determine access control. The most specific defined policy is used,
either an exact match or the longest-prefix glob match. Since everything 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 in Nomad must be accessed via the API, this gives strict control over every
aspect of Vault, including mounting backends, authenticating, as well as secret access. 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 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 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 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`. Save the above policy as `acl.hcl`.
@ -103,7 +103,7 @@ such as `vault mounts` will not work either.
## Mapping Policies to Auth Backends ## 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 multiple backends. Any mounted auth backend must map identities to these
core policies. core policies.
@ -124,12 +124,12 @@ mapping policies to identity.
## Next ## 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 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 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, with, and because auth backends all must map to the central policy system,
you only have to learn this 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).

View file

@ -7,9 +7,9 @@ description: |-
--- ---
# Using the HTTP APIs with Authentication # 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 $ 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 ## 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. 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 $ 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 \ $ 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 $ 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 \ $ curl \
@ -95,38 +95,38 @@ We can enable an authentication backend with the following `curl` command:
``` ```
$ curl \ $ curl \
-X POST \ -X POST \
-H "X-Vault-Token:$VAULT_TOKEN" \ -H "X-Nomad-Token:$VAULT_TOKEN" \
-d '{"type":"app-id"}' \ -d '{"type":"app-id"}' \
http://127.0.0.1:8200/v1/sys/auth/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). 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 \ $ curl \
-X POST \ -X POST \
-H "X-Vault-Token:$VAULT_TOKEN" \ -H "X-Nomad-Token:$VAULT_TOKEN" \
-d '{"value":"root", "display_name":"demo"}' \ -d '{"value":"root", "display_name":"demo"}' \
http://localhost:8200/v1/auth/app-id/map/app-id/152AEA38-85FB-47A8-9CBD-612D645BFACA 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. 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 \ $ curl \
-X POST \ -X POST \
-H "X-Vault-Token:$VAULT_TOKEN" \ -H "X-Nomad-Token:$VAULT_TOKEN" \
-d '{"value":"152AEA38-85FB-47A8-9CBD-612D645BFACA"}' \ -d '{"value":"152AEA38-85FB-47A8-9CBD-612D645BFACA"}' \
http://localhost:8200/v1/auth/app-id/map/user-id/5ADF8218-D7FB-4089-9E38-287465DBF37E 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 \ $ 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`: 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" $ 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 \ $ curl \
-X POST \ -X POST \
-H "X-Vault-Token:$VAULT_TOKEN" \ -H "X-Nomad-Token:$VAULT_TOKEN" \
-H 'Content-type: application/json' \ -H 'Content-type: application/json' \
-d '{"bar":"baz"}' \ -d '{"bar":"baz"}' \
http://127.0.0.1:8200/v1/secret/foo 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 \ $ curl \
-H "X-Vault-Token:$VAULT_TOKEN" \ -H "X-Nomad-Token:$VAULT_TOKEN" \
http://127.0.0.1:8200/v1/secret/foo 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. 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 ## Next

View file

@ -3,36 +3,36 @@ layout: "intro"
page_title: "Authentication" page_title: "Authentication"
sidebar_current: "gettingstarted-auth" sidebar_current: "gettingstarted-auth"
description: |- 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 # Authentication
Now that we know how to use the basics of Vault, it is important to understand Now that we know how to use the basics of Nomad, it is important to understand
how to authenticate to Vault itself. Up to this point, we haven't had to how to authenticate to Nomad itself. Up to this point, we haven't had to
authenticate because starting the Vault server in dev mode automatically logs 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. 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 On this page, we'll talk specifically about _authentication_. On the next
page, we talk about _authorization_. 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 The access control and permissions associated with an identity are
authorization, and will not be covered on this page. authorization, and will not be covered on this page.
Vault has pluggable authentication backends, making it easy to authenticate Nomad has pluggable authentication backends, making it easy to authenticate
with Vault using whatever form works best for your organization. On this page 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. we'll use the token backend as well as the GitHub backend.
## Tokens ## Tokens
We'll first explain token authentication before going over any other We'll first explain token authentication before going over any other
authentication backends. Token authentication is enabled by default in 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. point.
When you start a dev server with `vault server -dev`, it outputs your 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. _root token_. The root token is the initial access token to configure Nomad.
It has root privileges, so it can perform any operation within Vault. It has root privileges, so it can perform any operation within Nomad.
We'll cover how to limit privileges in the next section. We'll cover how to limit privileges in the next section.
You can create more tokens using `vault token-create`: You can create more tokens using `vault token-create`:
@ -70,17 +70,17 @@ with this token are listed below:
root 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 what access policies the token is associated with. If you want to test
`vault auth`, make sure you create a new token first. `vault auth`, make sure you create a new token first.
## Auth Backends ## Auth Backends
In addition to tokens, other authentication backends can be enabled. 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. 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, easiest for your environment. For example, for desktop environments,
private key or GitHub based authentication may be easiest. For server private key or GitHub based authentication may be easiest. For server
environments, some shared secret may be best. Auth backends give you 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'! 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 anymore unless you have another root token, since it invalidated your
own session since we authenticated with GitHub above. Since we're still own session since we authenticated with GitHub above. Since we're still
operating in development mode, just restart the dev server to fix this. operating in development mode, just restart the dev server to fix this.
## Next ## 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 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. 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. most appropriate authentication mechanism for your organization.
In this next section, we'll learn about In this next section, we'll learn about

View file

@ -1,26 +1,26 @@
--- ---
layout: "intro" layout: "intro"
page_title: "Deploy Vault" page_title: "Deploy Nomad"
sidebar_current: "gettingstarted-deploy" sidebar_current: "gettingstarted-deploy"
description: |- 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 Up to this point, we've been working with the dev server, which
automatically authenticated us, setup in-memory storage, etc. Now that automatically authenticated us, setup in-memory storage, etc. Now that
you know the basics of Vault, it is important to learn how to deploy you know the basics of Nomad, it is important to learn how to deploy
Vault into a real environment. Nomad into a real environment.
On this page, we'll cover how to configure Vault, start Vault, the On this page, we'll cover how to configure Nomad, start Nomad, the
seal/unseal process, and scaling Vault. 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 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 ```javascript
backend "consul" { backend "consul" {
@ -36,17 +36,17 @@ listener "tcp" {
Within the configuration file, there are two primary configurations: 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), 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), but in the example above we're using [Consul](http://www.consul.io),
a much more production-ready backend. 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 API requests. In the example above we're listening on localhost port
8200 without TLS. 8200 without TLS.
For now, copy and paste the configuration above to `example.hcl`. It will 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 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) [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 -config=example.hcl
==> Vault server configuration: ==> Nomad server configuration:
Log Level: info Log Level: info
Backend: consul Backend: consul
Listener 1: tcp (addr: "127.0.0.1:8200", tls: "disabled") 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 This process should be run using a resource manager such as systemd or
upstart. upstart.
You'll notice that you can't execute any commands. We don't have any 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. 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 ```shell
$ vault server -config=example.hcl $ vault server -config=example.hcl
Error initializing core: Failed to lock memory: cannot allocate memory Error initializing core: Failed to lock memory: cannot allocate memory
This usually means that the mlock syscall is not available. 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 disk. This requires root privileges as well as a machine
that supports mlock. Please enable mlock on your system or 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 set the `disable_mlock` configuration option in your configuration
file. file.
``` ```
@ -99,16 +99,16 @@ file.
For guidance on dealing with this issue, see the discussion of For guidance on dealing with this issue, see the discussion of
`disable_mlock` in [Server Configuration](/docs/config/index.html). `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 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 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 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 $ vault init
@ -119,21 +119,21 @@ Key 4: 8dd72fd7d1af254de5f82d1270fd87ab04
Key 5: b47fdeb7dda82dbe92d88d3c860f605005 Key 5: b47fdeb7dda82dbe92d88d3c860f605005
Initial Root Token: eaf5cc32-b48f-7785-5c94-90b5ce300e9b 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) 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 of the keys above (any of the keys, as long as the total number equals
the threshold). 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 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: Initialization outputs two incredibly important pieces of information:
the _unseal keys_ and the _initial root token_. This is the 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. only time that the unseal keys should ever be so close together.
For the purpose of this getting started guide, save all these keys For the purpose of this getting started guide, save all these keys
@ -142,25 +142,25 @@ save these keys together.
## Seal/Unseal ## Seal/Unseal
Every initialized Vault server starts in the _sealed_ state. From Every initialized Nomad server starts in the _sealed_ state. From
the configuration, Vault can access the physical storage, but it can't 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 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 of teaching Nomad how to decrypt the data is known as _unsealing_ the
Vault. Nomad.
Unsealing has to happen every time Vault starts. It can be done via Unsealing has to happen every time Nomad starts. It can be done via
the API and via the command line. To unseal the Vault, you the API and via the command line. To unseal the Nomad, you
must have the _threshold_ number of unseal keys. In the output above, must have the _threshold_ number of unseal keys. In the output above,
notice that the "key threshold" is 3. This means that to unseal 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 uses an algorithm known as
[Shamir's Secret Sharing](http://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) [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 to split the master key into shards. Only with the threshold number of keys
can it be reconstructed and your data finally accessed. 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 $ vault unseal
@ -171,20 +171,20 @@ Key Threshold: 3
Unseal Progress: 1 Unseal Progress: 1
``` ```
After pasting in a valid key and confirming, you'll see that the Vault After pasting in a valid key and confirming, you'll see that the Nomad
is still sealed, but progress is made. Vault knows it has 1 key out of 3. is still sealed, but progress is made. Nomad knows it has 1 key out of 3.
Due to the nature of the algorithm, Vault doesn't know if it has the Due to the nature of the algorithm, Nomad doesn't know if it has the
_correct_ key until the threshold is reached. _correct_ key until the threshold is reached.
Also notice that the unseal process is stateful. You can go to another 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, 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 that other computer can continue the unseal process. This is incredibly
important to the design of the unseal process: multiple people with multiple 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 multiple computers and the keys should never be together. A single malicious
operator does not have enough keys to be 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 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: they're correct, you should soon see output like this:
@ -197,26 +197,26 @@ Key Threshold: 3
Unseal Progress: 0 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 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. 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 Once you're ready to move on, use `vault auth` to authenticate with
the root token. 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 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 When the Nomad is sealed again, it clears all of its state (including
the encryption key) from memory. The Vault is secure and locked down the encryption key) from memory. The Nomad is secure and locked down
from access. from access.
## Next ## Next
You now know how to configure, initialize, and unseal/seal Vault. You now know how to configure, initialize, and unseal/seal Nomad.
This is the basic knowledge necessary to deploy Vault into a real This is the basic knowledge necessary to deploy Nomad into a real
environment. Once the Vault is unsealed, you access it as you have environment. Once the Nomad is unsealed, you access it as you have
throughout this getting started guide (which worked with an unsealed Vault). 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. Next, we have a [short tutorial](/intro/getting-started/apis.html) on using the HTTP APIs to authenticate and access secrets.

View file

@ -3,51 +3,51 @@ layout: "intro"
page_title: "Starting the Server" page_title: "Starting the Server"
sidebar_current: "gettingstarted-devserver" sidebar_current: "gettingstarted-devserver"
description: |- 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 Nomad operates as a client/server application. The Nomad server is the
only piece of the Vault architecture that interacts with the data only piece of the Nomad architecture that interacts with the data
storage and backends. All operations done via the Vault CLI interact storage and backends. All operations done via the Nomad CLI interact
with the server over a TLS connection. 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. how the server is started, and understanding the seal/unseal process.
## Starting the Dev Server ## 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 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. 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 $ vault server -dev
WARNING: Dev mode is enabled! WARNING: Dev mode is enabled!
In this mode, Vault is completely in-memory and unsealed. In this mode, Nomad is completely in-memory and unsealed.
Vault is configured to only have a single unseal key. The root Nomad is configured to only have a single unseal key. The root
token has already been authenticated with the CLI, so you can 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 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' export VAULT_ADDR='http://127.0.0.1:8200'
The unseal key and root token are reproduced below in case you 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 Unseal Key: 2252546b1a8551e8411502501719c4b3
Root Token: 79bd8011-af5a-f147-557e-c58be4fedf6c Root Token: 79bd8011-af5a-f147-557e-c58be4fedf6c
==> Vault server configuration: ==> Nomad server configuration:
Log Level: info Log Level: info
Backend: inmem 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 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 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. automatically unseals and shows you the unseal key and root access key.
We'll go over what all this means shortly. 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: else:
1. Copy and run the `export VAULT_ADDR ...` command from your terminal 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 2. Save the unseal key somewhere. Don't worry about _how_ to save this
securely. For now, just save it anywhere. 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 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 only reason these would ever be different is if you're running a dev
server from going through this guide previously. server from going through this guide previously.
@ -106,7 +106,7 @@ We'll cover what this output means later in the guide.
## Next ## 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. any secrets yet, but we'll do that in the next section.
Next, we're going to Next, we're going to

View file

@ -3,14 +3,14 @@ layout: "intro"
page_title: "Dynamic Secrets" page_title: "Dynamic Secrets"
sidebar_current: "gettingstarted-dynamicsecrets" sidebar_current: "gettingstarted-dynamicsecrets"
description: |- 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 # 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 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, Dynamic secrets are secrets that are generated when they're accessed,
and aren't statically written like we did in 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 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 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 mechanisms (covered later), the dynamic secret can be revoked right after
use, minimizing the amount of time the secret existed. 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 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 $ 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 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. `vault write` to write the contents of a file.
## Generating the Secret ## 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 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. 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. revocation, etc. Copy and save your Lease ID now.
## Revoking the Secret ## 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 On this page we experienced our first dynamic secret, and we also saw
the revocation system in action. Dynamic secrets are incredibly powerful. the revocation system in action. Dynamic secrets are incredibly powerful.
As time goes on, we expect that more systems will support some sort of 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. most value out of this practice.
Before going further, we're going to take a quick detour to learn Before going further, we're going to take a quick detour to learn

View file

@ -3,7 +3,7 @@ layout: "intro"
page_title: "Your First Secret" page_title: "Your First Secret"
sidebar_current: "gettingstarted-firstsecret" sidebar_current: "gettingstarted-firstsecret"
description: |- 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 # Your First Secret
@ -11,18 +11,18 @@ description: |-
Now that the dev server is up and running, let's get straight to it and Now that the dev server is up and running, let's get straight to it and
read and write our first secret. 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, arbitrary secrets securely. On this page, we'll do this using the CLI,
but there is also a complete but there is also a complete
[HTTP API](/docs/http/index.html) [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 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). 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 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 ## Writing a Secret
@ -69,7 +69,7 @@ excited yes
value world 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 data from storage and decrypted it.
The output format is purposefully whitespace separated to make it easy The output format is purposefully whitespace separated to make it easy
to pipe into a tool like `awk`. to pipe into a tool like `awk`.
@ -112,7 +112,7 @@ Success! Deleted 'secret/hello'
## Next ## Next
In this section we learned how to use the powerful CRUD features of 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. but basic feature.
Next, we'll learn the basics about [secret backends](/intro/getting-started/secret-backends.html). Next, we'll learn the basics about [secret backends](/intro/getting-started/secret-backends.html).

View file

@ -3,7 +3,7 @@ layout: "intro"
page_title: "Built-in Help" page_title: "Built-in Help"
sidebar_current: "gettingstarted-help" sidebar_current: "gettingstarted-help"
description: |- 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 # 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 Instead of having to memorize or reference documentation constantly
to determine what paths to use, we built a help system directly into 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. generates human-readable help for any mounted backend.
On this page, we'll learn how to use this help system. It is an invaluable 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 ## Backend Overview
@ -112,9 +112,9 @@ generic `secret/` path.
## Next ## Next
The help system may not be the most exciting feature of Vault, but it The help system may not be the most exciting feature of Nomad, but it
is indispensable in day-to-day usage of Vault. The help system lets you is indispensable in day-to-day usage of Nomad. The help system lets you
learn about how to use any backend within Vault without leaving the command learn about how to use any backend within Nomad without leaving the command
line. line.
Next, we'll learn about Next, we'll learn about

View file

@ -1,28 +1,28 @@
--- ---
layout: "intro" layout: "intro"
page_title: "Install Vault" page_title: "Install Nomad"
sidebar_current: "gettingstarted-install" sidebar_current: "gettingstarted-install"
description: |- 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 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) 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 for those who want to be sure they're compiling source they trust into
the final binary. the final binary.
## Installing Vault ## Installing Nomad
To install Vault, find the [appropriate package](/downloads.html) for To install Nomad, find the [appropriate package](/downloads.html) for
your system and download it. Vault is packaged as a zip archive. 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 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. 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) 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 ## 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 terminal session and checking that `vault` is available. By executing
`vault`, you should see help output similar to the following: `vault`, you should see help output similar to the following:
@ -41,30 +41,30 @@ $ vault
usage: vault [-version] [-help] <command> [args] usage: vault [-version] [-help] <command> [args]
Common commands: 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 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 renew Renew the lease of a secret
revoke Revoke a secret. revoke Revoke a secret.
server Start a Vault server server Start a Nomad server
status Outputs status of whether Vault is sealed and if HA mode is enabled status Outputs status of whether Nomad is sealed and if HA mode is enabled
write Write secrets or configuration into Vault write Write secrets or configuration into Nomad
All other commands: All other commands:
audit-disable Disable an audit backend audit-disable Disable an audit backend
audit-enable Enable an audit backend audit-enable Enable an audit backend
audit-list Lists enabled audit backends in Vault audit-list Lists enabled audit backends in Nomad
auth Prints information about how to authenticate with Vault auth Prints information about how to authenticate with Nomad
auth-disable Disable an auth provider auth-disable Disable an auth provider
auth-enable Enable a new 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 key-status Provides information about the active encryption key
mount Mount a logical backend mount Mount a logical backend
mounts Lists mounted backends in Vault mounts Lists mounted backends in Nomad
policies List the policies on the server policies List the policies on the server
policy-delete Delete a policy from the server policy-delete Delete a policy from the server
policy-write Write a policy to 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 remount Remount a secret backend to a new path
rotate Rotates the backend encryption key used to persist data rotate Rotates the backend encryption key used to persist data
seal Seals the vault server seal Seals the vault server
@ -73,11 +73,11 @@ All other commands:
token-revoke Revoke one or more auth tokens token-revoke Revoke one or more auth tokens
unmount Unmount a secret backend unmount Unmount a secret backend
unseal Unseals the vault server 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 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!

View file

@ -3,18 +3,18 @@ layout: "intro"
page_title: "Next Steps" page_title: "Next Steps"
sidebar_current: "gettingstarted-nextsteps" sidebar_current: "gettingstarted-nextsteps"
description: |- 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 # Next Steps
That concludes the getting started guide for Vault. Hopefully you're That concludes the getting started guide for Nomad. Hopefully you're
excited about the possibilities of Vault and ready to put this knowledge excited about the possibilities of Nomad and ready to put this knowledge
to use to improve your environment. 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 Due to the importance of securing secrets, we recommend reading the following
as next steps. as next steps.
* [Documentation](/docs/index.html) - The documentation is an in-depth * [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.

View file

@ -8,21 +8,21 @@ description: |-
# Secret Backends # 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 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 backend to `secret/`. The generic backend reads and writes raw data to
the backend storage. the backend storage.
Vault supports other backends in addition to "generic", and this feature Nomad supports other backends in addition to "generic", and this feature
in particular is what makes Vault unique. For example, the "aws" backend in particular is what makes Nomad unique. For example, the "aws" backend
generates AWS access keys dynamically, on demand. Another example -- generates AWS access keys dynamically, on demand. Another example --
this type of backend does not yet exist -- is a backend that this type of backend does not yet exist -- is a backend that
reads and writes data directly to an reads and writes data directly to an
[HSM](http://en.wikipedia.org/wiki/Hardware_security_module). [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 are _mounted_ at specific paths. For example, the "generic" backend is
_mounted_ at the `secret/` prefix. _mounted_ at the `secret/` prefix.
@ -33,7 +33,7 @@ to the next page, where we'll create dynamic secrets.
## Mount a Backend ## Mount a Backend
To start, let's mount another "generic" backend. Just like a normal 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 mount points. This is useful if you want different access control policies
(covered later) or configurations for different paths. (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 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 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 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 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 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: 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?" "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 The read/write/delete operations are forwarded to the backend, and the
backend can choose to react to these operations however it wishes. backend can choose to react to these operations however it wishes.
For example, the "generic" backend simply passes this through to the 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 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. 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 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, can interact with more unique environments: AWS IAM, dynamic SQL user creation,
etc. all using the same read/write interface. etc. all using the same read/write interface.

View file

@ -3,25 +3,25 @@ layout: "intro"
page_title: "Introduction" page_title: "Introduction"
sidebar_current: "what" sidebar_current: "what"
description: |- 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 Welcome to the intro guide to Nomad! This guide is the best
place to start with Vault. We cover what Vault is, what place to start with Nomad. We cover what Nomad is, what
problems it can solve, how it compares to existing software, 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 [documentation](/docs/index.html) provides a better reference
guide for all available features as well as internals. 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, 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 secret, while providing tight access control and recording a detailed
audit log. audit log.
@ -30,36 +30,36 @@ credentials, API keys for external services, credentials for
service-oriented architecture communication, etc. Understanding who is service-oriented architecture communication, etc. Understanding who is
accessing what secrets is already very difficult and platform-specific. accessing what secrets is already very difficult and platform-specific.
Adding on key rolling, secure storage, and detailed audit logs is almost 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). [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 * **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 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. 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 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 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. 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 it. This allows security teams to define encryption parameters and
developers to store encrypted data in a location such as SQL without developers to store encrypted data in a location such as SQL without
having to design their own encryption methods. having to design their own encryption methods.
* **Leasing and Renewal**: All secrets in Vault have a _lease_ associated * **Leasing and Renewal**: All secrets in Nomad have a _lease_ associated
with it. At the end of the lease, Vault will automatically revoke that 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. 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 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. 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 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 ## Next Steps
See the page on [Vault use cases](/intro/use-cases.html) to see the See the page on [Nomad use cases](/intro/use-cases.html) to see the
multiple ways Vault can be used. Then see multiple ways Nomad can be used. Then see
[how Vault compares to other software](/intro/vs/index.html) [how Nomad compares to other software](/intro/vs/index.html)
to see how it fits into your existing infrastructure. Finally, continue onwards with to see how it fits into your existing infrastructure. Finally, continue onwards with
the [getting started guide](/intro/getting-started/install.html) to use 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.

View file

@ -3,30 +3,30 @@ layout: "intro"
page_title: "Use Cases" page_title: "Use Cases"
sidebar_current: "use-cases" sidebar_current: "use-cases"
description: |- 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 # Use Cases
Before understanding use cases, it's useful to know [what Vault is](/intro/index.html). Before understanding use cases, it's useful to know [what Nomad is](/intro/index.html).
This page lists some concrete use cases for Vault, but the possible use cases are This page lists some concrete use cases for Nomad, but the possible use cases are
much broader than what we cover. much broader than what we cover.
#### General Secret Storage #### General Secret Storage
At a bare minimum, Vault can be used for the storage of any secrets. For At a bare minimum, Nomad can be used for the storage of any secrets. For
example, Vault would be a fantastic way to store sensitive environment variables, example, Nomad would be a fantastic way to store sensitive environment variables,
database credentials, API keys, etc. database credentials, API keys, etc.
Compare this with the current way to store these which might be Compare this with the current way to store these which might be
plaintext in files, configuration management, a database, etc. It would 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 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. audit log.
#### Employee Credential Storage #### 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 for storing credentials that employees share to access web services. The
audit log mechanism lets you know what secrets an employee accessed and 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 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 #### 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. 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 The keypair will not exist before or after the script runs, and the
creation of the keys are completely logged. creation of the keys are completely logged.
@ -44,12 +44,12 @@ effectively hardcoding limited-access access tokens in various places.
#### Data Encryption #### 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 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 to allow applications to encrypt their data while still storing it in the
primary data store. primary data store.
The benefit of this is that developers do not need to worry about how to 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 and the security team managing it, and developers just encrypt/decrypt
data as needed. data as needed.

View file

@ -1,12 +1,12 @@
--- ---
layout: "intro" layout: "intro"
page_title: "Vault vs. Chef, Puppet, etc." page_title: "Nomad vs. Chef, Puppet, etc."
sidebar_current: "vs-other-chef" sidebar_current: "vs-other-chef"
description: |- 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 A big part of configuring software is setting up secrets: configuring a
web application to talk to a service, configuring the credentials of 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 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. 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 read secrets from configuration management, but you can also use the API
directly to read secrets from applications. This means that configuration directly to read secrets from applications. This means that configuration
management requires less secrets, and in many cases doesn't ever have to management requires less secrets, and in many cases doesn't ever have to
persist them to disk. 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 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 encrypted storage, it couldn't be read without multiple keys which are generally
distributed to multiple individuals. This is known as _unsealing_, and happens 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. Even erroneous requests (invalid access tokens, for example) are logged.
To access any data, an access token is required. This token is usually 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. 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 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 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.

View file

@ -1,12 +1,12 @@
--- ---
layout: "intro" layout: "intro"
page_title: "Vault vs. Consul" page_title: "Nomad vs. Consul"
sidebar_current: "vs-other-consul" sidebar_current: "vs-other-consul"
description: |- 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, [Consul](https://consul.io) is system for service discovery, monitoring,
and configuration that is distributed and highly available. Consul also 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, in transit nor at rest, it does not have pluggable authentication mechanisms,
and there is no per-request auditing mechanism. 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 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 providing clients with root privileges to underlying systems and makes
it possible to do key rolling and revocation. it possible to do key rolling and revocation.
The strength of Consul is that it is fault tolerant and highly scalable. 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 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 the higher level policy management, secret leasing, audit logging, and automatic
revocation. revocation.

View file

@ -1,12 +1,12 @@
--- ---
layout: "intro" layout: "intro"
page_title: "Vault vs. Custom Solutions" page_title: "Nomad vs. Custom Solutions"
sidebar_current: "vs-other-custom" sidebar_current: "vs-other-custom"
description: |- 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, Many organizations resort to custom solutions for storing secrets,
whether that be Dropbox, encrypted disk images, encrypted SQL columns, 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 that must be done correctly. This increases the pressure to maintain
the internal systems. 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. 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 as good as the entire community working together to improve it. This
isn't just features and bug fixes, but finding potential security holes. isn't just features and bug fixes, but finding potential security holes.
Additionally, since it is an open source, your own security teams can 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. for security.

View file

@ -1,12 +1,12 @@
--- ---
layout: "intro" layout: "intro"
page_title: "Vault vs. Dropbox" page_title: "Nomad vs. Dropbox"
sidebar_current: "vs-other-dropbox" sidebar_current: "vs-other-dropbox"
description: |- 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, It is an unfortunate truth that many organizations, big and small,
often use Dropbox as a mechanism for storing secrets. It is so common 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 such as an encrypted disk image within Dropbox, it is subpar versus a
real secret storage server. 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 model, integrates with many different authentication services, stores
audit logs, can generate dynamic secrets, and more. audit logs, can generate dynamic secrets, and more.

View file

@ -1,12 +1,12 @@
--- ---
layout: "intro" layout: "intro"
page_title: "Vault vs. HSMs" page_title: "Nomad vs. HSMs"
sidebar_current: "vs-other-hsm" sidebar_current: "vs-other-hsm"
description: |- 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) 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 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 requires SSH and setting up various keypairs manually. It is difficult to
automate. 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 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 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. 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 as generating _dynamic secrets_. Instead of storing AWS access keys directly
within Vault, Vault can generate access keys according to a specific within Nomad, Nomad can generate access keys according to a specific
policy on the fly. Vault has the potential of doing this for any policy on the fly. Nomad has the potential of doing this for any
system through its mountable secret backend system. system through its mountable secret backend system.
For most companies, an HSM is overkill, and Vault is enough. For companies For most companies, an HSM is overkill, and Nomad is enough. For companies
that can afford an HSM, it can be used with Vault to get the best of both that can afford an HSM, it can be used with Nomad to get the best of both
worlds. worlds.

View file

@ -1,22 +1,22 @@
--- ---
layout: "intro" layout: "intro"
page_title: "Vault vs. Other Software" page_title: "Nomad vs. Other Software"
sidebar_current: "vs-other" sidebar_current: "vs-other"
description: |- 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 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. 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 to only use facts. If you find something that is invalid or out of date
in the comparisons, please in the comparisons, please
[open an issue](https://github.com/hashicorp/vault/issues) and we'll [open an issue](https://github.com/hashicorp/vault/issues) and we'll
address it as soon as possible. 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. systems.

View file

@ -1,12 +1,12 @@
--- ---
layout: "intro" layout: "intro"
page_title: "Vault vs. Keywhiz" page_title: "Nomad vs. Keywhiz"
sidebar_current: "vs-other-keywhiz" sidebar_current: "vs-other-keywhiz"
description: |- 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 Keywhiz is a secret management solution built by Square. Keywhiz
has a client/server architecture based on a RESTful API. Clients of 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 operators may authenticate using a cookie-based authentication either via command
line utilities or through a management web interface. line utilities or through a management web interface.
Vault similarly is designed as a comprehensive secret management Nomad similarly is designed as a comprehensive secret management
solution. The client interaction with Vault is flexible solution. The client interaction with Nomad is flexible
both for authentication and usage of secrets. Vault supports [mTLS both for authentication and usage of secrets. Nomad supports [mTLS
authentication](/docs/auth/cert.html) along with many [other authentication](/docs/auth/cert.html) along with many [other
mechanisms](/docs/auth/index.html). The goal being to make it easy to 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 authenticate as a machine for programmatic access and as a human for
operator usage. 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 [ACL system](/docs/concepts/policies.html) is used
to protect secrets and gate access, similarly to the 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). server side using [audit backends](/docs/audit/index.html).
Keywhiz focuses on storage and distribution of secrets and supports Keywhiz focuses on storage and distribution of secrets and supports
rotation through secret versioning, which is possible in the Keywhiz UI and 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 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. that no external systems need to be used.
Lastly Vault forces a mandatory lease contract with clients. All secrets read Lastly Nomad forces a mandatory lease contract with clients. All secrets read
from Vault have an associated lease which enables operators to audit key usage, from Nomad have an associated lease which enables operators to audit key usage,
perform key rolling, and ensure automatic revocation. Vault provides multiple perform key rolling, and ensure automatic revocation. Nomad provides multiple
revocation mechanisms to give operators a clear "break glass" procedure after revocation mechanisms to give operators a clear "break glass" procedure after
a potential compromise. a potential compromise.

View file

@ -1,40 +1,40 @@
--- ---
layout: "intro" layout: "intro"
page_title: "Vault vs. Amazon Key Management Service" page_title: "Nomad vs. Amazon Key Management Service"
sidebar_current: "vs-other-kms" sidebar_current: "vs-other-kms"
description: |- 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 Amazon Key Management Service (KMS) is a service provided in the AWS
ecosystem for encryption key management. It is backed by Hardware Security ecosystem for encryption key management. It is backed by Hardware Security
Modules (HSM) for physical 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 The KMS service is focused on securely storing encryption keys and supporting
cryptographic operations (encrypt and decrypt) using those keys. It supports cryptographic operations (encrypt and decrypt) using those keys. It supports
access controls and auditing as well. 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) The [`transit` backend](/docs/secrets/transit/index.html)
provides similar capabilities as the KMS service, allowing for encryption keys 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. 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. 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. fine-grained security controls, auditing, and non-repudiation.
Lastly Vault forces a mandatory lease contract with clients. All secrets read Lastly Nomad forces a mandatory lease contract with clients. All secrets read
from Vault have an associated lease which enables operations to audit key usage, from Nomad have an associated lease which enables operations to audit key usage,
perform key rolling, and ensure automatic revocation. Vault provides multiple perform key rolling, and ensure automatic revocation. Nomad provides multiple
revocation mechansims to give operators a clear "break glass" procedure after revocation mechansims to give operators a clear "break glass" procedure after
a potential compromise. 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 and does not require any special hardware. This makes it well suited for cloud
environments where HSMs are not available or are cost prohibitive. environments where HSMs are not available or are cost prohibitive.

View file

@ -22,7 +22,7 @@
<nav role="navigation"> <nav role="navigation">
<ul class="nav navbar-nav navbar-right"> <ul class="nav navbar-nav navbar-right">
<li class="first download"><a href="/downloads.html">Download</a></li> <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> </ul>
</nav> </nav>
</div> </div>

View file

@ -7,7 +7,7 @@
<link rel="shortcut icon" href="<%= image_path('favicon.png') %>"> <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" %> <%= stylesheet_link_tag "application" %>

View file

@ -21,6 +21,6 @@
<!-- Sidebar navigation 2--> <!-- Sidebar navigation 2-->
<ul class="buttons-nav"> <ul class="buttons-nav">
<li class="first"><a class="v-btn gray sml" href="/downloads.html">Download</a></li> <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> </ul>
</aside> </aside>

View file

@ -13,25 +13,17 @@
<a href="/docs/internals/architecture.html">Architecture</a> <a href="/docs/internals/architecture.html">Architecture</a>
</li> </li>
<li<%= sidebar_current("docs-internals-ha") %>> <li<%= sidebar_current("docs-internals-consensus") %>>
<a href="/docs/internals/high-availability.html">High Availability</a> <a href="/docs/internals/consensus.html">Consensus Protocol</a>
</li> </li>
<li<%= sidebar_current("docs-internals-security") %>> <li<%= sidebar_current("docs-internals-gossip") %>>
<a href="/docs/internals/security.html">Security Model</a> <a href="/docs/internals/gossip.html">Gossip Protocol</a>
</li> </li>
<li<%= sidebar_current("docs-internals-telemetry") %>> <li<%= sidebar_current("docs-internals-telemetry") %>>
<a href="/docs/internals/telemetry.html">Telemetry</a> <a href="/docs/internals/telemetry.html">Telemetry</a>
</li> </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> </ul>
</li> </li>

View file

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

View file

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

View file

@ -2,7 +2,7 @@
layout: "inner" layout: "inner"
page_title: "Security" page_title: "Security"
description: |- 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> <h1>Security</h1>
@ -22,6 +22,6 @@ which has the proper email to communicate with as well as our PGP key.
</p> </p>
<p> <p>
If you aren't reporting a security sensitive vulnerability, please 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. repository.
</p> </p>