From 15fe925a57817edf012286290a7da2392e993fcc Mon Sep 17 00:00:00 2001
From: Gauvain Pocentek <gauvain.pocentek@objectif-libre.com>
Date: Sun, 17 Nov 2013 15:08:48 +0100
Subject: [PATCH] User Guide: document the manual creation of openrc.sh

This helps if the user doesn't have access to an OpenStack dashboard.

Change-Id: I2e9e86e2bf092a0b429c2c4da32618d7e7b1078f
backport: none
---
 doc/common/section_cli_install.xml |  2 +-
 doc/common/section_cli_openrc.xml  | 51 +++++++++++++++++++++++-------
 2 files changed, 40 insertions(+), 13 deletions(-)

diff --git a/doc/common/section_cli_install.xml b/doc/common/section_cli_install.xml
index 928d5a3ad1..df2511fa9c 100644
--- a/doc/common/section_cli_install.xml
+++ b/doc/common/section_cli_install.xml
@@ -196,7 +196,7 @@
             </step>
             <step>
                 <para>Before you can issue client commands, you must
-                    download and source the
+                    create and source the
                         <filename>openrc</filename> file to set
                     environment variables. See <xref
                         linkend="cli_openrc"/>.</para>
diff --git a/doc/common/section_cli_openrc.xml b/doc/common/section_cli_openrc.xml
index db60d512fb..f5dad7baf3 100644
--- a/doc/common/section_cli_openrc.xml
+++ b/doc/common/section_cli_openrc.xml
@@ -3,20 +3,19 @@
     xmlns:xi="http://www.w3.org/2001/XInclude"
     xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
     xml:id="cli_openrc">
-    <title>Download and source the OpenStack RC file</title>
+    <title>Create and source the OpenStack RC file</title>
     <para>To set the required environment variables for the OpenStack
-        command-line clients, you must download and source an
-        environment file, <filename>openrc.sh</filename>. It is
-        project-specific and contains the credentials used by
-        OpenStack Compute, Image, and Identity services.</para>
-    <para>When you source the file and enter the password, environment
-        variables are set for that shell. They allow the commands to
-        communicate to the OpenStack services that run in the
-        cloud.</para>
-    <para>You can download the file from the OpenStack dashboard as an
-        administrative user or any other user.</para>
+        command-line clients, you must either create or download an environment
+        file, and source it. It is project-specific and contains the
+        credentials used by all OpenStack services.</para>
+    <para>When you source the file, environment variables are set for your
+        current shell. They allow the commands to communicate to the OpenStack
+        services that run in the cloud.</para>
+
+    <para>If your OpenStack installation provides it, you can download the file
+        from the OpenStack dashboard as an administrative user or any other
+        user.</para>
     <procedure>
-   <!--     <title>To download the OpenStack RC file</title> -->
         <step>
             <para>Log in to the OpenStack dashboard, choose the
                 project for which you want to download the OpenStack
@@ -57,4 +56,32 @@
                 your password.</para>
         </step>
     </procedure>
+
+    <para>Alternatively, you can create the <filename>openrc.sh</filename> file from scratch.</para>
+    <procedure>
+        <step>
+            <para>Create the file <filename>openrc.sh</filename> containing the
+              authentication:</para>
+            <programlisting language="bash">export OS_USERNAME=<replaceable>USERNAME</replaceable>
+export OS_PASSWORD=<replaceable>PASSWORD</replaceable>
+export OS_TENANT_NAME=<replaceable>PROJECT_NAME</replaceable>
+export OS_AUTH_URL=<replaceable>https://IDENTITY_HOST:PORT/v2.0</replaceable>
+# The following lines can be omitted
+export OS_TENANT_ID=<replaceable>9d792532ffce494583138c495801d164</replaceable>
+export OS_REGION_NAME=<replaceable>RegionOne</replaceable></programlisting>
+        </step>
+        <step>
+            <para>On any shell from where you want to run OpenStack
+              commands, source the <filename>openrc.sh</filename>
+              file for the respective project.</para>
+            <screen><prompt>$</prompt> <userinput>source openrc.sh</userinput></screen>
+        </step>
+    </procedure>
+    <note>
+        <para>The password will not be prompted with this method, but lives in
+        clear text in the <filename>openrc.sh</filename> file. Restrict the
+        permissions on this file to avoid security problems. You can also
+        remove the <literal>OS_PASSWORD</literal> variable from the file, and
+        use the <literal>--password</literal> option of OpenStack clients.</para>
+    </note>
 </section>