diff --git a/helper/tlsutil/testdata/README.md b/helper/tlsutil/testdata/README.md index 234500c7f..5a951a007 100644 --- a/helper/tlsutil/testdata/README.md +++ b/helper/tlsutil/testdata/README.md @@ -17,7 +17,7 @@ Using [cfssl 1.2.0](https://github.com/cloudflare/cfssl) ```sh # Write defaults and update cfssl print-defaults csr > ca-csr.json -cfssl print-defaults config > ca.config.json +cfssl print-defaults config > ca-config.json # Generate CA certificate and key cfssl gencert -config ca-config.json -initca ca-csr.json | cfssljson -bare ca - diff --git a/website/source/docs/agent/configuration/tls.html.md b/website/source/docs/agent/configuration/tls.html.md index d3071a460..80c3042d5 100644 --- a/website/source/docs/agent/configuration/tls.html.md +++ b/website/source/docs/agent/configuration/tls.html.md @@ -68,18 +68,6 @@ This example shows enabling TLS configuration. This enables TLS communication between all servers and clients using the default system CA bundle and certificates. -```hcl -tls { - http = true - rpc = true -} -``` - -### Custom Certificates - -This example shows configuring Nomad to communicate via TLS over HTTP and RPC -using a custom certificate and CA bundle. - ```hcl tls { http = true diff --git a/website/source/docs/agent/encryption.html.md b/website/source/docs/agent/encryption.html.md index 45fc7b7c8..275b834b2 100644 --- a/website/source/docs/agent/encryption.html.md +++ b/website/source/docs/agent/encryption.html.md @@ -3,14 +3,14 @@ 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. + Learn how to configure Nomad to encrypt HTTP, RPC, and Serf 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. +two separate encryption systems, one for gossip traffic, and one for HTTP and +RPC. ## Gossip @@ -30,7 +30,7 @@ cg8StVXbQJ0gPvMd9o7yrg== With that key, you can enable gossip encryption on the agent. -## RPC and Raft Encryption with TLS +## HTTP, 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 @@ -42,13 +42,88 @@ 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. +hostname verification. Unlike traditional HTTPS browser validation, 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]: /docs/agent/configuration/tls.html "Nomad TLS Configuration" + +### Example TLS Configuration using cfssl + +While [Vault's PKI backend][vault] is an ideal solution for managing +certificates and other secrets in a production environment, it's useful to use +simpler command line tools when learning how to configure TLS and your [PKI]. + +[`cfssl`][cfssl] is a tool for working with TLS certificates and certificate +authorities similar to [OpenSSL's][openssl] `x509` command line tool. + +Once you have the `cfssl` command line tool installed, the first step to +setting up TLS is to create a Certificate Authority (CA) certificate. The +following command will generate a suitable example CA CSR, certificate, and +key: + +```sh +# Run in the directory where you want to store certificates +cfssl print-defaults csr | cfssl gencert -initca - | cfssljson -bare ca +``` + +Next create a `nomad-csr.json` which contains the configuration for the actual +certificate you'll be using in Nomad: + +```json +{ + "CN": "global.nomad", + "hosts": [ + "server.global.nomad", + "client.global.nomad", + "localhost" + ] +} +``` + +This will create a certificate suitable for both clients and servers in the +`global` (default) region. + +In production Nomad agents should have a certificate valid for the name +`${ROLE}.${REGION}.nomad` where role is either `client` or `server` depending +on the node's role. + +Create a certificate signed by your CA: + +```sh +cfssl gencert -ca ca.pem -ca-key ca-key.pem nomad-csr.json | cfssljson -bare nomad +``` + +You've now successfully generated self-signed certificates! You should see the +following files: + +| File | Description | Usage | +|-----------------|------------------------------|---------------------------| +| `ca.pem` | CA certificate | `ca_file` setting | +| `ca-key.pem` | CA private key | Signing CSRs | +| `nomad.pem` | Nomad cert for global region | `cert_file` setting | +| `nomad-key.pem` | Nomad key for foo region | `key_file` setting | +| `*.csr` | Certificate Signing Requests | Generating certs (temporary) | + +In your Nomad configuration add the `tls` stanza: + +```hcl +tls { + http = true + rpc = true + verify_server_hostname = true + ca_file = "ca.pem" + cert_file = "nomad.pem" + key_file = "nomad-key.pem" +} +``` + +[vault]: https://www.vaultproject.io/docs/secrets/pki/ +[PKI]: https://en.wikipedia.org/wiki/Public_key_infrastructure +[cfssl]: https://cfssl.org/ +[openssl]: https://www.openssl.org/