Chapter 1. OpenStack command-line clients

1.1. Overview

You can use the OpenStack command-line clients to run simple commands that make API calls. You can run these commands from the command line or in scripts to automate tasks. If you provide OpenStack credentials, you can run these commands on any computer.
Internally, each client command runs cURL commands that embed API requests. The OpenStack APIs are RESTful APIs that use the HTTP protocol, including methods, URIs, media types, and response codes.
These open-source Python clients run on Linux or Mac OS X systems and are easy to learn and use. Each OpenStack service has its own command-line client. On some client commands, you can specify a debug parameter to show the underlying API request for the command. This is a good way to become familiar with the OpenStack API calls.
The following table lists the command-line client for each OpenStack service with its package name and description.

Table 1.1. OpenStack services and clients

Service Client Package Description
Block Storage cinder python-cinderclient Create and manage volumes.
Compute nova python-novaclient Create and manage images, instances, and flavors.
Database Service trove python-troveclient Create and manage databases.
Identity keystone python-keystoneclient Create and manage users, tenants, roles, endpoints, and credentials.
Image Service glance python-glanceclient Create and manage images.
Networking neutron python-neutronclient Configure networks for guest servers. This client was previously called quantum.
Object Storage swift python-swiftclient Gather statistics, list items, update metadata, and upload, download, and delete files stored by the Object Storage service. Gain access to an Object Storage installation for ad hoc processing.
Orchestration heat python-heatclient Launch stacks from templates, view details of running stacks including events and resources, and update and delete stacks.
Telemetry ceilometer python-ceilometerclient Create and collect measurements across OpenStack.
An OpenStack common client is in development.
For client installation instructions, see Section 1.2, “Install the OpenStack command-line clients”. For information about the OpenStack RC file, see the Red Hat Enterprise Linux OpenStack Platform End User Guide.

1.2. Install the OpenStack command-line clients

Install the prerequisite software and the Python package for each OpenStack client.

1.2.1. Install the prerequisite software

The following table lists the software that you need to have to run the command-line clients, and provides installation instructions as needed.

Table 1.2. Prerequisite software

Prerequisite Description
Python 2.6 or later
Currently, the clients do not support Python 3.
setuptools package
Many Linux distributions provide packages to make setuptools easy to install. Search your package manager for setuptools to find an installation package. If you cannot find one, download the setuptools package directly from http://pypi.python.org/pypi/setuptools.

1.2.2. Install the clients

When following the instructions in this section, replace PROJECT with the lowercase name of the client to install, such as nova. Repeat for each client. The following values are valid:
  • ceilometer - Telemetry API
  • cinder - Block Storage API and extensions
  • glance - Image Service API
  • heat - Orchestration API
  • keystone - Identity service API and extensions
  • neutron - Networking API
  • nova - Compute API and extensions
  • swift - Object Storage API
  • trove - Database Service API
The following example shows the command for installing the nova client with yum. 
# yum install python-novaclient

1.2.2.1. Installing from packages

On Red Hat Enterprise Linux, use yum to install the clients: 
# yum install python-PROJECTclient

1.2.3. Upgrade or remove clients

To upgrade a client, add the --upgrade option to the yum install command: 
# yum install --upgrade python-PROJECTclient
To remove the a client, run the yum erase command: 
# yum erase python-PROJECTclient

1.2.4. What's next

Before you can run client commands, you must create and source the PROJECT-openrc.sh file to set environment variables. See Section 1.4, “Set environment variables using the OpenStack RC file”.

1.3. Discover the version number for a client

Run the following command to discover the version number for a client: 
$ PROJECT --version
For example, to see the version number for the nova client, run the following command: 
$ nova --version
The version number (2.15.0 in the example) is returned. 
2.15.0

1.4. Set environment variables using the OpenStack RC file

To set the required environment variables for the OpenStack command-line clients, you must create an environment file called an OpenStack rc file, or openrc.sh file. If your OpenStack installation provides it, you can download the file from the OpenStack dashboard as an administrative user or any other user. This project-specific environment file contains the credentials that all OpenStack services use.
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.
Note
Defining environment variables using an environment file is not a common practice on Microsoft Windows. Environment variables are usually defined in the Advanced tab of the System Properties dialog box.

1.4.1. Download and source the OpenStack RC file

  1. Log in to the OpenStack dashboard, choose the project for which you want to download the OpenStack RC file, and click Access & Security.
  2. On the API Access tab, click Download OpenStack RC File and save the file. The filename will be of the form PROJECT-openrc.sh where PROJECT is the name of the project for which you downloaded the file.
  3. Copy the PROJECT-openrc.sh file to the computer from which you want to run OpenStack commands.
    For example, copy the file to the computer from which you want to upload an image with a glance client command.
  4. On any shell from which you want to run OpenStack commands, source the PROJECT-openrc.sh file for the respective project.
    In the following example, the demo-openrc.sh file is sourced for the demo project: 
    $ source demo-openrc.sh
  5. When you are prompted for an OpenStack password, enter the password for the user who downloaded the PROJECT-openrc.sh file.

1.4.2. Create and source the OpenStack RC file

Alternatively, you can create the PROJECT-openrc.sh file from scratch, if for some reason you cannot download the file from the dashboard.
  1. In a text editor, create a file named PROJECT-openrc.sh file and add the following authentication information: 
    export OS_USERNAME=username
export OS_PASSWORD=password
export OS_TENANT_NAME=projectName
export OS_AUTH_URL=https://identityHost:portNumber/v2.0
# The following lines can be omitted
export OS_TENANT_ID=tenantIDString
export OS_REGION_NAME=regionName
    The following example shows the information for a project called admin, where the OS username is also admin, and the identity host is located at controller. 
    export OS_USERNAME=admin
export OS_PASSWORD=ADMIN_PASS
export OS_TENANT_NAME=admin
export OS_AUTH_URL=http://controller:35357/v2.0
  2. On any shell from which you want to run OpenStack commands, source the PROJECT-openrc.sh file for the respective project. In this example, you source the admin-openrc.sh file for the admin project: 
    $ source admin-openrc.sh
Note
You are not prompted for the password with this method. The password lives in clear text format in the PROJECT-openrc.sh file. Restrict the permissions on this file to avoid security problems. You can also remove the OS_PASSWORD variable from the file, and use the --password parameter with OpenStack client commands instead.

1.4.3. Override environment variable values

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 help output of the various client commands. For example, you can override the OS_PASSWORD setting in the PROJECT-openrc.sh file by specifying a password on a keystone command, as follows: 
$ keystone --os-password PASSWORD service-list
Where PASSWORD is your password.