openstack-manuals/doc/common/section_cli_openrc.xml
Karin Levenstein b2c7f2864c bk and ch fixes: edits up to cli_nova_boot, removed excess info
- excess removed from cli_version
- removed redundant section from ch_cli

Change-Id: I31b5c49e007ec2ff5e58b964c8b32dbcfa7cab32
2014-04-21 12:54:30 -05:00

141 lines
7.5 KiB
XML

<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="cli_openrc">
<?dbhtml stop-chunking?>
<title>Set environment variables using the OpenStack RC
file</title>
<para>To set the required environment variables for the OpenStack
command-line clients, you must create an environment file
called an OpenStack rc file, or <filename>openrc.sh</filename>
file.<phrase audience="enduser"> If your OpenStack
installation provides it, you can download the file from
the OpenStack dashboard as an administrative user or any
other user.</phrase> This project-specific environment
file contains the credentials that all OpenStack services
use.</para>
<para>When you source the file, environment variables are set for
your current shell. The variables enable the OpenStack client
commands to communicate with the OpenStack services that run
in the cloud.</para>
<note>
<para>Defining environment variables using an environment file is not a
common practice on Microsoft Windows. Environment variables are usually
defined in the <guilabel>Advanced</guilabel> tab of the System
Properties dialog box.</para>
</note>
<section xml:id="openrc-dashboard" audience="enduser">
<title>Download and source the OpenStack RC file</title>
<procedure>
<step>
<para>Log in to the OpenStack dashboard, choose the
project for which you want to download the
OpenStack RC file, and click <guibutton>Access
&amp; Security</guibutton>.</para>
</step>
<step>
<para>On the API Access tab, click <guibutton>Download
OpenStack RC File</guibutton> and save the
file. The filename will be of the form
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
where <replaceable>PROJECT</replaceable> is the
name of the project for which you downloaded the
file.</para>
</step>
<step>
<para>Copy the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file to the computer from which you want to run
OpenStack commands.</para>
<para>For example, copy the file to the computer from
which you want to upload an image with a
<command>glance</command> client
command.</para>
</step>
<step>
<para>On any shell from which you want to run
OpenStack commands, source the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file for the respective project.</para>
<para>In the following example, the
<filename>demo-openrc.sh</filename> file is
sourced for the demo project:</para>
<screen><prompt>$</prompt> <userinput>source demo-openrc.sh</userinput></screen>
</step>
<step>
<para>When you are prompted for an OpenStack password,
enter the password for the user who downloaded the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file.</para>
</step>
</procedure>
</section>
<section xml:id="openrc-create">
<title>Create and source the OpenStack RC file</title>
<para audience="enduser">Alternatively, you can create the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file from scratch, if for some reason you cannot download
the file from the dashboard.</para>
<procedure>
<step>
<para>In a text editor, create a file named
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file and add the following authentication
information:</para>
<programlisting language="bash" audience="enduser">export OS_USERNAME=<replaceable>username</replaceable>
export OS_PASSWORD=<replaceable>password</replaceable>
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>
<para>The following example shows the information for
a project called <literal>admin</literal>, where
the OS username is also <literal>admin</literal>,
and the identity host is located at
<literal>controller</literal>.</para>
<programlisting language="bash" audience="installer">export OS_USERNAME=admin
export OS_PASSWORD=<replaceable>ADMIN_PASS</replaceable>
export OS_TENANT_NAME=admin
export OS_AUTH_URL=http://controller:35357/v2.0</programlisting>
</step>
<step>
<para>On any shell from which you want to run
OpenStack commands, source the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file for the respective project. In this example,
you source the
<filename>admin-openrc.sh</filename> file for
the <replaceable>admin</replaceable>
project:</para>
<screen><prompt>$</prompt> <userinput>source admin-openrc.sh</userinput></screen>
</step>
</procedure>
<note audience="enduser">
<para>You are not prompted for the password with this
method. The password lives in clear text format in the
<filename><replaceable>PROJECT</replaceable>-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 <parameter>--password</parameter>
parameter with OpenStack client commands
instead.</para>
</note>
</section>
<section xml:id="override-variables">
<title>Override environment variable values</title>
<para>When you run OpenStack client commands, you can override
some environment variable settings by using the options
that are listed at the end of the <command>help</command> output
of the various client commands. For example, you can override
the <option>OS_PASSWORD</option> setting in the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file by specifying a password on a <command>keystone</command> command, as
follows:</para>
<screen><prompt>$</prompt> <userinput>keystone --os-password <replaceable>PASSWORD</replaceable> service-list</userinput></screen>
<para>Where <replaceable>PASSWORD</replaceable> is your password.</para>
</section>
</section>