section_cli_openrc.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>
export OS_CACERT=<replaceable>/path/to/cacertFile</replaceable></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>
        <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>
        <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>
    <xi:include href="../common/section_keystone-keyring-support.xml"/>
</section>