From 7970f15e69c745c280ff4ef1a853600446ff80ab Mon Sep 17 00:00:00 2001
From: Joao Fernandes <joao.fernandes@docker.com>
Date: Mon, 11 Jul 2016 13:14:57 -0700
Subject: [PATCH] Adds docs on how to replace certs

Fixes #1946
---
 configuration/configure-logs.md              |  2 +-
 configuration/dtr-integration.md             |  2 +-
 configuration/ldap-integration.md            |  2 +-
 configuration/use-externally-signed-certs.md | 66 ++++++++++++++++++++
 installation/install-production.md           |  2 +-
 5 files changed, 70 insertions(+), 4 deletions(-)
 create mode 100644 configuration/use-externally-signed-certs.md

diff --git a/configuration/configure-logs.md b/configuration/configure-logs.md
index b2c57d927f..ac379f1d6b 100644
--- a/configuration/configure-logs.md
+++ b/configuration/configure-logs.md
@@ -6,7 +6,7 @@ keywords = ["docker, ucp, integrate, logs"]
 [menu.main]
 parent="mn_ucp_configuration"
 identifier="ucp_configure_logs"
-weight=0
+weight=10
 +++
 <![end-metadata]-->
 
diff --git a/configuration/dtr-integration.md b/configuration/dtr-integration.md
index 37c36e9294..0a64a695c5 100644
--- a/configuration/dtr-integration.md
+++ b/configuration/dtr-integration.md
@@ -7,7 +7,7 @@ keywords = ["trusted, registry, integrate, UCP, DTR"]
 [menu.main]
 parent="mn_ucp_configuration"
 identifier="ucp_integrate_dtr"
-weight=10
+weight=20
 +++
 <![end-metadata]-->
 
diff --git a/configuration/ldap-integration.md b/configuration/ldap-integration.md
index 6a84763e7f..d455d3ffc4 100644
--- a/configuration/ldap-integration.md
+++ b/configuration/ldap-integration.md
@@ -6,7 +6,7 @@ description="Learn how to integrate UCP with an LDAP service, so that you can ma
 [menu.main]
 parent="mn_ucp_configuration"
 identifier="ucp_ldap_integration"
-weight=20
+weight=30
 +++
 <![end-metadata]-->
 
diff --git a/configuration/use-externally-signed-certs.md b/configuration/use-externally-signed-certs.md
new file mode 100644
index 0000000000..cb45e8d5fe
--- /dev/null
+++ b/configuration/use-externally-signed-certs.md
@@ -0,0 +1,66 @@
+<!--[metadata]>
++++
+title = "Use externally-signed certificates"
+description = "Learn how to configure Docker Universal Control Plane to use your own certificates."
+keywords = ["Universal Control Plane, UCP, certificate, authentiation, tls"]
+[menu.main]
+parent="mn_ucp_configuration"
+identifier="ucp_configure_certs"
+weight=0
++++
+<![end-metadata]-->
+
+# Use externally-signed certificates
+
+Docker Universal Control Plane uses TLS to encrypt the traffic between users
+and your cluster. By default this is done using self-signed certificates.
+Since self-signed certificates are not trusted by web browsers, when users
+access the UCP web UI, their browsers display a security warning. To avoid this,
+you can configure UCP to use externally signed certificates.
+
+This can be done while
+[installing the UCP cluster](../installation/install-production.md) by
+providing the externally signed certificates during the installation.
+If you install UCP without providing externally signed certificates, then
+self-signed certificates are used by default. These certificates can be replaced
+at any time.
+
+Since client certificate bundles are signed and verified with the UCP server
+certificates, if you replace the UCP server certificates, users have to
+download new client certificate bundles to be able to run Docker commands on
+the cluster.
+
+## Replace existing certificates
+
+To replace the server certificates used by UCP, for each controller node:
+
+1. Login into the node with ssh.
+2. In the directory where you have the keys and certificates to use, run:
+
+    ```bash
+    # Create a container that attaches to the same volume where certificates are stored
+    $ docker create --name replace-certs -v ucp-controller-server-certs:/data busybox
+
+    # Copy your keys and certificates to the container's volumes
+    $ docker cp cert.pem replace-certs:/data/cert.pem
+    $ docker cp ca.pem replace-certs:/data/ca.pem
+    $ docker cp key.pem replace-certs:/data/key.pem
+
+    # Remove the container, since you won't need it any longer
+    $ docker rm replace-certs
+    ```
+
+3. Restart the `ucp-controller` container.
+
+    To avoid downtime, don't restart all the `ucp-controller` containers of
+    your cluster at the same time.
+
+    ```bash
+    $ docker restart ucp-controller
+    ```
+
+4. Let your users know.
+
+    After replacing the certificates your users won't be able to authenticate
+    with their old client certificate bundles. Ask your users to go to the UCP
+    web UI and [get new client certificate bundles](../access-ucp/cli-based-access.md).
diff --git a/installation/install-production.md b/installation/install-production.md
index 5b119cb7b2..e945f07c69 100644
--- a/installation/install-production.md
+++ b/installation/install-production.md
@@ -62,7 +62,7 @@ If you want to use your own certificates:
 
 2. Create a volume with the name `ucp-controller-server-certs`.
 
-3. Add the following files to the volume top-level directory:
+3. Add the following files to `/var/lib/docker/volumes/ucp-controller-server-certs/_data/`:
 
     | File     | Description                                                                       |
     |:---------|:----------------------------------------------------------------------------------|