Command Line Client

StratusLab provides a simple command line client that is easy to install on all platforms. This client provides access to all of the StratusLab services.


The command line client is the principal method for accessing the StratusLab services. It is written almost entirely in portable python and is easy to install and configure on all platforms (Linux, Mac OS X, Windows).

A list of the commands along with brief descriptions are provided in the table. All of the commands start with the stratus- prefix. On platforms that support it, tab completion can be used to find all of the commands. All of the commands support the --help option, which provides detailed information about the command and its options. All of the commands also support the --version option that will display the version of the client being used.

stratus-copy-config copy reference configuration file into the correct location
stratus-describe-instance list VM instances
stratus-run-instance start a new VM instance
stratus-kill-instance destroy and release resources for a given VM instance
stratus-shutdown-instance stop and save a VM instance, must be used with --save option when starting VM instance
stratus-describe-volumes list persistent disk volumes
stratus-create-volume create a new persistent disk volume
stratus-delete-volume destroy an existing persistent disk volume
stratus-attach-volume dynamically attach a persistent disk volume to a VM instance
stratus-detach-volume dynamically detach a persistent disk volume from a VM instance
stratus-update-volume update the metadata for a persistent disk volume
stratus-build-metadata create a Marketplace entry for a VM image
stratus-sign-metadata cryptographically sign a Marketplace entry for a VM image
stratus-validate-metadata verify that a VM image entry is syntactically correct and signed
stratus-upload-metadata upload a VM image entry to the Marketplace
stratus-deprecate-metadata deprecate a Marketplace entry for a VM image
stratus-create-image create a new VM image from an existing image
stratus-upload-image (deprecated) upload an image to the appliance repository
stratus-connect-instance connect via ssh to a given VM instance
stratus-hash-password hash a password to give to cloud administrator
stratus-prepare-context prepare a CloudInit contextualization file
stratus-run-cluster utility to run a batch cluster on the cloud

Table: Overview of StratusLab commands.


Verifying the Prerequisities

Before starting, you must verify that the prerequisites for the StratusLab command line are satisfied:

  • Python 2 (2.6+), virtualenv and pip are installed.
  • Java 1.6 or later is installed.
  • An SSH client is installed with an SSH key pair.
  • You have an active StratusLab account and connection parameters.

Quick recipes for checking the first three points are below, with more detailed information in the appendices.

For the StratusLab account, you must contact the administrator of your cloud infrastructure. The administrator must give you 1) your credentials and 2) the service endpoints of the cloud infrastructure.

You can quickly verify the availability of Python and utilities with the following commands:

$ python --version
Python 2.6.6

$ which virtualenv

Note that pip is always installed with virtualenv.

Similarly for java use the following:

