Command Line Client

The StratusLab command line client is written primarily in Python, although there is a small part related to XML cryptographic signatures that is written in Java.

Installation

End-users should use the Python package installer (pip) to install the client on their machines. Do the following to install the client and all of the required dependencies:

$ pip install stratuslab-client
Downloading/unpacking stratuslab-client
...
Successfully installed stratuslab-client dirq httplib2 requests
Cleaning up...

The command should end with a message saying that the installation was successful. By default, pip will install the software in the system area to make it available for all users on the system.

Note

If you want to install a beta version or release candidate, then for newer versions of pip you will have to use the --pre option to allow pre-release versions to be installed.

Note

For CentOS, the client can also be installed via the yum package repository. The RPM and pip installations conflict with one another, so only one of these methods should be used.

Warning

On Mac OS X with the latest version of pip, the system-wide installation will not work correctly because of a change in where data files are placed. A user-level or virtualenv installation is recommended to work around this problem.

If you don’t want a system-wide installation of the client, you can do a user-level installation using the option --user. However in this case, you will need to modify your environment, adding for example, the appropriate directories to your PATH:

PATH=$PATH:$HOME/.local/bin

Adjust the command appropriately for your operating system and command shell.

Configuration

You must configure the command line client, providing the service endpoints for the StratusLab cloud that you want to use and your credentials for that cloud.

Create your configuration file by running the following command:

$ stratus-copy-config

If successful, this will create the file $HOME/.stratuslab/stratuslab-user.cfg. You will now need to edit this file to provide the required information. The file itself is extensively commented, showing all of the available options.

Your edited file should be similar to the following:

[default]

selected_section = sl-cloud

endpoint_timeout = 5

[sl-cloud]

name = "StratusLab Cloud"
country = "France"

endpoint = https://cloud.lal.stratuslab.eu/one-proxy/xmlrpc
pdisk_endpoint = https://pdisk.lal.stratuslab.eu/pdisk
marketplace_endpoint = https://marketplace.stratuslab.eu/marketplace

username = ....
password = ....

Obviously, you will need to replace the username and password values with your actual credentials. You will also need to replace the endpoint values for the cloud you are using. The endpoints given here are for the StratusLab reference infrastructure.

Note

If your password (or any other value) contains a percent sign (%), you must double that character in the configuration file. This is because the Python software used to read the configuration files allows variable substitution with the syntax %(variable).

Testing

To test that the client is installed correctly and that you can contact the cloud services, run the following commands:

$ stratus-describe-instance
id  state     vcpu memory    cpu% host/ip                 name

$ stratus-describe-volumes
No disk to show

These should return an empty list of virtual machines and of volumes, respectively. Any error indicates a problem with the installation or configuration of the client. Correct these errors before continuing!

Getting Help

To see the help for a given command, do the following:

$ stratus-describe-instance --help
Usage: stratus-describe-instance [options] [vm-id ...]

 Provides information about the virtual machine with the given
 identifiers or all virtual machine if no identifier is given.
...

All of the StratusLab commands support this option. It provides a summary of the purpose of the command and a detailed list of the available options.

All of the commands also support the --version option that prints the version number of the client. When reporting problems, it is very helpful to also provide the exact version number of the client.

In general the command line interface returns a minimum of information to the user. To make the commands more verbose (especially when tracking down errors), you can add the -v or --verbose option. This can be specified multiple times to increase the verbosity further. All commands support this option.