Providing Metacloud Credentials to CLI Tools

Prerequisites: You must prepare your environment to use the CLI Tools for Mac OS X or Windows.

You need your Metacloud project name, username, and password to set the required environment variables for use with the OpenStack command-line clients. Metacloud provides this information in an easy-to-download file from the Dashboard.

The OpenStack RC file is written for Linux-based systems and emulators, such as Mac OS X and Git for Windows. The filename syntax is PROJECT_NAME-openrc.sh. This project-specific environment file contains the credentials that all OpenStack services use. It also informs the system which region, API versions, and Identity endpoint to use for authentication. Ask your cloud administrators if you have questions regarding these values.

To download the OpenStack RC file:

  1. Log in to the Dashboard.
  2. From the Project drop-down list, select Access & Security.
  3. On the API Access tab, click Download OpenStack RC File and save the file.
  4. Copy the PROJECT_NAME-openrc.sh file to the computer with the virtual environment that you want to use to run OpenStack commands.

Sourcing the OpenStack RC File

Sourcing your OpenStack RC file sets the environment variables in your current shell. The variables enable the OpenStack client commands to communicate with the OpenStack services running in the cloud.

  1. In a Terminal or Git Bash window, activate the virtual environment you created while installing the OpenStack CLI Tools.
  2. Source the PROJECT_NAME-openrc.sh file. This example sources the demo-openrc.sh file for the demo project:

    (virtualenv_name) $ source ~/demo-openrc.sh
    
  3. When you are prompted, enter your Metacloud password that corresponds to the OpenStack RC file.

    Please enter your OpenStack Password: 
    (virtualenv_name) username$
    
  4. Verify the credentials by running an OpenStack command:

    (virtualenv_name) username$ openstack image list
    
  5. If you receive an error, such as The request you have made requires authentication. (HTTP 401), check your environment variables using the following command:

    (virtualenv_name) username$ env | grep "OS_"
    

    Carefully check any possible differences between a version 4.0 Metacloud installation and an earlier version.

Checking Environment Variables

You must have the following variables in your environment. You can run these export commands one line at a time to set the environment variables on Mac OSX or Linux, for example:

$ export OS_AUTH_URL=https://<API-AZ.METACLOUD.NET>:35357/v2.0
$ export OS_PROJECT_ID=<PROJECT_ID>
$ export OS_PROJECT_NAME="Cisco Demo"
$ export OS_USERNAME="username"
$ export OS_REGION_NAME="RegionOne"
$ export OS_VOLUME_API_VERSION=1
$ export OS_IMAGE_API_VERSION=1

For Metacloud version 4.0 and later, you must export the following variables in addition to the ones listed above. Remove the /v2.0 from the OS_AUTH_URL value. You can get the Domain UUID values from your administrator.

$ export OS_IDENTITY_API_VERSION=3
$ export OS_PROJECT_DOMAIN_ID=<DOMAIN_UUID>
$ export OS_USER_DOMAIN_ID=<DOMAIN_UUID>

Setting Environment Variables in Microsoft Windows

We recommend using PowerShell or Git Bash.

  • If you use Git for Windows, you can source the OpenStack RC file using Git Bash.
  • If you use PowerShell, you must set environment variables for all the required variables with these commands.
set-item env:OS_AUTH_URL -value "https://<API-AZ.METACLOUD.NET>:35357/v2.0"
set-item env:OS_TENANT_ID -value "tenantidhere"
set-item env:OS_TENANT_NAME -value "Cisco Demo"
set-item env:OS_USERNAME -value "username"
set-item env:OS_REGION_NAME -value "RegionOne"
set-item env:OS_VOLUME_API_VERSION -value "1"
set-item env:OS_IMAGE_API_VERSION -value "1"
set-item env:OS_PASSWORD -value "notmyp455"

For Metacloud version 4.0 and later, you must set the following Windows PowerShell environment variables in addition to the ones listed above. Remove the /v2.0 from the OS_AUTH_URL value. You can get the Domain UUID values from your administrator:

set-item env:OS_IDENTITY_API_VERSION -value "3"
set-item env:OS_PROJECT_DOMAIN_ID -value "<DOMAIN_UUID>"
set-item env:OS_USER_DOMAIN_ID -value "<DOMAIN_UUID>"

Creating a Credentials File

You can create the OpenStack RC file manually using a text editor. Create a file named PROJECT_NAME-openrc.sh and add the following authentication information:

# Replace X with the correct version
export OS_AUTH_URL=https://<API-AZ.METACLOUD.NET>:<PORT>

export OS_USERNAME=<USERNAME>
export OS_TENANT_NAME=<PROJECT_NAME>

export OS_IDENTITY_API_VERSION=3
    
# The following lines can be omitted
export OS_TENANT_ID=<TENANT_ID>
export OS_REGION_NAME=<REGION>
export OS_CACERT=<CACERT/PATH>
   
# The password could cause security issue, need to protect the file
export OS_PASSWORD=<PASSWORD>

In Metacloud versions prior to 4.0, the Identity service API v2.0 endpoints include port 35357 for administrative access and port 5000 for public access, with limited operations available for port 5000. In Metacloud version 4.0 and later, the Identity service API v3 endpoints allow all operations on both ports.

Note
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 is used when verifying the TLS (HTTPS) server certificate.

Prompting for your Password

With the above method for creating a credentials file, the password lives in clear text format in the file. You need to restrict the permissions on this file to avoid security problems. If you do not want your password stored in a file, you can use the following example bash script to activate a prompt:

# With Keystone you pass the keystone password.
echo "Please enter your OpenStack Password: "
read -sr OS_PASSWORD_INPUT
export OS_PASSWORD=$OS_PASSWORD_INPUT

Alternatively, you can remove the OS_PASSWORD variable from the file, and use the --password parameter with OpenStack client commands instead.

Overriding Environment Variables

When you run OpenStack client commands, you can override environment variable settings by using the options that are listed at the end of the help output of the various client commands. For example, you can override the OS_PASSWORD setting in the PROJECT_NAME-openrc.sh file by specifying a password on an openstack command, as follows:

$ openstack --os-password <PASSWORD> server list

Any user can specify their username and password credentials to interact with OpenStack, using any client command. These credentials can be specified using various mechanisms, like the environment variable or a command-line argument.

It is not safe to specify the password using either of these methods. When you specify your password using the command-line client and the --os-password argument, anyone with access to your computer can view it in plain text with the ps field. It is best to employ an interactive prompt for the OpenStack password, to avoid storing the password in plain text.