diff --git a/website/LICENSE.md b/website/LICENSE.md index f8bf349a8..3ab7c7eb8 100644 --- a/website/LICENSE.md +++ b/website/LICENSE.md @@ -6,5 +6,5 @@ this should make it clear: * The text contents of this website are MPL 2.0 licensed. * The design contents of this website are proprietary and may not be reproduced - or reused in any way other than to run the Vault website locally. The license + or reused in any way other than to run the Nomad website locally. The license for the design is owned solely by HashiCorp, Inc. diff --git a/website/config.rb b/website/config.rb index 0c7f7bdb2..aa8a6723e 100644 --- a/website/config.rb +++ b/website/config.rb @@ -2,12 +2,12 @@ # Configure Middleman #------------------------------------------------------------------------- -set :base_url, "https://www.vaultproject.io/" +set :base_url, "https://www.nomadproject.io/" activate :hashicorp do |h| - h.version = ENV["VAULT_VERSION"] + h.version = ENV["NOMAD_VERSION"] h.bintray_enabled = ENV["BINTRAY_ENABLED"] - h.bintray_repo = "mitchellh/vault" + h.bintray_repo = "mitchellh/nomad" h.bintray_user = "mitchellh" h.bintray_key = ENV["BINTRAY_API_KEY"] diff --git a/website/source/assets/images/global-arch.png b/website/source/assets/images/global-arch.png new file mode 100644 index 000000000..256c4a632 --- /dev/null +++ b/website/source/assets/images/global-arch.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ccd687b93da15d011ca7b660613e8847ab0b32964f1c4a63006c62c164e51b84 +size 49248 diff --git a/website/source/assets/images/region-arch.png b/website/source/assets/images/region-arch.png new file mode 100644 index 000000000..ad419c357 --- /dev/null +++ b/website/source/assets/images/region-arch.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2a4ee143be4cf4d5094b6d2ce4ee82d9e9943aae67a8f5d0e94186fca6c4d0cd +size 99318 diff --git a/website/source/community.html.erb b/website/source/community.html.erb index 57d64c39a..95d5ff282 100644 --- a/website/source/community.html.erb +++ b/website/source/community.html.erb @@ -2,36 +2,36 @@ layout: "inner" page_title: "Community" description: |- - Vault is an open source project with a growing community. + Nomad is an open source project with a growing community. ---

Community

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

-IRC: #vault-tool on Freenode +IRC: #nomad-tool on Freenode

Mailing list: -Vault Google Group +Nomad Google Group

Bug Tracker: -Issue tracker +Issue tracker on GitHub. Please only use this for reporting bugs. Do not ask for general help here. Use IRC or the mailing list for that.

People

-The following people are some of the faces behind Vault. They each -contribute to Vault in some core way. Over time, faces may appear and +The following people are some of the faces behind Nomad. They each +contribute to Nomad in some core way. Over time, faces may appear and disappear from this list as contributors come and go. In addition to -the faces below, Vault is a project by +the faces below, Nomad is a project by HashiCorp, so many HashiCorp -employees actively contribute to Vault. +employees actively contribute to Nomad.

@@ -39,8 +39,8 @@ employees actively contribute to Vault.

Mitchell Hashimoto (@mitchellh)

- Mitchell Hashimoto is the creator of Vault and works on all - layers of Vault from the core to backends. In addition to Vault, + Mitchell Hashimoto is the creator of Nomad and works on all + layers of Nomad from the core to backends. In addition to Nomad, Mitchell is the creator of Vagrant, Packer, @@ -55,7 +55,7 @@ employees actively contribute to Vault.

Armon Dadgar (@armon)

- 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 Consul, Serf, @@ -71,9 +71,9 @@ employees actively contribute to Vault.

Jack Pearkes (@pearkes)