$ java -version
java version "1.7.0_19"
OpenJDK Runtime Environment (rhel-
OpenJDK 64-Bit Server VM (build 23.7-b01, mixed mode)

Note that there is only one hyphen in the option.

For SSH check to see if the directory $HOME/.ssh/ contains files starting with “id_”.

$ ls $HOME/.ssh/id_*
/home/sluser/.ssh/id_rsa  /home/sluser/.ssh/

Local Installation

For local installations of the StratusLab client, for example within a non-priviledged user account or on a user’s laptop, an installation using virtualenv and pip is very strongly recommended.

Assuming that the prerequisites are installed, the installation is just a matter of a few commands. First create a virtual environment to hold the StratusLab client and its dependencies.

$ virtualenv $HOME/env/SL
New python executable in /home/sluser/env/SL/bin/python
Installing setuptools............done.
Installing pip...............done.

You may want to choose a different name or location for your virtual environment. Now you will need to activate that environment.

$ source $HOME/env/SL/bin/activate

The prompt should change to include the name of the virtual environment.

Now use pip to install the StratusLab client:

(SL)$ pip install stratuslab-client
Downloading/unpacking stratuslab-client
  Downloading stratuslab-client-13.05.0.RC1.tar.gz ...
Successfully installed stratuslab-client dirq ...
Cleaning up...

This will also install all of the required Python dependencies for the client as well. (The above output has been abridged.)

You can verify that the client is installed and accessible with by searching for one of the StratusLab commands:

(SL)$ which stratus-copy-config

All of the StratusLab commands begin with stratus-. On systems that support it, you can use tab completion to see all of the available commands.

Once the client is installed, it must be configured. See the instructions below.

System Wide Installation

The above method can also be used for system wide installations for multi-user machines. Simply use pip directly without using virtualenv.

Additionally, StratusLab provides client packages for RedHat Enterprise Linux (RHEL) systems. These packages work also on derivatives of these systems like CentOS, ScientificLinux, and OpenSuSE.

You must have root access to your machine to install these packages. For RHEL and RHEL-like systems, it is recommended to do the installation with yum. The configuration for yum tells yum where to find the StratusLab packages. Choose the centos-6 repository. Use the command:

$ yum install stratuslab-cli-user

to install the latest version of the client tools.

For SuSE, configure zypper for the StratusLab OpenSuSE repository (“opensuse-12.1”) and use it to install the package.

Users must then configure the client within their accounts.

Client Configuration

The values of the configuration parameters for the client can be provided in several different ways. The various mechanisms in order of precedence are:

  • Command line parameters
  • Environment variables (STRATUSLAB_*)
  • Configuration file parameters
  • Defaults in the code

The names of the command line parameters and the environmental variables can be derived from the name of the configuration file parameter. The table gives an example for one parameter and the algorithm for deriving the other names.

pdisk_endpoint configuration file parameter
--pdisk-endpoint command line option: change underscores to hyphens and prefix with two hyphens (--)
STRATUSLAB_PDISK_ENDPOINT environmental variable: make all letters uppercase, prefix with STRATUSLAB_

Table: Deriving command line option and environmental names from the configuration file parameter.

The configuration file is in the standard INI format. The file must contain the [default] section. It may also contain additional sections describing parameters for different cloud infrastructures.

A minimal configuration file, assuming that a username/password pair is used for credentials is:

endpoint =
pdisk_endpoint =
username = sluser
password = slpass

The values will obviously have to change to correspond to your credentials and the cloud infrastructure that you are using.


StratusLab provides a very flexible authentication system, supporting username/password pairs, X509 certificates, Globus/VOMS certificate proxies, and PKCS12 certificates.

username user’s StratusLab username
password user’s password
pem_certificate X509 or proxy certificate file
pem_key X509 or proxy key file

Table: Parameters for supplying user credentials.

Users should specify either the username/password or the pem_certificate/pem_key parameters but not both sets. If both are specified, then the username/password will take precedence.

The default for the pem certificate and key are the files usercert.pem and userkey.pem, respectively in the directory $HOME/.globus. Contrary to the usual rules, the command line parameter for pem_certificate is --pem-cert.

Service Endpoints

The user must also specify the cloud service endpoints. These will be provided by the cloud administrator.

endpoint cloud entry point (VM mgt.)
pdisk_endpoint pdisk entry point (storage mgt.)
marketplace Marketplace URL

Table: Cloud service endpoints.

If the pdisk_endpoint parameter is not specified, then the value for endpoint will be used. The default value for the marketplace parameter is, the central StratusLab Marketplace.

Other Credentials

Various other credentials are used to access running virtual machines and for signing information for the Marketplace.

user_public_key_file user public SSH key file
p12_certificate PKCS12-formatted certificate
p12_password password for PKCS12 certificate

Table: Other user credentials.

The default for the public SSH key file is $HOME/.ssh/ Contrary to the usual rules, the environmental variable and command line parameter are STRATUSLAB_KEY and --key, respectively.

The PKCS12 certificate is used to sign image metadata entries before uploading them to the Marketplace. Contrary to the usual rules, the command line option for the parameter p12_certificate is --p12-cert.

Multi-cloud Configuration

If more than one StratusLab cloud infrastructure is being used, then the configuration for all of these can be kept in a single file. This allows you to quickly switch between the various clouds.

In the configuration file it is possible to create uniquely named user specific sections to define any of the variables described above. Example of ‘endpoint’

endpoint = <>
username = <another.username>
password = <another.password>

which can be activated using the selected_section parameter in the [default] section of the configuration file:

selected_section = my-section

It can also be activated using command-line options --user-config-section or -S or via the environmental variable STRATUSLAB_USER_CONFIG_SECTION.

This example configuration file defines custom ‘fav-cloud’ section with endpoint/credentials and a custom SSH key:

endpoint = favorit-cloud.tld
username = clouduser
password = cloudpass
user_public_key_file = /home/clouduser/.ssh/

Values for parameters not specified in this section will be taken from the [default] section.