TLS Guide

demo/vagrant/Vagrantfile

@@ -67,6 +67,13 @@ EOF
 sudo systemctl enable consul.service
 sudo systemctl start consul
 
+for bin in cfssl cfssl-certinfo cfssljson
+do
+	echo "Installing $bin..."
+	curl -sSL https://pkg.cfssl.org/R1.2/${bin}_linux-amd64 > /tmp/${bin}
+	sudo install /tmp/${bin} /usr/local/bin/${bin}
+done
+
 SCRIPT
 
 Vagrant.configure(2) do |config|

website/source/docs/agent/encryption.html.md

@@ -34,7 +34,7 @@ With that key, you can enable gossip encryption on the agent.
 
 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.
+generated and signed by a private Certificate Authority (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
@@ -82,89 +82,10 @@ connections as well as verify proper names on all other certificates.
 Consul will not attempt to health check agents with `verify_https_client` set
 as it is unable to use client certificates.
 
-## Encryption Examples
+# Configuring Nomad with TLS
 
-### TLS Configuration using `cfssl`
+Read the [Configuring TLS Guide][guide] for details on how to configure
+encryption for Nomad.
 
-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:
-
-```shell
-# 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:
-
-```shell
-$ 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:
-
-- `ca.pem` - the CA certificate. This corresponds to the Nomad `ca_file`
-  parameter in the Nomad [`tls` stanza][tls].
-
-- `ca-key.pem` - the CA private key. This is used to sign CSRs and should
-  **not** be included in the Nomad [`tls` stanza][tls].
-
-- `nomad.pem` - the Nomad certificate for the region. This corresponds to the
-  `cert_file` parameter in the Nomad [`tls` stanza][tls].
-
-- `nomad-key.pem` - the Nomad private key. This corresponds to the `key_file`
-  parameter in the Nomad [`tls` stanza][tls].
-
-- `*.csr` - the certificate signing request. This is temporary for generating
-  certificates and should **not** be included in the Nomad [`tls` stanza][tls].
-
-In your Nomad configuration add the `tls` stanza:
-
-```hcl
-tls {
-  http = true
-  rpc  = true
-
-  ca_file   = "ca.pem"
-  cert_file = "nomad.pem"
-  key_file  = "nomad-key.pem"
-
-  verify_server_hostname = true
-}
-```
-
-[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/
+[guide]: /guides/tls.html "Configuring TLS"
 [tls]: /docs/agent/configuration/tls.html "Nomad TLS Configuration"