- Jack Pearkes is the creator of the online interactive demo of Vault. + Jack Pearkes is the creator of the online interactive demo of Nomad. He maintains this demo as well as the design and interaction of the - Vault website. Jack is an employee of HashiCorp and a primary engineer + Nomad website. Jack is an employee of HashiCorp and a primary engineer behind Atlas. He is also a core committer to Packer, diff --git a/website/source/docs/audit/index.html.md b/website/source/docs/audit/index.html.md index 51f89303d..72122f56f 100644 --- a/website/source/docs/audit/index.html.md +++ b/website/source/docs/audit/index.html.md @@ -3,25 +3,25 @@ layout: "docs" page_title: "Audit Backends" sidebar_current: "docs-audit" description: |- - Audit backends are mountable backends that log requests and responses in Vault. + Audit backends are mountable backends that log requests and responses in Nomad. --- # Audit Backends -Audit backends are the components in Vault that keep a detailed log -of all requests and response to Vault. Because _every_ operation with -Vault is an API request/response, the audit log contains _every_ interaction -with Vault, including errors. +Audit backends are the components in Nomad that keep a detailed log +of all requests and response to Nomad. Because _every_ operation with +Nomad is an API request/response, the audit log contains _every_ interaction +with Nomad, including errors. -Vault ships with multiple audit backends, depending on the location you want -the logs sent to. Multiple audit backends can be enabled and Vault will send +Nomad ships with multiple audit backends, depending on the location you want +the logs sent to. Multiple audit backends can be enabled and Nomad will send the audit logs to both. This allows you to not only have a redundant copy, but also a second copy in case the first is tampered with. ## Sensitive Information The audit logs contain the full request and response objects for every -interaction with Vault. The data in the request and the data in the +interaction with Nomad. The data in the request and the data in the response (including secrets and authentication tokens) will be hashed without a salt using SHA1. @@ -31,7 +31,7 @@ secrets by SHA-ing it yourself. ## Enabling/Disabling Audit Backends -When a Vault server is first initialized, no auditing is enabled. Audit +When a Nomad server is first initialized, no auditing is enabled. Audit backends must be enabled by a root user using `vault audit-enable`. When enabling an audit backend, options can be passed to it to configure it. @@ -51,17 +51,17 @@ The existing logs that it did store are untouched. ## Blocked Audit Backends -If there are any audit backends enabled, Vault requires that at least -one be able to persist the log before completing a Vault request. +If there are any audit backends enabled, Nomad requires that at least +one be able to persist the log before completing a Nomad request. If you have only one audit backend enabled, and it is blocking (network -block, etc.), then Vault will be _unresponsive_. Vault _will not_ complete +block, etc.), then Nomad will be _unresponsive_. Nomad _will not_ complete any requests until the audit backend can write. -If you have more than one audit backend, then Vault will complete the request +If you have more than one audit backend, then Nomad will complete the request as long as one audit backend persists the log. -Vault will not respond to requests if audit backends are blocked because +Nomad will not respond to requests if audit backends are blocked because audit logs are critically important and ignoring blocked requests opens an avenue for attack. Be absolutely certain that your audit backends cannot block. diff --git a/website/source/docs/audit/syslog.html.md b/website/source/docs/audit/syslog.html.md index 2b0a94025..afca907c9 100644 --- a/website/source/docs/audit/syslog.html.md +++ b/website/source/docs/audit/syslog.html.md @@ -14,7 +14,7 @@ The "syslog" audit backend writes audit logs to syslog. It currently does not support a configurable syslog destination, and always sends to the local agent. This backend is only supported on Unix systems, -and should not be enabled if any standby Vault instances do not support it. +and should not be enabled if any standby Nomad instances do not support it. ## Options diff --git a/website/source/docs/auth/app-id.html.md b/website/source/docs/auth/app-id.html.md index 579930fc8..51927d2c7 100644 --- a/website/source/docs/auth/app-id.html.md +++ b/website/source/docs/auth/app-id.html.md @@ -3,7 +3,7 @@ layout: "docs" page_title: "Auth Backend: App ID" sidebar_current: "docs-auth-appid" description: |- - The App ID auth backend is a mechanism for machines to authenticate with Vault. + The App ID auth backend is a mechanism for machines to authenticate with Nomad. --- # Auth Backend: App ID @@ -11,13 +11,13 @@ description: |- Name: `app-id` The App ID auth backend is a mechanism for machines to authenticate with -Vault. It works by requiring two hard-to-guess unique pieces of information: +Nomad. It works by requiring two hard-to-guess unique pieces of information: a unique app ID, and a unique user ID. The goal of this credential provider is to allow elastic users -(dynamic machines, containers, etc.) to authenticate with Vault without -having to store passwords outside of Vault. It is a single method of -solving the chicken-and-egg problem of setting up Vault access on a machine. +(dynamic machines, containers, etc.) to authenticate with Nomad without +having to store passwords outside of Nomad. It is a single method of +solving the chicken-and-egg problem of setting up Nomad access on a machine. With this provider, nobody except the machine itself has access to both pieces of information necessary to authenticate. For example: configuration management will have the app IDs, but the machine itself @@ -40,7 +40,7 @@ An example, real world process for using this provider: 4. A new server is provisioned. Configuration management configures the app ID, the server itself detects its user ID. With both of these - pieces of information, Vault can be accessed according to the policy + pieces of information, Nomad can be accessed according to the policy set by the app ID. More details on this process follow: diff --git a/website/source/docs/auth/cert.html.md b/website/source/docs/auth/cert.html.md index b2cb75166..70c529b76 100644 --- a/website/source/docs/auth/cert.html.md +++ b/website/source/docs/auth/cert.html.md @@ -3,7 +3,7 @@ layout: "docs" page_title: "Auth Backend: TLS Certificates" sidebar_current: "docs-auth-cert" description: |- - The "cert" auth backend allows users to authenticate with Vault using TLS client certificates. + The "cert" auth backend allows users to authenticate with Nomad using TLS client certificates. --- # Auth Backend: TLS Certificates diff --git a/website/source/docs/auth/github.html.md b/website/source/docs/auth/github.html.md index 5d290a9ef..f8afd0506 100644 --- a/website/source/docs/auth/github.html.md +++ b/website/source/docs/auth/github.html.md @@ -3,17 +3,17 @@ layout: "docs" page_title: "Auth Backend: GitHub" sidebar_current: "docs-auth-github" description: |- - The GitHub auth backend allows authentication with Vault using GitHub. + The GitHub auth backend allows authentication with Nomad using GitHub. --- # Auth Backend: GitHub Name: `github` -The GitHub auth backend can be used to authenticate with Vault using +The GitHub auth backend can be used to authenticate with Nomad using a GitHub personal access token. This method of authentication is most useful for humans: operators or -developers using Vault directly via the CLI. +developers using Nomad directly via the CLI. ## Authentication @@ -63,7 +63,7 @@ Success! Data written to: auth/github/config ``` After configuring that, you must map the teams of that organization to -policies within Vault. Use the `map/teams/` endpoints to do that. +policies within Nomad. Use the `map/teams/` endpoints to do that. Example: ``` @@ -71,7 +71,7 @@ $ vault write auth/github/map/teams/owners value=root Success! Data written to: auth/github/map/teams/owners ``` -The above would make anyone in the "owners" team a root user in Vault +The above would make anyone in the "owners" team a root user in Nomad (not recommended). You can then auth with a user that is a member of the "owners" team using a Personal Access Token with the `read:org` scope. diff --git a/website/source/docs/auth/index.html.md b/website/source/docs/auth/index.html.md index 210505fa2..37c2dcef6 100644 --- a/website/source/docs/auth/index.html.md +++ b/website/source/docs/auth/index.html.md @@ -3,17 +3,17 @@ layout: "docs" page_title: "Auth Backends" sidebar_current: "docs-auth" description: |- - Auth backends are mountable backends that perform authentication for Vault. + Auth backends are mountable backends that perform authentication for Nomad. --- # Auth Backends -Auth backends are the components in Vault that perform authentication +Auth backends are the components in Nomad that perform authentication and are responsible for assigning identity and a set of policies to a user. Having multiple auth backends enables you to use an auth backend -that makes the sense for your use case of Vault and your organization. +that makes the sense for your use case of Nomad and your organization. For example, on developer machines, the [GitHub auth backend](/docs/auth/github.html) is easiest to use. But for servers the [App ID](/docs/auth/app-id.html) @@ -27,7 +27,7 @@ To learn more about authentication, see the Auth backends can be enabled/disabled using the CLI or the API. When enabled, auth backends are similar to [secret backends](/docs/secrets/index.html): -they are mounted within the Vault mount table and can be accessed +they are mounted within the Nomad mount table and can be accessed and configured using the standard read/write API. The only difference is that all auth backends are mounted underneath the `auth/` prefix. diff --git a/website/source/docs/auth/ldap.html.md b/website/source/docs/auth/ldap.html.md index cf4c2fb5b..ad7130a69 100644 --- a/website/source/docs/auth/ldap.html.md +++ b/website/source/docs/auth/ldap.html.md @@ -3,7 +3,7 @@ layout: "docs" page_title: "Auth Backend: LDAP" sidebar_current: "docs-auth-ldap" description: |- - The "ldap" auth backend allows users to authenticate with Vault using LDAP credentials. + The "ldap" auth backend allows users to authenticate with Nomad using LDAP credentials. --- # Auth Backend: LDAP @@ -11,11 +11,11 @@ description: |- Name: `ldap` The "ldap" auth backend allows authentication using an existing LDAP -server and user/password credentials. This allows Vault to be integrated +server and user/password credentials. This allows Nomad to be integrated into environments using LDAP without duplicating the user/pass configuration in multiple places. -The mapping of groups in LDAP to Vault policies is managed by using the +The mapping of groups in LDAP to Nomad policies is managed by using the `users/` and `groups/` paths. ## Authentication @@ -100,13 +100,13 @@ $ vault write auth/ldap/config url="ldap://ldap.forumsys.com" \ The above configures the target LDAP server, along with the parameters specifying how users and groups should be queried from the LDAP server. -Next we want to create a mapping from an LDAP group to a Vault policy: +Next we want to create a mapping from an LDAP group to a Nomad policy: ``` $ vault write auth/ldap/groups/scientists policies=foo,bar ``` -This maps the LDAP group "scientists" to the "foo" and "bar" Vault policies. +This maps the LDAP group "scientists" to the "foo" and "bar" Nomad policies. We can also add specific LDAP users to additional (potentially non-LDAP) groups: @@ -116,7 +116,7 @@ $ vault write auth/ldap/users/tesla groups=engineers ``` This adds the LDAP user "tesla" to the "engineers" group, which maps to -the "foobar" Vault policy. +the "foobar" Nomad policy. Finally, we can test this by authenticating: diff --git a/website/source/docs/auth/token.html.md b/website/source/docs/auth/token.html.md index 83763cd23..2707039af 100644 --- a/website/source/docs/auth/token.html.md +++ b/website/source/docs/auth/token.html.md @@ -14,7 +14,7 @@ built-in CLI methods such as `vault token-create`. It allows users to authenticate using a token, as well to create new tokens, revoke secrets by token, and more. -When any other auth backend returns an identity, Vault core invokes the +When any other auth backend returns an identity, Nomad core invokes the token backend to create a new unique token for that identity. The token store can also be used to bypass any other auth backend: diff --git a/website/source/docs/auth/userpass.html.md b/website/source/docs/auth/userpass.html.md index 32e795938..8f05c694f 100644 --- a/website/source/docs/auth/userpass.html.md +++ b/website/source/docs/auth/userpass.html.md @@ -3,14 +3,14 @@ layout: "docs" page_title: "Auth Backend: Username & Password" sidebar_current: "docs-auth-userpass" description: |- - The "userpass" auth backend allows users to authenticate with Vault using a username and password. + The "userpass" auth backend allows users to authenticate with Nomad using a username and password. --- # Auth Backend: Username & Password Name: `userpass` -The "userpass" auth backend allows users to authenticate with Vault using +The "userpass" auth backend allows users to authenticate with Nomad using a username and password combination. The username/password combinations are configured directly to the auth diff --git a/website/source/docs/concepts/auth.html.md b/website/source/docs/concepts/auth.html.md index 873759a83..5737cd586 100644 --- a/website/source/docs/concepts/auth.html.md +++ b/website/source/docs/concepts/auth.html.md @@ -3,23 +3,23 @@ layout: "docs" page_title: "Authentication" sidebar_current: "docs-concepts-auth" description: |- - Before performing any operation with Vault, the connecting client must be authenticated. + Before performing any operation with Nomad, the connecting client must be authenticated. --- # Authentication -Before performing any operation with Vault, the connecting client must be +Before performing any operation with Nomad, the connecting client must be _authenticated_. Authentication is the process of verifying a person or machine is who they say they are and assigning an identity to them. This -identity is then used when making requests with Vault. +identity is then used when making requests with Nomad. -Authentication in Vault is pluggable via authentication backends. This -allows you to authenticate with Vault using a method that works best for your +Authentication in Nomad is pluggable via authentication backends. This +allows you to authenticate with Nomad using a method that works best for your organization. For example, you can authenticate using GitHub, certs, etc. ## Authentication Backends -There are many authentication backends available for Vault. They +There are many authentication backends available for Nomad. They are enabled using `vault auth-enable`. After they're enabled, you can learn more about them using `vault path-help auth/`. For example, if you enable GitHub, you can use `vault path-help auth/github` to learn more @@ -40,7 +40,7 @@ but it is important to understand that authentication works by verifying your identity and then generating a token to associate with that identity. For example, even though you may authenticate using something like GitHub, -Vault generates a unique access token for you to use for future requests. +Nomad generates a unique access token for you to use for future requests. The CLI automatically attaches this token to requests, but if you're using the API you'll have to do this manually. @@ -88,7 +88,7 @@ be used. Just like secrets, identities have [leases](/docs/concepts/lease.html) associated with them. This means that you must reauthenticate after the given lease period to continue accessing -Vault. +Nomad. To set the lease associated with an identity, reference the help for the specific authentication backend in use. It is specific to each backend diff --git a/website/source/docs/concepts/dev-server.html.md b/website/source/docs/concepts/dev-server.html.md index b7c35f7a4..f579e4a3b 100644 --- a/website/source/docs/concepts/dev-server.html.md +++ b/website/source/docs/concepts/dev-server.html.md @@ -3,15 +3,15 @@ layout: "docs" page_title: "Dev Server Mode" sidebar_current: "docs-concepts-devserver" description: |- - The dev server in Vault can be used for development or to experiment with Vault. + The dev server in Nomad can be used for development or to experiment with Nomad. --- # "Dev" Server Mode -You can start Vault as a server in "dev" mode like so: `vault server -dev`. +You can start Nomad as a server in "dev" mode like so: `vault server -dev`. This dev-mode server requires no further setup, and your local `vault` CLI will -be authenticated to talk to it. This makes it easy to experiment with Vault or -start a Vault instance for development. Every feature of Vault is available in +be authenticated to talk to it. This makes it easy to experiment with Nomad or +start a Nomad instance for development. Every feature of Nomad is available in "dev" mode. The `-dev` flag just short-circuits a lot of setup to insecure defaults. @@ -27,25 +27,25 @@ The properties of the dev server: and unsealed. You don't need to use `vault unseal`. It is ready for use immediately. - * **In-memory storage** - All data is stored (encrypted) in-memory. Vault + * **In-memory storage** - All data is stored (encrypted) in-memory. Nomad server doesn't require any file permissions. * **Bound to local address without TLS** - The server is listening on `127.0.0.1:8200` (the default server address) _without_ TLS. * **Automatically Authenticated** - The server stores your root access - token so `vault` CLI access is ready to go. If you are accessing Vault + token so `vault` CLI access is ready to go. If you are accessing Nomad via the API, you'll need to authenticate using the token printed out. * **Single unseal key** - The server is initialized with a single unseal - key. The Vault is already unsealed, but if you want to experiment with + key. The Nomad is already unsealed, but if you want to experiment with seal/unseal, then only the single outputted key is required. ## Use Case -The dev server should be used for experimentation with Vault features, such +The dev server should be used for experimentation with Nomad features, such as different authentication backends, secret backends, audit backends, etc. -If you're new to Vault, you may want to pick up with [Your First +If you're new to Nomad, you may want to pick up with [Your First Secret](http://vaultproject.io/intro/getting-started/first-secret.html) in our getting started guide. diff --git a/website/source/docs/concepts/ha.html.markdown b/website/source/docs/concepts/ha.html.markdown index 0058aed43..630d7f45c 100644 --- a/website/source/docs/concepts/ha.html.markdown +++ b/website/source/docs/concepts/ha.html.markdown @@ -3,29 +3,29 @@ layout: "docs" page_title: "High Availability" sidebar_current: "docs-concepts-ha" description: |- - Vault can be highly available, allowing you to run multiple Vaults to protect against outages. + Nomad can be highly available, allowing you to run multiple Nomads to protect against outages. --- # High Availability Mode (HA) -Vault supports multi-server mode for high availability. This mode protects -against outages by running multiple Vault servers. High availability mode +Nomad supports multi-server mode for high availability. This mode protects +against outages by running multiple Nomad servers. High availability mode is automatically enabled when using a storage backend that supports it. You can tell if a backend supports high availability mode ("HA") by starting the server and seeing if "(HA available)" is outputted next to the backend information. If it is, then HA will begin happening automatically. -To be highly available, Vault elects a leader and does request forwarding to +To be highly available, Nomad elects a leader and does request forwarding to the leader. Due to this architecture, HA does not enable increased scalability. -In general, the bottleneck of Vault is the storage backend itself, not -Vault core. For example: to increase scalability of Vault with Consul, you -would scale Consul instead of Vault. +In general, the bottleneck of Nomad is the storage backend itself, not +Nomad core. For example: to increase scalability of Nomad with Consul, you +would scale Consul instead of Nomad. In addition to using a backend that supports HA, you have to configure -Vault with an _advertise address_. This is the address that Vault advertises -to other Vault servers in the cluster for request forwarding. By default, -Vault will use the first private IP address it finds, but you can override +Nomad with an _advertise address_. This is the address that Nomad advertises +to other Nomad servers in the cluster for request forwarding. By default, +Nomad will use the first private IP address it finds, but you can override this to any address you want. ## Backend Support diff --git a/website/source/docs/concepts/index.html.md b/website/source/docs/concepts/index.html.md index 37063f5bd..94675d2c4 100644 --- a/website/source/docs/concepts/index.html.md +++ b/website/source/docs/concepts/index.html.md @@ -3,14 +3,14 @@ layout: "docs" page_title: "Basic Concepts" sidebar_current: "docs-concepts" description: |- - Basic concepts that are important to understand for Vault usage. + Basic concepts that are important to understand for Nomad usage. --- # Basic Concepts This section covers some high level basic concepts that are important -to understand for day to day Vault usage and operation. Every page in +to understand for day to day Nomad usage and operation. Every page in this section is recommended reading for anyone consuming or operating -Vault. +Nomad. Please use the navigation to the left to learn more about a topic. diff --git a/website/source/docs/concepts/lease.html.md b/website/source/docs/concepts/lease.html.md index 267190efa..fc89b9e79 100644 --- a/website/source/docs/concepts/lease.html.md +++ b/website/source/docs/concepts/lease.html.md @@ -3,22 +3,22 @@ layout: "docs" page_title: "Lease, Renew, and Revoke" sidebar_current: "docs-concepts-lease" description: |- - Vault provides a lease with every secret. When this lease is expired, Vault will revoke that secret. + Nomad provides a lease with every secret. When this lease is expired, Nomad will revoke that secret. --- # Lease, Renew, and Revoke -With every secret and authentication token, Vault provides a _lease_: -an amount of time that Vault promises that the data will be valid for. -Once the lease is up, Vault can automatically revoke the data, and the +With every secret and authentication token, Nomad provides a _lease_: +an amount of time that Nomad promises that the data will be valid for. +Once the lease is up, Nomad can automatically revoke the data, and the consumer of the secret can no longer be certain that it is valid. The benefit should be clear: consumers of secrets need to check in with -Vault routinely to either renew the lease (if allowed) or request a -replacement secret. This makes the Vault audit logs more valuable and +Nomad routinely to either renew the lease (if allowed) or request a +replacement secret. This makes the Nomad audit logs more valuable and also makes key rolling a lot easier. -All secrets in Vault are required to have a lease. Even if the data is +All secrets in Nomad are required to have a lease. Even if the data is meant to be valid for eternity, a lease is required to force the consumer to check in routinely. @@ -33,12 +33,12 @@ be deleted from AWS the moment a secret is revoked. This renders the access keys invalid from that point forward. Revocation can happen manually via the API or `vault revoke`, or automatically -by Vault. When a lease is expired, Vault will automatically revoke that +by Nomad. When a lease is expired, Nomad will automatically revoke that lease. ## Lease IDs -When reading a secret, such as via `vault read`, Vault always returns +When reading a secret, such as via `vault read`, Nomad always returns a `lease_id`. This is the ID used with commands such as `vault renew` and `vault revoke` to manage the lease of the secret. diff --git a/website/source/docs/concepts/policies.html.md b/website/source/docs/concepts/policies.html.md index ebe476b68..5e9d38184 100644 --- a/website/source/docs/concepts/policies.html.md +++ b/website/source/docs/concepts/policies.html.md @@ -3,18 +3,18 @@ layout: "docs" page_title: "Policies" sidebar_current: "docs-concepts-policies" description: |- - Policies are how authorization is done in Vault, allowing you to restrict which parts of Vault a user can access. + Policies are how authorization is done in Nomad, allowing you to restrict which parts of Nomad a user can access. --- # Access Control Policies -After [authenticating](/docs/concepts/auth.html) with Vault, the +After [authenticating](/docs/concepts/auth.html) with Nomad, the next step is authorization. This is the process of determining what -a user is allowed to do. Authorization is unified in Vault in the form +a user is allowed to do. Authorization is unified in Nomad in the form of _policies_. Policies are [HCL](https://github.com/hashicorp/hcl) or JSON documents -that describe what parts of Vault a user is allowed to access. An example +that describe what parts of Nomad a user is allowed to access. An example of a policy is shown below: ```javascript @@ -37,8 +37,8 @@ path "secret/super-secret" { Policies use path based matching to apply rules. A policy may be an exact match, or might be a glob pattern which uses a prefix. The default policy -is always deny so if a path isn't explicitly allowed, Vault will reject access to it. -This works well due to Vault's architecture of being like a filesystem: +is always deny so if a path isn't explicitly allowed, Nomad will reject access to it. +This works well due to Nomad's architecture of being like a filesystem: everything has a path associated with it, including the core configuration mechanism under "sys". @@ -59,7 +59,7 @@ Allowed policies for a path are: * `read` - Read-only access to a path. -The only non-obvious policy is "sudo". Some routes within Vault and mounted +The only non-obvious policy is "sudo". Some routes within Nomad and mounted backends are marked as _root_ paths. Clients aren't allowed to access root paths unless they are a root user (have the special policy "root") or have access to that path with the "sudo" policy. @@ -71,7 +71,7 @@ Only root or "sudo" privilege users are allowed to do this. The "root" policy is a special policy that can not be modified or removed. Any user associated with the "root" policy becomes a root user. A root -user can do _anything_ within Vault. +user can do _anything_ within Nomad. There always exists at least one root user (associated with the token when initializing a new server). After this root user, it is recommended @@ -104,7 +104,7 @@ active identity. ## Changes from 0.1 -In Vault versions prior to 0.2, the ACL policy language had a slightly +In Nomad versions prior to 0.2, the ACL policy language had a slightly different specification and semantics. The current specification requires that glob behavior explicitly be specified by adding the `*` character to the end of a path. Previously, all paths were glob based matches and no @@ -125,9 +125,9 @@ path "sys/seal" { ``` The merge would previously give the "read" higher precedence. The current -version of Vault prioritizes the explicit deny, so that the "deny" would +version of Nomad prioritizes the explicit deny, so that the "deny" would take precedence. -To make all Vault 0.1 policies compatible with Vault 0.2, the explicit +To make all Nomad 0.1 policies compatible with Nomad 0.2, the explicit glob character must be added to all the path prefixes. diff --git a/website/source/docs/concepts/seal.html.md b/website/source/docs/concepts/seal.html.md index e980c3d06..165536bfd 100644 --- a/website/source/docs/concepts/seal.html.md +++ b/website/source/docs/concepts/seal.html.md @@ -3,36 +3,36 @@ layout: "docs" page_title: "Seal/Unseal" sidebar_current: "docs-concepts-seal" description: |- - A Vault must be unsealed before it can access its data. Likewise, it can be sealed to lock it down. + A Nomad must be unsealed before it can access its data. Likewise, it can be sealed to lock it down. --- # Seal/Unseal -When a Vault server is started, it starts in a _sealed_ state. In this -state, Vault is configured to know where and how to access the physical +When a Nomad server is started, it starts in a _sealed_ state. In this +state, Nomad is configured to know where and how to access the physical storage, but doesn't know how to decrypt any of it. _Unsealing_ is the process of constructing the master key necessary to -read the decryption key to decrypt the data, allowing access to the Vault. +read the decryption key to decrypt the data, allowing access to the Nomad. -Prior to unsealing, almost no operations are possible with Vault. For +Prior to unsealing, almost no operations are possible with Nomad. For example authentication, managing the mount tables, etc. are all not possible. -The only possible operations are to unseal the Vault and check the status +The only possible operations are to unseal the Nomad and check the status of the unseal. ## Why? -The data stored by Vault is stored encrypted. Vault needs the +The data stored by Nomad is stored encrypted. Nomad needs the _encryption key_ in order to decrypt the data. The encryption key is also stored with the data, but encrypted with another encryption key known as the _master key_. The master key isn't stored anywhere. -Therefore, to decrypt the data, Vault must decrypt the encryption key +Therefore, to decrypt the data, Nomad must decrypt the encryption key which requires the master key. Unsealing is the process of reconstructing this master key. Instead of distributing this master key as a single key to an operator, -Vault uses an algorithm known as +Nomad uses an algorithm known as [Shamir's Secret Sharing](http://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) to split the key into shards. A certain threshold of shards is required to reconstruct the master key. @@ -48,25 +48,25 @@ This process is stateful: each key can be entered via multiple mechanisms on multiple computers and it will work. This allows each shard of the master key to be on a distinct machine for better security. -Once a Vault is unsealed, it remains unsealed until one of two things happens: +Once a Nomad is unsealed, it remains unsealed until one of two things happens: 1. It is resealed via the API (see below). 2. The server is restarted. --> **Note:** Unsealing makes the process of automating a Vault install -difficult. Automated tools can easily install, configure, and start Vault, +-> **Note:** Unsealing makes the process of automating a Nomad install +difficult. Automated tools can easily install, configure, and start Nomad, but unsealing it is a very manual process. We have plans in the future to make it easier. For the time being, the best method is to manually unseal -multiple Vault servers in [HA mode](/docs/concepts/ha.html). Use a tool such -as Consul to make sure you only query Vault servers that are unsealed. +multiple Nomad servers in [HA mode](/docs/concepts/ha.html). Use a tool such +as Consul to make sure you only query Nomad servers that are unsealed. ## Sealing -There is also an API to seal the Vault. This will throw away the encryption +There is also an API to seal the Nomad. This will throw away the encryption key and require another unseal process to restore it. Sealing only requires a single operator with root privileges. -This way, if there is a detected intrusion, the Vault data can be locked +This way, if there is a detected intrusion, the Nomad data can be locked quickly to try to minimize damages. It can't be accessed again without access to the master key shards. diff --git a/website/source/docs/concepts/tokens.html.md b/website/source/docs/concepts/tokens.html.md index 8ecbd7690..f52f3f473 100644 --- a/website/source/docs/concepts/tokens.html.md +++ b/website/source/docs/concepts/tokens.html.md @@ -3,18 +3,18 @@ layout: "docs" page_title: "Tokens" sidebar_current: "docs-concepts-tokens" description: |- - Tokens are a core authentication method in Vault. Child tokens, token-based revocation, and more. + Tokens are a core authentication method in Nomad. Child tokens, token-based revocation, and more. --- # Tokens -Tokens are the core method for _authentication_ within Vault. Tokens +Tokens are the core method for _authentication_ within Nomad. Tokens can be used directly or [authentication backends](/docs/concepts/auth.html) can be used to dynamically generate tokens based on external identities. If you've gone through the getting started guide, you probably noticed that `vault server -dev` (or `vault init` for a non-dev server) outputs an -initial "root token." This is the first method of authentication for Vault. +initial "root token." This is the first method of authentication for Nomad. It is also the only authentication backend that cannot be disabled. As stated in the [authentication concepts](/docs/concepts/auth.html), @@ -47,7 +47,7 @@ with the token. Learn more about policies on the Every token has a lease associated with it. These leases behave in much the same way as [leases for secrets](/docs/concepts/lease.html). After the lease period is up, the token will no longer function. In addition -to no longer functioning, Vault will revoke it. +to no longer functioning, Nomad will revoke it. In order to avoid your token being revoked, the `vault token-renew` command should be used to renew the lease on the token periodically. diff --git a/website/source/docs/config/index.html.md b/website/source/docs/config/index.html.md index a9a5a81ef..7528a9b20 100644 --- a/website/source/docs/config/index.html.md +++ b/website/source/docs/config/index.html.md @@ -3,12 +3,12 @@ layout: "docs" page_title: "Server Configuration" sidebar_current: "docs-config" description: |- - Vault server configuration reference. + Nomad server configuration reference. --- # Server Configuration -Outside of development mode, Vault servers are configured using a file. +Outside of development mode, Nomad servers are configured using a file. The format of this file is [HCL](https://github.com/hashicorp/hcl) or JSON. An example configuration is shown below: @@ -34,11 +34,11 @@ to specify where the configuration is. ## Reference -* `backend` (required) - Configures the storage backend where Vault data +* `backend` (required) - Configures the storage backend where Nomad data is stored. There are multiple options available for storage backends, and they're documented below. -* `listener` (required) - Configures how Vault is listening for API requests. +* `listener` (required) - Configures how Nomad is listening for API requests. "tcp" is currently the only option available. A full reference for the inner syntax is below. @@ -59,9 +59,9 @@ to specify where the configuration is. In production, you should only consider setting the `disable_mlock` option on Linux systems that only use encrypted swap or do not use swap at all. -Vault does not currently support memory locking on Mac OS X and Windows +Nomad does not currently support memory locking on Mac OS X and Windows and so the feature is automatically disabled on those platforms. To give -the Vault executable access to the `mlock` syscall on Linux systems: +the Nomad executable access to the `mlock` syscall on Linux systems: ```shell sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault)) @@ -70,11 +70,11 @@ sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault)) ## Backend Reference For the `backend` section, the supported backends are shown below. -Vault requires that the backend itself will be responsible for backups, +Nomad requires that the backend itself will be responsible for backups, durability, etc. * `consul` - Store data within [Consul](http://www.consul.io). This - backend supports HA. It is the most recommended backend for Vault + backend supports HA. It is the most recommended backend for Nomad and has been shown to work at high scale under heavy load. * `etcd` - Store data within [etcd](https://coreos.com/etcd/). @@ -89,7 +89,7 @@ durability, etc. * `mysql` - Store data within MySQL. This backend does not support HA. * `inmem` - Store data in-memory. This is only really useful for - development and experimentation. Data is lost whenever Vault is + development and experimentation. Data is lost whenever Nomad is restarted. * `file` - Store data on the filesystem using a directory structure. @@ -100,7 +100,7 @@ durability, etc. All backends support the following options: * `advertise_addr` (optional) - For backends that support HA, this - is the address to advertise to other Vault servers in the cluster + is the address to advertise to other Nomad servers in the cluster for request forwarding. Most HA backends will attempt to determine the advertise address if not provided. @@ -213,7 +213,7 @@ The supported options are: defaults to "127.0.0.1:8200". * `tls_disable` (optional) - If non-empty, then TLS will be disabled. - This is an opt-in; Vault assumes by default that TLS will be used. + This is an opt-in; Nomad assumes by default that TLS will be used. * `tls_cert_file` (required unless disabled) - The path to the certificate for TLS. @@ -221,7 +221,7 @@ The supported options are: * `tls_key_file` (required unless disabled) - The path to the private key for the certificate. - * `tls_min_version` (optional) - **(Vault > 0.2)** If provided, specifies + * `tls_min_version` (optional) - **(Nomad > 0.2)** If provided, specifies the minimum supported version of TLS. Accepted values are "tls10", "tls11" or "tls12". This defaults to "tls12". WARNING: TLS 1.1 and lower are generally considered less secure; avoid using these if diff --git a/website/source/docs/http/index.html.md b/website/source/docs/http/index.html.md index 282eebf54..6eaa6d27f 100644 --- a/website/source/docs/http/index.html.md +++ b/website/source/docs/http/index.html.md @@ -3,14 +3,14 @@ layout: "http" page_title: "HTTP API" sidebar_current: "docs-http-overview" description: |- - Vault has an HTTP API that can be used to control every aspect of Vault. + Nomad has an HTTP API that can be used to control every aspect of Nomad. --- # HTTP API -The Vault HTTP API gives you full access to Vault via HTTP. Every -aspect of Vault can be controlled via this API. The Vault CLI uses -the HTTP API to access Vault. +The Nomad HTTP API gives you full access to Nomad via HTTP. Every +aspect of Nomad can be controlled via this API. The Nomad CLI uses +the HTTP API to access Nomad. ## Version Prefix @@ -18,10 +18,10 @@ All API routes are prefixed with `/v1/`. This documentation is only for the v1 API. -~> **Backwards compatibility:** At the current version, Vault does +~> **Backwards compatibility:** At the current version, Nomad does not yet promise backwards compatibility even with the v1 prefix. We'll remove this warning when this policy changes. We expect we'll reach API -stability by Vault 0.3. +stability by Nomad 0.3. ## Transport @@ -33,10 +33,10 @@ depending on user settings. ## Authentication -Once the Vault is unsealed, every other operation requires +Once the Nomad is unsealed, every other operation requires a _client token_. A user may have a client token explicitly. The client token must be sent as the `token` cookie or the -`X-Vault-Token` HTTP header. +`X-Nomad-Token` HTTP header. Otherwise, a client token can be retrieved via [authentication backends](/docs/auth/index.html). @@ -49,7 +49,7 @@ to each authentication backend. Login endpoints for authentication backends that generate an identity will be sent down with a `Set-Cookie` header as well as via JSON. If you have a well-behaved HTTP client, then authentication information will -automatically be saved and sent to the Vault API. +automatically be saved and sent to the Nomad API. ## Reading and Writing Secrets @@ -66,7 +66,7 @@ Here is an example of reading a secret using cURL: ```shell curl \ - -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ + -H "X-Nomad-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ -X GET \ http://127.0.0.1:8200/v1/secret/foo ``` @@ -89,18 +89,18 @@ Here is an example of writing a secret using cURL: ```shell curl \ - -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ + -H "X-Nomad-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ -H "Content-Type: application/json" \ -X POST \ -d '{"value":"bar"}' \ http://127.0.0.1:8200/v1/secret/baz ``` -For more examples, please look at the Vault API client. +For more examples, please look at the Nomad API client. ## Help -To retrieve the help for any API within Vault, including mounted +To retrieve the help for any API within Nomad, including mounted backends, credential providers, etc. then append `?help=1` to any URL. If you have valid permission to access the path, then the help text will be returned with the following structure: @@ -144,5 +144,5 @@ The following HTTP status codes are used throughout the API. of time. - `500` - Internal server error. An internal error has occurred, try again later. If the error persists, report a bug. -- `503` - Vault is down for maintenance or is currently sealed. +- `503` - Nomad is down for maintenance or is currently sealed. Try again later. diff --git a/website/source/docs/http/libraries.html.md b/website/source/docs/http/libraries.html.md index 26ed42b19..46ad58e65 100644 --- a/website/source/docs/http/libraries.html.md +++ b/website/source/docs/http/libraries.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: Libraries" sidebar_current: "docs-http-libraries" description: |- - List of official and community contributed libraries for interacting with the Vault HTTP API. + List of official and community contributed libraries for interacting with the Nomad HTTP API. --- # Libraries @@ -13,11 +13,11 @@ Some are officially maintained while others are provided by the community. ## Go -* [Vault Go Client](https://github.com/hashicorp/vault/tree/master/api) (official) +* [Nomad Go Client](https://github.com/hashicorp/vault/tree/master/api) (official) ## Ruby -* [Vault Ruby Client](https://github.com/hashicorp/vault-ruby) (official) +* [Nomad Ruby Client](https://github.com/hashicorp/vault-ruby) (official) ## Python diff --git a/website/source/docs/http/sys-auth.html.md b/website/source/docs/http/sys-auth.html.md index 777095d44..99e22eca5 100644 --- a/website/source/docs/http/sys-auth.html.md +++ b/website/source/docs/http/sys-auth.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: /sys/auth" sidebar_current: "docs-http-auth-auth" description: |- - The `/sys/auth` endpoint is used to manage auth backends in Vault. + The `/sys/auth` endpoint is used to manage auth backends in Nomad. --- # /sys/auth diff --git a/website/source/docs/http/sys-health.html.md b/website/source/docs/http/sys-health.html.md index 80e2d2b81..05d24164b 100644 --- a/website/source/docs/http/sys-health.html.md +++ b/website/source/docs/http/sys-health.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: /sys/health" sidebar_current: "docs-http-debug-health" description: |- - The '/sys/health' endpoint is used to check the health status of Vault. + The '/sys/health' endpoint is used to check the health status of Nomad. --- # /sys/health @@ -11,8 +11,8 @@ description: |-

