From 3e8bd93e66fb83816a63ea65c2dfecc756229b60 Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Tue, 1 Nov 2016 17:40:42 -0700 Subject: [PATCH] Respond to comments --- website/source/docs/agent/config.html.md | 6 ++- website/source/docs/agent/encryption.html.md | 40 ++++++++++--------- .../docs/vault-integration/index.html.md | 2 +- website/source/layouts/docs.erb | 7 ++-- 4 files changed, 31 insertions(+), 24 deletions(-) diff --git a/website/source/docs/agent/config.html.md b/website/source/docs/agent/config.html.md index e0dbefed5..a5d41b29e 100644 --- a/website/source/docs/agent/config.html.md +++ b/website/source/docs/agent/config.html.md @@ -406,8 +406,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. @@ -418,6 +416,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 index 3c36ec741..5dd516550 100644 --- a/website/source/docs/agent/encryption.html.md +++ b/website/source/docs/agent/encryption.html.md @@ -1,45 +1,47 @@ --- layout: "docs" -page_title: "Encryption" +page_title: "Gossip and RPC Encryption" sidebar_current: "docs-agent-encryption" description: |- - Learn about the encryption in Nomad. + Learn how to configure Nomad to encrypt both its gossip traffic and its RPC + traffic. --- -The Nomad agent supports encrypting all of its network traffic. There are -two separate encryption systems, one for gossip traffic and one for RPC. +# Encryption -# Gossip 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 agent. 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. +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 +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 Encryption with TLS +## 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, used -only internally. +generated and signed by a Certificate Authority. This can be a private CA. -TLS can be used to verify the authenticity of the servers or verify the -authenticity of clients. The configuration option `verify_server_hostname` makes -the Nomad server verify that the client has the same name as mentionioned in the -certificate. +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. -Also if `verify_server_hostname` is set, then outgoing connections perform +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 @@ -48,3 +50,5 @@ 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 28087790f..f96e4a2f0 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -257,12 +257,13 @@ Configuration - > - Telemetry - > Encryption + + > + Telemetry +