kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-08 19:35:41 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update website to remove a lot of copy-paste with Vault + improve images

Browse Source
This commit is contained in:
Seth Vargo
2015-09-20 16:37:22 -04:00
parent 6a3623ebe0
commit d9aed3af4d
65 changed files with 116 additions and 3676 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
website/source/docs/commands/index.html.md.erb
View File

@@ -16,7 +16,7 @@ subcommands is in the navigation to the left.
The Nomad CLI is a well-behaved command line application. In erroneous cases,
a non-zero exit status will be returned. It also responds to `-h` and `--help`
as you'd most likely expect.
as you would most likely expect.
To view a list of the available commands at any time, just run Nomad
with no arguments. To get help for any specific subcommand, run the subcommand

99
website/source/docs/concepts/auth.html.md
View File

@@ -1,99 +0,0 @@
---
layout: "docs"
page_title: "Authentication"
sidebar_current: "docs-concepts-auth"
description: |-
Before performing any operation with Nomad, the connecting client must be authenticated.
---
# Authentication
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 Nomad.
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 Nomad. They
are enabled using `vault auth-enable`. After they're enabled, you can
learn more about them using `vault path-help auth/<name>`. For example,
if you enable GitHub, you can use `vault path-help auth/github` to learn more
about how to configure it and login.
Multiple authentication backends can be enabled, but only one is required
to gain authentication. It is not currently possible to force a user through
multiple authentication backends to gain access.
This allows you to enable human-friendly as well as machine-friendly
backends at the same time. For example, for humans you might use the
"github" auth backend, and for machines you might use the "app-id" backend.
## Tokens
There is an [entire page dedicated to tokens](/docs/concepts/tokens.html),
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,
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.
This token given for authentication with any backend can also be used
with the full set of token commands, such as creating new sub-tokens,
revoking tokens, and renewing tokens. This is all covered on the
[token concepts page](/docs/concepts/tokens.html).
## Authenticating
#### Via the CLI
To authenticate with the CLI, `vault auth` is used. This supports many
of the built-in authentication methods. For example, with GitHub:
```
$ vault auth -method=github token=<token>
...
```
After authenticating, you will be logged in. The CLI command will also
output your raw token. This token is used for revocation and renewal.
As the user logging in, the primary use case of the token is renewal,
covered below in the "Auth Leases" section.
To determine what variables are needed for an authentication method,
supply the `-method` flag without any additional arguments and help
will be shown.
If you're using a method that isn't supported via the CLI, then the API
must be used.
#### Via the API
API authentication is generally used for machine authentication. Each
auth backend implements is own login endpoint. Use the `vault path-help`
mechanism to find the proper endpoint.
For example, the GitHub login endpoint is located at `auth/github/login`.
And to determine the arguments needed, `vault path-help auth/github/login` can
be used.
## Auth Leases
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
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
how leasing is implemented.
And just like secrets, identities can be renewed without having to
completely reauthenticate. Just use `vault token-renew <token>` with the
token associated with your identity to renew it.

53
website/source/docs/concepts/dev-server.html.md
View File

@@ -1,53 +0,0 @@
---
layout: "docs"
page_title: "Dev Server Mode"
sidebar_current: "docs-concepts-devserver"
description: |-
The dev server in Nomad can be used for development or to experiment with Nomad.
---
# "Dev" Server Mode
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 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.
~> **Warning:** Never, ever, ever run a "dev" mode server in production.
It is insecure and will lose data on every restart (since it stores data
in-memory). It is only made for development or experimentation.
## Properties
The properties of the dev server:
* **Initialized and unsealed** - The server will be automatically initialized
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. 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 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 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 Nomad features, such
as different authentication backends, secret backends, audit backends, etc.
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.
In addition to experimentation, the dev server is very easy to automate
for development environments.

29
website/source/docs/concepts/ha.html.markdown
View File

@@ -12,31 +12,4 @@ 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, 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 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
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
Currently there are several backends that support high availability mode,
including Consul, ZooKeeper and etcd. These may change over time, and the
[configuration page](/docs/config/index.html) should be referenced.
The Consul backend is the recommended HA backend, as it is used in production
by HashiCorp and it's customers with commercial support.
If you're interested in implementing another backend or adding HA support
to another backend, we'd love your contributions. Adding HA support
requires implementing the `physical.HABackend` interface for the storage backend.
TODO: Document HA

75
website/source/docs/concepts/lease.html.md
View File