Description
- Returns the health status of Vault. This matches the semantics of a Consul HTTP health - check and provides a simple way to monitor the health of a Vault instance. + Returns the health status of Nomad. This matches the semantics of a Consul HTTP health + check and provides a simple way to monitor the health of a Nomad instance.
Method
diff --git a/website/source/docs/http/sys-init.html.md b/website/source/docs/http/sys-init.html.md index 6b8695f92..f1d79be73 100644 --- a/website/source/docs/http/sys-init.html.md +++ b/website/source/docs/http/sys-init.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: /sys/init" sidebar_current: "docs-http-sys-init" description: |- - The '/sys/init' endpoint is used to initialize a new Vault. + The '/sys/init' endpoint is used to initialize a new Nomad. --- # /sys/init @@ -13,7 +13,7 @@ description: |-
Description
- Return the initialization status of a Vault. + Return the initialization status of a Nomad.
Method
@@ -39,7 +39,7 @@ description: |-
Description
- Initializes a new Vault. The Vault must've not been previously + Initializes a new Nomad. The Nomad must've not been previously initialized.
diff --git a/website/source/docs/http/sys-key-status.html.md b/website/source/docs/http/sys-key-status.html.md index 74d3ffde2..07cc58076 100644 --- a/website/source/docs/http/sys-key-status.html.md +++ b/website/source/docs/http/sys-key-status.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: /sys/key-status" sidebar_current: "docs-http-rotate-key-status" description: |- - The '/sys/key-status' endpoint is used to query info about the current encryption key of Vault. + The '/sys/key-status' endpoint is used to query info about the current encryption key of Nomad. --- # /sys/key-status @@ -11,7 +11,7 @@ description: |-
Description
- Returns information about the current encryption key used by Vault. + Returns information about the current encryption key used by Nomad.
Method
diff --git a/website/source/docs/http/sys-leader.html.md b/website/source/docs/http/sys-leader.html.md index 273ac3102..c1c12970f 100644 --- a/website/source/docs/http/sys-leader.html.md +++ b/website/source/docs/http/sys-leader.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: /sys/leader" sidebar_current: "docs-http-ha-leader" description: |- - The '/sys/leader' endpoint is used to check the high availability status and current leader of Vault. + The '/sys/leader' endpoint is used to check the high availability status and current leader of Nomad. --- # /sys/leader @@ -11,7 +11,7 @@ description: |-
Description
- Returns the high availability status and current leader instance of Vault. + Returns the high availability status and current leader instance of Nomad.
Method
diff --git a/website/source/docs/http/sys-mounts.html.md b/website/source/docs/http/sys-mounts.html.md index 0bdb4f9cd..e49076c85 100644 --- a/website/source/docs/http/sys-mounts.html.md +++ b/website/source/docs/http/sys-mounts.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: /sys/mounts" sidebar_current: "docs-http-mounts-mounts" description: |- - The '/sys/mounts' endpoint is used manage secret backends in Vault. + The '/sys/mounts' endpoint is used manage secret backends in Nomad. --- # /sys/mounts diff --git a/website/source/docs/http/sys-policy.html.md b/website/source/docs/http/sys-policy.html.md index e29359383..c252fc3a1 100644 --- a/website/source/docs/http/sys-policy.html.md +++ b/website/source/docs/http/sys-policy.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: /sys/policy" sidebar_current: "docs-http-auth-policy" description: |- - The `/sys/policy` endpoint is used to manage ACL policies in Vault. + The `/sys/policy` endpoint is used to manage ACL policies in Nomad. --- # /sys/policy diff --git a/website/source/docs/http/sys-raw.html.md b/website/source/docs/http/sys-raw.html.md index 2ce1a206f..03e5f0030 100644 --- a/website/source/docs/http/sys-raw.html.md +++ b/website/source/docs/http/sys-raw.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: /sys/raw" sidebar_current: "docs-http-debug-raw" description: |- - The `/sys/raw` endpoint is access the raw underlying store in Vault. + The `/sys/raw` endpoint is access the raw underlying store in Nomad. --- # /sys/raw diff --git a/website/source/docs/http/sys-rekey.html.md b/website/source/docs/http/sys-rekey.html.md index cd1349a61..cfbf2d2d5 100644 --- a/website/source/docs/http/sys-rekey.html.md +++ b/website/source/docs/http/sys-rekey.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: /sys/rekey/" sidebar_current: "docs-http-rotate-rekey" description: |- - The `/sys/rekey/` endpoints are used to rekey the unseal keys for Vault. + The `/sys/rekey/` endpoints are used to rekey the unseal keys for Nomad. --- # /sys/rekey/init @@ -116,8 +116,8 @@ description: |-
Description
- Enter a single master key share to progress the rekey of the Vault. - If the threshold number of master key shares is reached, Vault + Enter a single master key share to progress the rekey of the Nomad. + If the threshold number of master key shares is reached, Nomad will complete the rekey. Otherwise, this API must be called multiple times until that threshold is met.
diff --git a/website/source/docs/http/sys-seal-status.html.md b/website/source/docs/http/sys-seal-status.html.md index fa996f343..5e40ed932 100644 --- a/website/source/docs/http/sys-seal-status.html.md +++ b/website/source/docs/http/sys-seal-status.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: /sys/seal-status" sidebar_current: "docs-http-seal-status" description: |- - The '/sys/seal-status' endpoint is used to check the seal status of a Vault. + The '/sys/seal-status' endpoint is used to check the seal status of a Nomad. --- # /sys/seal-status @@ -11,7 +11,7 @@ description: |-
Description
- Returns the seal status of the Vault. + Returns the seal status of the Nomad.
Method
diff --git a/website/source/docs/http/sys-seal.html.md b/website/source/docs/http/sys-seal.html.md index 8f9765d4c..ccedcf099 100644 --- a/website/source/docs/http/sys-seal.html.md +++ b/website/source/docs/http/sys-seal.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: /sys/seal" sidebar_current: "docs-http-seal-seal" description: |- - The '/sys/seal' endpoint seals the Vault. + The '/sys/seal' endpoint seals the Nomad. --- # /sys/seal @@ -11,7 +11,7 @@ description: |-
Description
- Seals the Vault. + Seals the Nomad.
Method
diff --git a/website/source/docs/http/sys-unseal.html.md b/website/source/docs/http/sys-unseal.html.md index 699db4614..abe793ef7 100644 --- a/website/source/docs/http/sys-unseal.html.md +++ b/website/source/docs/http/sys-unseal.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API: /sys/seal-unseal" sidebar_current: "docs-http-seal-unseal" description: |- - The '/sys/seal-unseal' endpoint is used to unseal the Vault. + The '/sys/seal-unseal' endpoint is used to unseal the Nomad. --- # /sys/unseal @@ -11,9 +11,9 @@ description: |-
Description
- Enter a single master key share to progress the unsealing of the Vault. - If the threshold number of master key shares is reached, Vault - will attempt to unseal the Vault. Otherwise, this API must be + Enter a single master key share to progress the unsealing of the Nomad. + If the threshold number of master key shares is reached, Nomad + will attempt to unseal the Nomad. Otherwise, this API must be called multiple times until that threshold is met.
diff --git a/website/source/docs/index.html.markdown b/website/source/docs/index.html.markdown index f62c30f51..857f5c05c 100644 --- a/website/source/docs/index.html.markdown +++ b/website/source/docs/index.html.markdown @@ -3,12 +3,12 @@ layout: "docs" page_title: "Documentation" sidebar_current: "docs-home" description: |- - Welcome to the Vault documentation! This documentation is more of a reference guide for all available features and options of Vault. If you're just getting started with Vault, please start with the introduction and getting started guide instead. + Welcome to the Nomad documentation! This documentation is more of a reference guide for all available features and options of Nomad. If you're just getting started with Nomad, please start with the introduction and getting started guide instead. --- -# Vault Documentation +# Nomad Documentation -Welcome to the Vault documentation! This documentation is more of a reference -guide for all available features and options of Vault. If you're just getting -started with Vault, please start with the +Welcome to the Nomad documentation! This documentation is more of a reference +guide for all available features and options of Nomad. If you're just getting +started with Nomad, please start with the [introduction and getting started guide](/intro/index.html) instead. diff --git a/website/source/docs/install/index.html.md b/website/source/docs/install/index.html.md index 3fef65c65..183f83bcc 100644 --- a/website/source/docs/install/index.html.md +++ b/website/source/docs/install/index.html.md @@ -1,24 +1,24 @@ --- layout: "docs" -page_title: "Install Vault" +page_title: "Install Nomad" sidebar_current: "docs-install" description: |- - Learn how to install Vault. + Learn how to install Nomad. --- -# Install Vault +# Install Nomad -Installing Vault is simple. There are two approaches to installing Vault: +Installing Nomad is simple. There are two approaches to installing Nomad: downloading a precompiled binary for your system, or installing from source. Downloading a precompiled binary is easiest, and we provide downloads over TLS along with SHA256 sums to verify the binary is what we say it is. We also distribute a PGP signature with the SHA256 sums that can be verified. However, we use a 3rd party storage host, and some people feel that -due to the importance of security with Vault, they'd rather compile it +due to the importance of security with Nomad, they'd rather compile it from source. -For this reason, we also document on this page how to compile Vault +For this reason, we also document on this page how to compile Nomad from source, from the same versions of all dependent libraries that we used for the official builds. @@ -26,13 +26,13 @@ we used for the official builds. To install the precompiled binary, [download](/downloads.html) the appropriate package for your system. -Vault is currently packaged as a zip file. We don't have any near term +Nomad is currently packaged as a zip file. We don't have any near term plans to provide system packages. Once the zip is downloaded, unzip it into any directory. The -`vault` binary inside is all that is necessary to run Vault (or +`vault` binary inside is all that is necessary to run Nomad (or `vault.exe` for Windows). Any additional files, if any, aren't -required to run Vault. +required to run Nomad. Copy the binary to anywhere on your system. If you intend to access it from the command-line, make sure to place it somewhere on your `PATH`. @@ -42,22 +42,22 @@ from the command-line, make sure to place it somewhere on your `PATH`. To compile from source, you'll need [Go](https://golang.org) installed and configured properly. You'll also need Git. - 1. Clone the Vault repository into your GOPATH: https://github.com/hashicorp/vault + 1. Clone the Nomad repository into your GOPATH: https://github.com/hashicorp/vault 1. Verify that the file `$GOPATH/src/github.com/hashicorp/vault/main.go` - exists. If it doesn't, then you didn't clone Vault into the proper + exists. If it doesn't, then you didn't clone Nomad into the proper path. - 1. Run `make dev`. This will build Vault for your current system + 1. Run `make dev`. This will build Nomad for your current system and put the binary in `bin` (relative to the git checkout). -~> **Note:** All the dependencies of Vault are vendored and the command +~> **Note:** All the dependencies of Nomad are vendored and the command above will use these vendored binaries. This is to avoid malicious upstream dependencies if possible. ## Verifying the Installation -To verify Vault is properly installed, execute the `vault` binary on +To verify Nomad is properly installed, execute the `vault` binary on your system. You should see help output. If you are executing it from the command line, make sure it is on your PATH or you may get an error about `vault` not being found. diff --git a/website/source/docs/internals/architecture.html.md b/website/source/docs/internals/architecture.html.md index c1f2b062e..982394550 100644 --- a/website/source/docs/internals/architecture.html.md +++ b/website/source/docs/internals/architecture.html.md @@ -3,155 +3,130 @@ layout: "docs" page_title: "Architecture" sidebar_current: "docs-internals-architecture" description: |- - Learn about the internal architecture of Vault. + Learn about the internal architecture of Nomad. --- # Architecture -Vault is a complex system that has many different pieces. To help both users and developers of Vault +Nomad is a complex system that has many different pieces. To help both users and developers of Nomad build a mental model of how it works, this page documents the system architecture. ~> **Advanced Topic!** This page covers technical details -of Vault. You don't need to understand these details to -effectively use Vault. The details are documented here for +of Nomad. You don't need to understand these details to +effectively use Nomad. The details are documented here for those who wish to learn about them without having to go -spelunking through the source code. However, if you're an -operator of Vault, we recommend learning about the architecture -due to the importance of Vault in an environment. +spelunking through the source code. # Glossary Before describing the architecture, we provide a glossary of terms to help clarify what is being discussed: -* **Storage Backend** - A storage backend is responsible for durable storage of _encrypted_ data. - Backends are not trusted by Vault and are only expected to provide durability. The storage - backend is configured when starting the Vault server. +* **Job** - A Job is a specification provided by users that declares a workload for + Nomad. A Job is a form of _desired state_, the user is expressing that the job should + be running, but not where it should be run. The responsibility of Nomad is to make sure + the _actual state_ matches the user desired state. A Job is composed of one or more + task groups. -* **Barrier** - The barrier is cryptographic steel and concrete around the Vault. All data that - flows between Vault and the Storage Backend passes through the barrier. The barrier ensures - that only encrypted data is written out, and that data is verified and decrypted on the way - in. Much like a bank vault, the barrier must be "unsealed" before anything inside can be accessed. +* **Task Group** - A Task Group is a set of tasks that must be run together. For example, a + web server may require that a log shipping co-process is always running as well. A task + group is the unit of scheduling, meaning the entire group must run on a client node and + cannot be split. -* **Secret Backend** - A secret backend is responsible for managing secrets. Simple secret backends - like the "generic" backend simply return the same secret when queried. Some backends support - using policies to dynamically generate a secret each time they are queried. This allows for - unique secrets to be used which allows Vault to do fine-grained revocation and policy updates. - As an example, a MySQL backend could be configured with a "web" policy. When the "web" secret - is read, a new MySQL user/password pair will be generated with a limited set of privileges - for the web server. +* **Task** - A Task is the smallest unit of work in Nomad. Tasks are executed by drivers, + which allow Nomad to be flexible in the types of tasks it supports. Examples include Docker, + Qemu, Java and static binaries. Tasks specify their driver, configuration for the driver, + constraints, and resources required. -* **Audit Backend** - An audit backend is responsible for managing audit logs. Every request to Vault - and response from Vault goes through the configured audit backends. This provides a simple - way to integrate Vault with multiple audit logging destinations of different types. +* **Client** - A Client of Nomad is a machine that tasks can be run on. All clients run the + Nomad agent. The agent is responsible for registering with the servers, watching for any + work to be assigned and executing tasks. The Nomad agent is a long lived process which + interfaces with the servers. -* **Credential Backend** - A credential backend is used to authenticate users or applications which - are connecting to Vault. Once authenticated, the backend returns the list of applicable policies - which should be applied. Vault takes an authenticated user and returns a client token that can - be used for future requests. As an example, the `user-password` backend uses a username and password - to authenticate the user. Alternatively, the `github` backend allows users to authenticate - via GitHub. +* **Server** - Nomad servers are the brains of the cluster. There is a cluster of servers + per region and they manage all jobs and clients, run evalutations and create task allocations. + The servers replicate data between each other and perform leader election to ensure high + availability. Servers federate across regions to make Nomad globally aware. -* **Client Token** - A client token is a conceptually similar to a session cookie on a web site. - Once a user authenticates, Vault returns a client token which is used for future requests. - The token is used by Vault to verify the identity of the client and to enforce the applicable - ACL policies. +* **Regions and Datacenters** - Nomad models infrastructure as regions and datacenters. + Regions may contain multiple datacenters. Servers are assigned to regions and manage + all state for the region and make scheduling decisions within that region. Requests that + are made between regions are forwarded to the appropriate servers. As an example, you may + have a "US" region with the "us-east-1" and "us-west-1" datacenters, connected to the + "EU" region with the "eu-fr-1" and "eu-uk-1" datacenters. -* **Secret** - A secret is the term for anything returned by Vault which contains confidential - or cryptographic material. Not everything returned by Vault is a secret, for example - system configuration, status information, or backend policies are not considered Secrets. - Secrets always have an associated lease. This means clients cannot assume that the secret - contents can be used indefinitely. Vault will revoke a secret at the end of the lease, and - an operator may intervene to revoke the secret before the lease is over. This contract - between Vault and its clients is critical, as it allows for changes in keys and policies - without manual intervention. +* **Evaluation** - Evaluations are the mechanism by which Nomad makes scheduling decisions. + When either the _desired state_ (jobs) or _actual state_ (clients) changes, Nomad creates + a new evaluation to determine if any actions must be taken. An evaluation may result + in changes to allocations if necessary. -* **Server** - Vault depends on a long-running instance which operates as a server. - The Vault server provides an API which clients interact with and manages the - interaction between all the backends, ACL enforcement, and secret lease revocation. - Having a server based architecture decouples clients from the security keys and policies, - enables centralized audit logging and simplifies administration for operators. +* **Allocation** - An Allocation is a mapping between a task group in a job, and a client + node. A single job may have hundreds or thousands of task groups, meaning an equivalent + number of allocations must exist to map the work to client machines. Allocations are created + by the Nomad servers as part of scheduling decisions made during an evaluation. + +* **Bin Packing** - Bin Packing is the process of filling bins with items in a way that + maximizes the utilization of bins. This extends to Nomad, where the clients are "bins" + and the items are task groups. Nomad optimizes resources by efficiently bin packing + tasks onto client machines. # High-Level Overview -A very high level overview of Vault looks like this: +Looking at only a single region, at a high level Nomad looks like: -![Architecture Overview](/assets/images/layers.png) +![Regional Architecture](/assets/images/region-arch.png) -Let's begin to break down this picture. There is a clear separation of components -that are inside or outside of the security barrier. Only the storage backend and -the HTTP API are outside, all other components are inside the barrier. +Within each region, we have both clients and servers. Servers are responsible for +accepting jobs from users, managing clients, and computing task placements. Each +region may have clients from multiple datacenters, allowing a small number of servers +to handle very large clusters. -The storage backend is untrusted and is used to durably store encrypted data. When -the Vault server is started, it must be provided with a storage backend so that data -is available across restarts. The HTTP API similarly must be started by the Vault server -on start so that clients can interact with it. +In some cases, for either availability or scalability, you may need to run multiple +regions. Nomad supports federating multiple regions together into a single cluster. +At a high level, this looks like: -Once started, the Vault is in a _sealed_ state. Before any operation can be performed -on the Vault it must be unsealed. This is done by providing the unseal keys. When -the Vault is initialized it generates an encryption key which is used to protect all the -data. That key is protected by a master key. By default, Vault uses a technique known -as [Shamir's secret sharing algorithm](http://en.wikipedia.org/wiki/Shamir's_Secret_Sharing) -to split the master key into 5 shares, any 3 of which are required to reconstruct the master -key. +![Global Architecture](/assets/images/global-arch.png) -![Keys](/assets/images/keys.png) +Regions are fully independent from each other, and do not share jobs, clients or +state. They are loosely-coupled using a gossip protocol, which allows users to +submit jobs to any region or query the state of any region transparently. Requests +are forwarded to the appropriate server to be processed and the results returned. -The number of shares and the minimum threshold required can both be specified. Shamir's -technique can be disabled, and the master key used directly for unsealing. Once Vault -retrieves the encryption key, it is able to decrypt the data in the storage backend, -and enters the _unsealed_ state. Once unsealed, Vault loads all of the configured -audit, credential and secret backends. +The servers in each datacenter are all part of a single consensus group. This means +that they work together to elect a single leader which has extra duties. The leader +is responsible for processing all queries and transactions. Nomad is an optimistically +concurrent, meaning all servers participate in making scheduling decisions in parallel. +The leader provides the additional coordination necessary to do this safely and +to ensure clients are not oversubscribed. -The configuration of those backends must be stored in Vault since they are security -sensitive. Only users with the correct permissions should be able to modify them, -meaning they cannot be specified outside of the barrier. By storing them in Vault, -any changes to them are protected by the ACL system and tracked by audit logs. +Each region is expected to have either three or five servers. This strikes a balance +between availability in the case of failure and performance, as consensus gets +progressively slower as more servers are added. However, there is no limit to the number +of clients per region. -After the Vault is unsealed, requests can be processed from the HTTP API to the Core. -The core is used to manage the flow of requests through the system, enforce ACLs, -and ensure audit logging is done. +Clients are configured to communicate with their regional servers and communicate +using remote procedure calls (RPC) to register themselves, heartbeat for liveness, +wait for new allocations, and update the status of allocations. A client registers +with the servers to provide the resources available, attributes, and installed drivers. +Servers use this information for scheduling decisions and create allocations to assign +work to clients. -When a client first connects to Vault, it needs to authenticate. Vault provides -configurable credential backends providing flexibility in the authentication mechanism -used. Human friendly mechanisms such as username/password or GitHub might be -used for operators, while applications may use public/private keys or tokens to authenticate. -An authentication request flows through core and into a credential backend, which determines -if the request is valid and returns a list of associated policies. - -Policies are just a named ACL rule. For example, the "root" policy is builtin and -permits access to all resources. You can create any number of named policies with -fine-grained control over paths. Vault operates exclusively in a blacklist mode, meaning -unless access is explicitly granted via a policy the action is not allowed. -Since a user may have multiple policies associated, an action is allowed if any policy -permits it. Policies are stored and managed by an internal policy store. This internal store -is manipulated through the system backend, which is always mounted at `sys/`. - -Once authentication takes place and a credential backend provides a set of applicable -policies, a new client token is generated and managed by the token store. This client token -is sent back to the client, and is used to make future requests. This is similar to -a cookie sent by a website after a user logs in. The client token may have a lease associated -with it depending on the credential backend configuration. This means the client token -may need to be periodically renewed to avoid invalidation. - -Once authenticated, requests are made providing the client token. The token is used -to verify the client is authorized and to load the relevant policies. The policies -are used to authorize the client request. The request is then routed to the secret backend, -which is processed depending on the type of backend. If the backend returns a secret, -the core registers it with the expiration manager and attaches a lease ID. -The lease ID is used by clients to renew or revoke their secret. If a client allows the -lease to expire, the expiration manager automatically revokes the secret. - -The core handles logging of requests and responses to the audit broker, which fans the -request out to all the configured audit backends. Outside of the request flow, the core -performs certain background activity. Lease management is critical, as it allows -expired client tokens or secrets to be revoked automatically. Additionally, Vault handles -certain partial failure cases by using write ahead logging with a rollback manager. -This is managed transparently within the core and is not user visible. +Users make use of the Nomad CLI or API to submit jobs to the servers. A job represents +a desired state, providing the set of tasks that should be run. The servers are +responsible for scheduling the tasks, which is done by finding an optimial placement for +each task such that resource utilization is maximized while satisfying all constraints +specified by the job. Resource utilization is maximized by bin packing, in which +the scheduling tries to make use of all the resources of a machine without +exhausing any dimension. Job constraints can be used to ensure an application is +running in an appropriate environment. Constraints can be technical requirements based +on hardware features such as architecture, availability of GPUs, or software features +like operating system and kernel version, or they can be business constraints like +ensuring PCI compliant workloads run on appropriate servers. # Getting in Depth -This has been a brief high-level overview of the architecture of Vault. There -are more details available for each of the sub-systems. +This has been a brief high-level overview of the architecture of Nomad. There +are more details available for each of the sub-systems. The [consensus protocol](/docs/internals/consensus.html) is +documented in detail as is the [gossip protocol](/docs/internals/gossip.html). For other details, either consult the code, ask in IRC or reach out to the mailing list. diff --git a/website/source/docs/internals/consensus.html.md b/website/source/docs/internals/consensus.html.md new file mode 100644 index 000000000..aba700507 --- /dev/null +++ b/website/source/docs/internals/consensus.html.md @@ -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. + +## 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ServersQuorum SizeFailure Tolerance
110
220
321
431
532
642
743
diff --git a/website/source/docs/internals/gossip.html.md b/website/source/docs/internals/gossip.html.md new file mode 100644 index 000000000..240809939 --- /dev/null +++ b/website/source/docs/internals/gossip.html.md @@ -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. diff --git a/website/source/docs/internals/high-availability.html.md b/website/source/docs/internals/high-availability.html.md deleted file mode 100644 index 270401e6f..000000000 --- a/website/source/docs/internals/high-availability.html.md +++ /dev/null @@ -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. diff --git a/website/source/docs/internals/index.html.md b/website/source/docs/internals/index.html.md index f2defdf66..8db3cc7aa 100644 --- a/website/source/docs/internals/index.html.md +++ b/website/source/docs/internals/index.html.md @@ -3,15 +3,15 @@ layout: "docs" page_title: "Internals" sidebar_current: "docs-internals" description: |- - This section covers the internals of Vault and explains technical details of Vaults operation. + This section covers the internals of Nomad and explains technical details of Nomads operation. --- -# Vault Internals +# Nomad Internals -This section covers the internals of Vault and explains the technical -details of how Vault functions, its architecture and security properties. +This section covers the internals of Nomad and explains the technical +details of how Nomad functions, its architecture and sub-systems. --> **Note:** Knowledge of Vault internals is not -required to use Vault. If you aren't interested in the internals -of Vault, you may safely skip this section. If you're operating Vault, +-> **Note:** Knowledge of Nomad internals is not +required to use Nomad. If you aren't interested in the internals +of Nomad, you may safely skip this section. If you're operating Nomad, we recommend understanding the internals. diff --git a/website/source/docs/internals/rotation.html.md b/website/source/docs/internals/rotation.html.md deleted file mode 100644 index fc74d4503..000000000 --- a/website/source/docs/internals/rotation.html.md +++ /dev/null @@ -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. - diff --git a/website/source/docs/internals/security.html.md b/website/source/docs/internals/security.html.md deleted file mode 100644 index 6ebbf628e..000000000 --- a/website/source/docs/internals/security.html.md +++ /dev/null @@ -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. diff --git a/website/source/docs/internals/telemetry.html.md b/website/source/docs/internals/telemetry.html.md index 86baa878b..ab6d543f1 100644 --- a/website/source/docs/internals/telemetry.html.md +++ b/website/source/docs/internals/telemetry.html.md @@ -3,21 +3,21 @@ layout: "docs" page_title: "Telemetry" sidebar_current: "docs-internals-telemetry" description: |- - Learn about the telemetry data available in Vault. + Learn about the telemetry data available in Nomad. --- # Telemetry -The Vault agent collects various runtime metrics about the performance of +The Nomad agent collects various runtime metrics about the performance of different libraries and subsystems. These metrics are aggregated on a ten second interval and are retained for one minute. -To view this data, you must send a signal to the Vault process: on Unix, -this is `USR1` while on Windows it is `BREAK`. Once Vault receives the signal, +To view this data, you must send a signal to the Nomad process: on Unix, +this is `USR1` while on Windows it is `BREAK`. Once Nomad receives the signal, it will dump the current telemetry information to the agent's `stderr`. This telemetry information can be used for debugging or otherwise -getting a better view of what Vault is doing. +getting a better view of what Nomad is doing. Telemetry information can be streamed to both [statsite](http://github.com/armon/statsite) as well as statsd based on providing the appropriate configuration options. @@ -25,24 +25,39 @@ as well as statsd based on providing the appropriate configuration options. Below is sample output of a telemetry dump: ```text -[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.num_goroutines': 12.000 -[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.free_count': 11882.000 -[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.total_gc_runs': 9.000 -[2015-04-20 12:24:30 -0700 PDT][G] 'vault.expire.num_leases': 1.000 -[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.alloc_bytes': 502992.000 -[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.sys_bytes': 3999992.000 -[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.malloc_count': 17315.000 -[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.heap_objects': 5433.000 -[2015-04-20 12:24:30 -0700 PDT][G] 'vault.runtime.total_gc_pause_ns': 3794124.000 -[2015-04-20 12:24:30 -0700 PDT][S] 'vault.audit.log_response': Count: 2 Min: 0.001 Mean: 0.001 Max: 0.001 Stddev: 0.000 Sum: 0.002 -[2015-04-20 12:24:30 -0700 PDT][S] 'vault.route.read.secret-': Count: 1 Sum: 0.036 -[2015-04-20 12:24:30 -0700 PDT][S] 'vault.barrier.get': Count: 3 Min: 0.004 Mean: 0.021 Max: 0.050 Stddev: 0.025 Sum: 0.064 -[2015-04-20 12:24:30 -0700 PDT][S] 'vault.token.lookup': Count: 2 Min: 0.040 Mean: 0.074 Max: 0.108 Stddev: 0.048 Sum: 0.148 -[2015-04-20 12:24:30 -0700 PDT][S] 'vault.policy.get_policy': Count: 2 Min: 0.003 Mean: 0.004 Max: 0.005 Stddev: 0.001 Sum: 0.009 -[2015-04-20 12:24:30 -0700 PDT][S] 'vault.core.check_token': Count: 2 Min: 0.053 Mean: 0.087 Max: 0.121 Stddev: 0.048 Sum: 0.174 -[2015-04-20 12:24:30 -0700 PDT][S] 'vault.audit.log_request': Count: 2 Min: 0.001 Mean: 0.001 Max: 0.001 Stddev: 0.000 Sum: 0.002 -[2015-04-20 12:24:30 -0700 PDT][S] 'vault.barrier.put': Count: 3 Min: 0.004 Mean: 0.010 Max: 0.019 Stddev: 0.008 Sum: 0.029 -[2015-04-20 12:24:30 -0700 PDT][S] 'vault.route.write.secret-': Count: 1 Sum: 0.035 -[2015-04-20 12:24:30 -0700 PDT][S] 'vault.core.handle_request': Count: 2 Min: 0.097 Mean: 0.228 Max: 0.359 Stddev: 0.186 Sum: 0.457 -[2015-04-20 12:24:30 -0700 PDT][S] 'vault.expire.register': Count: 1 Sum: 0.18 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.broker.total_blocked': 0.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.plan.queue_depth': 0.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.malloc_count': 7568.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.total_gc_runs': 8.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.broker.total_ready': 0.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.num_goroutines': 56.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.sys_bytes': 3999992.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.heap_objects': 4135.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.heartbeat.active': 1.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.broker.total_unacked': 0.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.nomad.broker.total_waiting': 0.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.alloc_bytes': 634056.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.free_count': 3433.000 +[2015-09-17 16:59:40 -0700 PDT][G] 'nomad.runtime.total_gc_pause_ns': 6572135.000 +[2015-09-17 16:59:40 -0700 PDT][C] 'nomad.memberlist.msg.alive': Count: 1 Sum: 1.000 +[2015-09-17 16:59:40 -0700 PDT][C] 'nomad.serf.member.join': Count: 1 Sum: 1.000 +[2015-09-17 16:59:40 -0700 PDT][C] 'nomad.raft.barrier': Count: 1 Sum: 1.000 +[2015-09-17 16:59:40 -0700 PDT][C] 'nomad.raft.apply': Count: 1 Sum: 1.000 +[2015-09-17 16:59:40 -0700 PDT][C] 'nomad.nomad.rpc.query': Count: 2 Sum: 2.000 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.serf.queue.Query': Count: 6 Sum: 0.000 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.fsm.register_node': Count: 1 Sum: 1.296 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.serf.queue.Intent': Count: 6 Sum: 0.000 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.runtime.gc_pause_ns': Count: 8 Min: 126492.000 Mean: 821516.875 Max: 3126670.000 Stddev: 1139250.294 Sum: 6572135.000 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.raft.leader.dispatchLog': Count: 3 Min: 0.007 Mean: 0.018 Max: 0.039 Stddev: 0.018 Sum: 0.054 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.leader.reconcileMember': Count: 1 Sum: 0.007 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.leader.reconcile': Count: 1 Sum: 0.025 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.raft.fsm.apply': Count: 1 Sum: 1.306 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.client.get_allocs': Count: 1 Sum: 0.110 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.worker.dequeue_eval': Count: 29 Min: 0.003 Mean: 363.426 Max: 503.377 Stddev: 228.126 Sum: 10539.354 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.serf.queue.Event': Count: 6 Sum: 0.000 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.raft.commitTime': Count: 3 Min: 0.013 Mean: 0.037 Max: 0.079 Stddev: 0.037 Sum: 0.110 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.leader.barrier': Count: 1 Sum: 0.071 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.client.register': Count: 1 Sum: 1.626 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.nomad.eval.dequeue': Count: 21 Min: 500.610 Mean: 501.753 Max: 503.361 Stddev: 1.030 Sum: 10536.813 +[2015-09-17 16:59:40 -0700 PDT][S] 'nomad.memberlist.gossip': Count: 12 Min: 0.009 Mean: 0.017 Max: 0.025 Stddev: 0.005 Sum: 0.204 ``` diff --git a/website/source/docs/internals/token.html.md b/website/source/docs/internals/token.html.md deleted file mode 100644 index d13c3ccfe..000000000 --- a/website/source/docs/internals/token.html.md +++ /dev/null @@ -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. diff --git a/website/source/docs/secrets/aws/index.html.md b/website/source/docs/secrets/aws/index.html.md index 17feb3306..3e0a1d417 100644 --- a/website/source/docs/secrets/aws/index.html.md +++ b/website/source/docs/secrets/aws/index.html.md @@ -3,16 +3,16 @@ layout: "docs" page_title: "Secret Backend: AWS" sidebar_current: "docs-secrets-aws" description: |- - The AWS secret backend for Vault generates access keys dynamically based on IAM policies. + The AWS secret backend for Nomad generates access keys dynamically based on IAM policies. --- # AWS Secret Backend Name: `aws` -The AWS secret backend for Vault generates AWS access credentials dynamically +The AWS secret backend for Nomad generates AWS access credentials dynamically based on IAM policies. This makes IAM much easier to use: credentials could -be generated on the fly, and are automatically revoked when the Vault +be generated on the fly, and are automatically revoked when the Nomad lease is expired. This page will show a quick start for this backend. For detailed documentation @@ -59,7 +59,7 @@ This path will create a named role along with the IAM policy used to restrict permissions for it. This is used to dynamically create a new pair of IAM credentials when needed. -The `@` tells Vault to load the policy from the file named `policy.json`. Here +The `@` tells Nomad to load the policy from the file named `policy.json`. Here is an example IAM policy to get started: ```javascript diff --git a/website/source/docs/secrets/cassandra/index.html.md b/website/source/docs/secrets/cassandra/index.html.md index 8b8041a16..2bf255a63 100644 --- a/website/source/docs/secrets/cassandra/index.html.md +++ b/website/source/docs/secrets/cassandra/index.html.md @@ -3,17 +3,17 @@ layout: "docs" page_title: "Secret Backend: Cassandra" sidebar_current: "docs-secrets-cassandra" description: |- - The Cassandra secret backend for Vault generates database credentials to access Cassandra. + The Cassandra secret backend for Nomad generates database credentials to access Cassandra. --- # Cassandra Secret Backend Name: `cassandra` -The Cassandra secret backend for Vault generates database credentials +The Cassandra secret backend for Nomad generates database credentials dynamically based on configured roles. This means that services that need to access a database no longer need to hardcode credentials: they can request -them from Vault, and use Vault's leasing mechanism to more easily roll keys. +them from Nomad, and use Nomad's leasing mechanism to more easily roll keys. Additionally, it introduces a new ability: with every service accessing the database with unique credentials, it makes auditing much easier when @@ -33,7 +33,7 @@ $ vault mount cassandra Successfully mounted 'cassandra' at 'cassandra'! ``` -Next, Vault must be configured to connect to Cassandra. This is done by +Next, Nomad must be configured to connect to Cassandra. This is done by writing one or more hosts, a username, and a password: ```text @@ -41,8 +41,8 @@ $ vault write cassandra/config/connection \ hosts=localhost username=cassandra password=cassandra ``` -In this case, we've configured Vault with the user "cassandra" and password "cassandra", -It is important that the Vault user is a superuser, in order to manage other user accounts. +In this case, we've configured Nomad with the user "cassandra" and password "cassandra", +It is important that the Nomad user is a superuser, in order to manage other user accounts. The next step is to configure a role. A role is a logical name that maps to a policy used to generated those credentials. For example, lets create @@ -58,14 +58,14 @@ Success! Data written to: cassandra/roles/readonly By writing to the `roles/readonly` path we are defining the `readonly` role. This role will be created by evaluating the given `creation_cql` statements. By default, the `{{username}}` and `{{password}}` fields will be populated by -Vault with dynamically generated values. This CQL statement is creating +Nomad with dynamically generated values. This CQL statement is creating the named user, and then granting it `SELECT` or read-only privileges to keyspaces. More complex `GRANT` queries can be used to customize the privileges of the role. See the [CQL Reference Manual](http://docs.datastax.com/en/cql/3.1/cql/cql_reference/grant_r.html) for more information. To generate a new set of credentials, we simply read from that role: -Vault is now configured to create and manage credentials for Cassandra! +Nomad is now configured to create and manage credentials for Cassandra! ```text $ vault read cassandra/creds/readonly @@ -77,7 +77,7 @@ password dfa80eea-ccbe-b228-ebf7-e2f62b245e71 username vault-root-1434647667-9313 ``` -By reading from the `creds/readonly` path, Vault has generated a new +By reading from the `creds/readonly` path, Nomad has generated a new set of credentials using the `readonly` role configuration. Here we see the dynamically generated username and password, along with a one hour lease. diff --git a/website/source/docs/secrets/consul/index.html.md b/website/source/docs/secrets/consul/index.html.md index 05fb10083..7ee33b67d 100644 --- a/website/source/docs/secrets/consul/index.html.md +++ b/website/source/docs/secrets/consul/index.html.md @@ -3,14 +3,14 @@ layout: "docs" page_title: "Secret Backend: Consul" sidebar_current: "docs-secrets-consul" description: |- - The Consul secret backend for Vault generates tokens for Consul dynamically. + The Consul secret backend for Nomad generates tokens for Consul dynamically. --- # Consul Secret Backend Name: `consul` -The Consul secret backend for Vault generates +The Consul secret backend for Nomad generates [Consul](http://consul.io) API tokens dynamically based on Consul ACL policies. @@ -27,7 +27,7 @@ $ vault mount consul Successfully mounted 'consul' at 'consul'! ``` -Next, we must configure Vault to know how to contact Consul. +Next, we must configure Nomad to know how to contact Consul. This is done by writing the access information: ``` @@ -35,9 +35,9 @@ $ vault write consul/config/access address=127.0.0.1:8500 token=root Success! Data written to: consul/config/access ``` -In this case, we've configured Vault to connect to Consul +In this case, we've configured Nomad to connect to Consul on the default port with the loopback address. We've also provided -an ACL token to use with the `token` parameter. Vault must have a management +an ACL token to use with the `token` parameter. Nomad must have a management type token so that it can create and revoke ACL tokens. The next step is to configure a role. A role is a logical name that maps @@ -64,7 +64,7 @@ lease_duration 3600 token 973a31ea-1ec4-c2de-0f63-623f477c2510 ``` -Here we can see that Vault has generated a new Consul ACL token for us. +Here we can see that Nomad has generated a new Consul ACL token for us. We can test this token out, and verify that it is read-only: ``` diff --git a/website/source/docs/secrets/custom.html.md b/website/source/docs/secrets/custom.html.md index ef3f976e7..15e8b8d8f 100644 --- a/website/source/docs/secrets/custom.html.md +++ b/website/source/docs/secrets/custom.html.md @@ -3,13 +3,13 @@ layout: "docs" page_title: "Secret Backend: Custom" sidebar_current: "docs-secrets-custom" description: |- - Create custom secret backends for Vault. + Create custom secret backends for Nomad. --- # Custom Secret Backends -Vault doesn't currently support the creation of custom secret backends. -The primary reason is because we want to ensure the core of Vault is +Nomad doesn't currently support the creation of custom secret backends. +The primary reason is because we want to ensure the core of Nomad is secure before attempting any sort of plug-in system. We're interested in supporting custom secret backends, but don't yet have a clear strategy or timeline to do. diff --git a/website/source/docs/secrets/generic/index.html.md b/website/source/docs/secrets/generic/index.html.md index ad4742b47..be754fc21 100644 --- a/website/source/docs/secrets/generic/index.html.md +++ b/website/source/docs/secrets/generic/index.html.md @@ -11,9 +11,9 @@ description: |- Name: `generic` The generic secret backend is used to store arbitrary secrets within -the configured physical storage for Vault. If you followed along with +the configured physical storage for Nomad. If you followed along with the getting started guide, you interacted with a generic secret backend -via the `secret/` prefix that Vault mounts by default. +via the `secret/` prefix that Nomad mounts by default. Writing to a key in the `secret/` backend will replace the old value, the sub-fields are not merged together. diff --git a/website/source/docs/secrets/index.html.md b/website/source/docs/secrets/index.html.md index 6e4fd3667..adb01e65d 100644 --- a/website/source/docs/secrets/index.html.md +++ b/website/source/docs/secrets/index.html.md @@ -3,12 +3,12 @@ layout: "docs" page_title: "Secret Backends" sidebar_current: "docs-secrets" description: |- - Secret backends are mountable backends that store or generate secrets in Vault. + Secret backends are mountable backends that store or generate secrets in Nomad. --- # Secret Backends -Secret backends are the components in Vault which store and generate +Secret backends are the components in Nomad which store and generate secrets. Some secret backends, such as "generic", simply store and read @@ -17,12 +17,12 @@ secrets_: secrets that are made on demand. Secret backends are part of the [mount system](#) -in Vault. They behave very similarly to a virtual filesystem: +in Nomad. They behave very similarly to a virtual filesystem: any read/write/delete is sent to the secret backend, and the secret backend can choose to react to that operation however it sees fit. For example, the "generic" backend passes through any operation back -to the configured storage backend for Vault. A "read" turns into a +to the configured storage backend for Nomad. A "read" turns into a "read" of the storage backend at the same path, a "write" turns into a write, etc. This is a lot like a normal filesystem. @@ -62,14 +62,14 @@ system to determine the paths it responds to. ## Barrier View An important concept around secret backends is that they receive a -_barrier view_ to the configured Vault physical storage. This is a lot +_barrier view_ to the configured Nomad physical storage. This is a lot like a [chroot](http://en.wikipedia.org/wiki/Chroot). Whenever a secret backend is mounted, a random UUID is generated. This becomes the data root for that backend. Whenever that backend writes to the physical storage layer, it is prefixed with that UUID folder. Since -the Vault storage layer doesn't support relative access (such as `..`), +the Nomad storage layer doesn't support relative access (such as `..`), this makes it impossible for a mounted backend to access any other data. -This is an important security feature in Vault: even a malicious backend +This is an important security feature in Nomad: even a malicious backend can't access the data from any other backend. diff --git a/website/source/docs/secrets/jwt/index.html.md b/website/source/docs/secrets/jwt/index.html.md index aecc94f9e..61fa62e7b 100644 --- a/website/source/docs/secrets/jwt/index.html.md +++ b/website/source/docs/secrets/jwt/index.html.md @@ -2,7 +2,7 @@ Name: `jwt` -The JWT secret backend for Vault generates JSON Web Tokens dynamically based on configured roles. This means services can get tokens needed for authentication without going through the usual manual process of generating a private key and signing the token and maintaining the private key's security. Vault's built-in authentication and authorization mechanisms provide the verification functionality. +The JWT secret backend for Nomad generates JSON Web Tokens dynamically based on configured roles. This means services can get tokens needed for authentication without going through the usual manual process of generating a private key and signing the token and maintaining the private key's security. Nomad's built-in authentication and authorization mechanisms provide the verification functionality. This page will show a quick start for this backend. For detailed documentation on every path, use `vault path-help` after mounting the backend. @@ -62,8 +62,8 @@ Generating a token requires passing of additional information so we use the ```text $ vault write jwt/issue/webauth \ - issuer="Vault" \ - audience="Vault Client" \ + issuer="Nomad" \ + audience="Nomad Client" \ expiration="1538096292" \ claims=@extra.json ``` diff --git a/website/source/docs/secrets/mysql/index.html.md b/website/source/docs/secrets/mysql/index.html.md index d45c12a0b..0f555761d 100644 --- a/website/source/docs/secrets/mysql/index.html.md +++ b/website/source/docs/secrets/mysql/index.html.md @@ -3,24 +3,24 @@ layout: "docs" page_title: "Secret Backend: MySQL" sidebar_current: "docs-secrets-mysql" description: |- - The MySQL secret backend for Vault generates database credentials to access MySQL. + The MySQL secret backend for Nomad generates database credentials to access MySQL. --- # MySQL Secret Backend Name: `mysql` -The MySQL secret backend for Vault generates database credentials +The MySQL secret backend for Nomad generates database credentials dynamically based on configured roles. This means that services that need to access a database no longer need to hardcode credentials: they can request -them from Vault, and use Vault's leasing mechanism to more easily roll keys. +them from Nomad, and use Nomad's leasing mechanism to more easily roll keys. Additionally, it introduces a new ability: with every service accessing the database with unique credentials, it makes auditing much easier when questionable data access is discovered: you can track it down to the specific instance of a service based on the SQL username. -Vault makes use of its own internal revocation system to ensure that users +Nomad makes use of its own internal revocation system to ensure that users become invalid within a reasonable time of the lease expiring. This page will show a quick start for this backend. For detailed documentation @@ -36,7 +36,7 @@ $ vault mount mysql Successfully mounted 'mysql' at 'mysql'! ``` -Next, we must configure Vault to know how to connect to the MySQL +Next, we must configure Nomad to know how to connect to the MySQL instance. This is done by providing a DSN (Data Source Name): ``` @@ -44,13 +44,13 @@ $ vault write mysql/config/connection value="root:root@tcp(192.168.33.10:3306)/" Success! Data written to: mysql/config/connection ``` -In this case, we've configured Vault with the user "root" and password "root, +In this case, we've configured Nomad with the user "root" and password "root, connecting to an instance at "192.168.33.10" on port 3306. It is not necessary -that Vault has the root user, but the user must have privileges to create +that Nomad has the root user, but the user must have privileges to create other users, namely the `GRANT OPTION` privilege. Optionally, we can configure the lease settings for credentials generated -by Vault. This is done by writing to the `config/lease` key: +by Nomad. This is done by writing to the `config/lease` key: ``` $ vault write mysql/config/lease lease=1h lease_max=24h @@ -74,7 +74,7 @@ Success! Data written to: mysql/roles/readonly By writing to the `roles/readonly` path we are defining the `readonly` role. This role will be created by evaluating the given `sql` statements. By default, the `{{name}}` and `{{password}}` fields will be populated by -Vault with dynamically generated values. This SQL statement is creating +Nomad with dynamically generated values. This SQL statement is creating the named user, and then granting it `SELECT` or read-only privileges to tables in the database. More complex `GRANT` queries can be used to customize the privileges of the role. See the [MySQL manual](https://dev.mysql.com/doc/refman/5.7/en/grant.html) @@ -91,7 +91,7 @@ password 132ae3ef-5a64-7499-351e-bfe59f3a2a21 username root-aefa635a-18 ``` -By reading from the `creds/readonly` path, Vault has generated a new +By reading from the `creds/readonly` path, Nomad has generated a new set of credentials using the `readonly` role configuration. Here we see the dynamically generated username and password, along with a one hour lease. diff --git a/website/source/docs/secrets/pki/index.html.md b/website/source/docs/secrets/pki/index.html.md index 85e3d9c88..171b0caf0 100644 --- a/website/source/docs/secrets/pki/index.html.md +++ b/website/source/docs/secrets/pki/index.html.md @@ -3,14 +3,14 @@ layout: "docs" page_title: "Secret Backend: PKI" sidebar_current: "docs-secrets-pki" description: |- - The PKI secret backend for Vault generates TLS certificates. + The PKI secret backend for Nomad generates TLS certificates. --- # PKI Secret Backend Name: `pki` -The PKI secret backend for Vault generates X.509 certificates dynamically based on configured roles. This means services can get certificates needed for both client and server authentication without going through the usual manual process of generating a private key and CSR, submitting to a CA, and waiting for a verification and signing process to complete. Vault's built-in authentication and authorization mechanisms provide the verification functionality. +The PKI secret backend for Nomad generates X.509 certificates dynamically based on configured roles. This means services can get certificates needed for both client and server authentication without going through the usual manual process of generating a private key and CSR, submitting to a CA, and waiting for a verification and signing process to complete. Nomad's built-in authentication and authorization mechanisms provide the verification functionality. By keeping leases relatively short, revocations are less likely to be needed, keeping CRLs short and helping the backend scale to large workloads. This in turn allows each instance of a running application to have a unique certificate, eliminating sharing and the accompanying pain of revocation and rollover. @@ -24,7 +24,7 @@ To successfully deploy this backend, there are a number of important considerati ### Never use root CAs -Vault storage is secure, but not as secure as a piece of paper in a bank vault. It is, after all, networked software. Your long-lived self-signed root CA's private key should instead be used to issue a shorter-lived intermediate CA certificate, and this is what you should put into Vault. This aligns with industry best practices. +Nomad storage is secure, but not as secure as a piece of paper in a bank vault. It is, after all, networked software. Your long-lived self-signed root CA's private key should instead be used to issue a shorter-lived intermediate CA certificate, and this is what you should put into Nomad. This aligns with industry best practices. ### One CA Certificate, One Backend @@ -34,13 +34,13 @@ This also provides a convenient method of switching to a new CA certificate whil ### Keep certificate lifetimes short, for CRL's sake -This backend aligns with Vault's philosophy of short-lived secrets. As such it is not expected that CRLs will grow large; the only place a private key is ever returned is to the requesting client (this backend does *not* store generated private keys). In most cases, if the key is lost, the certificate can simply be ignored, as it will expire shortly. +This backend aligns with Nomad's philosophy of short-lived secrets. As such it is not expected that CRLs will grow large; the only place a private key is ever returned is to the requesting client (this backend does *not* store generated private keys). In most cases, if the key is lost, the certificate can simply be ignored, as it will expire shortly. -If a certificate must truly be revoked, the normal Vault revocation function can be used; alternately a root token can be used to revoke the certificate using the certificate's serial number. Any revocation action will cause the CRL to be regenerated. When the CRL is regenerated, any expired certificates are removed from the CRL (and any revoked, expired certificate are removed from backend storage). +If a certificate must truly be revoked, the normal Nomad revocation function can be used; alternately a root token can be used to revoke the certificate using the certificate's serial number. Any revocation action will cause the CRL to be regenerated. When the CRL is regenerated, any expired certificates are removed from the CRL (and any revoked, expired certificate are removed from backend storage). This backend does not support multiple CRL endpoints with sliding date windows; often such mechanisms will have the transition point a few days apart, but this gets into the expected realm of the actual certificate validity periods issued from this backend. A good rule of thumb for this backend would be to simply not issue certificates with a validity period greater than your maximum comfortable CRL lifetime. Alternately, you can control CRL caching behavior on the client to ensure that checks happen more often. -Often multiple endpoints are used in case a single CRL endpoint is down so that clients don't have to figure out what to do with a lack of response. Run Vault in HA mode, and the CRL endpoint should be available even if a particular node is down. +Often multiple endpoints are used in case a single CRL endpoint is down so that clients don't have to figure out what to do with a lack of response. Run Nomad in HA mode, and the CRL endpoint should be available even if a particular node is down. ### You must configure CRL information *in advance* @@ -48,7 +48,7 @@ This backend serves CRLs from a predictable location. That location must be enco ### No OCSP support, yet -Vault's architecture does not currently allow for a binary protocol such as OCSP to be supported by a backend. As such, you should configure your software to use CRLs for revocation information, with a caching lifetime that feels good to you. Since you are following the advice above about keeping lifetimes short (right?), CRLs should not grow too large. +Nomad's architecture does not currently allow for a binary protocol such as OCSP to be supported by a backend. As such, you should configure your software to use CRLs for revocation information, with a caching lifetime that feels good to you. Since you are following the advice above about keeping lifetimes short (right?), CRLs should not grow too large. ## Quick Start @@ -62,7 +62,7 @@ crlDistributionPoints = URI:https://vault.example.com:8200/v1/pki/crl Adjust the URI as appropriate. -### Vault +### Nomad The first step to using the PKI backend is to mount it. Unlike the `generic` backend, the `pki` backend is not mounted by default. @@ -71,7 +71,7 @@ $ vault mount pki Successfully mounted 'pki' at 'pki'! ``` -Next, Vault must be configured with a root certificate and associated private key. This is done by writing the contents of a file or *stdin*: +Next, Nomad must be configured with a root certificate and associated private key. This is done by writing the contents of a file or *stdin*: ```text $ vault write pki/config/ca pem_bundle="@ca_bundle.pem" @@ -85,7 +85,7 @@ $ cat bundle.pem | vault write pki/config/ca pem_bundle="-" Success! Data written to: pki/config/ca ``` -Although in this example the value being piped into *stdin* could be passed directly into the Vault CLI command, a more complex usage might be to use [Ansible](http://www.ansible.com) to securely store the certificate and private key in an `ansible-vault` file, then have an `ansible-playbook` command decrypt this value and pass it in to Vault. +Although in this example the value being piped into *stdin* could be passed directly into the Nomad CLI command, a more complex usage might be to use [Ansible](http://www.ansible.com) to securely store the certificate and private key in an `ansible-vault` file, then have an `ansible-playbook` command decrypt this value and pass it in to Nomad. The next step is to configure a role. A role is a logical name that maps to a policy used to generated those credentials. For example, let's create an "example-dot-com" role: @@ -96,7 +96,7 @@ $ vault write pki/roles/example-dot-com \ Success! Data written to: pki/roles/example-dot-com ``` -By writing to the `roles/example-dot-com` path we are defining the `example-dot-com` role. To generate a new set of credentials, we simply write to the `issue` endpoint with that role name: Vault is now configured to create and manage certificates! +By writing to the `roles/example-dot-com` path we are defining the `example-dot-com` role. To generate a new set of credentials, we simply write to the `issue` endpoint with that role name: Nomad is now configured to create and manage certificates! ```text $ vault write pki/issue/example-dot-com common_name=blah.example.com @@ -123,7 +123,7 @@ serial 5e:62:eb:2e:44:dd:04:83:8e:21:88:36:fc:15:ce:ed:da:1c:29:f5 Note that this is a write, not a read, to allow values to be passed in at request time. -Vault has now generated a new set of credentials using the `example-dot-com` role configuration. Here we see the dynamically generated private key and certificate. The issuing CA certificate is returned as well. +Nomad has now generated a new set of credentials using the `example-dot-com` role configuration. Here we see the dynamically generated private key and certificate. The issuing CA certificate is returned as well. Using ACLs, it is possible to restrict using the pki backend such that trusted operators can manage the role definitions, and both users and applications are restricted in the credentials they are allowed to read. @@ -139,7 +139,7 @@ If you get stuck at any time, simply run `vault path-help pki` or with a subpath
Retrieves the CA certificate *in raw DER-encoded form*. This is a bare endpoint that does not return a - standard Vault data structure. If `/pem` is added to the + standard Nomad data structure. If `/pem` is added to the endpoint, the CA certificate is returned in PEM format.

