diff --git a/website/source/docs/agent/config.html.md b/website/source/docs/agent/config.html.md index 77bb488ca..1eda96220 100644 --- a/website/source/docs/agent/config.html.md +++ b/website/source/docs/agent/config.html.md @@ -409,8 +409,6 @@ traffic for Nomad * `verify_server_hostname`: Setting this to true causes the outgoing TLS connections to verify the server's hostname. Default is `false`. - **NOTE**: Users should not mark it as `true` if they are using the Nomad - 0.5-rc1 release and not using wildcard certificates for servers and clients. * `ca_file`: Path to the CA certificate used for Nomad's TLS configuration. @@ -421,6 +419,10 @@ traffic for Nomad Incorrect configuration of the TLS related configuration will result to startup errors of the Nomad agent. + Please see the [Agent's Gossip and RPC + Encryption](/docs/agent/encryption.html) documentation for how certificates + should be signed. + ## Server-specific Options The following options are applicable to server agents only and need not be diff --git a/website/source/docs/agent/encryption.html.md b/website/source/docs/agent/encryption.html.md new file mode 100644 index 000000000..5dd516550 --- /dev/null +++ b/website/source/docs/agent/encryption.html.md @@ -0,0 +1,54 @@ +--- +layout: "docs" +page_title: "Gossip and RPC Encryption" +sidebar_current: "docs-agent-encryption" +description: |- + Learn how to configure Nomad to encrypt both its gossip traffic and its RPC + traffic. +--- + +# Encryption + +The Nomad agent supports encrypting all of its network traffic. There are +two separate encryption systems, one for gossip traffic, and one for RPC. + +## Gossip + +Enabling gossip encryption only requires that you set an encryption key when +starting the Nomad server. The key can be set via the +[`encrypt`](/docs/agent/config.html#encrypt) parameter: the value of this +setting is a server configuration file containing the encryption key. + +The key must be 16-bytes, base64 encoded. As a convenience, Nomad provides the +[`nomad keygen`](/docs/commands/keygen.html) command to generate a cryptographically suitable key: + +```shell +$ nomad keygen +cg8StVXbQJ0gPvMd9o7yrg== +``` + +With that key, you can enable gossip encryption on the agent. + + +## RPC and Raft Encryption with TLS + +Nomad supports using TLS to verify the authenticity of servers and clients. To +enable this, Nomad requires that all clients and servers have key pairs that are +generated and signed by a Certificate Authority. This can be a private CA. + +TLS can be used to verify the authenticity of the servers and clients. The +configuration option [`verify_server_hostname`][tls] causes Nomad to verify that +a certificate is provided that is signed by the Certificate Authority from the +[`ca_file`][tls] for TLS connections. + +If `verify_server_hostname` is set, then outgoing connections perform +hostname verification. All servers must have a certificate valid for +"server..nomad" or the client will reject the handshake. It is also +recommended for the certificate to sign `localhost` such that the CLI can +validate the server name. + +TLS is used to secure the RPC calls between agents, but gossip between nodes is +done over UDP and is secured using a symmetric key. See above for enabling +gossip encryption. + +[tls]: http://127.0.0.1:4567/docs/agent/config.html#tls-options "Nomad TLS Configuration" diff --git a/website/source/docs/vault-integration/index.html.md b/website/source/docs/vault-integration/index.html.md index 8e2808f99..a22ae283c 100644 --- a/website/source/docs/vault-integration/index.html.md +++ b/website/source/docs/vault-integration/index.html.md @@ -121,7 +121,7 @@ download. The below example assumes Vault is accessible, unsealed and the the operator has appropriate permissions. -``` +```shell # Download the policy and role $ curl https://nomadproject.io/data/vault/nomad-server-policy.hcl -O -s $ curl https://nomadproject.io/data/vault/nomad-server-role.json -O -s diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 331988ccf..f96e4a2f0 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -200,6 +200,12 @@ > inspect + > + keygen + + > + keyring + > logs @@ -251,6 +257,10 @@ Configuration + > + Encryption + + > Telemetry