From 7e8861d76e34b635958b64289324bebe37bb22cc Mon Sep 17 00:00:00 2001
From: Pedro Navarro <pednape@gmail.com>
Date: Tue, 13 Jan 2015 12:09:54 +0100
Subject: [PATCH] Add documentation how to setup CLI credentials to use in PKI
 scenarios.

This adds CACERT configuration to the credentials section used
in the user guide section and in the CLI keystone section.

Change-Id: Iff59b2c27b3704bdc878cc4c406d95db608de1d7
Closes-Bug: #1163938
---
 .../section_cli_keystone_credentials.xml      | 21 +++++++++++++++++--
 doc/common/section_cli_openrc.xml             | 10 ++++++++-
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/doc/common/section_cli_keystone_credentials.xml b/doc/common/section_cli_keystone_credentials.xml
index 0e03ab1469..f162bec1ea 100644
--- a/doc/common/section_cli_keystone_credentials.xml
+++ b/doc/common/section_cli_keystone_credentials.xml
@@ -72,8 +72,7 @@
         </step>
         <step>
             <para>Export the URL of the keystone auth server, for
-                example <link xlink:href="http://localhost:5000/v2.0'"
-                    >http://localhost:5000/v2.0'</link>, to the
+                example <uri>http://localhost:5000/v2.0</uri>, to the
                     <varname>OS_AUTH_URL</varname> environment
                 variable:</para>
             <screen><prompt>$</prompt> <userinput>export OS_AUTH_URL="&lt;authServerURL&gt;"</userinput></screen>
@@ -117,4 +116,22 @@
             </note>
         </step>
     </procedure>
+    <procedure>
+        <title>To configure the keystone client to verify the TLS (HTTPS) server certificate</title>
+        <step>
+            <para>Define the <varname>OS_CACERT</varname> environment variable to set the location for the
+                CA trust store (PEM formatted) for this client:</para>
+            <screen><prompt>$</prompt> <userinput>export OS_CACERT=<replaceable>/path/to/cacertFile</replaceable></userinput></screen>
+            <note>
+                <para>Alternatively, you can specify these parameters
+                    on any keystone client command:</para>
+                <para>
+                    <literal>--os-cacert
+                           <replaceable>OS_CACERT</replaceable></literal>.
+                    CA bundle file to use in verifying a TLS
+                    (HTTPS) server certificate. Defaults to
+                        <code>env[OS_CACERT]</code>.</para>
+            </note>
+        </step>
+    </procedure>
 </section>
diff --git a/doc/common/section_cli_openrc.xml b/doc/common/section_cli_openrc.xml
index 99e98f4bfb..a0dae9b8bb 100644
--- a/doc/common/section_cli_openrc.xml
+++ b/doc/common/section_cli_openrc.xml
@@ -90,7 +90,8 @@ export OS_TENANT_NAME=<replaceable>projectName</replaceable>
 export OS_AUTH_URL=<replaceable>https://identityHost:portNumber/v2.0</replaceable>
 # The following lines can be omitted
 export OS_TENANT_ID=<replaceable>tenantIDString</replaceable>
-export OS_REGION_NAME=<replaceable>regionName</replaceable></programlisting>
+export OS_REGION_NAME=<replaceable>regionName</replaceable>
+export OS_CACERT=<replaceable>/path/to/cacertFile</replaceable></programlisting>
             </step>
             <step>
                 <para>On any shell from which you want to run
@@ -115,6 +116,13 @@ export OS_REGION_NAME=<replaceable>regionName</replaceable></programlisting>
                 parameter with OpenStack client commands
                 instead.</para>
         </note>
+        <note audience="enduser">
+            <para>You must set the OS_CACERT environment variable when
+                  using the https protocol in the OS_AUTH_URL environment setting because
+                  the verification process for the TLS (HTTPS) server certificate uses
+                  the one indicated in the environment. This certificate will be used when
+                  verifying the TLS (HTTPS) server certificate.</para>
+        </note>
     </section>
     <section xml:id="override-variables">
         <title>Override environment variable values</title>