... how to install them on Linux, and how to set up credentials

Introduction

You can use the NeCTAR Dashboard (via your web browser) to perform simple management tasks for your NeCTAR project and virtuals.  But for some things, it is necessary to use a "client" installed on some machine; e.g. your desktop.

Here are the clients that you may need to use.

ServiceClient packageOfficial Source Repository URLPurpose
nova python-novaclient https://github.com/openstack/python-novaclient Nova is the primary OpenStack cloud management API
glance python-glanceclient https://github.com/openstack/python-glanceclient Glance is the OpenStack Image management API.
keystone python-keystoneclient https://github.com/openstack/python-keystoneclient Keystone is the OpenStack Authentication API.
swift python-swiftclient https://github.com/openstack/python-swiftclient Swift is the ObjectStack Object Store API.

For Chef users, note that the "setup::openstack_clients" recipe in the NeCTAR Cookbooks collection offers a convenient way to preinstall the commonly used OpenStack clients, and set up credential for them.

Note: this page does not cover the following tools which are (more or less) alternatives to the Dashboard:

  • HybridFox is an OpenStack client implemented as a Firefox browser add-on.  It reportedly does not current work with NeCTAR.
  • EucaTools is a client designed for Amazon EC2.  Since the EC2 APIs are an extension to the OpenStack APIs, some EucaTools functionality does not work with the NeCTAR cloud.

Installing using the Package Manager

OpenStack clients are typically installable via your Linux distro's package installer and repositories, and can be installed from there.  This is is the simple (and preferred) option, unless you hear otherwise. 

For other alternatives, see Advanced Installation below. 

The pattern for installing using the package manager is:

  • On Ubuntu or similar:
    sudo apt-get install <package-name>
  • On CentOS or similar:
    sudo yum install <package-name>

If there are issues and you need to remove a package manager installed client, use "sudo apt-get remove --purge ...", or "sudo yum remove ..."

Setting up OpenStack Credentials

The OpenStack clients require credentials to allow them to interact with the NeCTAR services.  These are typically presented to the client using environment variable settings.  Setting up the credentials is a three step procedure:

  1. Obtain (e.g. generate) a personal OpenStack password.
  2. Download an "OpenStack RC" script for setting up the environment variables.
  3. Use "source" or "." to run the script and enter the password.

Note that NeCTAR's OpenStack passwords are personal, as NeCTAR does not support "service accounts" at this time.  If you set up an application service that uses your password for (say) backups to Object Store then:

  • If the application service's configuration files (containing your password) are compromised, then bad things may be done in your name to any project you belong to.
  • If you forget and reset your password, then the password in the application service's configuration files will be invalid and the backups will break.
  • If your access to the project is removed by a project manager, then the backups will break.

Generating a password via the NeCTAR dashboard

  1. From your web browser, connect to the Dashboard (at https://dashboard.rc.nectar.org.au/) and go through the AAF login sequence.
  2. Click on the "settings" link (top right of page) to go to your "User Settings" page. 
  3. Select the "Reset Password" panel.
  4. Click the "Reset Password" button ... bearing in mind that this will invalidate any previously generated passwords for your account.
  5. Use copy-paste to save the password somewhere safe.

Download the shell script via the NeCTAR dashboard

  1. From your web browser, connect to the Dashboard (at https://dashboard.rc.nectar.org.au/) and go through the AAF login sequence.
  2. Select the Project that you want to manage from the Project drop-down (top of the left side menu).
  3. Select the "Access & Security" page.
  4. Select the "API Access" panel.
  5. Click "Download OpenStack RC file", and save the file to your local machine.  Note that this file will contain both your account name and the "tenancy" details for your current project.

Run the OpenStack RC script

In the command shell that you are going to use to run the client(s):

  1. Source the RC file; e.g. use your shell's "." or "source" command.
  2. When prompted, enter (i.e. paste) the password that you saved above.

Advanced Installation

Installing using Pip

If you need a newer version of an OpenStack client than is available through your standard package manager repositories, you can Python's package installer.

  1. Make sure that the "python-pip" package is installed (using "apt-get" or "yum" as above)
  2. Use the python "pip" command to install the client package:
    sudo pip install <package-name>

Building and installing from Source

Warning: the following should only be attempted if you are prepared to debug potential build problems ...

If you need the "bleeding edge" version of a client, or if you need to use a version with private modifications, you can download a client's source tree and build it.  The following assumes that you know about Git and Github.

  1. Make sure that "git" and the packages required for building python are installed. (On Ubuntu and similar "build-essentials" should cover it, but on CentOS and similar you need to install "gcc", "gcc-c++", "kernel-devel" and "make" explicitly.  And possibly others.)
  2. Checkout the source tree.  For example:
    cd ~/git
    git clone  
    cd 
  3. Build and install the client:
    sudo python setup.py install