This is an unauthenticated endpoint.
@@ -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:
```text - curl -X POST --data "@cabundle.json" http://127.0.0.1:8200/v1/pki/config/ca -H X-Vault-Token:06b9d... + curl -X POST --data "@cabundle.json" http://127.0.0.1:8200/v1/pki/config/ca -H X-Nomad-Token:06b9d... ``` Note that if you provide the data through the HTTP API it must be @@ -261,7 +261,7 @@ If you get stuck at any time, simply run `vault path-help pki` or with a subpath Retrieves the current CRL *in raw DER-encoded form*. This endpoint is suitable for usage in the CRL Distribution Points extension in a CA certificate. This is a bare endpoint that does not return a - standard Vault data structure. If `/pem` is added to the endpoint, + standard Nomad data structure. If `/pem` is added to the endpoint, the CRL is returned in PEM format.

This is an unauthenticated endpoint. @@ -408,7 +408,7 @@ If you get stuck at any time, simply run `vault path-help pki` or with a subpath
Revokes a certificate using its serial number. This is an alternative option to the standard method of revoking - using Vault lease IDs. A successful revocation will + using Nomad lease IDs. A successful revocation will rotate the CRL.

This is a root-protected endpoint.
diff --git a/website/source/docs/secrets/postgresql/index.html.md b/website/source/docs/secrets/postgresql/index.html.md index 3d0da282e..ea67c55ee 100644 --- a/website/source/docs/secrets/postgresql/index.html.md +++ b/website/source/docs/secrets/postgresql/index.html.md @@ -3,24 +3,24 @@ layout: "docs" page_title: "Secret Backend: PostgreSQL" sidebar_current: "docs-secrets-postgresql" description: |- - The PostgreSQL secret backend for Vault generates database credentials to access PostgreSQL. + The PostgreSQL secret backend for Nomad generates database credentials to access PostgreSQL. --- # PostgreSQL Secret Backend Name: `postgresql` -The PostgreSQL secret backend for Vault generates database credentials +The PostgreSQL secret backend for Nomad generates database credentials dynamically based on configured roles. This means that services that need to access a database no longer need to hardcode credentials: they can request -them from Vault, and use Vault's leasing mechanism to more easily roll keys. +them from Nomad, and use Nomad's leasing mechanism to more easily roll keys. Additionally, it introduces a new ability: with every service accessing the database with unique credentials, it makes auditing much easier when questionable data access is discovered: you can track it down to the specific instance of a service based on the SQL username. -Vault makes use both of its own internal revocation system as well as the +Nomad makes use both of its own internal revocation system as well as the `VALID UNTIL` setting when creating PostgreSQL users to ensure that users become invalid within a reasonable time of the lease expiring. @@ -37,7 +37,7 @@ $ vault mount postgresql Successfully mounted 'postgresql' at 'postgresql'! ``` -Next, Vault must be configured to connect to the PostgreSQL. This is done by +Next, Nomad must be configured to connect to the PostgreSQL. This is done by writing either a PostgreSQL URL or PG connection string: ```text @@ -45,12 +45,12 @@ $ vault write postgresql/config/connection \ value="postgresql://root:vaulttest@vaulttest.ciuvljjni7uo.us-west-1.rds.amazonaws.com:5432/postgres" ``` -In this case, we've configured Vault with the user "root" and password "vaulttest", +In this case, we've configured Nomad with the user "root" and password "vaulttest", connecting to a PostgreSQL instance in AWS RDS. The "postgres" database name is being used. -It is important that the Vault user have the `GRANT OPTION` privilege to manage users. +It is important that the Nomad user have the `GRANT OPTION` privilege to manage users. Optionally, we can configure the lease settings for credentials generated -by Vault. This is done by writing to the `config/lease` key: +by Nomad. This is done by writing to the `config/lease` key: ``` $ vault write postgresql/config/lease lease=1h lease_max=24h @@ -76,14 +76,14 @@ Success! Data written to: postgresql/roles/readonly By writing to the `roles/readonly` path we are defining the `readonly` role. This role will be created by evaluating the given `sql` statements. By default, the `{{name}}`, `{{password}}` and `{{expiration}}` fields will be populated by -Vault with dynamically generated values. This SQL statement is creating +Nomad with dynamically generated values. This SQL statement is creating the named user, and then granting it `SELECT` or read-only privileges to tables in the database. More complex `GRANT` queries can be used to customize the privileges of the role. See the [PostgreSQL manual](http://www.postgresql.org/docs/9.4/static/sql-grant.html) for more information. To generate a new set of credentials, we simply read from that role: -Vault is now configured to create and manage credentials for Postgres! +Nomad is now configured to create and manage credentials for Postgres! ```text $ vault read postgresql/creds/readonly @@ -94,7 +94,7 @@ password 34205e88-0de1-68b7-6267-72d8e32c5d3d username vault-root-1430162075-7887 ``` -By reading from the `creds/readonly` path, Vault has generated a new +By reading from the `creds/readonly` path, Nomad has generated a new set of credentials using the `readonly` role configuration. Here we see the dynamically generated username and password, along with a one hour lease. diff --git a/website/source/docs/secrets/ssh/index.html.md b/website/source/docs/secrets/ssh/index.html.md index ddae56515..0a8a79215 100644 --- a/website/source/docs/secrets/ssh/index.html.md +++ b/website/source/docs/secrets/ssh/index.html.md @@ -3,14 +3,14 @@ layout: "docs" page_title: "Secret Backend: SSH" sidebar_current: "docs-secrets-ssh" description: |- - The SSH secret backend for Vault generates dynamic SSH keys or One-Time-Passwords. + The SSH secret backend for Nomad generates dynamic SSH keys or One-Time-Passwords. --- # SSH Secret Backend Name: `ssh` -Vault SSH backend generates SSH credentials for remote hosts dynamically. This +Nomad SSH backend generates SSH credentials for remote hosts dynamically. This backend increases the security by removing the need to share the private key to everyone who needs access to infrastructures. It also solves the problem of management and distribution of keys belonging to remote hosts. @@ -27,14 +27,14 @@ on every path, use `vault path-help` after mounting the backend. ---------------------------------------------------- ## I. Dynamic Type -Register the shared secret key (having super user privileges) with Vault and let -Vault take care of issuing a dynamic secret key every time a client wants to SSH +Register the shared secret key (having super user privileges) with Nomad and let +Nomad take care of issuing a dynamic secret key every time a client wants to SSH into the remote host. -When a Vault authenticated client requests for a dynamic credential, Vault server +When a Nomad authenticated client requests for a dynamic credential, Nomad server creates a key-pair, uses the previously shared secret key to login to the remote host and appends the newly generated public key to `~/.ssh/authorized_keys` file for -the desired username. Vault uses an install script (configurable) to achieve this. +the desired username. Nomad uses an install script (configurable) to achieve this. To run this script in super user mode without password prompts, `NOPASSWD` option for sudoers should be enabled at all remote hosts. @@ -45,8 +45,8 @@ File: `/etc/sudoers` ``` The private key returned to the user will be leased and can be renewed if desired. -Once the key is given to the user, Vault will not know when it gets used or how many -time it gets used. Therefore, Vault **WILL NOT** and cannot audit the SSH session +Once the key is given to the user, Nomad will not know when it gets used or how many +time it gets used. Therefore, Nomad **WILL NOT** and cannot audit the SSH session establishments. An alternative is to use OTP type, which audits every SSH request (see below). @@ -60,7 +60,7 @@ $ vault mount ssh Successfully mounted 'ssh' at 'ssh'! ``` -Next, we must register infrastructures with Vault. This is done by writing the role +Next, we must register infrastructures with Nomad. This is done by writing the role information. The type of credentials created are determined by the `key_type` option. To do this, first create a named key and then create a role. @@ -95,7 +95,7 @@ are explained in the comments. # $1: "install" or "uninstall" # -# $2: File name containing public key to be installed. Vault server uses UUID +# $2: File name containing public key to be installed. Nomad server uses UUID # as file name to avoid collisions with public keys generated for requests. # # $3: Absolute path of the authorized_keys file. @@ -175,7 +175,7 @@ username@ip:~$ ### Automate it! Creation of new key, saving it in a file and establishing an SSH session will all be done -via a single Vault CLI. +via a single Nomad CLI. ```shell $ vault ssh -role dynamic_key_role username@ip @@ -184,18 +184,18 @@ username@ip:~$ ---------------------------------------------------- ## II. One-Time-Password (OTP) Type -Install Vault SSH Agent in remote hosts and let Vault server issue an OTP every time +Install Nomad SSH Agent in remote hosts and let Nomad server issue an OTP every time a client wants to SSH into remote hosts. -Vault authenticated clients request for a credential from Vault server and get an OTP +Nomad authenticated clients request for a credential from Nomad server and get an OTP issued. When clients try to establish SSH connection with the remote host, OTP typed -in at the password prompt will be received by the Vault agent and gets validated -by the Vault server. Vault server deletes the OTP after validating it once (hence one-time). +in at the password prompt will be received by the Nomad agent and gets validated +by the Nomad server. Nomad server deletes the OTP after validating it once (hence one-time). -Since Vault server is contacted for every successful connection establishment, unlike +Since Nomad server is contacted for every successful connection establishment, unlike Dynamic type, every login attempt **WILL** be audited. -See [Vault-SSH-Agent](https://github.com/hashicorp/vault-ssh-agent) for details +See [Nomad-SSH-Agent](https://github.com/hashicorp/vault-ssh-agent) for details on how to configure the agent. ### Mounting SSH @@ -212,7 +212,7 @@ Successfully mounted 'ssh' at 'ssh'! Create a role, say `otp_key_role` for key type `otp`. All the machines represented by CIDR block should have agent installed in them and have their SSH configuration -modified to support Vault SSH Agent client authentication. +modified to support Nomad SSH Agent client authentication. ```shell $ vault write ssh/roles/otp_key_role key_type=otp default_user=username cidr_list=x.x.x.x/y,m.m.m.m/n @@ -411,7 +411,7 @@ username@ip:~$ key required for Dynamic type, NA for OTP type (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.
  • @@ -420,7 +420,7 @@ username@ip:~$ (String) Admin user at remote host. The shared key being registered should be for this user and should have root privileges. Everytime a dynamic - credential is being generated for other users, Vault uses this admin + credential is being generated for other users, Nomad uses this admin username to login to remote host and install the generated credential for the other user.
    • @@ -446,7 +446,7 @@ username@ip:~$ Port number for SSH connection. Default is '22'. Port number does not play any role in creation of OTP. For 'otp' type, this is just a way to inform client about the port number to use. Port number will be - returned to client by Vault server along with OTP. + returned to client by Nomad server along with OTP.
  • key_type diff --git a/website/source/docs/secrets/transit/index.html.md b/website/source/docs/secrets/transit/index.html.md index 8063ac9e3..927a93a31 100644 --- a/website/source/docs/secrets/transit/index.html.md +++ b/website/source/docs/secrets/transit/index.html.md @@ -3,25 +3,25 @@ layout: "docs" page_title: "Secret Backend: Transit" sidebar_current: "docs-secrets-transit" description: |- - The transit secret backend for Vault encrypts/decrypts data in-transit. It doesn't store any secrets. + The transit secret backend for Nomad encrypts/decrypts data in-transit. It doesn't store any secrets. --- # Transit Secret Backend Name: `transit` -The transit secret backend is used to encrypt/data in-transit. Vault doesn't +The transit secret backend is used to encrypt/data in-transit. Nomad doesn't store the data sent to the backend. It can also be viewed as "encryption as a service." The primary use case for the transit backend is to encrypt data from applications while still storing that encrypted data in some primary data store. This relieves the burden of proper encryption/decryption from -application developers and pushes the burden onto the operators of Vault. -Operators of Vault generally include the security team at an organization, +application developers and pushes the burden onto the operators of Nomad. +Operators of Nomad generally include the security team at an organization, which means they can ensure that data is encrypted/decrypted properly. -As of Vault 0.2, the transit backend also supports doing key derivation. This +As of Nomad 0.2, the transit backend also supports doing key derivation. This allows data to be encrypted within a context such that the same context must be used for decryption. This can be used to enable per transaction unique keys which further increase the security of data at rest. @@ -87,7 +87,7 @@ ciphertext vault:v0:czEwyKqGZY/limnuzDCUUe5AK0tbBObWqeZgFqxCuIqq7A84SeiOq3sKD0Y/ ``` The encryption endpoint expects the plaintext to be provided as a base64 encoded -strings, so we must first convert it. Vault does not store the plaintext or the +strings, so we must first convert it. Nomad does not store the plaintext or the ciphertext, but only handles it _in transit_ for processing. The application is free to store the ciphertext in a database or file at rest. diff --git a/website/source/downloads.html.erb b/website/source/downloads.html.erb index c6d763b38..d646e0e44 100644 --- a/website/source/downloads.html.erb +++ b/website/source/downloads.html.erb @@ -1,18 +1,18 @@ --- layout: "downloads" -page_title: "Download Vault" +page_title: "Download Nomad" sidebar_current: "downloads-vault" description: |- - Download Vault + Download Nomad --- -

    Download Vault

    +

    Download Nomad

    - Below are all available downloads for the latest version of Vault + Below are all available downloads for the latest version of Nomad (<%= latest_version %>). Please download the proper package for your operating system and architecture. You can find SHA256 checksums for packages here. You can verify the SHA256 checksums using our PGP public key and the SHA256SUMs signature file. diff --git a/website/source/index.html.erb b/website/source/index.html.erb index 3d0249134..a3d8d7bd8 100644 --- a/website/source/index.html.erb +++ b/website/source/index.html.erb @@ -15,8 +15,8 @@

    -

    Applications on a global fleet.

    -

    As simple as a Single Machine.

    +

    Easily deploy applications at any scale

    +

    Any App. Any OS. Any Cloud.

    Learn More Try Nomad @@ -47,10 +47,13 @@

    Deploy to any cloud

    -

    Deploy Applications and Docker containers across datacenters to any cloud

    +

    + Nomad supports multi-datacenter and multi-region clusters. Deploy applications that + span multiple geographic locations or cloud providers. +

    -

    Phasellus quis arcu nec turpis aliquet malesuada. Pellentesque auctor fermentum cursus.

    +

    Applications containerized with Docker can be quickly deployed, making it easy to scale.

    @@ -106,7 +109,7 @@

    Increase density and reduce cost

    -

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque hendrerit nulla ut orci ultricies viverra.

    +

    Nomad automatically bin packs tasks to maximize efficency, increase density and reduce costs.

    diff --git a/website/source/intro/getting-started/acl.html.md b/website/source/intro/getting-started/acl.html.md index 446affbe8..9bc18b9a5 100644 --- a/website/source/intro/getting-started/acl.html.md +++ b/website/source/intro/getting-started/acl.html.md @@ -3,28 +3,28 @@ layout: "intro" page_title: "Access Control Policies" sidebar_current: "gettingstarted-acl" description: |- - Access control policies in Vault control what a user can access. + Access control policies in Nomad control what a user can access. --- # Access Control Policies (ACLs) -Access control policies in Vault control what a user can access. In +Access control policies in Nomad control what a user can access. In the last section, we learned about _authentication_. This section is about _authorization_. -Whereas for authentication Vault has multiple options or backends that -can be enabled and used, the authorization or policies of Vault are always +Whereas for authentication Nomad has multiple options or backends that +can be enabled and used, the authorization or policies of Nomad are always the same format. All authentication backends must map identities back to -the core policies that are configured with Vault. +the core policies that are configured with Nomad. -When initializing Vault, there is always one special policy created +When initializing Nomad, there is always one special policy created that can't be removed: the "root" policy. This policy is a special policy -that gives superuser access to everything in Vault. An identity mapped to +that gives superuser access to everything in Nomad. An identity mapped to the root policy can do anything. ## Policy Format -Policies in Vault are formatted with +Policies in Nomad are formatted with [HCL](https://github.com/hashicorp/hcl). HCL is a human-readable configuration format that is also JSON-compatible, so you can use JSON as well. An example policy is shown below: @@ -42,13 +42,13 @@ path "secret/foo" { The policy format uses a prefix matching system on the API path to determine access control. The most specific defined policy is used, either an exact match or the longest-prefix glob match. Since everything -in Vault must be accessed via the API, this gives strict control over every -aspect of Vault, including mounting backends, authenticating, as well as secret access. +in Nomad must be accessed via the API, this gives strict control over every +aspect of Nomad, including mounting backends, authenticating, as well as secret access. In the policy above, a user could write any secret to `secret/`, except to `secret/foo`, where only read access is allowed. Policies default to deny, so any access to an unspecified path is not allowed. The policy -language changed slightly in Vault 0.2, [see this page for details](/docs/concepts/policies.html). +language changed slightly in Nomad 0.2, [see this page for details](/docs/concepts/policies.html). Save the above policy as `acl.hcl`. @@ -103,7 +103,7 @@ such as `vault mounts` will not work either. ## Mapping Policies to Auth Backends -Vault is the single policy authority, unlike auth where you can mount +Nomad is the single policy authority, unlike auth where you can mount multiple backends. Any mounted auth backend must map identities to these core policies. @@ -124,12 +124,12 @@ mapping policies to identity. ## Next -Policies are an important part of Vault. While using the root token +Policies are an important part of Nomad. While using the root token is easiest to get up and running, you'll want to restrict access to -Vault very quickly, and the policy system is the way to do this. +Nomad very quickly, and the policy system is the way to do this. The syntax and function of policies is easy to understand and work with, and because auth backends all must map to the central policy system, you only have to learn this policy system. -Next, we'll cover how to [deploy Vault](/intro/getting-started/deploy.html). +Next, we'll cover how to [deploy Nomad](/intro/getting-started/deploy.html). diff --git a/website/source/intro/getting-started/apis.html.md b/website/source/intro/getting-started/apis.html.md index 753b96517..f2bac7499 100644 --- a/website/source/intro/getting-started/apis.html.md +++ b/website/source/intro/getting-started/apis.html.md @@ -7,9 +7,9 @@ description: |- --- # Using the HTTP APIs with Authentication -All of Vault's capabilities are accessible via the HTTP API in addition to the CLI. In fact, most calls from the CLI actually invoke the HTTP API. In some cases, Vault features are not available via the CLI and can only be accessed via the HTTP API. +All of Nomad's capabilities are accessible via the HTTP API in addition to the CLI. In fact, most calls from the CLI actually invoke the HTTP API. In some cases, Nomad features are not available via the CLI and can only be accessed via the HTTP API. -Once you have started the Vault server, you can use `curl` or any other http client to make API calls. For example, if you started the Vault server in [development mode](/docs/concepts/dev-server.html), you could validate the initialization status like this: +Once you have started the Nomad server, you can use `curl` or any other http client to make API calls. For example, if you started the Nomad server in [development mode](/docs/concepts/dev-server.html), you could validate the initialization status like this: ``` $ curl http://127.0.0.1:8200/v1/sys/init @@ -22,7 +22,7 @@ This will return a JSON response: ``` ## Accessing Secrets via the REST APIs -Machines that need access to information stored in Vault will most likely access Vault via its REST API. For example, if a machine were using [app-id](/docs/auth/app-id.html) for authentication, the application would first authenticate to Vault which would return a Vault API token. The application would use that token for future communication with Vault. +Machines that need access to information stored in Nomad will most likely access Nomad via its REST API. For example, if a machine were using [app-id](/docs/auth/app-id.html) for authentication, the application would first authenticate to Nomad which would return a Nomad API token. The application would use that token for future communication with Nomad. For the purpose of this guide, we will use the following configuration which disables TLS and uses a file-based backend. You should never disable TLS in production, but it is okay for the purposes of this tutorial. @@ -36,13 +36,13 @@ listener "tcp" { } ``` -Save this file on disk and then start the Vault server with this command: +Save this file on disk and then start the Nomad server with this command: ``` $ vault server -config=/etc/vault.conf ``` -At this point, we can use Vault's API for all our interactions. For example, we can initialize Vault like this: +At this point, we can use Nomad's API for all our interactions. For example, we can initialize Nomad like this: ``` $ curl \ @@ -60,15 +60,15 @@ The response should be JSON and look something like this: } ``` -This response contains our initial root token. It also includes the unseal key. You can use the uneal key to unseal the Vault and use the root token perform other requests in Vault that require authentication. +This response contains our initial root token. It also includes the unseal key. You can use the uneal key to unseal the Nomad and use the root token perform other requests in Nomad that require authentication. -To make this guide easy to copy-and-paste, we will be using the environment variable `$VAULT_TOKEN` to store the root token. You can export this Vault token in your current shell like this: +To make this guide easy to copy-and-paste, we will be using the environment variable `$VAULT_TOKEN` to store the root token. You can export this Nomad token in your current shell like this: ``` $ export VAULT_TOKEN=0e2ede5a-6664-a49e-ca33-8f204d1cdb95 ``` -Using the unseal key (not the root token) from above, you can unseal the Vault via the HTTP API: +Using the unseal key (not the root token) from above, you can unseal the Nomad via the HTTP API: ``` $ curl \ @@ -95,38 +95,38 @@ We can enable an authentication backend with the following `curl` command: ``` $ curl \ -X POST \ - -H "X-Vault-Token:$VAULT_TOKEN" \ + -H "X-Nomad-Token:$VAULT_TOKEN" \ -d '{"type":"app-id"}' \ http://127.0.0.1:8200/v1/sys/auth/app-id ``` -Notice that the request to the app-id endpoint needed an authentication token. In this case we are passing the root token generated when we started the Vault server. We could also generate tokens using any other authentication mechanisms, but we will use the root token for simplicity. +Notice that the request to the app-id endpoint needed an authentication token. In this case we are passing the root token generated when we started the Nomad server. We could also generate tokens using any other authentication mechanisms, but we will use the root token for simplicity. The last thing we need to do before using our App ID endpoint is writing the data to the store to associate an app id with a user id. For more information on this process, see the documentation on the [app-id auth backend](/docs/auth/app-id.html). -First, we need to associate the application with a particular [ACL policy](/docs/concepts/policies.html) in Vault. In the following command, we are going to associate the created tokens with the `root` policy. You would not want to do this in a real production scenario because the root policy allows complete read, write, and administrator access to Vault. For a production application, you should create an ACL policy (which is also possible via the HTTP API), but is not covered in this guide for simplicity. +First, we need to associate the application with a particular [ACL policy](/docs/concepts/policies.html) in Nomad. In the following command, we are going to associate the created tokens with the `root` policy. You would not want to do this in a real production scenario because the root policy allows complete read, write, and administrator access to Nomad. For a production application, you should create an ACL policy (which is also possible via the HTTP API), but is not covered in this guide for simplicity. ``` $ curl \ -X POST \ - -H "X-Vault-Token:$VAULT_TOKEN" \ + -H "X-Nomad-Token:$VAULT_TOKEN" \ -d '{"value":"root", "display_name":"demo"}' \ http://localhost:8200/v1/auth/app-id/map/app-id/152AEA38-85FB-47A8-9CBD-612D645BFACA ``` Note that `152AEA38-85FB-47A8-9CBD-612D645BFACA` is a randomly generated UUID. You can use any tool to generate a UUID, but make sure it is unique. -Next we need to map the application to a particular "user". In Vault, this is actually a particular application: +Next we need to map the application to a particular "user". In Nomad, this is actually a particular application: ``` $ curl \ -X POST \ - -H "X-Vault-Token:$VAULT_TOKEN" \ + -H "X-Nomad-Token:$VAULT_TOKEN" \ -d '{"value":"152AEA38-85FB-47A8-9CBD-612D645BFACA"}' \ http://localhost:8200/v1/auth/app-id/map/user-id/5ADF8218-D7FB-4089-9E38-287465DBF37E ``` -Now your app can identify itself via the app-id and user-id and get access to Vault. The first step is to authenticate: +Now your app can identify itself via the app-id and user-id and get access to Nomad. The first step is to authenticate: ``` $ curl \ @@ -156,7 +156,7 @@ This will return a response that looks like the following: } ``` -The returned client token (`7a25c58b-9bad-5750-b579-edbb9f10a5ef`) can now be used to authenticate with Vault. As you can see from the returned payload, the App ID backend does not currently support lease expiration or renewal. If you authenticate with backend that does support leases, your application will have to track expiration and handle renewal, but that is a topic for another guide. +The returned client token (`7a25c58b-9bad-5750-b579-edbb9f10a5ef`) can now be used to authenticate with Nomad. As you can see from the returned payload, the App ID backend does not currently support lease expiration or renewal. If you authenticate with backend that does support leases, your application will have to track expiration and handle renewal, but that is a topic for another guide. We can export this new token as our new `VAULT_TOKEN`: @@ -164,12 +164,12 @@ We can export this new token as our new `VAULT_TOKEN`: $ export VAULT_TOKEN="7a25c58b-9bad-5750-b579-edbb9f10a5ef" ``` -Be sure to replace this with the value returned from your API response. We can now use this token to authentication requests to Vault: +Be sure to replace this with the value returned from your API response. We can now use this token to authentication requests to Nomad: ``` $ curl \ -X POST \ - -H "X-Vault-Token:$VAULT_TOKEN" \ + -H "X-Nomad-Token:$VAULT_TOKEN" \ -H 'Content-type: application/json' \ -d '{"bar":"baz"}' \ http://127.0.0.1:8200/v1/secret/foo @@ -179,7 +179,7 @@ This will create a new secret named "foo" with the given JSON contents. We can r ``` $ curl \ - -H "X-Vault-Token:$VAULT_TOKEN" \ + -H "X-Nomad-Token:$VAULT_TOKEN" \ http://127.0.0.1:8200/v1/secret/foo ``` @@ -199,7 +199,7 @@ This should return a response like this: You can see the documentation on the [HTTP APIs](/docs/http/index.html) for more details on other available endpoints. -Congratulations! You now know all the basics to get started with Vault. +Congratulations! You now know all the basics to get started with Nomad. ## Next diff --git a/website/source/intro/getting-started/authentication.html.md b/website/source/intro/getting-started/authentication.html.md index 6ae058329..253152a85 100644 --- a/website/source/intro/getting-started/authentication.html.md +++ b/website/source/intro/getting-started/authentication.html.md @@ -3,36 +3,36 @@ layout: "intro" page_title: "Authentication" sidebar_current: "gettingstarted-auth" description: |- - Authentication to Vault gives a user access to use Vault. Vault can authenticate using multiple methods. + Authentication to Nomad gives a user access to use Nomad. Nomad can authenticate using multiple methods. --- # Authentication -Now that we know how to use the basics of Vault, it is important to understand -how to authenticate to Vault itself. Up to this point, we haven't had to -authenticate because starting the Vault server in dev mode automatically logs +Now that we know how to use the basics of Nomad, it is important to understand +how to authenticate to Nomad itself. Up to this point, we haven't had to +authenticate because starting the Nomad server in dev mode automatically logs us in as root. In practice, you'll almost always have to manually authenticate. On this page, we'll talk specifically about _authentication_. On the next page, we talk about _authorization_. -Authentication is the mechanism of assigning an identity to a Vault user. +Authentication is the mechanism of assigning an identity to a Nomad user. The access control and permissions associated with an identity are authorization, and will not be covered on this page. -Vault has pluggable authentication backends, making it easy to authenticate -with Vault using whatever form works best for your organization. On this page +Nomad has pluggable authentication backends, making it easy to authenticate +with Nomad using whatever form works best for your organization. On this page we'll use the token backend as well as the GitHub backend. ## Tokens We'll first explain token authentication before going over any other authentication backends. Token authentication is enabled by default in -Vault and cannot be disabled. It is also what we've been using up to this +Nomad and cannot be disabled. It is also what we've been using up to this point. When you start a dev server with `vault server -dev`, it outputs your -_root token_. The root token is the initial access token to configure Vault. -It has root privileges, so it can perform any operation within Vault. +_root token_. The root token is the initial access token to configure Nomad. +It has root privileges, so it can perform any operation within Nomad. We'll cover how to limit privileges in the next section. You can create more tokens using `vault token-create`: @@ -70,17 +70,17 @@ with this token are listed below: root ``` -This authenticates with Vault. It will verify your token and let you know +This authenticates with Nomad. It will verify your token and let you know what access policies the token is associated with. If you want to test `vault auth`, make sure you create a new token first. ## Auth Backends In addition to tokens, other authentication backends can be enabled. -Authentication backends enable alternate methods of identifying with Vault. +Authentication backends enable alternate methods of identifying with Nomad. These identities are tied back to a set of access policies, just like tokens. -Vault supports other authentication backends in order to make authentication +Nomad supports other authentication backends in order to make authentication easiest for your environment. For example, for desktop environments, private key or GitHub based authentication may be easiest. For server environments, some shared secret may be best. Auth backends give you @@ -148,19 +148,19 @@ $ vault auth-disable github Disabled auth provider at path 'github'! ``` -If you ran the above, you'll probably find you can't access your Vault +If you ran the above, you'll probably find you can't access your Nomad anymore unless you have another root token, since it invalidated your own session since we authenticated with GitHub above. Since we're still operating in development mode, just restart the dev server to fix this. ## Next -In this page you learned about how Vault authenticates users. You learned +In this page you learned about how Nomad authenticates users. You learned about the built-in token system as well as enabling other authentication -backends. At this point you know how Vault assigns an _identity_ to +backends. At this point you know how Nomad assigns an _identity_ to a user. -The multiple authentication backends Vault provides let you choose the +The multiple authentication backends Nomad provides let you choose the most appropriate authentication mechanism for your organization. In this next section, we'll learn about diff --git a/website/source/intro/getting-started/deploy.html.md b/website/source/intro/getting-started/deploy.html.md index 14aef2d9f..bd1b8f398 100644 --- a/website/source/intro/getting-started/deploy.html.md +++ b/website/source/intro/getting-started/deploy.html.md @@ -1,26 +1,26 @@ --- layout: "intro" -page_title: "Deploy Vault" +page_title: "Deploy Nomad" sidebar_current: "gettingstarted-deploy" description: |- - Learn how to deploy Vault into production, how to initialize it, configure it, etc. + Learn how to deploy Nomad into production, how to initialize it, configure it, etc. --- -# Deploy Vault +# Deploy Nomad Up to this point, we've been working with the dev server, which automatically authenticated us, setup in-memory storage, etc. Now that -you know the basics of Vault, it is important to learn how to deploy -Vault into a real environment. +you know the basics of Nomad, it is important to learn how to deploy +Nomad into a real environment. -On this page, we'll cover how to configure Vault, start Vault, the -seal/unseal process, and scaling Vault. +On this page, we'll cover how to configure Nomad, start Nomad, the +seal/unseal process, and scaling Nomad. -## Configuring Vault +## Configuring Nomad -Vault is configured using [HCL](https://github.com/hashicorp/hcl) files. +Nomad is configured using [HCL](https://github.com/hashicorp/hcl) files. As a reminder, these files are also JSON-compatible. The configuration -file for Vault is relatively simple. An example is shown below: +file for Nomad is relatively simple. An example is shown below: ```javascript backend "consul" { @@ -36,17 +36,17 @@ listener "tcp" { Within the configuration file, there are two primary configurations: - * `backend` - This is the physical backend that Vault uses for + * `backend` - This is the physical backend that Nomad uses for storage. Up to this point the dev server has used "inmem" (in memory), but in the example above we're using [Consul](http://www.consul.io), a much more production-ready backend. - * `listener` - One or more listeners determine how Vault listens for + * `listener` - One or more listeners determine how Nomad listens for API requests. In the example above we're listening on localhost port 8200 without TLS. For now, copy and paste the configuration above to `example.hcl`. It will -configure Vault to expect an instance of Consul running locally. +configure Nomad to expect an instance of Consul running locally. Starting a local Consul instance takes only a few minutes. Just follow the [Consul Getting Started Guide](https://www.consul.io/intro/getting-started/install.html) @@ -64,34 +64,34 @@ where you saved the configuration above. ``` $ vault server -config=example.hcl -==> Vault server configuration: +==> Nomad server configuration: Log Level: info Backend: consul Listener 1: tcp (addr: "127.0.0.1:8200", tls: "disabled") -==> Vault server started! Log data will stream in below: +==> Nomad server started! Log data will stream in below: ``` -Vault outputs some information about its configuration, and then blocks. +Nomad outputs some information about its configuration, and then blocks. This process should be run using a resource manager such as systemd or upstart. You'll notice that you can't execute any commands. We don't have any -auth information! When you first setup a Vault server, you have to start +auth information! When you first setup a Nomad server, you have to start by _initializing_ it. -On Linux, Vault may fail to start with the following error: +On Linux, Nomad may fail to start with the following error: ```shell $ vault server -config=example.hcl Error initializing core: Failed to lock memory: cannot allocate memory This usually means that the mlock syscall is not available. -Vault uses mlock to prevent memory from being swapped to +Nomad uses mlock to prevent memory from being swapped to disk. This requires root privileges as well as a machine that supports mlock. Please enable mlock on your system or -disable Vault from using it. To disable Vault from using it, +disable Nomad from using it. To disable Nomad from using it, set the `disable_mlock` configuration option in your configuration file. ``` @@ -99,16 +99,16 @@ file. For guidance on dealing with this issue, see the discussion of `disable_mlock` in [Server Configuration](/docs/config/index.html). -## Initializing the Vault +## Initializing the Nomad -Initialization is the process of first configuring the Vault. This +Initialization is the process of first configuring the Nomad. This only happens once when the server is started against a new backend that -has never been used with Vault before. +has never been used with Nomad before. During initialization, the encryption keys are generated, unseal keys -are created, and the initial root token is setup. To initialize Vault +are created, and the initial root token is setup. To initialize Nomad use `vault init`. This is an _unauthenticated_ request, but it only works -on brand new Vaults with no data: +on brand new Nomads with no data: ``` $ vault init @@ -119,21 +119,21 @@ Key 4: 8dd72fd7d1af254de5f82d1270fd87ab04 Key 5: b47fdeb7dda82dbe92d88d3c860f605005 Initial Root Token: eaf5cc32-b48f-7785-5c94-90b5ce300e9b -Vault initialized with 5 keys and a key threshold of 3! +Nomad initialized with 5 keys and a key threshold of 3! -Please securely distribute the above keys. Whenever a Vault server +Please securely distribute the above keys. Whenever a Nomad server is started, it must be unsealed with 3 (the threshold) of the keys above (any of the keys, as long as the total number equals the threshold). -Vault does not store the original master key. If you lose the keys +Nomad does not store the original master key. If you lose the keys above such that you no longer have the minimum number (the -threshold), then your Vault will not be able to be unsealed. +threshold), then your Nomad will not be able to be unsealed. ``` Initialization outputs two incredibly important pieces of information: the _unseal keys_ and the _initial root token_. This is the -**only time ever** that all of this data is known by Vault, and also the +**only time ever** that all of this data is known by Nomad, and also the only time that the unseal keys should ever be so close together. For the purpose of this getting started guide, save all these keys @@ -142,25 +142,25 @@ save these keys together. ## Seal/Unseal -Every initialized Vault server starts in the _sealed_ state. From -the configuration, Vault can access the physical storage, but it can't +Every initialized Nomad server starts in the _sealed_ state. From +the configuration, Nomad can access the physical storage, but it can't read any of it because it doesn't know how to decrypt it. The process -of teaching Vault how to decrypt the data is known as _unsealing_ the -Vault. +of teaching Nomad how to decrypt the data is known as _unsealing_ the +Nomad. -Unsealing has to happen every time Vault starts. It can be done via -the API and via the command line. To unseal the Vault, you +Unsealing has to happen every time Nomad starts. It can be done via +the API and via the command line. To unseal the Nomad, you must have the _threshold_ number of unseal keys. In the output above, notice that the "key threshold" is 3. This means that to unseal -the Vault, you need 3 of the 5 keys that were generated. +the Nomad, you need 3 of the 5 keys that were generated. --> **Note:** Vault does not store any of the unseal key shards. Vault +-> **Note:** Nomad does not store any of the unseal key shards. Nomad uses an algorithm known as [Shamir's Secret Sharing](http://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) to split the master key into shards. Only with the threshold number of keys can it be reconstructed and your data finally accessed. -Begin unsealing the Vault with `vault unseal`: +Begin unsealing the Nomad with `vault unseal`: ``` $ vault unseal @@ -171,20 +171,20 @@ Key Threshold: 3 Unseal Progress: 1 ``` -After pasting in a valid key and confirming, you'll see that the Vault -is still sealed, but progress is made. Vault knows it has 1 key out of 3. -Due to the nature of the algorithm, Vault doesn't know if it has the +After pasting in a valid key and confirming, you'll see that the Nomad +is still sealed, but progress is made. Nomad knows it has 1 key out of 3. +Due to the nature of the algorithm, Nomad doesn't know if it has the _correct_ key until the threshold is reached. Also notice that the unseal process is stateful. You can go to another computer, use `vault unseal`, and as long as it's pointing to the same server, that other computer can continue the unseal process. This is incredibly important to the design of the unseal process: multiple people with multiple -keys are required to unseal the Vault. The Vault can be unsealed from +keys are required to unseal the Nomad. The Nomad can be unsealed from multiple computers and the keys should never be together. A single malicious operator does not have enough keys to be malicious. -Continue with `vault unseal` to complete unsealing the Vault. Note that +Continue with `vault unseal` to complete unsealing the Nomad. Note that all 3 keys must be different, but they can be any other keys. As long as they're correct, you should soon see output like this: @@ -197,26 +197,26 @@ Key Threshold: 3 Unseal Progress: 0 ``` -The `Sealed: false` means the Vault is unsealed! +The `Sealed: false` means the Nomad is unsealed! Feel free to play around with entering invalid keys, keys in different orders, etc. in order to understand the unseal process. It is very important. Once you're ready to move on, use `vault auth` to authenticate with the root token. -As a root user, you can reseal the Vault with `vault seal`. A single +As a root user, you can reseal the Nomad with `vault seal`. A single operator is allowed to do this. This lets a single operator lock down -the Vault in an emergency without consulting other operators. +the Nomad in an emergency without consulting other operators. -When the Vault is sealed again, it clears all of its state (including -the encryption key) from memory. The Vault is secure and locked down +When the Nomad is sealed again, it clears all of its state (including +the encryption key) from memory. The Nomad is secure and locked down from access. ## Next -You now know how to configure, initialize, and unseal/seal Vault. -This is the basic knowledge necessary to deploy Vault into a real -environment. Once the Vault is unsealed, you access it as you have -throughout this getting started guide (which worked with an unsealed Vault). +You now know how to configure, initialize, and unseal/seal Nomad. +This is the basic knowledge necessary to deploy Nomad into a real +environment. Once the Nomad is unsealed, you access it as you have +throughout this getting started guide (which worked with an unsealed Nomad). Next, we have a [short tutorial](/intro/getting-started/apis.html) on using the HTTP APIs to authenticate and access secrets. diff --git a/website/source/intro/getting-started/dev-server.html.md b/website/source/intro/getting-started/dev-server.html.md index 21a6251e2..b8253f999 100644 --- a/website/source/intro/getting-started/dev-server.html.md +++ b/website/source/intro/getting-started/dev-server.html.md @@ -3,51 +3,51 @@ layout: "intro" page_title: "Starting the Server" sidebar_current: "gettingstarted-devserver" description: |- - After installing Vault, the next step is to start the server. + After installing Nomad, the next step is to start the server. --- -# Starting the Vault Server +# Starting the Nomad Server -With Vault installed, the next step is to start a Vault server. +With Nomad installed, the next step is to start a Nomad server. -Vault operates as a client/server application. The Vault server is the -only piece of the Vault architecture that interacts with the data -storage and backends. All operations done via the Vault CLI interact +Nomad operates as a client/server application. The Nomad server is the +only piece of the Nomad architecture that interacts with the data +storage and backends. All operations done via the Nomad CLI interact with the server over a TLS connection. -In this page, we'll start and interact with the Vault server to understand +In this page, we'll start and interact with the Nomad server to understand how the server is started, and understanding the seal/unseal process. ## Starting the Dev Server -To start, we're going to start the Vault _dev server_. The dev server +To start, we're going to start the Nomad _dev server_. The dev server is a built-in flag to start a pre-configured server that is not very -secure but useful for playing with Vault locally. Later in the getting +secure but useful for playing with Nomad locally. Later in the getting started guide we'll configure and start a real server. -To start the Vault dev server, run `vault server -dev`: +To start the Nomad dev server, run `vault server -dev`: ``` $ vault server -dev WARNING: Dev mode is enabled! -In this mode, Vault is completely in-memory and unsealed. -Vault is configured to only have a single unseal key. The root +In this mode, Nomad is completely in-memory and unsealed. +Nomad is configured to only have a single unseal key. The root token has already been authenticated with the CLI, so you can -immediately begin using the Vault CLI. +immediately begin using the Nomad CLI. The only step you need to take is to set the following -environment variable since Vault will be talking without TLS: +environment variable since Nomad will be talking without TLS: export VAULT_ADDR='http://127.0.0.1:8200' The unseal key and root token are reproduced below in case you -want to seal/unseal the Vault or play with authentication. +want to seal/unseal the Nomad or play with authentication. Unseal Key: 2252546b1a8551e8411502501719c4b3 Root Token: 79bd8011-af5a-f147-557e-c58be4fedf6c -==> Vault server configuration: +==> Nomad server configuration: Log Level: info Backend: inmem @@ -57,7 +57,7 @@ Root Token: 79bd8011-af5a-f147-557e-c58be4fedf6c ``` You should see output similar to that above. As you can see, when you -start a dev server, Vault warns you loudly. The dev server stores all +start a dev server, Nomad warns you loudly. The dev server stores all its data in-memory (but still encrypted), listens on localhost without TLS, and automatically unseals and shows you the unseal key and root access key. We'll go over what all this means shortly. @@ -71,7 +71,7 @@ With the dev server running, do the following three things before anything else: 1. Copy and run the `export VAULT_ADDR ...` command from your terminal - output. This will configure the Vault client to talk to our dev server. + output. This will configure the Nomad client to talk to our dev server. 2. Save the unseal key somewhere. Don't worry about _how_ to save this securely. For now, just save it anywhere. @@ -98,7 +98,7 @@ High-Availability Enabled: false ``` If the output looks different, especially if the numbers are different -or the Vault is sealed, then restart the dev server and try again. The +or the Nomad is sealed, then restart the dev server and try again. The only reason these would ever be different is if you're running a dev server from going through this guide previously. @@ -106,7 +106,7 @@ We'll cover what this output means later in the guide. ## Next -Congratulations! You've started your first Vault server. We haven't stored +Congratulations! You've started your first Nomad server. We haven't stored any secrets yet, but we'll do that in the next section. Next, we're going to diff --git a/website/source/intro/getting-started/dynamic-secrets.html.md b/website/source/intro/getting-started/dynamic-secrets.html.md index 2ef584735..ede1addd1 100644 --- a/website/source/intro/getting-started/dynamic-secrets.html.md +++ b/website/source/intro/getting-started/dynamic-secrets.html.md @@ -3,14 +3,14 @@ layout: "intro" page_title: "Dynamic Secrets" sidebar_current: "gettingstarted-dynamicsecrets" description: |- - On this page we introduce dynamic secrets by showing you how to create AWS access keys with Vault. + On this page we introduce dynamic secrets by showing you how to create AWS access keys with Nomad. --- # Dynamic Secrets -Now that we've written basic secrets to Vault and we have an understanding +Now that we've written basic secrets to Nomad and we have an understanding of the mount system, we're going to move on to the next core feature of -Vault: _dynamic secrets_. +Nomad: _dynamic secrets_. Dynamic secrets are secrets that are generated when they're accessed, and aren't statically written like we did in @@ -20,7 +20,7 @@ generate AWS access keys. The power of dynamic secrets is that they simply don't exist before they're read, so there is no risk of someone stealing them or another -client using the same secrets. And because Vault has built-in revocation +client using the same secrets. And because Nomad has built-in revocation mechanisms (covered later), the dynamic secret can be revoked right after use, minimizing the amount of time the secret existed. @@ -105,7 +105,7 @@ many policies with the backend. Save a file named "policy.json" with the followi ``` This is a basic IAM policy that lets the user perform any action within -Amazon EC2. With the policy saved, write it to Vault and create a new role: +Amazon EC2. With the policy saved, write it to Nomad and create a new role: ``` $ vault write aws/roles/deploy policy=@policy.json @@ -113,7 +113,7 @@ Success! Data written to: aws/roles/deploy ``` Again, we're using a special path here `aws/roles/` to write -an IAM policy to Vault. We also used the special syntax `@filename` with +an IAM policy to Nomad. We also used the special syntax `@filename` with `vault write` to write the contents of a file. ## Generating the Secret @@ -134,7 +134,7 @@ Success! The access and secret key can now be used to perform any EC2 operations within AWS. You can verify they work, if you want. Also notice that these keys are new, they're not the keys you entered earlier. -The `lease_id` above is a special ID used for Vault for renewal, +The `lease_id` above is a special ID used for Nomad for renewal, revocation, etc. Copy and save your Lease ID now. ## Revoking the Secret @@ -164,7 +164,7 @@ exist for the duration that they're needed. On this page we experienced our first dynamic secret, and we also saw the revocation system in action. Dynamic secrets are incredibly powerful. As time goes on, we expect that more systems will support some sort of -API to create access credentials, and Vault will be ready to get the +API to create access credentials, and Nomad will be ready to get the most value out of this practice. Before going further, we're going to take a quick detour to learn diff --git a/website/source/intro/getting-started/first-secret.html.md b/website/source/intro/getting-started/first-secret.html.md index dea0b463e..30b2f6d47 100644 --- a/website/source/intro/getting-started/first-secret.html.md +++ b/website/source/intro/getting-started/first-secret.html.md @@ -3,7 +3,7 @@ layout: "intro" page_title: "Your First Secret" sidebar_current: "gettingstarted-firstsecret" description: |- - With the Vault server running, let's read and write our first secret. + With the Nomad server running, let's read and write our first secret. --- # Your First Secret @@ -11,18 +11,18 @@ description: |- Now that the dev server is up and running, let's get straight to it and read and write our first secret. -One of the core features of Vault is the ability to read and write +One of the core features of Nomad is the ability to read and write arbitrary secrets securely. On this page, we'll do this using the CLI, but there is also a complete [HTTP API](/docs/http/index.html) -that can be used to programmatically do anything with Vault. +that can be used to programmatically do anything with Nomad. -Secrets written to Vault are encrypted and then written to the backend +Secrets written to Nomad are encrypted and then written to the backend storage. For our dev server, backend storage is in-memory, but in production this would more likely be on disk or in [Consul](https://www.consul.io). -Vault encrypts the value before it is ever handed to the storage driver. +Nomad encrypts the value before it is ever handed to the storage driver. The backend storage mechanism _never_ sees the unencrypted value and doesn't -have the means necessary to decrypt it without Vault. +have the means necessary to decrypt it without Nomad. ## Writing a Secret @@ -69,7 +69,7 @@ excited yes value world ``` -As you can see, the values we wrote are given back to us. Vault read +As you can see, the values we wrote are given back to us. Nomad read the data from storage and decrypted it. The output format is purposefully whitespace separated to make it easy to pipe into a tool like `awk`. @@ -112,7 +112,7 @@ Success! Deleted 'secret/hello' ## Next In this section we learned how to use the powerful CRUD features of -Vault to store arbitrary secrets. On its own this is already a useful +Nomad to store arbitrary secrets. On its own this is already a useful but basic feature. Next, we'll learn the basics about [secret backends](/intro/getting-started/secret-backends.html). diff --git a/website/source/intro/getting-started/help.html.md b/website/source/intro/getting-started/help.html.md index 523a7ce58..827886b3d 100644 --- a/website/source/intro/getting-started/help.html.md +++ b/website/source/intro/getting-started/help.html.md @@ -3,7 +3,7 @@ layout: "intro" page_title: "Built-in Help" sidebar_current: "gettingstarted-help" description: |- - Vault has a built-in help system to learn about the available paths in Vault and how to use them. + Nomad has a built-in help system to learn about the available paths in Nomad and how to use them. --- # Built-in Help @@ -16,11 +16,11 @@ the paths to use differed. AWS in particular had special paths like Instead of having to memorize or reference documentation constantly to determine what paths to use, we built a help system directly into -Vault. This help system can be accessed via the API or the command-line and +Nomad. This help system can be accessed via the API or the command-line and generates human-readable help for any mounted backend. On this page, we'll learn how to use this help system. It is an invaluable -tool as you continue to work with Vault. +tool as you continue to work with Nomad. ## Backend Overview @@ -112,9 +112,9 @@ generic `secret/` path. ## Next -The help system may not be the most exciting feature of Vault, but it -is indispensable in day-to-day usage of Vault. The help system lets you -learn about how to use any backend within Vault without leaving the command +The help system may not be the most exciting feature of Nomad, but it +is indispensable in day-to-day usage of Nomad. The help system lets you +learn about how to use any backend within Nomad without leaving the command line. Next, we'll learn about diff --git a/website/source/intro/getting-started/install.html.md b/website/source/intro/getting-started/install.html.md index e73aedabb..c865fae6d 100644 --- a/website/source/intro/getting-started/install.html.md +++ b/website/source/intro/getting-started/install.html.md @@ -1,28 +1,28 @@ --- layout: "intro" -page_title: "Install Vault" +page_title: "Install Nomad" sidebar_current: "gettingstarted-install" description: |- - The first step to using Vault is to get it installed. + The first step to using Nomad is to get it installed. --- -# Install Vault +# Install Nomad -Vault must first be installed on your machine. Vault is distributed as +Nomad must first be installed on your machine. Nomad is distributed as a [binary package](/downloads.html) for all supported platforms and -architectures. This page will not cover how to compile Vault from source, +architectures. This page will not cover how to compile Nomad from source, but compiling from source is covered in the [documentation](/docs/install/index.html) for those who want to be sure they're compiling source they trust into the final binary. -## Installing Vault +## Installing Nomad -To install Vault, find the [appropriate package](/downloads.html) for -your system and download it. Vault is packaged as a zip archive. +To install Nomad, find the [appropriate package](/downloads.html) for +your system and download it. Nomad is packaged as a zip archive. -After downloading Vault, unzip the package. Vault runs as a single binary +After downloading Nomad, unzip the package. Nomad runs as a single binary named `vault`. Any other files in the package can be safely removed and -Vault will still function. +Nomad will still function. The final step is to make sure that `vault` is available on the PATH. See [this page](http://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux) @@ -32,7 +32,7 @@ contains instructions for setting the PATH on Windows. ## Verifying the Installation -After installing Vault, verify the installation worked by opening a new +After installing Nomad, verify the installation worked by opening a new terminal session and checking that `vault` is available. By executing `vault`, you should see help output similar to the following: @@ -41,30 +41,30 @@ $ vault usage: vault [-version] [-help] [args] Common commands: - delete Delete operation on secrets in Vault + delete Delete operation on secrets in Nomad path-help Look up the help for a path - read Read data or secrets from Vault + read Read data or secrets from Nomad renew Renew the lease of a secret revoke Revoke a secret. - server Start a Vault server - status Outputs status of whether Vault is sealed and if HA mode is enabled - write Write secrets or configuration into Vault + server Start a Nomad server + status Outputs status of whether Nomad is sealed and if HA mode is enabled + write Write secrets or configuration into Nomad All other commands: audit-disable Disable an audit backend audit-enable Enable an audit backend - audit-list Lists enabled audit backends in Vault - auth Prints information about how to authenticate with Vault + audit-list Lists enabled audit backends in Nomad + auth Prints information about how to authenticate with Nomad auth-disable Disable an auth provider auth-enable Enable a new auth provider - init Initialize a new Vault server + init Initialize a new Nomad server key-status Provides information about the active encryption key mount Mount a logical backend - mounts Lists mounted backends in Vault + mounts Lists mounted backends in Nomad policies List the policies on the server policy-delete Delete a policy from the server policy-write Write a policy to the server - rekey Rekeys Vault to generate new unseal keys + rekey Rekeys Nomad to generate new unseal keys remount Remount a secret backend to a new path rotate Rotates the backend encryption key used to persist data seal Seals the vault server @@ -73,11 +73,11 @@ All other commands: token-revoke Revoke one or more auth tokens unmount Unmount a secret backend unseal Unseals the vault server - version Prints the Vault version + version Prints the Nomad version ``` -If you get an error that Vault could not be found, then your PATH environment +If you get an error that Nomad could not be found, then your PATH environment variable was not setup properly. Please go back and ensure that your PATH -variable contains the directory where Vault was installed. +variable contains the directory where Nomad was installed. -Otherwise, Vault is installed and ready to go! +Otherwise, Nomad is installed and ready to go! diff --git a/website/source/intro/getting-started/next-steps.html.md b/website/source/intro/getting-started/next-steps.html.md index 3e6b0e0d9..6d7d57b1d 100644 --- a/website/source/intro/getting-started/next-steps.html.md +++ b/website/source/intro/getting-started/next-steps.html.md @@ -3,18 +3,18 @@ layout: "intro" page_title: "Next Steps" sidebar_current: "gettingstarted-nextsteps" description: |- - After completing the getting started guide, learn about what to do next with Vault. + After completing the getting started guide, learn about what to do next with Nomad. --- # Next Steps -That concludes the getting started guide for Vault. Hopefully you're -excited about the possibilities of Vault and ready to put this knowledge +That concludes the getting started guide for Nomad. Hopefully you're +excited about the possibilities of Nomad and ready to put this knowledge to use to improve your environment. -We've covered the basics of all the core features of Vault in this guide. +We've covered the basics of all the core features of Nomad in this guide. Due to the importance of securing secrets, we recommend reading the following as next steps. * [Documentation](/docs/index.html) - The documentation is an in-depth - reference guide to all the features of Vault. + reference guide to all the features of Nomad. diff --git a/website/source/intro/getting-started/secret-backends.html.md b/website/source/intro/getting-started/secret-backends.html.md index 14f32cf2c..4516fc1e8 100644 --- a/website/source/intro/getting-started/secret-backends.html.md +++ b/website/source/intro/getting-started/secret-backends.html.md @@ -8,21 +8,21 @@ description: |- # Secret Backends -Previously, we saw how to read and write arbitrary secrets to Vault. +Previously, we saw how to read and write arbitrary secrets to Nomad. To do this, we used the `secret/` prefix. This prefix specifies the -_secret backend_ to use, and Vault defaults to mounting the _generic_ +_secret backend_ to use, and Nomad defaults to mounting the _generic_ backend to `secret/`. The generic backend reads and writes raw data to the backend storage. -Vault supports other backends in addition to "generic", and this feature -in particular is what makes Vault unique. For example, the "aws" backend +Nomad supports other backends in addition to "generic", and this feature +in particular is what makes Nomad unique. For example, the "aws" backend generates AWS access keys dynamically, on demand. Another example -- this type of backend does not yet exist -- is a backend that reads and writes data directly to an [HSM](http://en.wikipedia.org/wiki/Hardware_security_module). -As Vault matures, more and more backends will be added. +As Nomad matures, more and more backends will be added. -To represent backends, Vault behaves much like a filesystem: backends +To represent backends, Nomad behaves much like a filesystem: backends are _mounted_ at specific paths. For example, the "generic" backend is _mounted_ at the `secret/` prefix. @@ -33,7 +33,7 @@ to the next page, where we'll create dynamic secrets. ## Mount a Backend To start, let's mount another "generic" backend. Just like a normal -filesystem, Vault can mount a backend multiple times at different +filesystem, Nomad can mount a backend multiple times at different mount points. This is useful if you want different access control policies (covered later) or configurations for different paths. @@ -61,7 +61,7 @@ sys/ system system endpoints used for control, policy and debugging You can see the `generic/` path we just mounted, as well as the built-in secret path. You can also see the `sys/` path. We won't cover this in the getting started guide, but this mount point is used to interact with -the Vault core system. +the Nomad core system. Spend some time reading and writing secrets to the new mount point to convince yourself it works. As a bonus, write to the `secret/` endpoint @@ -92,7 +92,7 @@ closely tied to their mount paths. Now that you've mounted and unmounted a backend, you might wonder: "what is a secret backend? what is the point of this mounting system?" -Vault behaves a lot like a [virtual filesystem](http://en.wikipedia.org/wiki/Virtual_file_system). +Nomad behaves a lot like a [virtual filesystem](http://en.wikipedia.org/wiki/Virtual_file_system). The read/write/delete operations are forwarded to the backend, and the backend can choose to react to these operations however it wishes. For example, the "generic" backend simply passes this through to the @@ -103,9 +103,9 @@ policies and access tokens. So, while you might do a `vault read aws/deploy`, this isn't reading from any _physical_ path "aws/deploy". Instead, the AWS backend is dynamically generating an access key based on the "deploy" policy. -This abstraction is incredibly powerful. It lets Vault interface directly +This abstraction is incredibly powerful. It lets Nomad interface directly with physical systems such as the backend as well as things such as SQL -databases, HSMs, etc. But in addition to these physical systems, Vault +databases, HSMs, etc. But in addition to these physical systems, Nomad can interact with more unique environments: AWS IAM, dynamic SQL user creation, etc. all using the same read/write interface. diff --git a/website/source/intro/index.html.markdown b/website/source/intro/index.html.markdown index f6296cf18..10ae223d4 100644 --- a/website/source/intro/index.html.markdown +++ b/website/source/intro/index.html.markdown @@ -3,25 +3,25 @@ layout: "intro" page_title: "Introduction" sidebar_current: "what" description: |- - Welcome to the intro guide to Vault! This guide is the best place to start with Vault. We cover what Vault is, what problems it can solve, how it compares to existing software, and contains a quick start for using Vault. + Welcome to the intro guide to Nomad! This guide is the best place to start with Nomad. We cover what Nomad is, what problems it can solve, how it compares to existing software, and contains a quick start for using Nomad. --- -# Introduction to Vault +# Introduction to Nomad -Welcome to the intro guide to Vault! This guide is the best -place to start with Vault. We cover what Vault is, what +Welcome to the intro guide to Nomad! This guide is the best +place to start with Nomad. We cover what Nomad is, what problems it can solve, how it compares to existing software, -and contains a quick start for using Vault. +and contains a quick start for using Nomad. -If you are already familiar with the basics of Vault, the +If you are already familiar with the basics of Nomad, the [documentation](/docs/index.html) provides a better reference guide for all available features as well as internals. -## What is Vault? +## What is Nomad? -Vault is a tool for securely accessing _secrets_. A secret is anything +Nomad is a tool for securely accessing _secrets_. A secret is anything that you want to tightly control access to, such as API keys, passwords, -certificates, and more. Vault provides a unified interface to any +certificates, and more. Nomad provides a unified interface to any secret, while providing tight access control and recording a detailed audit log. @@ -30,36 +30,36 @@ credentials, API keys for external services, credentials for service-oriented architecture communication, etc. Understanding who is accessing what secrets is already very difficult and platform-specific. Adding on key rolling, secure storage, and detailed audit logs is almost -impossible without a custom solution. This is where Vault steps in. +impossible without a custom solution. This is where Nomad steps in. -Examples work best to showcase Vault. Please see the +Examples work best to showcase Nomad. Please see the [use cases](/intro/use-cases.html). -The key features of Vault are: +The key features of Nomad are: * **Secure Secret Storage**: Arbitrary key/value secrets can be stored - in Vault. Vault encrypts these secrets prior to writing them to persistent + in Nomad. Nomad encrypts these secrets prior to writing them to persistent storage, so gaining access to the raw storage isn't enough to access - your secrets. Vault can write to disk, [Consul](http://www.consul.io), + your secrets. Nomad can write to disk, [Consul](http://www.consul.io), and more. -* **Dynamic Secrets**: Vault can generate secrets on-demand for some +* **Dynamic Secrets**: Nomad can generate secrets on-demand for some systems, such as AWS or SQL databases. For example, when an application - needs to access an S3 bucket, it asks Vault for credentials, and Vault + needs to access an S3 bucket, it asks Nomad for credentials, and Nomad will generate an AWS keypair with valid permissions on demand. After - creating these dynamic secrets, Vault will also automatically revoke them + creating these dynamic secrets, Nomad will also automatically revoke them after the lease is up. -* **Data Encryption**: Vault can encrypt and decrypt data without storing +* **Data Encryption**: Nomad can encrypt and decrypt data without storing it. This allows security teams to define encryption parameters and developers to store encrypted data in a location such as SQL without having to design their own encryption methods. -* **Leasing and Renewal**: All secrets in Vault have a _lease_ associated - with it. At the end of the lease, Vault will automatically revoke that +* **Leasing and Renewal**: All secrets in Nomad have a _lease_ associated + with it. At the end of the lease, Nomad will automatically revoke that secret. Clients are able to renew leases via built-in renew APIs. -* **Revocation**: Vault has built-in support for secret revocation. Vault +* **Revocation**: Nomad has built-in support for secret revocation. Nomad can revoke not only single secrets, but a tree of secrets, for example all secrets read by a specific user, or all secrets of a particular type. Revocation assists in key rolling as well as locking down systems in the @@ -67,9 +67,9 @@ The key features of Vault are: ## Next Steps -See the page on [Vault use cases](/intro/use-cases.html) to see the -multiple ways Vault can be used. Then see -[how Vault compares to other software](/intro/vs/index.html) +See the page on [Nomad use cases](/intro/use-cases.html) to see the +multiple ways Nomad can be used. Then see +[how Nomad compares to other software](/intro/vs/index.html) to see how it fits into your existing infrastructure. Finally, continue onwards with the [getting started guide](/intro/getting-started/install.html) to use -Vault to read, write, and create real secrets and see how it works in practice. +Nomad to read, write, and create real secrets and see how it works in practice. diff --git a/website/source/intro/use-cases.html.markdown b/website/source/intro/use-cases.html.markdown index 4f9df2381..c380c6a3b 100644 --- a/website/source/intro/use-cases.html.markdown +++ b/website/source/intro/use-cases.html.markdown @@ -3,30 +3,30 @@ layout: "intro" page_title: "Use Cases" sidebar_current: "use-cases" description: |- - This page lists some concrete use cases for Vault, but the possible use cases are much broader than what we cover. + This page lists some concrete use cases for Nomad, but the possible use cases are much broader than what we cover. --- # Use Cases -Before understanding use cases, it's useful to know [what Vault is](/intro/index.html). -This page lists some concrete use cases for Vault, but the possible use cases are +Before understanding use cases, it's useful to know [what Nomad is](/intro/index.html). +This page lists some concrete use cases for Nomad, but the possible use cases are much broader than what we cover. #### General Secret Storage -At a bare minimum, Vault can be used for the storage of any secrets. For -example, Vault would be a fantastic way to store sensitive environment variables, +At a bare minimum, Nomad can be used for the storage of any secrets. For +example, Nomad would be a fantastic way to store sensitive environment variables, database credentials, API keys, etc. Compare this with the current way to store these which might be plaintext in files, configuration management, a database, etc. It would be much safer to query these using `vault read` or the API. This protects -the plaintext version of these secrets as well as records access in the Vault +the plaintext version of these secrets as well as records access in the Nomad audit log. #### Employee Credential Storage -While this overlaps with "General Secret Storage", Vault is a good mechanism +While this overlaps with "General Secret Storage", Nomad is a good mechanism for storing credentials that employees share to access web services. The audit log mechanism lets you know what secrets an employee accessed and when an employee leaves, it is easier to roll keys and understand which keys @@ -34,7 +34,7 @@ have and haven't been rolled. #### API Key Generation for Scripts -The "dynamic secrets" feature of Vault is ideal for scripts: an AWS +The "dynamic secrets" feature of Nomad is ideal for scripts: an AWS access key can be generated for the duration of a script, then revoked. The keypair will not exist before or after the script runs, and the creation of the keys are completely logged. @@ -44,12 +44,12 @@ effectively hardcoding limited-access access tokens in various places. #### Data Encryption -In addition to being able to store secrets, Vault can be used to +In addition to being able to store secrets, Nomad can be used to encrypt/decrypt data that is stored elsewhere. The primary use of this is to allow applications to encrypt their data while still storing it in the primary data store. The benefit of this is that developers do not need to worry about how to -properly encrypt data. The responsibility of encryption is on Vault +properly encrypt data. The responsibility of encryption is on Nomad and the security team managing it, and developers just encrypt/decrypt data as needed. diff --git a/website/source/intro/vs/chef-puppet-etc.html.md b/website/source/intro/vs/chef-puppet-etc.html.md index 6555d8ba4..01c08f7a1 100644 --- a/website/source/intro/vs/chef-puppet-etc.html.md +++ b/website/source/intro/vs/chef-puppet-etc.html.md @@ -1,12 +1,12 @@ --- layout: "intro" -page_title: "Vault vs. Chef, Puppet, etc." +page_title: "Nomad vs. Chef, Puppet, etc." sidebar_current: "vs-other-chef" description: |- - Comparison between Vault and configuration management solutions such as Chef, Puppet, etc. + Comparison between Nomad and configuration management solutions such as Chef, Puppet, etc. --- -# Vault vs. Chef, Puppet, etc. +# Nomad vs. Chef, Puppet, etc. A big part of configuring software is setting up secrets: configuring a web application to talk to a service, configuring the credentials of a @@ -22,19 +22,19 @@ to somehow get this secret to decrypt the data. Additionally, access to the encrypted data isn't always logged, so if there is an intrusion, it isn't clear what data has been accessed and by who. -Vault is not tied to any specific configuration management system. You can +Nomad is not tied to any specific configuration management system. You can read secrets from configuration management, but you can also use the API directly to read secrets from applications. This means that configuration management requires less secrets, and in many cases doesn't ever have to persist them to disk. -Vault encrypts the data onto physical storage and requires multiple +Nomad encrypts the data onto physical storage and requires multiple keys to even read it. If an attacker were to gain access to the physical encrypted storage, it couldn't be read without multiple keys which are generally distributed to multiple individuals. This is known as _unsealing_, and happens -once whenever Vault starts. +once whenever Nomad starts. -For an unsealed Vault, every interaction is logged in via the audit backends. +For an unsealed Nomad, every interaction is logged in via the audit backends. Even erroneous requests (invalid access tokens, for example) are logged. To access any data, an access token is required. This token is usually associated with an identity coming from a system such as GitHub, LDAP, etc. @@ -42,4 +42,4 @@ This identity is also written to the audit log. Access tokens can be given fine-grained control over what secrets can be accessed. It is rare to have a single key that can access all secrets. This -makes it easier to have fine-grained access for consumers of Vault. +makes it easier to have fine-grained access for consumers of Nomad. diff --git a/website/source/intro/vs/consul.html.md b/website/source/intro/vs/consul.html.md index 3754455a0..b12fe8066 100644 --- a/website/source/intro/vs/consul.html.md +++ b/website/source/intro/vs/consul.html.md @@ -1,12 +1,12 @@ --- layout: "intro" -page_title: "Vault vs. Consul" +page_title: "Nomad vs. Consul" sidebar_current: "vs-other-consul" description: |- - Comparison between Vault and attempting to store secrets with Consul. + Comparison between Nomad and attempting to store secrets with Consul. --- -# Vault vs. Consul +# Nomad vs. Consul [Consul](https://consul.io) is system for service discovery, monitoring, and configuration that is distributed and highly available. Consul also @@ -17,16 +17,16 @@ ACLs, it is not designed for that purpose. As such, data is not encrypted in transit nor at rest, it does not have pluggable authentication mechanisms, and there is no per-request auditing mechanism. -Vault is designed from the ground up as a secret management solution. As such, +Nomad is designed from the ground up as a secret management solution. As such, it protects secrets in transit and at rest. It provides multiple authentication -and audit logging mechanisms. Dynamic secret generation allows Vault to avoid +and audit logging mechanisms. Dynamic secret generation allows Nomad to avoid providing clients with root privileges to underlying systems and makes it possible to do key rolling and revocation. The strength of Consul is that it is fault tolerant and highly scalable. -By using Consul as a backend to Vault, you get the best of both. Consul +By using Consul as a backend to Nomad, you get the best of both. Consul is used for durable storage of encrypted data at rest and provides coordination -so that Vault can be highly available and fault tolerant. Vault provides +so that Nomad can be highly available and fault tolerant. Nomad provides the higher level policy management, secret leasing, audit logging, and automatic revocation. diff --git a/website/source/intro/vs/custom.html.markdown b/website/source/intro/vs/custom.html.markdown index 3d8015f4f..c745ce98c 100644 --- a/website/source/intro/vs/custom.html.markdown +++ b/website/source/intro/vs/custom.html.markdown @@ -1,12 +1,12 @@ --- layout: "intro" -page_title: "Vault vs. Custom Solutions" +page_title: "Nomad vs. Custom Solutions" sidebar_current: "vs-other-custom" description: |- - Comparison between Vault and writing a custom solution. + Comparison between Nomad and writing a custom solution. --- -# Vault vs. Custom Solutions +# Nomad vs. Custom Solutions Many organizations resort to custom solutions for storing secrets, whether that be Dropbox, encrypted disk images, encrypted SQL columns, @@ -17,12 +17,12 @@ Storing secrets is also an incredibly important piece of infrastructure that must be done correctly. This increases the pressure to maintain the internal systems. -Vault is designed for secret storage. It provides a simple interface +Nomad is designed for secret storage. It provides a simple interface on top of a strong security model to meet your secret storage needs. -Furthermore, Vault is an open source tool. This means that the tool is +Furthermore, Nomad is an open source tool. This means that the tool is as good as the entire community working together to improve it. This isn't just features and bug fixes, but finding potential security holes. Additionally, since it is an open source, your own security teams can -review and contribute to Vault and verify it meets your standards +review and contribute to Nomad and verify it meets your standards for security. diff --git a/website/source/intro/vs/dropbox.html.md b/website/source/intro/vs/dropbox.html.md index f3089549b..1d66d330e 100644 --- a/website/source/intro/vs/dropbox.html.md +++ b/website/source/intro/vs/dropbox.html.md @@ -1,12 +1,12 @@ --- layout: "intro" -page_title: "Vault vs. Dropbox" +page_title: "Nomad vs. Dropbox" sidebar_current: "vs-other-dropbox" description: |- - Comparison between Vault and attempting to store secrets with Dropbox. + Comparison between Nomad and attempting to store secrets with Dropbox. --- -# Vault vs. Dropbox +# Nomad vs. Dropbox It is an unfortunate truth that many organizations, big and small, often use Dropbox as a mechanism for storing secrets. It is so common @@ -17,7 +17,7 @@ Dropbox is not made for storing secrets. Even if you're using something such as an encrypted disk image within Dropbox, it is subpar versus a real secret storage server. -A real secret management tool such as Vault has a stronger security +A real secret management tool such as Nomad has a stronger security model, integrates with many different authentication services, stores audit logs, can generate dynamic secrets, and more. diff --git a/website/source/intro/vs/hsm.html.md b/website/source/intro/vs/hsm.html.md index 4aac1c5dd..adc130b63 100644 --- a/website/source/intro/vs/hsm.html.md +++ b/website/source/intro/vs/hsm.html.md @@ -1,12 +1,12 @@ --- layout: "intro" -page_title: "Vault vs. HSMs" +page_title: "Nomad vs. HSMs" sidebar_current: "vs-other-hsm" description: |- - Comparison between Vault and HSM systems. + Comparison between Nomad and HSM systems. --- -# Vault vs. HSMs +# Nomad vs. HSMs A [hardware security module (HSM)](http://en.wikipedia.org/wiki/Hardware_security_module) is a hardware device that is meant to secure various secrets. They generally @@ -21,19 +21,19 @@ and the "API" to request secrets is also difficult to use. Example: CloudHSM requires SSH and setting up various keypairs manually. It is difficult to automate. -Vault **doesn't replace an HSM**. There are many benefits to an HSM if +Nomad **doesn't replace an HSM**. There are many benefits to an HSM if you can afford it. Instead, an HSM is a fantastic potential secret backend -for Vault. This would allow Vault to access the HSM data via the Vault API, +for Nomad. This would allow Nomad to access the HSM data via the Nomad API, making it significantly easier to use an HSM, while also retaining all the -audit logs. In fact, you'd have multiple audit logs: requests to Vault +audit logs. In fact, you'd have multiple audit logs: requests to Nomad as well as to the HSM. -Vault can also do many things that HSMs cannot currently do, such +Nomad can also do many things that HSMs cannot currently do, such as generating _dynamic secrets_. Instead of storing AWS access keys directly -within Vault, Vault can generate access keys according to a specific -policy on the fly. Vault has the potential of doing this for any +within Nomad, Nomad can generate access keys according to a specific +policy on the fly. Nomad has the potential of doing this for any system through its mountable secret backend system. -For most companies, an HSM is overkill, and Vault is enough. For companies -that can afford an HSM, it can be used with Vault to get the best of both +For most companies, an HSM is overkill, and Nomad is enough. For companies +that can afford an HSM, it can be used with Nomad to get the best of both worlds. diff --git a/website/source/intro/vs/index.html.markdown b/website/source/intro/vs/index.html.markdown index ce7fc0b41..d4435251a 100644 --- a/website/source/intro/vs/index.html.markdown +++ b/website/source/intro/vs/index.html.markdown @@ -1,22 +1,22 @@ --- layout: "intro" -page_title: "Vault vs. Other Software" +page_title: "Nomad vs. Other Software" sidebar_current: "vs-other" description: |- - Comparisons between Vault and other software that claim to store secrets in some capacity. + Comparisons between Nomad and other software that claim to store secrets in some capacity. --- -# Vault vs. Other Software +# Nomad vs. Other Software There are a number of other options in the market currently that claim -to store secrets in some capacity. This section compares Vault to these +to store secrets in some capacity. This section compares Nomad to these other software choices. -Due to the bias of the comparisons being on the Vault website, we attempt +Due to the bias of the comparisons being on the Nomad website, we attempt to only use facts. If you find something that is invalid or out of date in the comparisons, please [open an issue](https://github.com/hashicorp/vault/issues) and we'll address it as soon as possible. -Use the navigation on the left to read comparisons of Vault versus other +Use the navigation on the left to read comparisons of Nomad versus other systems. diff --git a/website/source/intro/vs/keywhiz.html.md b/website/source/intro/vs/keywhiz.html.md index 84fcf2e7f..8621c23bb 100644 --- a/website/source/intro/vs/keywhiz.html.md +++ b/website/source/intro/vs/keywhiz.html.md @@ -1,12 +1,12 @@ --- layout: "intro" -page_title: "Vault vs. Keywhiz" +page_title: "Nomad vs. Keywhiz" sidebar_current: "vs-other-keywhiz" description: |- - Comparison between Vault and Keywhiz. + Comparison between Nomad and Keywhiz. --- -# Vault vs. Keywhiz +# Nomad vs. Keywhiz Keywhiz is a secret management solution built by Square. Keywhiz has a client/server architecture based on a RESTful API. Clients of @@ -17,30 +17,30 @@ as files on disk, and use Unix file permissions for access control. Human operators may authenticate using a cookie-based authentication either via command line utilities or through a management web interface. -Vault similarly is designed as a comprehensive secret management -solution. The client interaction with Vault is flexible -both for authentication and usage of secrets. Vault supports [mTLS +Nomad similarly is designed as a comprehensive secret management +solution. The client interaction with Nomad is flexible +both for authentication and usage of secrets. Nomad supports [mTLS authentication](/docs/auth/cert.html) along with many [other mechanisms](/docs/auth/index.html). The goal being to make it easy to authenticate as a machine for programmatic access and as a human for operator usage. -Vault and Keywhiz expose secrets via an API. The Vault +Nomad and Keywhiz expose secrets via an API. The Nomad [ACL system](/docs/concepts/policies.html) is used to protect secrets and gate access, similarly to the -Keywhiz ACL system. With Vault, All auditing is done +Keywhiz ACL system. With Nomad, All auditing is done server side using [audit backends](/docs/audit/index.html). Keywhiz focuses on storage and distribution of secrets and supports rotation through secret versioning, which is possible in the Keywhiz UI and -command-line utilities. Vault also supports dynamic secrets and generating credentials +command-line utilities. Nomad also supports dynamic secrets and generating credentials on-demand for fine-grained security controls, but adds first class support -for non-repudiation. Key rotation is a first class concern for Keywhiz and Vault, so +for non-repudiation. Key rotation is a first class concern for Keywhiz and Nomad, so that no external systems need to be used. -Lastly Vault forces a mandatory lease contract with clients. All secrets read -from Vault have an associated lease which enables operators to audit key usage, -perform key rolling, and ensure automatic revocation. Vault provides multiple +Lastly Nomad forces a mandatory lease contract with clients. All secrets read +from Nomad have an associated lease which enables operators to audit key usage, +perform key rolling, and ensure automatic revocation. Nomad provides multiple revocation mechanisms to give operators a clear "break glass" procedure after a potential compromise. diff --git a/website/source/intro/vs/kms.html.md b/website/source/intro/vs/kms.html.md index be3c4b15c..8b0cc7011 100644 --- a/website/source/intro/vs/kms.html.md +++ b/website/source/intro/vs/kms.html.md @@ -1,40 +1,40 @@ --- layout: "intro" -page_title: "Vault vs. Amazon Key Management Service" +page_title: "Nomad vs. Amazon Key Management Service" sidebar_current: "vs-other-kms" description: |- - Comparison between Vault and Amazon Key Management Service. + Comparison between Nomad and Amazon Key Management Service. --- -# Vault vs. Amazon KMS +# Nomad vs. Amazon KMS Amazon Key Management Service (KMS) is a service provided in the AWS ecosystem for encryption key management. It is backed by Hardware Security Modules (HSM) for physical security. -Vault and KMS differ in the scope of problems they are trying to solve. +Nomad and KMS differ in the scope of problems they are trying to solve. The KMS service is focused on securely storing encryption keys and supporting cryptographic operations (encrypt and decrypt) using those keys. It supports access controls and auditing as well. -In contrast, Vault provides a comprehensive secret management solution. +In contrast, Nomad provides a comprehensive secret management solution. The [`transit` backend](/docs/secrets/transit/index.html) provides similar capabilities as the KMS service, allowing for encryption keys -to be stored and cryptographic operations to be performed. However, Vault goes +to be stored and cryptographic operations to be performed. However, Nomad goes much futher than just key management. -The flexible secret backends allow Vault to handle any type of secret data, +The flexible secret backends allow Nomad to handle any type of secret data, including database credentials, API keys, PKI keys, and encryption keys. -Vault also supports dynamic secrets, generating credentials on-demand for +Nomad also supports dynamic secrets, generating credentials on-demand for fine-grained security controls, auditing, and non-repudiation. -Lastly Vault forces a mandatory lease contract with clients. All secrets read -from Vault have an associated lease which enables operations to audit key usage, -perform key rolling, and ensure automatic revocation. Vault provides multiple +Lastly Nomad forces a mandatory lease contract with clients. All secrets read +from Nomad have an associated lease which enables operations to audit key usage, +perform key rolling, and ensure automatic revocation. Nomad provides multiple revocation mechansims to give operators a clear "break glass" procedure after a potential compromise. -Vault is an open source tool that can be deployed to any environment, +Nomad is an open source tool that can be deployed to any environment, and does not require any special hardware. This makes it well suited for cloud environments where HSMs are not available or are cost prohibitive. diff --git a/website/source/layouts/_header.erb b/website/source/layouts/_header.erb index 2d4cb352f..bd2ca35c8 100644 --- a/website/source/layouts/_header.erb +++ b/website/source/layouts/_header.erb @@ -22,7 +22,7 @@
    diff --git a/website/source/layouts/_meta.erb b/website/source/layouts/_meta.erb index 283afb661..f1836e4e0 100644 --- a/website/source/layouts/_meta.erb +++ b/website/source/layouts/_meta.erb @@ -7,7 +7,7 @@ - <%= [current_page.data.page_title, "Vault by HashiCorp"].compact.join(" - ") %> + <%= [current_page.data.page_title, "Nomad by HashiCorp"].compact.join(" - ") %> <%= stylesheet_link_tag "application" %> diff --git a/website/source/layouts/_sidebar.erb b/website/source/layouts/_sidebar.erb index f87359090..85674fbdf 100644 --- a/website/source/layouts/_sidebar.erb +++ b/website/source/layouts/_sidebar.erb @@ -21,6 +21,6 @@ diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index a5d77e405..78d5f585e 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -13,25 +13,17 @@ Architecture
    • - > - High Availability - + > + Consensus Protocol + - > - Security Model + > + Gossip Protocol > Telemetry - - > - Token Authentication - - - > - Key Rotation - diff --git a/website/source/layouts/downloads.erb b/website/source/layouts/downloads.erb index 653969e58..e74ffcd4b 100644 --- a/website/source/layouts/downloads.erb +++ b/website/source/layouts/downloads.erb @@ -3,7 +3,7 @@