@@ -1,75 +0,0 @@
---
layout: "docs"
page_title: "Lease, Renew, and Revoke"
sidebar_current: "docs-concepts-lease"
description: |-
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, 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
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 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.
In addition to renewals, a lease can be _revoked_. When a lease is revoked,
it invalidates that secret immediately and prevents any further renewals.
For
[dynamic secrets](#),
the secrets themselves are often immediately disabled. For example, with
the
[AWS secret backend](/docs/secrets/aws/index.html), the access keys will
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 Nomad. When a lease is expired, Nomad will automatically revoke that
lease.
## Lease IDs
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.
## Lease Durations and Renewal
Along with the lease ID, a _lease duration_ can be read. The lease duration
is the time in seconds that the lease is valid for. A consumer of this
secret must renew the lease within that time.
When renewing the lease, the user can request a specific amount of time
from now to extend the lease. For example: `vault renew my-lease-id 3600`
would request to extend the lease of "my-lease-id" by 1 hour (3600 seconds).
The requested increment is completely advisory. The backend in charge
of the secret can choose to completely ignore it. For most secrets, the
backend does its best to respect the increment, but often limits it to
ensure renewals every so often.
As a result, the return value of renews should be carefully inspected
to determine what the new lease is.
## Prefix-based Revocation
In addition to revoking a single secret, operators with proper access
control can revoke multiple secrets based on their lease ID prefix.
Lease IDs are structured in a way that their prefix is always the path
where the secret was requested from. This lets you revoke trees of
secrets. For example, to revoke all AWS access keys, you can do
`vault revoke -prefix aws/`.
This is very useful if there is an intrusion within a specific system:
all secrets of a specific backend or a certain configured backend can
be revoked quickly and easily.

133
website/source/docs/concepts/policies.html.md
View File

@@ -1,133 +0,0 @@
---
layout: "docs"
page_title: "Policies"
sidebar_current: "docs-concepts-policies"
description: |-
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 Nomad, the
next step is authorization. This is the process of determining what
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 Nomad a user is allowed to access. An example
of a policy is shown below:
```javascript
path "sys/*" {
policy = "deny"
}
path "secret/*" {
policy = "write"
}
path "secret/foo" {
policy = "read"
}
path "secret/super-secret" {
policy = "deny"
}
```
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, 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".
~> Policy paths are matched using the most specific defined policy. This may
be an exact match or the longest-prefix match of a glob. This means if you
define a policy for `"secret/foo*"`, the policy would also match `"secret/foobar"`.
The glob character is only supported at the end of the path specification.
## Policies
Allowed policies for a path are:
* `deny` - No access allowed. Highest precedence.
* `sudo` - Read, write, and root access to a path.
* `write` - Read, write access to a path.
* `read` - Read-only access to a path.
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.
For example, modifying the audit log backends is done via root paths.
Only root or "sudo" privilege users are allowed to do this.
## Root Policy
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 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
to create more strictly controlled users. The original root token should
be protected accordingly.
## Managing Policies
Policy management can be done via the API or CLI. The CLI commands are
`vault policies` and `vault policy-write`. Please see the help associated
with these commands for more information. They are very easy to use.
## Associating Policies
To associate a policy with a user, you must consult the documentation for
the authentication backend you're using.
For tokens, they are associated at creation time with `vault token-create`
and the `-policy` flags. Child tokens can be associated with a subset of
a parent's policies. Root users can assign any policies.
There is no way to modify the policies associated with an active
identity. The identity must be revoked and reauthenticated to receive
the new policy list.
If an _existing_ policy is modified, the modifications propagate
to all associated users instantly. The above paragraph is more specifically
stating that you can't add new or remove policies associated with an
active identity.
## Changes from 0.1
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
exact match could be specified.
The other change is that deny had the lowest precedence. This meant if there
were two policies being merged (e.g. "ops" and "prod") and they had a conflicting
policy like:
```
path "sys/seal" {
policy = "deny"
}
path "sys/seal" {
policy = "read"
}
```
The merge would previously give the "read" higher precedence. The current
version of Nomad prioritizes the explicit deny, so that the "deny" would
take precedence.
To make all Nomad 0.1 policies compatible with Nomad 0.2, the explicit
glob character must be added to all the path prefixes.

72
website/source/docs/concepts/seal.html.md
View File

@@ -1,72 +0,0 @@
---
layout: "docs"
page_title: "Seal/Unseal"
sidebar_current: "docs-concepts-seal"
description: |-
A Nomad must be unsealed before it can access its data. Likewise, it can be sealed to lock it down.
---
# Seal/Unseal
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 Nomad.
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 Nomad and check the status
of the unseal.
## Why?
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, 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,
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.
This is the _unseal_ process: the shards are added one at a time (in any
order) until enough shards are present to reconstruct the key and
decrypt the data.
## Unsealing
The unseal process is done by running `vault unseal` or via the API.
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 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 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 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 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 Nomad data can be locked
quickly to try to minimize damages. It can't be accessed again without
access to the master key shards.

58
website/source/docs/concepts/tokens.html.md
View File

@@ -1,58 +0,0 @@
---
layout: "docs"
page_title: "Tokens"
sidebar_current: "docs-concepts-tokens"
description: |-
Tokens are a core authentication method in Nomad. Child tokens, token-based revocation, and more.
---
# 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 Nomad.
It is also the only authentication backend that cannot be disabled.
As stated in the [authentication concepts](/docs/concepts/auth.html),
all external authentication mechanisms such as GitHub map down to dynamically
created tokens. These tokens have all the same properties as a normal
manually created token.
On this page, we'll show you how to create and manage tokens.
## Token Creation
Tokens are created via the API or using `vault token-create` from the CLI.
This will create a new token that is a child of the currently authenticated
token. As a child, the new token will automatically be revoked if the parent
is revoked.
If you're logged in as root, you can create an _orphan_ token by
specifying the `-orphan` flag. An orphan token has no parent, and therefore
when your token is revoked, it will not revoke the orphan.
Metadata associated with the token with `-metadata` is used to annotate
the token with information that is added to the audit log.
Finally, the `-policy` flag can be used to set the policies associated
with the token. Learn more about policies on the
[policies concepts](/docs/concepts/policies.html) page.
## Token Leases
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, 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.
After a token is revoked, all of the secrets in use by that token will
also be revoked. Therefore, if a user requests AWS access keys, for example,
then after the token expires the AWS access keys will also be expired even
if they had remaining lease time.

178
website/source/docs/config/index.html.md
View File

@@ -6,12 +6,14 @@ description: |-
Nomad server configuration reference.
---
# Server Configuration
# Nomad Configuration
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:
TODO: Document Nomad configuration. Examples below stolen from Vault.
```javascript
backend "consul" {
address = "127.0.0.1:8500"
@@ -66,177 +68,3 @@ the Nomad executable access to the `mlock` syscall on Linux systems:
```shell
sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault))
```
## Backend Reference
For the `backend` section, the supported backends are shown below.
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 Nomad
and has been shown to work at high scale under heavy load.
* `etcd` - Store data within [etcd](https://coreos.com/etcd/).
This backend supports HA.
* `zookeeper` - Store data within [Zookeeper](https://zookeeper.apache.org/).
This backend supports HA.
* `s3` - Store data within an S3 bucket [S3](http://aws.amazon.com/s3/).
This backend does not support HA.
* `mysql` - Store data within MySQL. This backend does not support HA.
* `inmem` - Store data in-memory. This is only really useful for
development and experimentation. Data is lost whenever Nomad is
restarted.
* `file` - Store data on the filesystem using a directory structure.
This backend does not support HA.
#### Common Backend Options
All backends support the following options:
* `advertise_addr` (optional) - For backends that support HA, this
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.
#### Backend Reference: Consul
For Consul, the following options are supported:
* `path` (optional) - The path within Consul where data will be stored.
Defaults to "vault/".
* `address` (optional) - The address of the Consul agent to talk to.
Defaults to the local agent address, if available.
* `scheme` (optional) - "http" or "https" for talking to Consul.
* `datacenter` (optional) - The datacenter within Consul to write to.
This defaults to the local datacenter.
* `token` (optional) - An access token to use to write data to Consul.
* `tls_skip_verify` (optional) - If non-empty, then TLS host verification
will be disabled for Consul communication.
Defaults to false.
The following settings should be set according to your [Consul encryption settings](https://www.consul.io/docs/agent/encryption.html):
* `tls_ca_file` (optional) - The path to the CA certificate used for Consul communication.
Defaults to system bundle if not specified.
Set accordingly to the [ca_file](https://www.consul.io/docs/agent/options.html#ca_file) setting in Consul.
* `tls_cert_file` (optional) - The path to the certificate for Consul communication.
Set accordingly to the [cert_file](https://www.consul.io/docs/agent/options.html#cert_file) setting in Consul.
* `tls_key_file` (optional) - The path to the private key for Consul communication.
Set accordingly to the [key_file](https://www.consul.io/docs/agent/options.html#key_file) setting in Consul.
#### Backend Reference: Zookeeper
For Zookeeper, the following options are supported:
* `path` (optional) - The path within Zookeeper where data will be stored.
Defaults to "vault/".
* `address` (optional) - The address(es) of the Zookeeper instance(s) to talk to.
Can be comma separated list (host:port) of many Zookeeper instances.
Defaults to "localhost:2181" if not specified.
#### Backend Reference: etcd
For etcd, the following options are supported:
* `path` (optional) - The path within etcd where data will be stored.
Defaults to "vault/".
* `address` (optional) - The address(es) of the etcd instance(s) to talk to.
Can be comma separated list (protocol://host:port) of many etcd instances.
Defaults to "http://localhost:4001" if not specified.
#### Backend Reference: S3
For S3, the following options are supported:
* `bucket` (required) - The name of the S3 bucket to use.
* `access_key` - (required) The AWS access key. It must be provided, but it can also be sourced from the AWS_ACCESS_KEY_ID environment variable.
* `secret_key` - (required) The AWS secret key. It must be provided, but it can also be sourced from the AWS_SECRET_ACCESS_KEY environment variable.
* `session_token` - (optional) The AWS session_token. It can also be sourced from the AWS_SESSION_TOKEN environment variable.
* `region` (optional) - The AWS region. It can be sourced from the AWS_DEFAULT_REGION environment variable and will default to "us-east-1" if not specified.
#### Backend Reference: MySQL
The MySQL backend has the following options:
* `username` (required) - The MySQL username to connect with.
* `password` (required) - The MySQL password to connect with.
* `address` (optional) - The address of the MySQL host. Defaults to
"127.0.0.1:3306.
* `database` (optional) - The name of the database to use. Defaults to "vault".
* `table` (optional) - The name of the table to use. Defaults to "vault".
* `tls_ca_file` (optional) - The path to the CA certificate to connect using TLS
#### Backend Reference: Inmem
The in-memory backend has no configuration options.
#### Backend Reference: File
The file backend has the following options:
* `path` (required) - The path on disk to a directory where the
data will be stored.
## Listener Reference
For the `listener` section, the only supported listener currently
is "tcp". Regardless of future plans, this is the recommended listener,
since it allows for HA mode.
The supported options are:
* `address` (optional) - The address to bind to for listening. This
defaults to "127.0.0.1:8200".
* `tls_disable` (optional) - If non-empty, then TLS will be disabled.
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.
* `tls_key_file` (required unless disabled) - The path to the private key
for the certificate.
* `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
possible.
## Telemetry Reference
For the `telemetry` section, there is no resource name. All configuration
is within the object itself.
* `statsite_address` (optional) - An address to a [Statsite](https://github.com/armon/statsite)
instances for metrics. This is highly recommended for production usage.
* `statsd_address` (optional) - This is the same as `statsite_address` but
for StatsD.
* `disable_hostname` (optional) - Whether or not to prepend runtime telemetry
with the machines hostname. This is a global option. Defaults to false.

4
website/source/docs/drivers/custom.html.md
View File

@@ -8,10 +8,10 @@ description: |-
# Custom Drivers
Nomad doesn't currently support the creation of custom secret backends.
Nomad does not 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
in supporting custom secret backends, but do not yet have a clear strategy
or timeline to do.
In the mean time, you can use the

14
website/source/docs/drivers/index.html.md
View File

@@ -28,11 +28,11 @@ a write, etc. This is a lot like a normal filesystem.
The "aws" backend, on the other hand, behaves differently. When you
write to `aws/config/root`, it expects a certain format and stores that
information as configuration. You can't read from this path. When you
information as configuration. You cannot read from this path. When you
read from `aws/<name>`, it looks up an IAM policy named `<name>` and
generates AWS access credentials on demand and returns them. It doesn't
behave at all like a typical filesystem: you're not simply storing and
retrieving values, you're interacting with an API.
generates AWS access credentials on demand and returns them. It does not
behave at all like a typical filesystem: you are not simply storing and
retrieving values, you are interacting with an API.
## Mounting/Unmounting Secret Backends
@@ -53,7 +53,7 @@ with regards to mounting:
* **Remount** - This moves the mount point for an existing secret backend.
This revokes all secrets, since secret leases are tied to the path they
were created at. The data stored for the backend won't be deleted.
were created at. The data stored for the backend will not be deleted.
Once a secret backend is mounted, you can interact with it directly
at its mount point according to its own API. You can use the `vault path-help`
@@ -68,8 +68,8 @@ 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 Nomad storage layer doesn't support relative access (such as `..`),
the Nomad storage layer does not 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 Nomad: even a malicious backend
can't access the data from any other backend.
cannot access the data from any other backend.

135
website/source/docs/http/index.html.md
View File

@@ -12,137 +12,4 @@ 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
All API routes are prefixed with `/v1/`.
This documentation is only for the v1 API.
~> **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 Nomad 0.3.
## Transport
The API is expected to be accessed over a TLS connection at
all times, with a valid certificate that is verified by a well
behaved client. It is possible to disable TLS verification for
listeners, however, so API clients should expect to have to do both
depending on user settings.
## Authentication
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-Nomad-Token` HTTP header.
Otherwise, a client token can be retrieved via
[authentication backends](/docs/auth/index.html).
Each authentication backend will have one or more unauthenticated
login endpoints. These endpoints can be reached without any authentication,
and are used for authentication itself. These endpoints are specific
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 Nomad API.
## Reading and Writing Secrets
Reading a secret via the HTTP API is done by issuing a GET using the
following URL:
```text
/v1/secret/foo
```
This maps to `secret/foo` where `foo` is the key in the `secret/` backend/
Here is an example of reading a secret using cURL:
```shell
curl \
-H "X-Nomad-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
-X GET \
http://127.0.0.1:8200/v1/secret/foo
```
To write a secret, issue a POST on the following URL:
```text
/v1/secret/foo
```
with a JSON body like:
```javascript
{
"value": "bar"
}
```
Here is an example of writing a secret using cURL:
```shell
curl \
-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 Nomad API client.
## Help
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:
```javascript
{
"help": "help text"
}
```
## Error Response
A common JSON structure is always returned to return errors:
```javascript
{
"errors": [
"message",
"another message"
]
}
```
This structure will be sent down for any HTTP status greater than
or equal to 400.
## HTTP Status Codes
The following HTTP status codes are used throughout the API.
- `200` - Success with data.
- `204` - Success, no data returned.
- `400` - Invalid request, missing or invalid data. See the
"validation" section for more details on the error response.
- `401` - Unauthorized, your authentication details are either
incorrect or you don't have access to this feature.
- `404` - Invalid path. This can both mean that the path truly
doesn't exist or that you don't have permission to view a
specific path. We use 404 in some cases to avoid state leakage.
- `429` - Rate limit exceeded. Try again after waiting some period
of time.
- `500` - Internal server error. An internal error has occurred,
try again later. If the error persists, report a bug.
- `503` - Nomad is down for maintenance or is currently sealed.
Try again later.
TODO: Document Nomand API

29
website/source/docs/http/libraries.html.md
View File

@@ -1,29 +0,0 @@
---
layout: "http"
page_title: "HTTP API: Libraries"
sidebar_current: "docs-http-libraries"
description: |-
List of official and community contributed libraries for interacting with the Nomad HTTP API.
---
# Libraries
The programming libraries listed on this page can be used to consume the API more conveniently.
Some are officially maintained while others are provided by the community.
## Go
* [Nomad Go Client](https://github.com/hashicorp/vault/tree/master/api) (official)
## Ruby
* [Nomad Ruby Client](https://github.com/hashicorp/vault-ruby) (official)
## Python
* [HVAC](https://github.com/ianunruh/hvac)
## Node.js
* [node-vault](https://github.com/kr1sp1n/node-vault)
* [vaulted](https://github.com/chiefy/vaulted)

108
website/source/docs/http/sys-audit.html.md
View File

@@ -1,108 +0,0 @@
---
layout: "http"
page_title: "HTTP API: /sys/audit"
sidebar_current: "docs-http-audits-audits"
description: |-
The `/sys/audit` endpoint is used to enable and disable audit backends.
---
# /sys/audit
## GET
<dl>
<dt>Description</dt>
<dd>
Lists all the available policies.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"file": {
"type: "file",
"description: "Store logs in a file",
"options": {
"path": "/var/log/file"
}
}
}
```
</dd>
</dl>
## PUT
<dl>
<dt>Description</dt>
<dd>
Enable an audit backend.
</dd>
<dt>Method</dt>
<dd>PUT</dd>
<dt>URL</dt>
<dd>`/sys/audit/<name>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">type</span>
<span class="param-flags">required</span>
The type of the audit backend.
</li>
<li>
<span class="param">description</span>
<span class="param-flags">optional</span>
A description of the audit backend for operators.
</li>
<li>
<span class="param">options</span>
<span class="param-flags">optional</span>
An object of options to configure the backend. This is
dependent on the backend type. Please consult the documentation
for the backend type you intend to use.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
## DELETE
<dl>
<dt>Description</dt>
<dd>
Disable the given audit backend.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/sys/audit/<name>`</dd>
<dt>Parameters</dt>
<dd>None
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>

102
website/source/docs/http/sys-auth.html.md
View File

@@ -1,102 +0,0 @@
---
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 Nomad.
---
# /sys/auth
## GET
<dl>
<dt>Description</dt>
<dd>
Lists all the enabled auth backends.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"github": {
"type": "github",
"description": "GitHub auth"
}
}
```
</dd>
</dl>
## POST
<dl>
<dt>Description</dt>
<dd>
Enable a new auth backend. The auth backend can be accessed
and configured via the mount point specified in the URL. This
mount point will be exposed under the `auth` prefix. For example,
enabling with the `/sys/auth/foo` URL will make the backend
available at `/auth/foo`.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/sys/auth/<mount point>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">type</span>
<span class="param-flags">required</span>
The name of the auth backend type, such as "github"
</li>
<li>
<span class="param">description</span>
<span class="param-flags">optional</span>
A human-friendly description of the auth backend.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
## DELETE
<dl>
<dt>Description</dt>
<dd>
Disable the auth backend at the given mount point.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/sys/auth/<mount point>`</dd>
<dt>Parameters</dt>
<dd>None
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>

50
website/source/docs/http/sys-health.html.md
View File

@@ -1,50 +0,0 @@
---
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 Nomad.
---
# /sys/health
<dl>
<dt>Description</dt>
<dd>
Returns the health status of Nomad. This matches the semantics of a Consul HTTP health
check and provides a simple way to monitor the health of a Nomad instance.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">standbyok</span>
<span class="param-flags">optional</span>
A query parameter provided to indicate that being a standby should
still return a 200 status code instead of the standard 429 status code.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```
{
"initialized": true,
"sealed": false,
"standby": false
}
```
Status Codes:
* `200` if initialized, unsealed and active.
* `429` if unsealed and standby.
* `500` if not initialized or sealed.
</dd>
</dl>

78
website/source/docs/http/sys-init.html.md
View File

@@ -1,78 +0,0 @@
---
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 Nomad.
---
# /sys/init
## GET
<dl>
<dt>Description</dt>
<dd>
Return the initialization status of a Nomad.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>Parameters</dt>
<dd>None</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"initialize": true
}
```
</dd>
</dl>
## PUT
<dl>
<dt>Description</dt>
<dd>
Initializes a new Nomad. The Nomad must've not been previously
initialized.
</dd>
<dt>Method</dt>
<dd>PUT</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">secret_shares</span>
<span class="param-flags">required</span>
The number of shares to split the master key into.
</li>
<li>
<span class="param">secret_threshold</span>
<span class="param-flags">required</span>
The number of shares required to reconstruct the master key.
This must be less than or equal to <code>secret_shares</code>.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
A JSON-encoded object including the master keys and initial root token:
```javascript
{
"keys": ["one", "two", "three"],
"root_token": "foo"
}
```
</dd>
</dl>

38
website/source/docs/http/sys-key-status.html.md
View File

@@ -1,38 +0,0 @@
---
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 Nomad.
---
# /sys/key-status
<dl>
<dt>Description</dt>
<dd>
Returns information about the current encryption key used by Nomad.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
The "term" parameter is the sequential key number, and "install_time" is the time that
encryption key was installed.
```javascript
{
"term": 3,
"install_time": "2015-05-29T14:50:46.223692553-07:00"
}
```
</dd>
</dl>

37
website/source/docs/http/sys-leader.html.md
View File

@@ -1,37 +0,0 @@
---
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 Nomad.
---
# /sys/leader
<dl>
<dt>Description</dt>
<dd>
Returns the high availability status and current leader instance of Nomad.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"ha_enabled": true,
"is_self": false,
"leader_address": "https://127.0.0.1:8200/"
}
```
</dd>
</dl>

103
website/source/docs/http/sys-mounts.html.md
View File

@@ -1,103 +0,0 @@
---
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 Nomad.
---
# /sys/mounts
## GET
<dl>
<dt>Description</dt>
<dd>
Lists all the mounted secret backends.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"aws": {
"type": "aws",
"description": "AWS keys"
},
"sys": {
"type": "system",
"description": "system endpoint"
}
}
```
</dd>
</dl>
## POST
<dl>
<dt>Description</dt>
<dd>
Mount a new secret backend to the mount point in the URL.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/sys/mounts/<mount point>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">type</span>
<span class="param-flags">required</span>
The name of the backend type, such as "aws"
</li>
<li>
<span class="param">description</span>
<span class="param-flags">optional</span>
A human-friendly description of the mount.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
## DELETE
<dl>
<dt>Description</dt>
<dd>
Unmount the mount point specified in the URL.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/sys/mounts/<mount point>`</dd>
<dt>Parameters</dt>
<dd>None
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>

92
website/source/docs/http/sys-policy.html.md
View File

@@ -1,92 +0,0 @@
---
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 Nomad.
---
# /sys/policy
## GET
<dl>
<dt>Description</dt>
<dd>
Lists all the available policies.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"policies": ["root", "deploy"]
}
```
</dd>
</dl>
## PUT
<dl>
<dt>Description</dt>
<dd>
Add or update a policy. Once a policy is updated, it takes effect
immediately to all associated users.
</dd>
<dt>Method</dt>
<dd>PUT</dd>
<dt>URL</dt>
<dd>`/sys/policy/<name>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">rules</span>
<span class="param-flags">required</span>
The policy document.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
## DELETE
<dl>
<dt>Description</dt>
<dd>
Delete the policy with the given name. This will immediately
affect all associated users.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/sys/policy/<name>`</dd>
<dt>Parameters</dt>
<dd>None
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>

96
website/source/docs/http/sys-raw.html.md
View File

@@ -1,96 +0,0 @@
---
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 Nomad.
---
# /sys/raw
## GET
<dl>
<dt>Description</dt>
<dd>
Reads the value of the key at the given path. This is the raw path in the
storage backend and not the logical path that is exposed via the mount system.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/sys/raw/<path>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"value": "{'foo':'bar'}"
}
```
</dd>
</dl>
## PUT
<dl>
<dt>Description</dt>
<dd>
Update the value of the key at the given path. This is the raw path in the
storage backend and not the logical path that is exposed via the mount system.
</dd>
<dt>Method</dt>
<dd>PUT</dd>
<dt>URL</dt>
<dd>`/sys/raw/<path>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">value</span>
<span class="param-flags">required</span>
The value of the key.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
## DELETE
<dl>
<dt>Description</dt>
<dd>
Delete the key with given path. This is the raw path in the
storage backend and not the logical path that is exposed via the mount system.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/sys/raw/<path>`</dd>
<dt>Parameters</dt>
<dd>None
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>

155
website/source/docs/http/sys-rekey.html.md
View File

@@ -1,155 +0,0 @@
---
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 Nomad.
---
# /sys/rekey/init
## GET
<dl>
<dt>Description</dt>
<dd>
Reads the configuration and progress of the current rekey attempt.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/sys/rekey/init`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
If a rekey is started, then "n" is the new shares to generate and "t" is
the threshold required for the new shares. The "progress" is how many unseal
keys have been provided for this rekey, where "required" must be reached to
complete.
```javascript
{
"started": true,
"t": 3,
"n": 5,
"progress": 1,
"required": 3
}
```
</dd>
</dl>
## PUT
<dl>
<dt>Description</dt>
<dd>
Initializes a new rekey attempt. Only a single rekey attempt can take place
at a time, and changing the parameters of a rekey requires canceling and starting
a new rekey.
</dd>
<dt>Method</dt>
<dd>PUT</dd>
<dt>URL</dt>
<dd>`/sys/rekey/init`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">secret_shares</span>
<span class="param-flags">required</span>
The number of shares to split the master key into.
</li>
<li>
<span class="param">secret_threshold</span>
<span class="param-flags">required</span>
The number of shares required to reconstruct the master key.
This must be less than or equal to <code>secret_shares</code>.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
## DELETE
<dl>
<dt>Description</dt>
<dd>
Cancels any in-progress rekey. This clears the rekey settings as well as any
progress made. This must be called to change the parameters of the rekey.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/sys/rekey/init`</dd>
<dt>Parameters</dt>
<dd>None
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
# /sys/rekey/update
## PUT
<dl>
<dt>Description</dt>
<dd>
Enter a single master key share to progress the rekey of the Nomad.
If the threshold number of master key shares is reached, Nomad
will complete the rekey. Otherwise, this API must be called multiple
times until that threshold is met.
</dd>
<dt>Method</dt>
<dd>PUT</dd>
<dt>URL</dt>
<dd>`/sys/rekey/update`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">key</span>
<span class="param-flags">required</span>
A single master share key.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
A JSON-encoded object indicating completion and if so with the new master keys:
```javascript
{
"complete": true,
"keys": ["one", "two", "three"]
}
```
</dd>
</dl>

39
website/source/docs/http/sys-remount.html.md
View File

@@ -1,39 +0,0 @@
---
layout: "http"
page_title: "HTTP API: /sys/remount"
sidebar_current: "docs-http-mounts-remount"
description: |-
The '/sys/remount' endpoint is used remount a mounted backend to a new endpoint.
---
# /sys/remount
<dl>
<dt>Description</dt>
<dd>
Remount an already-mounted backend to a new mount point.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">from</span>
<span class="param-flags">required</span>
The previous mount point.
</li>
<li>
<span class="param">to</span>
<span class="param-flags">required</span>
The new mount point.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>

38
website/source/docs/http/sys-renew.html.md
View File

@@ -1,38 +0,0 @@
---
layout: "http"
page_title: "HTTP API: /sys/renew"
sidebar_current: "docs-http-lease-renew"
description: |-
The `/sys/renew` endpoint is used to renew secrets.
---
# /sys/renew
<dl>
<dt>Description</dt>
<dd>
Renew a secret, requesting to extend the lease.
</dd>
<dt>Method</dt>
<dd>PUT</dd>
<dt>URL</dt>
<dd>`/sys/renew/<lease id>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">increment</span>
<span class="param-flags">optional</span>
A requested amount of time in seconds to extend the lease.
This is advisory.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>A secret structure.
</dd>
</dl>

29
website/source/docs/http/sys-revoke-prefix.html.md
View File

@@ -1,29 +0,0 @@
---
layout: "http"
page_title: "HTTP API: /sys/revoke-prefix"
sidebar_current: "docs-http-lease-revoke-prefix"
description: |-
The `/sys/revoke-prefix` endpoint is used to revoke secrets based on prefix.
---
# /sys/revoke-prefix
<dl>
<dt>Description</dt>
<dd>
Revoke all secrets generated under a given prefix immediately.
</dd>
<dt>Method</dt>
<dd>PUT</dd>
<dt>URL</dt>
<dd>`/sys/revoke-prefix/<path prefix>`</dd>
<dt>Parameters</dt>
<dd>None</dd>
<dt>Returns</dt>
<dd>A `204` response code.
</dd>
</dl>

29
website/source/docs/http/sys-revoke.html.md
View File

@@ -1,29 +0,0 @@
---
layout: "http"
page_title: "HTTP API: /sys/revoke"
sidebar_current: "docs-http-lease-revoke-single"
description: |-
The `/sys/revoke` endpoint is used to revoke secrets.
---
# /sys/revoke
<dl>
<dt>Description</dt>
<dd>
Revoke a secret immediately.
</dd>
<dt>Method</dt>
<dd>PUT</dd>
<dt>URL</dt>
<dd>`/sys/revoke/<lease id>`</dd>
<dt>Parameters</dt>
<dd>None</dd>
<dt>Returns</dt>
<dd>A `204` response code.
</dd>
</dl>

37
website/source/docs/http/sys-rotate.html.md
View File

@@ -1,37 +0,0 @@
---
layout: "http"
page_title: "HTTP API: /sys/rotate"
sidebar_current: "docs-http-rotate-rotate"
description: |-
The `/sys/rotate` endpoint is used to rotate the encryption key.
---
# /sys/rotate
## PUT
<dl>
<dt>Description</dt>
<dd>
Trigger a rotation of the backend encryption key. This is the key that is used
to encrypt data written to the storage backend, and is not provided to operators.
This operation is done online. Future values are encrypted with the new key, while
old values are decrypted with previous encryption keys.
</dd>
<dt>Method</dt>
<dd>PUT</dd>
<dt>URL</dt>
<dd>`/sys/rotate`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>

39
website/source/docs/http/sys-seal-status.html.md
View File

@@ -1,39 +0,0 @@
---
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 Nomad.
---
# /sys/seal-status
<dl>
<dt>Description</dt>
<dd>
Returns the seal status of the Nomad.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
The "t" parameter is the threshold, and "n" is the number of shares.
```javascript
{
"sealed": true,
"t": 3,
"n": 5,
"progress": 2
}
```
</dd>
</dl>

28
website/source/docs/http/sys-seal.html.md
View File

@@ -1,28 +0,0 @@
---
layout: "http"
page_title: "HTTP API: /sys/seal"
sidebar_current: "docs-http-seal-seal"
description: |-
The '/sys/seal' endpoint seals the Nomad.
---
# /sys/seal
<dl>
<dt>Description</dt>
<dd>
Seals the Nomad.
</dd>
<dt>Method</dt>
<dd>PUT</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>A `204` response code.
</dd>
</dl>

36
website/source/docs/http/sys-unseal.html.md
View File

@@ -1,36 +0,0 @@
---
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 Nomad.
---
# /sys/unseal
<dl>
<dt>Description</dt>
<dd>
Enter a single master key share to progress the unsealing of the Nomad.
If the threshold number of master key shares is reached, Nomad
will attempt to unseal the Nomad. Otherwise, this API must be
called multiple times until that threshold is met.
</dd>
<dt>Method</dt>
<dd>PUT</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">key</span>
<span class="param-flags">required</span>
A single master share key.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>The same result as `/sys/seal-status`.
</dd>
</dl>

7
website/source/docs/index.html.markdown
View File

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

8
website/source/docs/install/index.html.md
View File

@@ -18,7 +18,7 @@ TLS along with SHA256 sums to verify the binary.
To install the precompiled binary,
[download](/downloads.html) the appropriate package for your system.
Nomad is currently packaged as a zip file. We don't have any near term
Nomad is currently packaged as a zip file. We do not have any near term
plans to provide system packages.
Once the zip is downloaded, unzip it into any directory. The
@@ -31,13 +31,13 @@ from the command-line, make sure to place it somewhere on your `PATH`.
## Compiling from Source
To compile from source, you'll need [Go](https://golang.org) installed
and configured properly. You'll also need Git.
To compile from source, you will need [Go](https://golang.org) installed
and configured properly. you will also need Git.
1. Clone the Nomad repository into your GOPATH: https://github.com/hashicorp/nomad
1. Verify that the file `$GOPATH/src/github.com/hashicorp/nomad/main.go`
exists. If it doesn't, then you didn't clone Nomad into the proper
exists. If it does not, then you did not clone Nomad into the proper
path.
1. Run `make`. This will build Nomad for your current system

6
website/source/docs/internals/architecture.html.md
View File

@@ -12,7 +12,7 @@ Nomad is a complex system that has many different pieces. To help both users and
build a mental model of how it works, this page documents the system architecture.
~> **Advanced Topic!** This page covers technical details
of Nomad. You don't need to understand these details to
of Nomad. You do not 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.
@@ -74,7 +74,7 @@ clarify what is being discussed:
Looking at only a single region, at a high level Nomad looks like:
![Regional Architecture](/assets/images/region-arch.png)
[![Regional Architecture](/assets/images/nomad-architecture-region.png)](/assets/images/nomad-architecture-region.png)
Within each region, we have both clients and servers. Servers are responsible for
accepting jobs from users, managing clients, and [computing task placements](/docs/internals/scheduling.html).
@@ -85,7 +85,7 @@ In some cases, for either availability or scalability, you may need to run multi
regions. Nomad supports federating multiple regions together into a single cluster.
At a high level, this looks like:
![Global Architecture](/assets/images/global-arch.png)
[![Global Architecture](/assets/images/nomad-architecture-global.png)](/assets/images/nomad-architecture-global.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

25
website/source/docs/internals/consensus.html.md
View File

@@ -3,54 +3,57 @@ 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.
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).
Nomad uses a [consensus protocol](https://en.wikipedia.org/wiki/Consensus_(computer_science))
to provide [Consistency (as defined by CAP)](https://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
the internals of Nomad. You do not 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
[Paxos](https://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
* **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).
* **FSM** - [Finite State Machine](https://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.
* **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** - 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
* **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.
* **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.

9
website/source/docs/internals/gossip.html.md
View File

@@ -3,19 +3,20 @@ 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.
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)
Nomad uses a [gossip protocol](https://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),
["SWIM: Scalable Weakly-consistent Infection-style Process Group Membership Protocol"](https://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
the internals of Nomad. You do not 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.

2
website/source/docs/internals/index.html.md
View File

@@ -13,5 +13,5 @@ details of how Nomad functions, its architecture and sub-systems.
-> **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,
of Nomad, you may safely skip this section. If you are operating Nomad,
we recommend understanding the internals.

10
website/source/docs/internals/scheduling.html.md
View File

@@ -13,18 +13,18 @@ from jobs to client machines. This process must respect the constraints as decla
in the job, and optimize for resource utilization. This page documents the details
of how scheduling works in Nomad to help both users and developers
build a mental model. The design is heavily inspired by Google's
work on both [Omega: flexible, scalable schedulers for large compute clusters](http://research.google.com/pubs/pub41684.html)
and [Large-scale cluster management at Google with Borg](http://research.google.com/pubs/pub43438.html).
work on both [Omega: flexible, scalable schedulers for large compute clusters](https://research.google.com/pubs/pub41684.html)
and [Large-scale cluster management at Google with Borg](https://research.google.com/pubs/pub43438.html).
~> **Advanced Topic!** This page covers technical details
of Nomad. You don't need to understand these details to
of Nomad. You do not 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.
# Scheduling in Nomad
![Data Model](/assets/images/nomad-nouns.png)
[![Nomad Data Model](/assets/images/nomad-data-model.png)](/assets/images/nomad-data-model.png)
There are four primary "nouns" in Nomad, these are jobs, nodes, allocations, and evaluations.
Jobs are submitted by users and represent a _desired state_. A job is a declarative description
@@ -43,7 +43,7 @@ it with the desired state.
This diagram shows the flow of an evaluation through Nomad:
![Evaluation Flow](/assets/images/eval-flow.png)
[![Nomad Evaluation Flow](/assets/images/nomad-evaluation-flow.png)](/assets/images/nomad-evaluation-flow.png)
The lifecycle of an evaluation beings with an event causing the evaluation to be
created. Evaluations are created in the `pending` state and are enqueued into the

2
website/source/docs/internals/telemetry.html.md
View File

@@ -19,7 +19,7 @@ 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 Nomad is doing.
Telemetry information can be streamed to both [statsite](http://github.com/armon/statsite)
Telemetry information can be streamed to both [statsite](https://github.com/armon/statsite)
as well as statsd based on providing the appropriate configuration options.
Below is sample output of a telemetry dump: