PK ¶&¦Fm$í!¦ ¦ stratuslab-latest/.buildinfo# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config:
tags:
PK ¶&¦FP¸Ý Ý stratuslab-latest/objects.inv# Sphinx inventory version 2
# Project: StratusLab
# Version: 14.06.0-RC6-SNAPSHOT
# The remainder of this file is compressed using zlib.
xÚKOÍËÌKI­P(.I±ÊILJÍQÐ5THêeäæ(+xØ\¹ù)XTêÂ$ ª}óSJsR¡S3Pµ@Ä ª!
ÓS¹ ÙD1PK ¶&¦F­NÕ%û %û stratuslab-latest/index.html

StratusLab is a complete cloud distribution that allows you to install
an “Infrastructure as a Service” cloud on your own hardware. The
StratusLab distribution aims to be simple to use, simple to install,
and simple to maintain.

If you can’t find the information you need in the documentation,
contact the developers through GitHub or our support mailing list.

This tutorial provides a whirlwind tour of the features available to
users of StratusLab cloud infrastructures. It covers the installation
of the command line client as well as use of the cloud’s compute,
storage, and network resources.

To follow this tutorial, you must have a machine running a recent
version of Linux, Mac OS X, or Windows and the ability to install and
configure software on that machine.

Linux and Mac OS X are fully supported and tested. The core features
work also on Windows, although there are a few commands that do not.
Those commands that do not work on Windows are pointed out in the
documentation.

To take advantage of all of the StratusLab features, you must have the
following software installed and configured:

Python 2 (2.6+)

pip, the python package installer

Java 1.6+ (any certified distribution)

SSH client (with an SSH keypair)

Recent web browser

You may optionally install the python virtualenv to isolate the
StratusLab python environment from others. All of the supported
platforms have widely available versions of these software packages
available.

Note

The commands that require the Java Virtual Machine will not be used
in this tutorial, so you do not need to install Java for this
tutorial.

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.

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.

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).

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!

$ 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.

“Infrastructure as a Service” cloud infrastructures provide computing
resources through “virtual machines”. For end users, these virtual
machines act just like physical machines, except that they can be
provisioned quickly with exactly the configuration desired.

This section starts with a description of the Marketplace, a catalog
of virtual machine images, and then covers how to start, access, and
stop virtual machine instances.

All virtual machine instances are created from virtual machine images
(or appliances) that contain the starting configuration for the
virtual machine.

For StratusLab clouds, the Marketplace contains a database of all of
the available appliances. These include standard appliances created
and maintained by the StratusLab developers as well as appliances
created by other StratusLab users.

Use your web browser to view the available appliances by navigating to
the central Marketplace. You can find the
standard images from StratusLab by putting “images@stratuslab.eu”
into the “endorser” field on the right side of the interface.

The summary contains the basic information for an appliance along with a
link to find more information. The most imporant bit of information is
the image identifier. This is a 27 character Base 64 value that
uniquely identifies the appliance. This identifier is used to select the
appliance you want to run as a virtual machine.

StratusLab provides minimal distributions of CentOS 6, ScientificLinux
6, Ubuntu 12.04, and Ubuntu 14.04. These follow the best practices for
appliance creation and are kept up to date with security patches. They
make good starting points for creating your own appliances.

Exercise

Use your web browser to navigate through the Marketplace. Use the
search widget on the right to see what appliances are available.
Use the search widget to find all of the appliances created by the
StratusLab collaboration.

The stratus-run-instance command starts a new virtual machine
instance. It requires the appliance or image identifier from the
Marketplace (APP_ID). This will return the virtual machine
identifier (VM_ID) and its assigned IP address (VM_IP).

The stratus-describe-instance command displays the information
about virtual machines. Without an argument, it will provide a
concise summary for all non-terminated virtual machines. If you
provide a virtual machine identifier, then only information for that
machine will be returned. More detailed information can be obtained
by using the --verbose option.

You can log into your virtual machine using SSH. Your public SSH key
will have been transferred to the machine and will allow you to log
into the machine as root. Use stratus-connect-instance${VM_ID} or just sshroot@${VM_IP} to log into the machine.
Depending on the operating system, resources, etc., it can take
several minutes to have access to a virtual machine.

Note

The stratus-connect-instance command does not work on Windows.
Use your local SSH command or application to connect to your
virtual machine.

The stratus-kill-instance command stops a virtual machine and
releases all of the allocated resources. Virtual machines that have
been terminated will no longer appear in the
stratus-describe-instance output by default.

Warning

The stratus-kill-instance stops a running virtual machine
instantly. This is the equivalent of pulling out the plug. A more
graceful shutdown should be done in most cases: halt the virtual
machine (with halt or shutdown within the machine) and then
run stratus-kill-instance.

Exercise

Choose one of the standard appliances (e.g. Ubuntu 14.04) and use
these commands to go through the lifecycle for a virtual machine.
How long was it before you could ping the virtual machine? How
long before you could log in?

The values for the CPU, RAM (MiB), and SWAP (MiB) space are listed for
each type with the default type marked with an asterisk. You can change
which type is selected by using the --type option when starting a
virtual machine.

Fine-grained control over the resource allocation is also
possible. The options --cpu, --ram, and --swap allow you
to set these values separately. For values that are not specified
explicitly, the value will be taken from the selected machine type.

Exercise

When logged into a virtual machine, can you determine how many CPUs
were allocated and how much memory? You can find this information
by looking at /proc/meminfo and /proc/cpuinfo, for example.

Exercise

Use the --type, --cpu, and --ram options to change the
allocated resources for a virtual machine. Verify that the correct
amount of resources has been allocated.

Contextualization is the process by which a virtual machine discovers
characteristics of its environment and properly configures itself. This
is used, for example, for network configuration but can also be used for
user-level service configuration.

Unfortunately, there is no standard for the contextualization
process, although the CloudInit process is slowly becoming a de
facto standard.

StratusLab supports two contextualization mechanisms: HEPiX/OpenNebula
and CloudInit. For historical reasons the HEPiX/OpenNebula mechanism
is currently the default.

The HEPiX/OpenNebula contextualization passes information from the
user (given with the stratus-run-instance command) to the virtual
machine via a CD-ROM image. The virtual machine automatically mounts
the CD-ROM image and executes a contextualization script using the
information from the image.

You public SSH key is automatically passed to the virtual machine
using this mechanism. Additional key-value pairs can be passed to the
virtual machine via the --context parameter.

The context information can be seen on the client side by using the
stratus-describe-instance-vvv${VM_ID} command. This displays
all of the information defining a given virtual machine.

From within the virtual machine, you can mount the CD-ROM image (if it
isn’t already mounted) to see what scripts and what information has
been passed from the client to the virtual machine. You can find the
image by using the blkid command. CD-ROMs have the type
“iso9660”.

Exercise

Start a virtual machine. Log into the virtual machine, find the
context CD-ROM, and mount it. What files are there? How are these
executed in the startup process? (Hint: Look in /etc/init.d/.)

Exercise

Use the context options to start another virtual machine. How are
the key-value pairs you defined passed into the virtual machine?
Can you imagine how to use this information to configure a service
on the machine?

CloudInit is a very flexible contextualization mechanism that is
becoming a de facto standard. StratusLab supports this mechanism.
You can make CloudInit the default contextualization mechanism by
setting the default_context_method value in your configuration
file:

default_context_method=cloud-init

You can set this for a specific cloud infrastructure or globally in
the defaults section.

To start a virtual machine using CloudInit, use the --cloud-init
option or the --context-method option. The following two commands
have the same effect:

After a couple of minutes, you should be able to visit the url
http://your-vm.example.com/test.txt to see a page containing
“SUCCESSFUL TEST”.

If you want to pass multiple files, you can separate the mimetype/file
pairs with hash (#) characters or use the stratus-prepare-context
and then the --context-file option of stratus-run-instance.

Exercise

Start a virtual machine with CloudInit. Log into the virtual
machine, find the context VFAT disk, and mount it. What files are
there? How are these executed in the startup process?

Exercise

Do the same exercise for an Ubuntu machine? What did you have to
change to get this to work? Can you install and configure another
service on a virtual machine that would be visible from your web
browser?

Raw compute power without persistent storage only supports a limited
range of applications. StratusLab like most cloud software also
provides services for managing persistent storage.

For StratusLab, persistent storage is in the form of raw block devices
(volumes). These volumes can be used in conjunction with virtual
machines, but importantly have a lifecycle that is independent of
them.

Raw block devices behave similarly to physical hard drives. In
particular, they have some of the same limitations:

They are initially empty and unformatted; they must be initialized
when first used.

They can only be attached on one virtual machine at a time; they
must be detached from one machine before being attached to
another.

StratusLab does not natively provide file or object-based storage
services.

The stratus-create-volume command takes the size of the volume in
Gibibytes (GiB) and an optional tag. The tag is useful for
remembering the contents of a given volume. A tag be added later with
the stratus-update-volume command. This command returns the UUID
of the created disk.

The stratus-describe-volumes command provides a list of persistent
disks if no argument is provided. If you provide an argument, then
the details for the given disk are provided. The --filter option
is useful for limiting the number of disks returned in the list.

Note

The StratusLab caching mechanism for virtual machine appliances
uses the persistent disk infrastructure. When virtual machines are
running you will see “snapshot” volumes corresponding to the root
volumes for those machines.

The stratus-delete-volume deletes a given volume. This releases
the allocated storage space and permanently deletes any stored
data.

Warning

Once a persistent disk has been deleted, all of the data on the
disk is deleted and cannot be recovered. Be certain that you
reference the correct disk before deleting it!

Exercise

Run through the entire persistent disk lifecycle with the command
line interface. Try to change the tag associated with the disk
after you’ve created it.

Exercise

Create several (small) disks with different tags and sizes. Use
the filtering to limit the information returned by the
stratus-describe-volumes command.

There is also a web interface for this service which allows you to
perform the same operations as you can from the command line. (It
also allows you to see the current mount status of a disk which the
command line client can’t do.)

You can discover the location of the web interface by pointing a
browser at the URL for the “pdisk_endpoint” in your configuration (or
at the “endpoint” value if “pdisk_endpoint” isn’t defined). Look for
the “svc-pdisk.html” file in the listing.

Warning

That the web interface will change significantly in the coming
releases.

Exercise

Run through the entire persistent disk lifecycle though the web
interface. Modify the tag (or add one) to an existing persistent
disk.

The easiest way to attach a persistent disk to machine is to use the
option --persistent-disk when launching a virtual machine. The
command for doing this looks like:

$ stratus-run-instance --persistent-disk=${VOLUME_UUID} ${APP_ID}

Attaching a disk at deployment time has a couple of limitations.
First, only one persistent disk can be attached to the machine.
Second, the persistent disk remains attached to the virtual machine
for the entire lifetime of the virtual machine.

A new persistent disk is an empty, uninitialized block device.
Consequently, the first time the disk is used, it must be formatted.

When the virtual machine starts the persistent disk will be attached
to the machine. Logging into the virtual machine, you can find the
device name for the disk by using the command fdisk-l, looking for
a disk without a partition table and with the expected size.

A new physical disk is usually partitioned so that the space can be
used for different purposes (file storage, swap, etc.). For
persistent disks on the cloud, there is really no benefit in doing
this unless there is a reason you need more than one file system on
the disk. If you do want to partition the disk, you can use the
command fdisk to do so.

You must however format the disk to make it useful. To format the
disk, use the command mkfs. It is very strongly recommended
that you provide a label for the file system.

This shows that you can use the disk normally as you would any other
disk on the system.

Note

The benefit in providing a label is that you don’t need to search
for the device name of the disk. The device name may vary
depending on when the disk is attached to the machine and different
operating systems may use different naming conventions.

When the machine is shutdown, the persistent disk will be released and
can then be mounted on another machine.

Exercise

Repeat this procedure yourself. At the end, start up a separate
virtual machine with this disk and verify that the file you
initially stored is still there.

Although using the --persistent-disk option of
stratus-run-instance is easy; it isn’t always convenient. You can
attach and detach disks dynamically from running virtual machines to
provide more flexiblity and to overcome the limitations stated
earlier.

The commands for attaching and detaching persistent disks dynamically
are:

These can be used at any time while the virtual machine is running.
Within the virtual machine, the volume must still be mounted from the
file system in order to be accessible.

Even though modern file systems are tolerant of abrupt deconnections of
devices, it is always a good idea to unmount the disk from the file
system from within the virtual machine before detaching the disk with
the stratus-detach-volume command.

Exercise

Start a virtual machine, wait for it to come up, and log into it.
From another terminal, dynamically attach a persistent disk to the
machine. Verify that the disk is visible on the virtual machine
(using blkid or fdisk-l). Mount the disk and verify that
any previous data is visible. Unmount the disk and detach it.
Verify that the disk is no longer visible on the virtual machine.

Exercise

Attach and detach a persistent disk multiple times. Does the
device name remain the same or change?

Exercise

A volume can be mounted only on one virtual machine at a time. Try
to mount a volume on more than one virtual machine to see what error
message is given.

Many applications have a need for a large storage space for temporary
data. StratusLab provides volatile storage for this purpose. The
space will be reclaimed (and the data lost) when the virtual machine
is terminated.

When starting a virtual machine a volatile disk can be added to the
machine using the --volatile-disk option:

As for persistent disks, the volatile disks are not formatted. You
will need to find and format the disk in the same way as for a
persistent disk.

Exercise

Start a virtual machine with a volatile disk. Find, format, mount,
and store data on the disk. Verify that the data on the disk will
survive a machine reboot. (Reboot the virtual machine using
reboot within the virtual machine.) Unless you added the disk
to the /etc/fstab file, you will need to remount the disk after
the reboot. The disk and data will disappear when the machine is
terminated with stratus-kill-instance.

Many applications use datasets that are either fixed or change
slowly, for example, input databases for a scientific calculation.
Since these are fixed datasets, you can take advantage of the virtual
machine image caching mechanisms to efficiently cache and duplicate
these datasets.

These static (read-only) disks can be attached when starting a virtual
machine. As for virtual machine images, these disk images are also
registered in the Marketplace. To start a machine with a static
disk:

Note that the disk is read-only, so you cannot make any changes to
this disk.

The disk will appear in the virtual machine exactly as it has been
formatted in the reference image. Usually these images are formatted as
a CD-ROM (or DVD) image so that they are portable between different
operating systems.

When creating such images it is strongly recommended (unlike here)
that they be created with a label so that they can easily be mounted
by the user without needing to know what device has been assigned.

Exercise

Run a machine with this disk image. Verify that it is indeed
read-only. What happens if you start a second disk with the same
image?

This tutorial has shown you the core functionality available on a
StratusLab cloud infrastructure. With just this functionality a large
majority of use cases are covered. Nonetheless you are invited to
look through the User Guide to acquaint yourself with advanced
StratusLab features.

Concretely, some advanced use cases require you to create new
appliances or data sets and to register them in the Marketplace.
Information about performing those tasks (as well as other advanced
features) can be found in the more extensive User Guide.

If you don’t find the information or features you need in the
documentation, contact StratusLab support for help!

This tutorial demonstrates a minimal installation of a StratusLab cloud
on two physical machines. Before trying to install the StratusLab
software there are many prerequisites that must be satisfied by the
hardware, operating system, and software.

The physical machines should be relatively modern machines with the
following minimum characteristics:

1 64-bit multicore CPU (>= 4 cores)

4 GB of RAM

200 GB local disk space

In general cloud infrastructures prefer “fat” machines; that is
machines that have the maximum number of CPUs, RAM, and disk space as
possible. This is because the maximum size of a single virtual
machine is limited by the size of the largest physical machine.

Install a minimal version of CentOS 6 on the
two physical machines that will be used for the cloud infrastructure.
Other distributions that are compatible with CentOS 6 will likely
work; however, only CentOS 6 is systematically tested.

Operating Systems in the Debian family (e.g. Ubuntu) are not currently
supported.

StratusLab allows for a variety of storage options behind the persistent
disk service.

This tutorial uses the default storage solution using LVM and iSCSI.
Because of this, the machines must be configured to use LVM for the
disk storage.

The Front End will host the storage service and the physical storage
associated with it. It is strongly recommended that the Front End
machine be configured with two LVM groups: one for the base
operating system (~20 GB) and one for the StratusLab storage service
(remaining space). One LVM group is possible, but you risk starving
normal system services of disk space.

In the tutorial, we assume that the volume group names are “vg.01” for
the operating system and “vg.02” for the StratusLab storage service on
the Front End. You can use other names, but change the commands and
configuration parameters below as necessary.

You’ll need the volume group name “VG Name” of the volume group you’ll
be using for the cloud storage. Verify that the device associated
with the group name exists. Here for example, the device is
/dev/rootvg.

The configuration for the CentOS repository is done when the system is
installed and the IGTF repository will be configured by the StratusLab
tools as necessary. The others require explicit configuration.

The directory /etc/yum.repos.d contains the currently configured yum
repositories.

Ensure that the host resolves to an IP address and that the IP address
resolves back to the original name (or alias).

Also ensure that the hostname is properly set for the node:

$ hostname -f

should return the full hostname (with domain). Set the hostname if it
is not correct.

Throughout this tutorial we use the variables $FRONTEND_HOST
($FRONTEND_IP) and $NODE_HOST ($NODE_IP) for the Front End and Node
hostnames (IP addresses), respectively. Change these to the proper names
for your physical machines when running the commands.

You must have a range of free IP addresses that can be assigned to
virtual machines. The range should be large enough to handle the
maximum number of virtual machines you expect to have running
simultaneously on your infrastructure.

These IP addresses must be publicly visible if the cloud instances are
to be accessible from the internet.

In addition, a DHCP server must be configured to assign static IP
addresses corresponding to known MAC addresses for the virtual
machines. You can use an external DHCP server or if one is not
available (or not desired), the StratusLab installation command can be
used to properly configure a DHCP server on the Front End for the
virtual machines.

A network bridge must be configured on the Node to allow virtual
machines access to the internet. You can do this manually if you want,
but the StratusLab installation scripts are capable of configuring this
automatically.

This tutorial uses the installation scripts to configure the network
bridge.

Now do the necessary configuration to ensure that you can log into the
Front End from the Front End with your SSH key (and without a
password). Do the following:

$ ssh-copy-id $FRONTEND_HOST
The authenticity of host 'onehost-5.lal.in2p3.fr (134.158.75.5)' can't be established.
RSA key fingerprint is e9:04:03:02:e5:2e:f9:a1:0e:ae:9f:9f:e4:3f:70:dd.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'onehost-5.lal.in2p3.fr,134.158.75.5' (RSA) to the list of known hosts.
root@onehost-5.lal.in2p3.fr's password:
Now try logging into the machine, with "ssh 'onehost-5.lal.in2p3.fr'", and check in:
.ssh/authorized_keys
to make sure we haven't added extra keys that you weren't
expecting.

and then the same thing for the node:

$ ssh-copy-id $NODE_HOST
...

After these commands you key should have been added to the
authorized_key file on both nodes and should allow you to log in
without a password.

Note

If you machine does not have the ssh-copy-id command, then you
will have to do the configuration by hand. Append the contents of
your $HOME/.ssh/id_rsa.pub file to the
$HOME/.ssh/authorized_keys file on both the Front End and the
Node. You will also have to accept the host’s SSH key the first
time you log in.

The command stratus-config will help you view and set the various
parameters for the StratusLab installation. This is essentially an
interface to the configuration file /etc/stratuslab/stratuslab.cfg
and the associated reference file
/etc/stratuslab/stratuslab.cfg.ref.

To list all of the defined parameters (keys) and their values use the
command:

$ stratus-config --keys
...

This will display a long list of keys, their current values, and their
default values, by section. You can view a single parameter by naming
the parameter:

$ stratus-config frontend_system

and set it by giving a value:

$ stratus-config frontend_system centos

Each service has a parameter to determine whether the service will be
installed. For example, the registration service:

$ stratus-config registration
False

is not installed by default. The values that should be set will be
discussed in the following sections.

Once all of the service configuration parameters have been set, you
can use the stratus-install command to perform the installation.
This command should always be executed on the Front End. It will use
SSH to access the machines (including the Front End!) where the
services will be installed.

Normally, if errors occur in the installation, you can simply correct
the configuration and rerun stratus-install.

This command is designed to simplify the initial installation of the
cloud. It can be used also to update the cloud software, although
there are some significant limitations when doing this. Notably there
are certain parts of the configuration (like the address ranges) that
cannot be updated automatically.

There is a fair number of cloud services and a large number of
associated parameters. Fortunately, the default values for many of
these services will work fine, so only a limited number of parameters
actually need to be set.

The Persistent Disk service and the Nodes communicate using a strategy
defined by the persistent_disk_storage and persistent_disk_share
parameters. The default values (“lvm” and “iscsi”, respectively) will be
used for this tutorial.

One needs to specify what device will be used for the physical storage
for the Persistent Disk service:

In this example, the Front-End is configured on IP address $FRONTEND_IP
and three IP/MAC address pairs are defined for virtual machines.

You must use the real values for the Front End IP addresses and for
the range of addresses you will use for the virtual machines. The
mac addresses are arbitrary, but it is a good idea to have the last
four fields match the IPv4 network address.

More network parameters are described in the “one-network” section in
the reference configuration file.

If the page doesn’t appear or any of the services are not running, you
should investigate the errors in the log files. The log files for all
StratusLab services are in /var/log/stratuslab. Each service in a
separate subdirectory.

At this point, you have both the Front End and one Node installed. In
principle this is a fully functional installation. To ensure this is
the case, we’ll run the standard battery of tests on the cloud
infrastructure as a normal user.

This creates a new StratusLab user ‘sluser’ with a password ‘slpass’.
The group ‘cloud-access’ is mandatory for the user to have access to
the cloud services. (Crypted or hashed password values are also
allowed in the configuration.)

The StratusLab distribution supports other authentication methods
(LDAP, X509 certificates, X509 proxies, etc.), but a username/password
pair is the simplest for this tutorial.

We’ve chosen the same name as the cloud user, but the unix and cloud
user accounts are distinct.

Now log in as the user and setup the account for using StratusLab. An
SSH key pair is required to log into your virtual machines and the
client requires that a complete client configuration file.

Log in as the user and create an SSH key pair. This is similar to the
process used for the root account on the machine:

$ su - sluser
$ ssh-keygen -q
...

You can create a passphrase for this SSH key if you want. If you do,
you’ll need to provide the passphrase when logging into virtual
machines.

Now copy the reference configuration file into place and edit the
parameters:

$ stratus-copy-config
$ vi $HOME/.stratuslab/stratuslab-user.cfg

You will need to set the “endpoint”, “username”, and “password”
parameters in this file. For the “endpoint” use the hostname or IP
address of your Front End. For the “username” and “password” use
“sluser” and “slpass”, respectively.

You’ve successfully installed a minimal StratusLab cloud. You can
checkout the documentation to
see what other configuration parameters are available or try the user
tutorials to discover more of the StratusLab services.

You can get help on the installation or use of StratusLab through the
support mailing list. You can also
report bugs and provide feedback on the same list.

This guide provides information of interest to researchers,
scientists, and engineers looking to use an existing StratusLab cloud
infrastructure. It also provides information for application
developers looking to port their software to a StratusLab cloud
environment.

This guide provides information of interest to researchers, scientists,
and engineers looking to use an existing StratusLab cloud
infrastructure. It also provides information for application developers
looking to port their software to a StratusLab cloud environment.

System administrators wanting to install a StratusLab cloud on their own
resources should start with the StratusLab Administrator’s Guide,
although they will also want to use the information in this guide to
test their cloud after installation.

Those wishing to contribute to the StratusLab software or documentation
should consult the StratusLab Contributor’s Guide.

Extended examples of commands and their outputs are displayed in the
monospace Courier font. Within these sections, command lines are
prefixed with a ‘$ ‘ prompt. Lines without this prompt are output from
the previous command. For example,

StratusLab, an international collaboration, provides a complete, open
source cloud distribution, allowing the installation of public or
private “Infrastructure as a Service” cloud infrastructures. It aims to
be both simple to use and simple to install.

StratusLab provides a couple mechanisms for accessing cloud resources: a
command line interface written in portable python and web interfaces
(for a subset of services). Developers can also use the Libcloud API,
the StratusLab Python API, or the service REST APIs for programmatic
access.

This chapter provides the bare-bones instructions for getting up and
running with the StratusLab command line client. The client provides a
set of commands for interacting with all of the StratusLab services.
Getting started involves just four steps:

Verifying the prerequisites,

Installation of the client,

Configuring the client, and

Testing the installation.

Each is covered in a section below. More detailed information on
installing and configuring the client are in subsequent chapters;
similarly later chapters also cover the utilization of the StratusLab
services more throughly.

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.

For the first three points, more information can be found in the
following chapter and in the appendix.

For the StratusLab account, you must contact the administrator of your
cloud infrastructure. The following parts of this chapter presume that
you have a username/password pair for credentials and are using the
StratusLab reference infrastructure at LAL.

Normally, you would browse the StratusLab
Marketplace to find an image
that is useful for you. You then use the image identifier to start a
copy of that image.

We use the image identifier BN1EEkPiBx87_uLj2-sdybSI-Xb for a
ttylinux image. This is a very minimal linux distribution usually
intended as an embedded operating system. It is extremely small and
boots quickly, making it ideal for tests.

Note that your must use the username defined by the person that created
the image. This is almost always “root”. In both these cases,
information about the SSH host key have been suppressed for clarity.

The resources allocated to the machine are only released when the
machine is killed. If you shutdown the machine while inside the
operating system with halt or shutdown, you must still use the
StratusLab command to kill the machine to release the resources.

This chapter has shown you the procedure for installing the client and
then, the basic lifecycles for starting machines and for creating
persistent disks. Hopefully, you are intrigued enough to read following
chapters that provide more detail on the StratusLab services and their
functionality.

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

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:

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.

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:

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.

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 https://marketplace.stratuslab.eu/, the central
StratusLab Marketplace.

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/id_rsa.pub.
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.

Web interfaces are often more intuitive than command line interfaces.
Moreover, they do not require the installation of software on the user’s
machine (aside from a web browser!).

Eventually StratusLab will provide a unified portal to allow access to
all services via a web browser, but this is not yet available.
Nevertheless, several of the StratusLab services provide a web
interface. These interfaces are essentially a thin veneer over the
services’ REST interfaces.

For the Marketplace, the primary interface is via a web browser. This
interface allows users to search for available images, to access the
metadata in several formats (HTML, XML, and JSON), and to upload new
metadata entries.

The storage service also provides a web browser interface that mirrors
the underlying REST interface. This interface allows a users to see the
complete list of disks, manage the metadata of the disks, and to mount
and dismount them from virtual machines dynamically.

The registration service is an optional service that allows users to
register for access to a cloud infrastructure and to manage the
information associated with their account. If used, the cloud
administrator validates the account requests.

This service is indeed used for the StratusLab reference cloud
infrastructure and users may register via this service
instance.

Probably the easiest way to see how this works is to run through a
complete example. We will go through a complete lifecycle for a ttylinux
machine. The ttylinux distribution is a small linux distribution mostly
intended for embedded systems. Its small size and fast boot make it
ideal for tests.

First you would normally browse the Marketplace to find a suitable
image. You can find the images provided by StratusLab by searching for
the endorser “images@stratuslab.eu”. For our case, the ttylinux image
has the identifier: “BN1EEkPiBx87_uLj2-sdybSI-Xb”.

More details will be provided if you increase the verbosity of the
commands with the options -v, -vv, or -vvv. More letters
provide increasingly more verbosity. This is especially helpful when
virtual machines fail.

You can control the number of CPUs, amount of RAM and size of the swap
space allocated to a virtual machine. StratusLab provides a number of
predefined machine cnofigurations. You can obtain a list of these with
the command:

Persistent Disk Storage is the StratusLab service that physically stores
machine and disk images as volumes on the cloud site. It facilitates
quick startup of VMs and hot-plugging of disk volumes as block devices
to the VMs.

Make sure to unmount any file systems on the device within your
operating system before detaching the volume. Failure to unmount file
systems, or otherwise properly release the device from use, can result
in lost data and will corrupt the file system.

umount/dev/vdaumount/dev/vdb

When you finish using your disks, you can detach them from the running
VM

In addition to persistent and volatile data volumes, StratusLab also
supports read-only volumes. These come in handy when you have fixed (or
slowly changing) data sets that you would like to use with multiple
machines.

Many scientific and engineering applications require access to fixed (or
slowly changing) data sets. This includes versioned copies of databases
(e.g. protein databases) or calibration information. These are often
inputs to calculations that analyze larger, more varied data sets.

Persistent disk volumes and volatile disk volumes are not well-suited
for this. The persistent disks cannot be shared between machine
instances, so multiple copies of the disk need to be maintained or the
data needs to be shared through a file server (e.g. NFS). Use of
volatile storage would require copying the data each time a new machine
instance starts.

Read-only disks allow users to create a fixed disk image containing the
data. It is then registered in the Marketplace and can then be attached
to multiple machine instances. This mechanism takes advantage of the
caching and snapshotting infrastructure used for machine images. Making
the initial copy of the data image and subsequent snapshotting for
individual machine instances completely transparent to the user.

Disk images must contain a formatted file system that can be read by the
chosen operating system for your machine images. Although this could be
any file system, for a couple of reasons the best choice is an ISO9660
(CDROM) image.

These images are easy to create using the mkisofs utility (or
variants) available in most operating systems.

It can be universally read by all operating systems.

It ensures that the operating system is aware that this is a
read-only file system.

Normally these volumes can be mounted and accessed by non-root users.

Using the mkisofs utility, create a disk is easy. The procedure is
just two steps: 1) create a directory containing all of the data for the
disk and 2) run mkisofs on this directory to create the CDROM image.

The only downside is that this requires enough disk space to hold the
directory with the original data and also the created CDROM image. Using
the persistent or volatile storage makes finding a big enough playground
easy.

It is strongly recommended that you provide a label for the disk
image. This will allow you to mount the image in a machine instance
without having to know the hardware device name within the machine
instance.

Just like for machine images, the data images must be registered in the
Marketplace. You need to create an image metadata entry and then upload
it into the Marketplace.

Before anything else, you need to put the image on a webserver. The URL
of the image will then be used in the ‘location’ element of the
metadata.

Then you’ll need to create the metadata itself. This can be done with
the stratus-build-metadata command in the standard way. However,
there are a few ‘gotchas’. The OS, OS version, and OS architecture must
be provided; just use ‘none’ for these values. You should gzip the image
and use ‘gz’ for the compression. The ‘format’ of the image should be
‘raw’. Lastly, the image should have a filename that ends with ‘.iso.gz’
after the compression.

If the disk has a label (it does right?!), then you should add this
information in the metadata description element.

Once you’ve created the metadata entry, sign it with
stratus-sign-metadata and upload it into the Marketplace.

Use of read-only disks is convenient for sharing fixed datasets between
multiple machine instances. Doing so reduces the size of customized
machine images and decouples the updates of the machine images from the
updates of the datasets. Because this takes advantage of the extensive
caching mechanisms of StratusLab, the transfer of such images and the
creation of disks for each machine instance is completely transparent to
the user.

In addition to persistent volumes and read only volumes, StratusLab also
offers the possibility of volatile storage. These disks are allocated
when a virtual machine starts and are destroyed automatically when the
VM terminates. Because of the volatile nature of these disks, they are
ideal for temporary storage.

Users can request a volatile disk when starting a virtual machine with
the --volatile-disk option to stratus-run-instance, giving the
required size of the disk. Note that this storage is allocated on the
physical machine where the VM is running, so requesting a very large
volatile disk may reduce the number of physical machines which can host
the virtual machine.

As for the persistent volumes, these are raw devices, so the user is
responsible for partitioning and/or formatting the volumes before using
them. They also must be subsequently mounted on the VM’s file system.

Again, these volumes are appropriate only for temporary data
storage. The data on these volumes will be destroyed when the virtual
machine is terminated.

Being able to fully customize the execution environment is one of the
strongest attractions of a IaaS cloud. StratusLab provides tools to find
existing customized virtual machine images and to create new ones if
necessary.

Building new virtual machine images can be a tedious and time-consuming
task. Your first instinct should be to first look to see if someone else
has done the work for you!

The StratusLab Marketplace
provides a registry for available, public virtual machine images. These
are created by the people within the community as well as by StratusLab
partners to help people get started using the cloud quickly.

The StratusLab partners themselves provide “base” images for ttylinux,
CentOS (a RHEL derivative), Ubuntu, Debian, and OpenSuSE. These are
minimal, but functional, installations of these operating systems. They
can be used directly or customized to create personalized machines.
These can be found in the Marketplace by looking for “hudson.builder” as
the endorser of the images.

The Marketplace also contains images for various scientific disciplines.
IGE has prepared images for testing Globus services and for running
tutorials with the services. IBCP has created appliances with numerous
bioinformatics applications already installed. Search the Marketplace to
find appliances that interest you.

Although there are many images in the Marketplace, sometimes a suitable
image cannot be found. In this case, try to find a suitable appliance as
a starting point and create a new appliance by customizing the initial
one.

StratusLab provides the stratus-create-image command to automate the
production of a new image based on an existing one. (NOTE: This command
does not work on Windows. See manual process section.) This takes three
inputs:

The Marketplace identifier of the starting image,

A list of additional packages to install, and

A script to configuring the image.

In addition, some information about the new information will be
required–such as a description, the author, and the author’s email
address.

As an example, let’s use the StratusLab Ubuntu base image, adding an
Apache web server, and customizing the home page. To do this, we will
need to add the “apache2” and “chkconfig” packages to the image. We will
also need to run a script that modifies the server’s home page.

First, create a script setup-ubuntu.sh that contains the following
commands:

Note that the necessary packages are included and the configuration
script has been referenced. In addition, information about the author
and the new image has been provided. The argument is the Marketplace
identifier of the image to start with; in this case, it is a base Ubuntu
image.

Warning: Be sure to provide a correct email address. The results of
the process will be sent to that address!

For a normal machine, the “Epilog” state flashes by very quickly because
it just deletes the virtual machine’s resources. In this case however,
the “Epilog” process actually saves the modified image to a new volume
in the persistent disk service. Because these are generally
multi-gigabyte files, this process can take several minutes.

At the end of the “Epilog” process, an email will be sent to the user
with a subject like “New image created IOeo3R5qEdCas5j_r1HxVne3JMk”.
The body of the email contains:

The location of the created image,

The identifier of the created image, and

A draft metadata entry for the new image.

There will also be a temporary entry created in the Marketplace to allow
private testing of the image after creation. You can search for the
image identifier to find the metadata entry.

You can also find the created disk by searching the persistent disk
service:

Now we will try to deploy the new machine and verify that the web
service responds. Ubuntu takes several minutes to go through the full
boot process and to start the web service, so a little patience is
required.

After testing the image, you’ll need to take a few more steps to make
the image accessible for more than 2 days or to make it public.

To make the image public, the contents will need to be copied to a
public server. Mount the define on a VM and copy the contents to a
suitable location. (A future version will allow you to expose the disk
contents directly without copying them.) For a private disk, you do not
need to make any copies.

In both cases, modify the draft image metadata, especially providing a
longer validity period for the image. A resonable value is 6 months.
Sign the metadata with stratus-sign-metadata and upload it to the
Marketplace with stratus-upload-metadata or via the web interface.

See the previous section for information about what these commands do.

After all of the modifications have been made, log out of the machine.
Use the command ``stratus-shutdown-instance`` to stop the machine.
If you use stratus-kill-instance the changes you’ve made will be
lost.

Sometimes a suitable starting image cannot be found and building an
image from scratch is required. Usually it is easiest to build new
images with desktop virtualization solutions. The results must be
converted to a format suitable for KVM.

Generating an image from scratch can be tedious and there are lots of
pitfalls along the way. Keep in mind the following points:

Contextualization allows a virtual machine instance to learn about its
cloud environment (the ‘context’) and to configure itself to run
correctly there. StratusLab now supports CloudInit contextualization in
addition to the OpenNebula and HEPiX contextualization schemes.

The CloudInit
mechanism is gaining traction within the cloud ecosystem and is moving
towards becoming a de facto standard for the process. Because it handles
both web-server and disk based contextualization mechanisms it is fairly
straightforward for cloud software developers to implement.

For the appliance developers it provides a convenient modular framework
for allowing both system and user-level service configuration. Being
written in python with OS packages for most systems, makes it easy for
those developers to include and use the software.

Ubuntu provides good
documentation for
CloudInit. The software itself can be downloaded from
launchpad or installed from
standard repositories for your operating system (e.g.
EPEL for CentOS).

All of the latest versions of the base virtual machine images maintained
by StratusLab now support CloudInit. Using one of those images is the
easiest way to see how CloudInit works. However, you can build your own
image with CloudInit support; see the appendix of this document for
instructions.

To show how users can pass CloudInit information to the appliance, we
will work through an example with the latest CentOS base image. We will
use a script to install and configure a web server on the example
machine. This script is generated by the user, sent via the
stratus-run-instance command and then executed in the machine
instance by the CloudInit contextualization.

The script that we want to execute on the machine instance is the
following:

and then pass this to the stratus-run-instance command with the
--context-file option:

$ stratus-run-instance --context-file cloud-init.txt

The first option is generally the most convenient option unless further
(non-cloud-init) options need to be passed to the virtual machine.

The context can contain multiple public ssh keys and multiple scripts or
other files. See the CloudInit
documentation for what
is permitted for ‘user data’.

Warning: No ssh keys are included by default. You must specify
explicitly any keys that you want to include.

Warning: Be sure that the contextualization information you are
passing can be used by the CloudInit version within the appliance
itself. Be particularly careful because multipart inputs do not work
if the python version in the virtual machine is less than 2.7.3.

This is the case with the CentOS image used here, so we’ll include the
script literally in the user data with context information:

ssh,$HOME/.ssh/id_rsa.pub
none,run-http.sh

Note the use of the ‘none’ pseudo-mimetype. If ‘none’ is used, only the
last file marked as ‘none’ will be included in the user data; it will be
included literally, that is without encapsulating it in a multipart
form.

If you use the stratus-prepare-context command, you can see what
key-value pairs are passed to the virtual machine. The
cloud-init.txt will look like:

StratusLab support for CloudInit should make it easier for users to
create appliances that will run on StratusLab as well as on other clouds
using an implementation compatible with CloudInit. This will be an
important gain for users as they move to a federated cloud environment.

This preview support for CloudInit demonstrates the utility of this
contextualization method. The collaboration is interested in hearing
your feedback on the implementation so that we can improve it in
upcoming releases. This will likely become the default contextualization
method in a future release.

The standard StratusLab commands for creating appliances (e.g.
stratus-create-image) can be used to create an appliance using
CloudInit. See the image creation document for details on the commands.

The following script can be fed to stratus-create-image to create an
example appliance with CloudInit support. Note that all of the recent
base images maintained by StratusLab already contain CloudInit support.

The image ID Jd3yRF6x4ofxfCeVK6BmCkuHc0m refers to a standard CentOS 6.2
machine without CloudInit support. The configuration commands and the
package to be installed will depend on what base operating system you
choose.

The image generated with the above procedure will work with the
CloudInit tutorial described above.

If you used VirtualBox to create a VM, you can convert it to a raw
images to run on StratusLab. The easiest way to make your VM compatible
with StratusLab is to convert your vdi disk into raw disk. This can be
done with standard VirtualBox tools with the following command:

Application developers often desire to have programmatic access to cloud
services. This allows them to easily integrate those services into
existing applications and analysis frameworks.

StratusLab provides several mechanisms by which application developers
can access its services. All services provide REST interfaces, making
them easily accessible from all languages via standard HTTP(S) client
libraries. The collaboration also provides the python APIs that are used
internally by the command line interface and a Libcloud plug-in.

Services with a resource-oriented architecture expose a set of resources
or objects via well defined URLs, standard CRUD (create, read, update,
and delete) operations are then supported for those resources. Although
not required, nearly all such services use the HTTP(S) protocol and
reuse the standard HTTP actions for implementing the CRUD functionality.

Using the standard HTTP protocol and having a well defined hierarchy of
URLs representing resources, makes access easy from any programming
language with a HTTP client library. Because of this universal
accessibility and the intuitive mapping between resources and URLs,
StratusLab using a resource-oriented architecture for all of its
services.

However, because of significant underlying changes in the StratusLab
service implementations at this time, it is recommended that application
developers either use the Libcloud API or script the command line
interface. This will protect them from the significant, incompatible
changes in the APIs that are currently taking place.

As mentioned above, the REST APIs and the corresponding StratusLab
python API are undergoing significant changes at the moment. Application
developers should avoid these interfaces if possible. Contact the
StratusLab support for more information about the current status.

The CIMI API, a standard REST API for IaaS clouds, will become the
standard interface for all of the StratusLab services. Application
developers planning to port their software to the StratusLab cloud
should target this API. This API should appear over the next couple of
StratusLab releases (i.e. 3-6 months).

The driver is intended to be installed with pip. You should be able to
simply do the following:

pip install stratuslab-libcloud-drivers

which will install the StratusLab Libcloud driver, Libcloud itself
(0.12.1), and the StratusLab client. If you want to use the
deploy_node() function, you’ll also need to install paramiko, a
python SSH library, as well.

pip install paramiko

If pip is configured to do system-wide installations, then the
PYTHONPATH and PATH should already be set correctly. If it is setup for
user area installations, you will likely need to set these variables by
hand.

You can download the package directly from
PyPi. The name of the package is
“stratuslab-libcloud-drivers”. You will also need to download and
install all of the dependencies. Using pip is very strongly
recommended.

The Libcloud drivers for StratusLab use the same configuration file as
for the command line client.

To copy a reference configuration file into place, use the command
stratus-copy-config to copy an example configuration file into
place. The command will print the location of your configuration file.
The example configuration file contains extensive documentation on the
parameters. Edit the file and put in your credentials and cloud
endpoints.

This registers the driver with the Libcloud library. This import must be
done before asking Libcloud to use the driver! Once this is done,
then the driver can be used like any other Libcloud driver.

# Obtain an instance of the StratusLab driver.fromlibcloud.compute.typesimportProviderfromlibcloud.compute.providersimportget_driverStratusLabDriver=get_driver('stratuslab')driver=StratusLabDriver('default')# Use the Libcloud methods to find, create and control nodes.nodes=driver.list_nodes()

There are a couple examples in the test area of the GitHub repository
for this driver
lc-sl-examples.
You can also find general information on the Apache Libcloud website.

The StratusLab command line client and other tools are written Python
and are packaged to take advantage of the Python installation tools.

An environment with an acceptable version of Python must be used. In
addition, it is strongly recommended that pip and virtualenv be
used to manage the installation and configuration of the StratusLab
tools.

Python packages are a standard part of all Linux distributions and can
be installed via the distribution’s standard package management tools.

Once installing Python verify that a version compatible with StratusLab
has been installed:

$ python --version
Python 2.6.6

If the version is not a recent Python 2 version (2.6+), then you must
install a separate version that is compatible with StratusLab and modify
your environment. You will find the virtualenv section below useful
in this case.

Python is not a standard part of the Windows distributions.
Consequently, you must install and configure Python yourself. You can
find installation packages on the python.org
website. Be sure to select an installer for Python 2 and not Python
3.

Pip is a tool for installing and managing Python packages. It allows
packages to be installed, listed, queried, upgraded, and uninstalled. It
uses information in the downloaded packages to automatically resolve
dependencies.

If pip is not already installed on your system, then you can find out
how to download and install it on the pip-installer.org
website. This website also
contains information on how to use it.

StratusLab strongly recommends using pip to manage the installation
of the its Python-based tools. The easy_install command can also be
used, but pip provides better management capabilities.

The virtualenv package allows users to create customized virtual Python
environments. This avoids having to modify the global system
environment, permits use of different Python versions, and avoids
potential dependency conflicts between installed packages.

An SSH client, usually OpenSSH, comes as a
standard part of all Linux operating systems. It is normally installed
by default, but can be installed via the distribution’s package
management system if necessary.

To use the client to connect to virtual machine instances, the user must
have an SSH key pair consisting of a “public” key and a “private” key.
These keys are usually located in the ~/.ssh/ directory and have
names like id_rsa (private) and id_rsa.pub (public).

You can generate them with the following command

$ ssh-keygen

The default values are appropriate in most cases, but you should provide
a passphrase and not leave it empty.

Verify the generated key pair permissions. The id_rsa should have
permissions 0600 (read/write access for owner only) and the
id_rsa.pub should have permissions 0644 (read access for all; write
access for owner).

Be sure to remember the passphrase that you have used! This
passphrase can (and usually is) different from the password for the
user’s account.

SSH agents allow users to provide the passphrase once per session,
caching the passphrase and providing it automatically after the first
request. This makes use of SSH more convenient when multiple connections
are being made to a virtual machine.

Some operating systems start an SSH agent automatically when a user logs
in. If this is the case, be sure that the agent uses the correct key and
the correct password for that key.

You can check if an SSH agent is running by looking at the
SSH_AGENT_PID variable.

$ printenv SSH_AGENT_PID

If this isn’t empty, then the agent is running. You can add your key to
the agent with the command:

$ ssh-add

Providing the passphrases for your keys when prompted for them. See the
manpages for ssh-agent and ssh-add for more information.

Windows does not ship with an SSH client, so you must install one.
Although there are some other solutions (especially for recent versions
of Windows), most people install and use PuTTY. Binaries and
installation instructions can be found on the PuTTY
website.

It is recommended to install the full PuTTY distribution, but at a
minimum the putty and puttygen executables need to be available.

Although Python is the primary programming language used by the
StratusLab client, a small portion uses Java–specifically the portions
related to the creation, validation, and signing of metadata for the
Marketplace.

For these features, an installation of a certified Java 1.7 or later
distribution is required.

In recent versions of Windows, there are two command line interfaces:
the traditional “cmd” shell and the newer “PowerShell”.

If available, PowerShell is recommended. It can be started directly from
the graphical interface or indirectly from the “cmd” shell by typing the
command powershell.

For security reasons, PowerShell does not allow scripts to be executed
by default. As the StratusLab command line interface consists of Python
scripts, these cannot be executed without changing the default
configuration.

To allow PowerShell to run scripts, execute the following within the
PowerShell:

Set-ExecutionPolicy Unrestricted -Scope CurrentUser

The shell does not need to be restarted. This configuration change only
needs to be done once.

Extended examples of commands and their outputs are displayed in the
monospace Courier font. Within these sections, command lines are
prefixed with a ‘$ ‘ prompt. Lines without this prompt are output from
the previous command. For example,

The guide starts with this introduction and then is followed by an
installation tutorial showing all of the steps to install a minimal,
two-machine StratusLab cloud infrastructure. The subsequent chapter
provide more detail on various aspects of the software.

The older terminology, still used in most parts of this (and other)
documents is the following:

Frontend: A physical machine that runs the services for virtual
machine management and storage services. This is the machine which is
contacted by the cloud users for managing their cloud resources.

Node: A physical machine that hosts virtual machines.

The newer terminology that has been adopted is:

Cloud Entry Point: One or more physical machines that run the CIMI
service. Users use this management interface to acquire, control, and
release all of their cloud resources.

VM Host: One or more physical machines that host virtual machines.

Storage Controller: One or more physical machines that act as a
gateway to a storage services.

Couchbase Node: A physical machine that hosts a Couchbase instance
running as part of a Couchbase cluster. This may be combined with
either the Cloud Entry Points or the VM Hosts to minimize the number
of physical machines used for the supporting services of the cloud.

The software and documentation is being gradually updated to
consistently use this newer terminology.

This tutorial demonstrates how to install manually a StratusLab cloud
infrastructure using the StratusLab system administrator command line
utilities. A minimal StratusLab cloud consists of two physical machines,
although additional machines may be necessary if the internet cannot be
accessed.

This tutorial demonstrates a minimal installation of a StratusLab cloud
on two physical machines. The physical machines should be relatively
modern machines with the following minimum characteristics:

1 64-bit multicore CPU (>= 4 cores) with VT-x extensions

4 GB of RAM

200 GB local disk space

The hardware virtualization extensions must be enabled in the BIOS on
the “Node” machine. Many vendors ship machines with these extensions
disabled.

In general cloud infrastructures prefer “fat” machines, that is machines
that have a maximum number of CPUs, RAM, and disk space as possible.
This is because the maximum size of a single virtual machine is limited
by the size of the largest physical machine.

The default version of Python installed with CentOS should be correct.
StratusLab requires a version of Python 2 with a version 2.6 or
later. The StratusLab command line tools do not work with Python
3.

StratusLab allows for a variety of storage options behind the persistent
disk service. The tutorial uses the defaults using LVM and iSCSI.

The machines must be configured to use LVM for the disk storage.

The Front End must be configured with two LVM groups: one for the base
operating system (~20 GB) and one for the StratusLab storage service
(remaining space).

The “Node” machine can be configured with a single LVM group.

Below, we assume that the volume group names are “vg.01” for the
operating system and “vg.02” for the StratusLab storage service. You can
use other names, but then change the commands below as necessary.

Ensure that the hostname is properly setup on the Front End and the
Node. The DNS must provide both the forward and reverse naming of the
nodes. This is required for critical services to start.

You can verify this on both the Front End and the Node with the command:

$ hostname -f

Set the hostname if it is not correct.

Throughout this tutorial we use the variables $FRONTEND_HOST
($FRONTEND_IP) and $NODE_HOST ($NODE_IP) for the Front End and Node
hostnames (IP addresses), respectively. Change these to the proper names
for your physical machines when running the commands.

Now ensure that you can log into the Front End from the Front End
without needing a password. Do the following:

$ ssh-copy-id $FRONTEND_HOST
The authenticity of host 'onehost-5.lal.in2p3.fr (134.158.75.5)' can't be established.
RSA key fingerprint is e9:04:03:02:e5:2e:f9:a1:0e:ae:9f:9f:e4:3f:70:dd.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'onehost-5.lal.in2p3.fr,134.158.75.5' (RSA) to the list of known hosts.
root@onehost-5.lal.in2p3.fr's password:
Now try logging into the machine, with "ssh 'onehost-5.lal.in2p3.fr'", and check in:
.ssh/authorized_keys
to make sure we haven't added extra keys that you weren't expecting.

A DHCP server must be configured to assign static IP addresses
corresponding to known MAC addresses for the virtual machines. These IP
addresses must be publicly visible if the cloud instances are to be
accessible from the internet.

If an external DHCP server is not available, the StratusLab installation
command can be used to properly configure a DHCP server on the Front End
for the virtual machines.

A network bridge must be configured on the Node to allow virtual
machines access to the internet. You can do this manually if you want,
but the StratusLab installation scripts are capable of configuring this
automatically.

This tutorial allows the installation scripts to configure the network
bridge.

The Persistent Disk service and the Nodes communicate using a strategy
defined by the persistent_disk_storage and persistent_disk_share
parameters. The default values (“lvm” and “iscsi”, respectively) will be
used for this tutorial.

One needs to specify what device will be used for the physical storage
for the Persistent Disk service:

At this point, you have both the Front End and one Node installed. This
is a functional installation, but you have not yet authorized any users
for the cloud. Here we will create a new StratusLab user account. Note
that StratusLab accounts are independent of the Unix accounts on the
machine itself.

Add the following line to the end of the file
/etc/stratuslab/authn/login-pswd.properties.

This creates a new StratusLab user ‘sluser’ with a password ‘slpass’.
The group ‘cloud-access’ is mandatory for the user to have access to the
cloud services. (Crypted or hashed password values are also allowed in
the configuration.)

The StratusLab distribution supports other authentication methods (LDAP,
X509 certificates, X509 proxies, etc.), but a username/password pair is
the simplest for this tutorial.

You will need to set the “endpoint”, “username”, and “password”
parameters in this file. For the “endpoint” use the hostname or IP
address of your Front End. For the “username” and “password” use
“sluser” and “slpass”, respectively.

Everything should be setup now. So try deploying a virtual machine. You
can look in the Marketplace to find an interesting machine to deploy.
We’ll use a ttylinux image here. This is a micro distribution that boots
very quickly and is ideal for tests.

You’ve successfully installed a minimal StratusLab cloud. You can
checkout the documentation to
see what other configuration parameters are available or try the user
tutorials to discover more of the StratusLab services.

You can get help on the installation or use of StratusLab through the
support mailing list. You can also
report bugs and provide feedback on the same list.

The StratusLab configuration parameters allow for three classes of IP
addresses: public, local, and private. The public IPs are accessible
from the WAN, local IPs are only visible within the cloud
infrastructure itself, and private IPs are only visible on the
physical machine hosting the virtual machine.

Each class you want to configure must have an associated range of free
IP addresses. The number of addresses for each range must be large
enough to cover the number of virtual machines you expect to be
running simultaneously.

At least one class of IP addresses must be configured. This is
usually the “public” class, which the StratusLab client uses by
default.

There must be a DHCP server available that will assign IP addresses to
virtual machines when they start. This DHCP server maintains a
mapping between the MAC addresses (managed by OpenNebula) and the IP
addresses. The DHCP server must be configured to send all of the
standard networking parameters (gateway, broadcast, domain, etc.) to
the DHCP clients.

A StratusLab cloud can work correctly with a single physical network
shared between virtual machines and the physical machines running the
StratusLab services. For a private cloud, this is probably
sufficient.

For clouds with a larger user base, it is better to isolate the
network for the virtual machines from that for the physical machines.
This can either be done with VLANs or by physically segmenting the
network (assuming that you have multiple network interface cards).

For large cloud infrastructures, it is also worthwhile to segment the
traffic to the storage service. This reduces interference between
high-bandwidth data access and the lower-bandwidth for control
messages.

All of the StratusLab services now sit behind a nginx web proxy. This
allows all of the services on a particular machine to share port 443
as well as the server certificate. This also means that port 443 is
the only port that must be open to the WAN.

Nonetheless, it is useful to know what ports and users are used by
the StratusLab services when debugging problems. The following table
summarizes those ports. The name of the init.d script to control
the service is the same as the name in the first column.

StratusLab supports a wide range of different authentication methods and
account storage options, allowing it to fit into a wide range of sites
with pre-existing authentication systems.

All of the configuration files for authentication are located in the
directory /etc/stratuslab/authn. The main configuration file
controlling the active authentication methods and their parameters is
login.conf. Properties files with username/password or certificate
information are also located in this directory.

Users can also be identified via client X509 credentials. Raw X509
certificates, RFC3820 certificate proxies, or VOMS proxies can all be
used to connect to and to authenticate with the StratusLab services.

As above, these credentials can be authorized in:

A java properties file or

An LDAP server

The registration service can also manage the required X509 Distinguished
Names (DNs) if using an LDAP server.

StratusLab provides an optional service, the “Registration Service”,
that allows users to register for an account on your cloud
infrastructure. Through a web-accessible interface, users can register
for an account and update the information associated their accounts.

The registration workflow proceeds through the following stages:

User submits form with required information,

Service sends email validation message to user,

User confirms email address by visiting confirmation link,

Service sends account validation request to administrator,

Administrator accepts or rejects account request, and

An email is sent to the user with the decision.

When users update their email addresses, the new email address is also
validated through an email and confirmation link.

The user information is stored in a separate LDAP server. The
registration service must have full access to that server, so that it
can manage the user entries.

To use the accounts managed by the Registration Service on your cloud
infrastructure, you must configure the authentication service to use the
LDAP server as a source of information. Users who supply a certificate
DN, can also authenticate with the cloud using their certificate.

The architecture of the StratusLab software has evolved to make the
overall system more scalable and more robust. At the center of the
system is a distributed database that removes single points-of-failure
in the system and permits redundant deployments of StratusLab service
components for better reliability.

StratusLab also now exposes the CIMI
interface–a
standard from DMTF that provides a coherent,
unified API for all of the StratusLab cloud resources and that follows
the usual REST patterns. It simplifies programmatic access to the cloud
and provides a good foundation for browser-based access.

The diagram shows a high-level view of the various components in the
StratusLab architecture. The distributed database is at the core of the
system. On the user-facing side are machines that provide the CIMI
interface to the system. On the service side are a set of controllers
for different types of resources (storage, VMs, etc.). Behind the
controllers are the physical resources used by the cloud.

StratusLab Architecture

The distributed database contains the complete state of the cloud.
Consequently, the CIMI interfaces and the various controllers can be
completely stateless, allowing redundant instances to be deployed as
necessary.

As all of the communication between controllers takes place through the
database, specialized controllers can be added to the cloud
infrastructure easily, such as:

Different type of storage (backed up, shared, fast, etc.)

Support for Linux containers as well as virtual machines

Dynamic network configurations

The controllers react to jobs and resources in the database, and update
those entries when completing tasks or making adjustments to resources.

Generally, the configuration of the StratusLab cloud services also
resides within the database. This allows deployment of redundant
services while maintaining a consistent configuration of those services
across machines.

The configuration information within the database is split into a series
of JSON-formatted documents. Each document has an document identifier of
the form ServiceConfiguration/service-instance, where the “service”
corresponds to the name of the service and the “-instance” is optional
and used only if the configuration of an instance differs from the
general service configuration.

Most configuration exists within the database, but there are two notable
exceptions: third-party services and the Couchbase access parameters.

To minimize the StratusLab development effort, third-party services used
by StratusLab are not modified to use the database. Consequently, these
continue to use configuration files on the local file system. One
example are the certificate authorities used for PKI authentication in
the European Grid Infrastructure. When deploying multiple service
instances, these files must be coordinated between physical machines.

The StratusLab services must discover the contact parameters for the
Couchbase database. This information resides in a file on each node
(/etc/stratuslab/couchbase.cfg). If this file doesn’t exist, then
services will use the default bucket and assume that the local machine
is a member of the Couchbase cluster.

This example shows the default values. You can define a different bucket
and location for the database. However, the same database must be shared
by all of the StratusLab cloud services. If changes are made to this
file, then the StratusLab service must be restarted.

The example also shows the possibility of providing instance-specific
configuration documents for services. Generally, these should not be
needed but are available for allow for specialized service
configurations.

Despite the exceptions, having the majority of configuration information
in the database will make configuring and maintaining the services
simpler for system administrators. Generally, it is just a matter of
updating a document in the database to change the behavior of the cloud
infrastructure.

The components of the StratusLab distribution are quite modular and
allow for a variety of different deployment layouts. This chapter
provides some advice when considering the deployment of StratusLab in
your data center.

The chapter concludes with a description of the minimal deployment of
StratusLab on two machines. This deployment serves as a good testbed for
understanding the installation process and how the cloud services work.

When considering your deployment, you must consider who are your
intended users. The level of trust you have in those users will impact
further decisions on the network configuration, service layout, and
authentication methods.

For clouds at the “Infrastructure as a Service” level, like StratusLab,
there are generally three types of cloud deployments: private,
community, and public.

Private cloud deployments target a limited set of known and trusted
users. An example is using a cloud deployment to provide a flexible
infrastructure for an institute’s services. These types of clouds are
often run by and used by the same system administrators. Because of the
high-level of trust in the users, less needs to be done to isolate cloud
services from the cloud’s virtual machines.

On the other end of the spectrum are public cloud infrastructures. These
target external and possibly unknown users outside of the institute’s
administrative domain. These generally require a higher level of
isolation of service and more fine-grained network segmentation.

Between the two are “community” clouds. These function like public
clouds but have a more limited set of users. A cloud infrastructure
destined for scientists at a number of collaborating institutes is a
good example of a community cloud infrastructure.

StratusLab puts very few constraints on the network configuration
supporting the cloud infrastructure. At its simplest, it can work on a
single network tying together all cloud services and resources. It can
also be made to work on complicated network configurations with multiple
VLANs, protocols, etc.

The only network constraints for StratusLab are:

Range of addresses to allocate to virtual machines,

DCHP server configured to serve those addresses, and

DNS configured with reverse-DNS lookups for those addresses.

The range of addresses must be IPv4 addresses, but each address can also
have an IPv6 address associated with it.

There are three different types of network traffic on a StratusLab cloud
infrastructure:

Control messages between the cloud services (and through the
Couchbase database),

The level of isolation between these different types of traffic depends
on your type of cloud deployment and your desire for a secure
infrastructure.

For a private cloud infrastructure, mixing these three types of traffic
on the same network doesn’t pose any particular problem and is the
easiest to configure.

However, for a public cloud infrastructure it is a good idea to separate
the three types of traffic on separate VLANs. Even better, physical
segregation of the virtual machine traffic from the other traffic
prevents any possible compromise of the cloud services from the running
virtual machines. This is obviously more complicated to configure. You
must weight the additional complexity against the potential threats from
your users.

There are three classes of services that need to be mapped to physical
machines: Couchbase instances, CIMI interfaces, and resource
controllers.

The usual mapping for Couchbase instances and CIMI interfaces is to
deploy these on the same physical machine. For scalability and
redundancy, two or more such physical machines are deployed.

Resource controllers are generally deployed on the same physical nodes
that provide the underlying resources. For example, the VM controller is
deployed directly on the machine(s) running the hypervisors. This
arrangement minimizes the number of physical machines that need to be
deployed.

You can alter the mapping as necessary to adapt the needs of your data
center. For example, you may have resources (like a storage appliance)
that require having the controller hosted on a different machine than
the resource it is controlling.

The examples in this guide use a minimal deployment of two physical
machines. One machine (the “cloud entry point”) contains the Couchbase
database and the CIMI interface. The other contains all of the resources
controllers and resources used for the cloud. A single network for all
traffic types is assumed for simplicity in this minimal deployment. The
following diagram summarizes this deployment.

This tutorial demonstrates a minimal installation of a StratusLab cloud
on two physical machines. The physical machines should be relatively
modern machines with the following minimum characteristics:

1 64-bit multicore CPU (>= 4 cores) with VT-x extensions

4 GB of RAM

200 GB local disk space

The hardware virtualization extensions must be enabled in the BIOS on
the “Node” machine. Many vendors ship machines with these extensions
disabled.

In general cloud infrastructures prefer “fat” machines, that is machines
that have a maximum number of CPUs, RAM, and disk space as possible.
This is because the maximum size of a single virtual machine is limited
by the size of the largest physical machine.

The default version of Python installed with CentOS should be correct.
StratusLab requires a version of Python 2 with a version 2.6 or
later. The StratusLab command line tools do not work with Python
3.

StratusLab allows for a variety of storage options behind the persistent
disk service. The tutorial uses the defaults using LVM and iSCSI.

The machines must be configured to use LVM for the disk storage.

The Front End must be configured with two LVM groups: one for the base
operating system (~20 GB) and one for the StratusLab storage service
(remaining space).

The “Node” machine can be configured with a single LVM group.

Below, we assume that the volume group names are “vg.01” for the
operating system and “vg.02” for the StratusLab storage service. You can
use other names, but then change the commands below as necessary.

Ensure that the hostname is properly setup on the Front End and the
Node. The DNS must provide both the forward and reverse naming of the
nodes. This is required for critical services to start.

You can verify this on both the Front End and the Node with the command:

$ hostname -f

Set the hostname if it is not correct.

Throughout this tutorial we use the variables $FRONTEND_HOST
($FRONTEND_IP) and $NODE_HOST ($NODE_IP) for the Front End and Node
hostnames (IP addresses), respectively. Change these to the proper names
for your physical machines when running the commands.

Now ensure that you can log into the Front End from the Front End
without needing a password. Do the following:

$ ssh-copy-id $FRONTEND_HOST
The authenticity of host 'onehost-5.lal.in2p3.fr (134.158.75.5)' can't be established.
RSA key fingerprint is e9:04:03:02:e5:2e:f9:a1:0e:ae:9f:9f:e4:3f:70:dd.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'onehost-5.lal.in2p3.fr,134.158.75.5' (RSA) to the list of known hosts.
root@onehost-5.lal.in2p3.fr's password:
Now try logging into the machine, with "ssh 'onehost-5.lal.in2p3.fr'", and check in:
.ssh/authorized_keys
to make sure we haven't added extra keys that you weren't expecting.

A DHCP server must be configured to assign static IP addresses
corresponding to known MAC addresses for the virtual machines. These IP
addresses must be publicly visible if the cloud instances are to be
accessible from the internet.

If an external DHCP server is not available, the StratusLab installation
command can be used to properly configure a DHCP server on the Front End
for the virtual machines.

A network bridge must be configured on the Node to allow virtual
machines access to the internet. You can do this manually if you want,
but the StratusLab installation scripts are capable of configuring this
automatically.

This tutorial allows the installation scripts to configure the network
bridge.

The StratusLab architecture uses a distributed database at the core to
hold the full state of the cloud. This simplifies all of the other
components of the system by allowing them to stateless and by acting as
a means for coordinating the components of the system.

StratusLab uses Couchbase for this
distributed database. It was chosen because of its ability to store
and to index JSON-formatted documents efficiency, closely matching the
needs of managing cloud resources through the CIMI data model. It is
easy to deploy for small database, while retaining the ability to
scale to very large systems.

Because all other StratusLab components rely on having access to the
Couchbase database, it is the first component that must be installed.

Couchbase is available as a standard RPM package from the Couchbase
website. The company distributes two versions of the database:

The community version is open source and released under the
Apache 2 license (the same as for StratusLab). StratusLab uses this
version for all of its own deployments and tests. For convenience,
the RPM package for Couchbase is included in the StratusLab yum
repository.

The enterprise version requires the purchase of a commercial
license for anything other than small test deployments. The
commercial support may be interesting for mission-critical cloud
infrastructures. StratusLab should work with the enterprise version,
but does not require it. The enterprise version is not
systematically tested by the StratusLab collaboration.

init.d script

couchbase-server

language

erlang

APIs

Java, Python, and C

log file(s)

/opt/couchbase/var/lib/couchbase/logs/*

initial password

/opt/couchbase/cluster-password.txt

8091

web administration port

8092

Couchbase API port

11209*, 11210

internal cluster ports

4369*

Erlang Port Mapper

21100-21199*

Node data exchange

Table: Couchbase Server Characteristics

All of the listed ports must be open to communication between the nodes
participating in the Couchbase cluster. All ports except those with an
asterisk must be open to cloud services accessing the database.

Couchbase is written in Erlang, but StratusLab uses the Java and Python
APIs to access the database. The Python API depends on the C API, so it
must also be installed.

The usual service mapping puts the Couchbase instances on the “cloud
entry point” nodes, along with the CIMI interface. The instances on
these nodes form the Couchbase cluster for the full StratusLab cloud.
The minimal deployment has only one “cloud entry point” node and hence
only one Couchbase instance.

Production StratusLab deployments should have more than one Couchbase
instance in the Couchbase cluster for reliability and redundancy.
Although the default location for these instances is on the “cloud entry
point” nodes, you can deploy them on dedicated nodes or other cloud
services nodes, if needed.

The installation of Couchbase consists of installing the RPM package and
then initializing a Couchbase cluster. The StratusLab installation
commands automate the process.

Log into the node that will function as the “cloud entry point” node for
your cloud infrastructure as “root”. Verify that all of the
prerequisites detailed in the previous chapter are satisfied.

Install the StratusLab system administrator command line interface
(CLI). This installs the commands that simplify and automate the
installation of all of the StratusLab components. Assuming that you have
already configured the machine for using the StratusLab yum repository
(see “Prerequisites”), this should be as simple as:

$ yum install -y stratuslab-cli-sysadmin

Once this completes, you should have a set of StratusLab commands in
your path. All of the StratusLab commands start with the prefix
stratus-. You may want to look at the help for the
stratus-install command:

This is the command that we will use to automate the installation of the
cloud services.

We will now use this command to install and initialize the Couchbase
database on the machine. Do the following:

$ stratus-install --couchbase
...
Starting couchbase-server [OK]

You can get more detailed output if you add the -vvv option. This
command installs the necessary packages and then sets up the
database. The last line should indicate that Couchbase has been
started; if successful you will see an “OK” indication.

Note

The installation creates an administrator account for the database
called ‘admin’. The randomly generated password for this account is
available in /opt/couchbase/cluster-password.txt.

The easiest way to verify that Couchbase has been correctly installed
is to use the Couchbase web interface. This interface is available on
port 8091, but by default, is only accessible locally on the
machine. To view it remotely you will need to tunnel to the machine:

$ ssh -L2000:cep.example.org:8091 -N root@cep.example.org

in a separate terminal window. You can then connect to the interface
on the “http://localhost:2000/” URL. You must use the “admin”
account with the generated password to log in.

If everything has been installed correctly, you should see a display
similar to the screenshot below.

The CIMI service is the only StratusLab service accessible by users on a
cloud infrastructure. All interactions between the user and the
underlying resources occur through this service. This service also
handles all of the user authentication for the cloud, passing verified
authentication information to the underlying services.

The service is written in clojure and uses
the Ring and Compojure frameworks for
implementing the web service. The
Friend framework is used for
authentication.

The characteristics of the service are summarized in the following
table.

As for all of the StratusLab services, the installation consists of the
installation of an RPM package followed by configuration of the service.
This process is automated via the stratus-install command.

Warning

The CIMI service depends on the Couchbase database. You must
install and configure Couchbase before tying to install the CIMI
service.

Logged in as “root” on the “cloud entry point” machine, execute the
following command to install the CIMI service:

$ stratus-install --cimi

This should complete without error and start the cimi service. You can
check that it is running with the command:

The CIMI service runs behind an nginx proxy. The installation of
nginx and the necessary configuration will all be done automatically
by the StratusLab RPM packages.

The default installation will generate a self-signed certificate for
the service. If you want to use a certificate signed by an accredited
certificate authority, you must install it in the
/etc/stratuslab/nginx-proxy/ directory. The certificate and key
must be in the cert.pem and cert.key files, respectively.

The details for configuring the authentication for the service are
explained in the next chapter. For now, it is enough to know that an
administrator account is created the first time the service starts. The
username is “admin”; the randomly-generated password is available in the
service log /var/log/stratuslab/cimi/cimi.log.

The “CloudEntryPoint” resource as well as a few others are visible to
anyone, even those without an account on the cloud. We can verify that
the service is working correctly by retrieving the CloudEntryPoint.

To do this via the command line, just use curl on the base URL of
the service:

This resource (in JSON format) contains the list of all of the cloud
resource collecitons supported by this cloud infrastructure, along with
relative URLs (in the “href” field) for those resource collections. It
also contains metadata concerning the cloud infrastructure itself.

Note

The first access to the server takes some time to respond because
the server is dynamically compiling the source clojure files and
initializing the database. Subsequent accesses to the service
should be much faster.

There is also a rudimentary web browser interface provided by the
service. Point a browser at the URL
http://cloud.example.org/cimi/webui, replacing the hostname with your
own. You should see an HTML representation of the CloudEntryPoint as
in the following screenshot.

You will be using the administrator account to update the service
configuration. To verify that it works, first recover the
administrator’s account password from the service log. You should find a
message in the log like the following:

...User/adminentrycreated;initialpasswordis6GfRtIeWVygK

The username of this initial account is always “admin”; the “6G...”
value is the generated password. Use the value from your log file.

To login as the administrator from the web interface, click on the
“login” link in the upper right corner, fill in the username and
password on the form, and then click the “login” button. If the login
was successful, then you should be redirected back to the
CloudEntryPoint, but you will see your login information on the right
side of the header.

Logged in User Information

Note

You can always see your full authentication information by visiting
the URL https://cloud.example.org/cimi/authn. The most important
fields are the “identity” field (giving your username) and the
“roles” field (giving your authorizations).

Full Authentication Information

If you can see pages similar to the screenshots, the administrator of
the CIMI is correctly configured. However, you will likely want to
change the password of the administrator account. Now that you are
logged into the server, you can do this.

Return to the CloudEntryPoint using the web browser interface (i.e. the
URL ending with “webui”). From there, click on “User”. This brings up
the list of user records; only the “admin” account should be listed.
Then click on “admin” to view the user record. You should see a page
listing characteristics of the “admin” account, notably there will be a
field “password” containing the bcrypt hash of the current administrator
password.

You should see three buttons on the right of the page: “view json”,
“edit”, and “delete”. You will want to click on the “edit” button which
will bring up a JSON editor with the current contents of the “admin”
user.

However, before doing this, you want to generate the bcrypt hash for a
new (memorable) password. This can be done with python using the
following command:

You may have to install the package “py-bcrypt” on CentOS for this to
work. It returns the hash of your password. Change the ‘hello’ in the
example to the password you want to use.

Now that you have a new password, click on the “edit” button, change the
value of the password field to the hash value you’ve generated and click
on the “save” button. You should be redirected back to the same page,
but the password field will have been updated.

You can now logout via the “logout” link and log back into the service
(with your new password!) using the same procedure as before.

As a further example of how to use the web interface (which you will use
to handle service configuration), you can create “ServiceMessage”
resources on the server.

The ServiceMessage resources are visible to anyone but can only be
created by the administrator. These messages are intended to provide
general service information to users, like the MOTD (message of the day)
text on many operating systems.

From the CloudEntryPoint, click on the “ServiceMessage” link. This
should bring up an empty list of ServiceMessage resources. Click on the
“add” button, which will bring up the same JSON editor you saw
previously.

and then click on the “save” button. You should then see a summary panel
of the message along with metadata that was added to the entry. You can
view JSON for the entry with the “view json” button, update it with the
“edit” button, or delete it with the “delete” button.

If you go back to the ServiceMessageCollection, you will see the entry
in the list.

For ServiceMessage resources the “name” field is treated like a title
and the “description” gives the full message.

As mentioned in the previous chapter, the CIMI server also handles all
of the user authentication for the cloud. The server supports the use of
internal or external databases of users.

The internal database, with user records stored in Couchbase, is
convenient because all information is contained within the cloud
infrastructure and user records can be managed in the same way as other
configuration files.

Using an external database, such as LDAP, allows the user information to
be exported to other system or allows better integration of the cloud
with other services in the data center. In the case of VOMS proxies,
this also delegates some authority to third parties to manage the users
associated with a particular Virtual Organization.

There are two aspects to the authentication configuration for a
StratusLab cloud: defining the methods to be used and managing the
users.

To define the authentication mechanisms for the cloud infrastructure,
you must create the document “ServiceConfiguration/authn” in the
Couchbase database. You can use the same web interface shown earlier to
browse to the “ServiceConfiguration” collection and then to add the new
document.

where the “service” and “localdb” fields are required (and the value for
the “service” field must be “authn”!). The fields “ldap” and “voms” are
optional. The details of the “ldap” map are given below.

If the configuration document does not exist, then the default is to
only use the local user database with password credentials. It is
recommended to always keep this method active along with at least one
administrative account defined in the database.

NOTE: Enabling or disabling authentication methods requires that
the CIMI service be restarted.

Adding or removing users from the system, requires changes to the local
or external user databases. The details on this are given in the
following sections.

NOTE: Adding, removing, or modifying users does not require
restarting the CIMI service. These changes will be taken into
account immediately for all future authentication actions.

You can also define “roles” for the users to either indicate group
membership or rights to perform particular actions. There are three
special roles ”::ADMIN”, ”::USER”, and ”::ANON”. The first confers
administrative rights to the user; users with this role will have
complete control over the cloud configuration. The ”::USER” role is
given to anyone who has been authenticated. The ”::ANON” role is used
for users that have not been authenticated.

You can manage users directly in the Couchbase database via the CIMI
interface. There is a “User” collection and you can add, modify, and
remove entries from the system with the same web browser interface
you’ve used for the other resources.

The schema for user records is:

{"last-name":"required","first-name":"required","username":"required, must be unique","password":"optional, value is bcrypt hash","enabled":true,"roles":["list","of","roles"],"altnames":{"x500dn":"DN of user in RFC2253 format"}}

If the “enabled” field is not supplied, the default value is “false”.
The “password” is used only for password authentication; similarly, the
“x500dn” field is only used for certificate authentication.

The schema is a “loose” one, meaning that other fields may be added if
you want to track additional information. One example would be an
“email” field.

To use password authentication, the “localdb/password-enabled” flag must
be true in the “ServiceConfiguration/authn” document. The user record
for the given username must exist, must be enabled, and must have a
password set.

The value of the password field is the bcrypt hash of the clear text
password. See the preceeding text for generating the bcrypt hash.

To use certificate authentication, the “localdb/cert-enabled” flag must
be true. The field “x500dn” must exist and have the RFC2253-formatted DN
of the user’s certificate. The user can use the raw certificate or a
proxy generated from that certificate. The user will be identified with
the value of the “username” field in the user record.

For certificate authentication to work, the SSL configuration for the
Jetty server must be done. By default, the configuration for trusting
the EGI Certificate Authorities is done by the stratus-install
command. If you want to trust different Certificate Authorities, you
must adjust the SSL configuration. See the previous chapter for what
needs to be done.

To authenticate users against an LDAP database, you must have deployed
and populated an LDAP server. The authentication configuration for using
LDAP is quite flexible, so nearly any standard layout for the
information should work.

The “ldap” field in the “ServiceConfiguration/authn” document must
follow the schema:

All of the fields are required. The “connection” values provide the
location of the server. The “user-” fields indicate what objects in the
LDAP database are user records and the “role-” fields indicate the
groups that are mapped to roles.

The “skip-bind?” field indicates whether to try to bind to the database
with the given user password to authenticate the user. Normally, for
password authentication this should be false and the LDAP server should
be setup to allow only the user to view her user record.

VOMS proxies are a mechanism by which users can delegate some rights to
a third party such as a service. These proxies also convey certain
rights associated with a user who belongs to a Virtual Organization. The
Virtual Organization itself manages its membership, defines the rights,
and allocates those rights to members.

By default, the SSL configuration of the server will be setup to allow
validation of VOMS proxies according to the policies of the European
Grid Infrastructure. You must use this configuration (or a similar one
if you are an expert) to use VOMS proxy authentication.

To enable this, set the “voms/enabled” flag to true in the
authentication configuration. You must then add a pseudo-user entry in
the local database for each Virtual Organization you want to support.

An example pseudo-user entry for the “vo.lal.in2p3.fr” Virtual
Organization is:

It is important that the username contain the “vo:” prefix to the name
of the Virtual Organization that is being authorized. The entry should
not have a password associated with it.

The “username” associated with users identified via VOMS proxies is the
DN of their certificate. The FQANs (fully-qualified attribute names) of
the VOMS certificate are mapped to roles in the StratusLab
authentication.

The authentication framework used by StratusLab is extensible allowing
different mechanisms to be incorporated fairly easily. Candidates for
additional mechansims to support in the future include OAUTH2 and
Shibboleth. Feedback on the desire for these (or other) mechanisms is
welcome.

Some modifications are needed for the persistent disk server and the VM
hosts.

Linux kernel 3.x

Ceph package

Ceph configuration in /etc/ceph/ceph.conf

Manager keyring in /etc/ceph/ceph.client.${identity}.keyring

Parameters in pdisk-backend.cfg and pdisk-host.conf

For testing, you can use a package provided by ELrepo
repository which provides a
3.x kernel for CentOS v6.4.

Currently, using a proxy server is not very useful for this backend
because the persistent disk server needs a 3.x kernel and the Ceph
package to attach pdisks to itself when importing a remote appliance
(cf. DiskUtils.copyUrlToVolume).

There is not automatic configuration via the StratusLab installer yet.
This is being worked on.

The oneadmin user must also be able to execute Ceph commands as
root. Update the /etc/sudoers file appropriately:

This section collects a number of frequently asked questions
concerning the administration of a StratusLab cloud infrastructure.
If there are other questions that you would like to see treated here,
please contact StratusLab support.

After the power outage the nodes hosting the virtual machines must be
restarted. If this has not happened automatically, ensure that all of
the nodes have rebooted.

Connect to each of the nodes to ensure that all of the iSCSI mounts
are present.

# iscsiadm -m session

If the links are not correctly mounted (bad links will blink in the
list), then the easiest way to recover this is simply to reboot the
machine again.

Once you have verified all of the iSCSI links on all of the nodes,
then you must log into the frontend machine as oneadmin. As this
user, you can then force OpenNebula to restart all of the machines in
the unknown state.

The commands for this (assuming that you’re logged into the frontend
as root), are:

After this, all of the VMs should return to the running state and
again be accessible from the network. Any machines that don’t restart
are probably lost and will have to be killed and a new instance
created.

By default, libvirt and KVM provide a generic CPU processor to virtual
machines. For computing intensive applications, access to more
advanced CPU capabilities (CPU “flags”) can make an enormous
difference in the efficiency of a calculation. Consequently, the
generic CPU profile provided by libvirt and KVM is inadequate for
these applications.

Most modern processors have the advanced CPU capabilities that
numerical applications need. The only problem is how to get libvirt
and KVM to expose these capabilities to the hosted virtual machines?

Unfortunately, libvirt does not provide a mechanism for passing
arbitrary options to the underlying hypervisor. However, the call to
the hypervisor can be wrapped to provide the additional options.

Create a wrapper script for the call to qemu that will add the
-cpu option:

#!/bin/bash
/usr/libexec/qemu-kvm -cpu host $@

This additional option will allow the host CPU specification to be
passed directly to virtual machines, allowing all of the advanced
capabilities of the host processor to be used.

Warning

The wrapper script must be installed on all of the nodes of the
StratusLab cloud infrastructure. This script is named
/var/lib/one/bin/qemu-start.sh below; change this value as
necessary.

Once the wrapper script is installed, then the OpenNebula
configuration must be changed to force this script to be used to start
virtual machines. Modify the configuration files
/etc/one/vmm_exec/vmm_exec_kvm*.conf setting the value of the
EMULATOR parameters:

EMULATOR = /var/lib/one/bin/qemu-start.sh

Change the value to match the wrapper script that you have created.
Once this is done, restart OpenNebula. Execute:

$ service oned restart

on the frontend node of your StratusLab cloud infrastructure.

Once this is done, any new virtual machines will use the wrapper
script and will have the full CPU capabilities of the host
processor. You can verify the CPU capabilities from the virtual
machine with the command:

Occasionally when debugging problems with virtual machines it is
useful to use virt-manager via X11 to bring up the machine console.
The default configuration unfortunately makes the keyboard mapping
completely useless. To fix this, you must use the -k option when
starting virtual machines with QEMU.

To do this, follow the same procedure as for exposing the CPU flags
above and add the -k en-us option to the qemu command line. This
will cause the keyboard mapping to always be a US English. You may
use other language values, although the US English is the safest
default.

This guide provides information for people who contribute to the
development and documentation of the StratusLab cloud distribution. It
describes how to become a member of the StratusLab development
community and provides information about languages and coding
standards.

This guide provides information for people who contribute to the
development and documentation of the StratusLab cloud distribution. It
describes how to become a member of the StratusLab development community
and provides guidelines on contributions.

Those wanting to use a StratusLab cloud infrastructure should consult
the StratusLab User’s Guide.

System administrators wanting to install a StratusLab cloud on their own
resources should start with the StratusLab Administrator’s Guide.

Extended examples of commands and their outputs are displayed in the
monospace Courier font. Within these sections, command lines are
prefixed with a ‘$ ‘ prompt. Lines without this prompt are output from
the previous command. For example,

The StratusLab Collaboration aims to provide a complete, open-source
cloud distribution that allows resource centers to deploy their own
public or private “Infrastructure as a Service” (IaaS) cloud
infrastructure.

The collaboration’s motto is “Darn Simple Cloud”. We aim to provide a
cloud solution that is both simple to install and simple to use. Where
possible, we build on existing software and technologies to minimize and
to simplify our own code base.

At the same time, we strongly believe in providing high quality, well
tested code; we use agile software development processes and tools to
achieve this.

StratusLab started as an informal, academic collaboration between
several partners involved in the EGEE series of grid projects in 2008.
The initial aim of this collaboration was to investigate if the new
cloud technologies (primarily Amazon Web Services) could be used as a
platform for running grid services. The collaboration concluded that is
was indeed possible and further, was convinced that cloud technologies
would be an important platform for scientific computing.

The collaboration subsequently grew into a more formal collaboration
that proposed a European-level project to build an open-source cloud
distribution suitable for running grid services. This proposal was
accepted and StratusLab, as a project co-funded by the European
Commission, ran from June 2010 to May 2012. During this period, the
foundations of the current StratusLab cloud distribution were built.

The StratusLab collaboration continues to maintain and to develop
further this cloud distribution as an open collaboration of institutes
and individuals. The four principal institutes currently participating
are CNRS (France), SixSq (Switzerland), GRNET (Greece), and Trinity
College Dublin (Ireland).

The collaboration welcomes new collaborators, both institutions and
individuals. All it takes is a willingness to participate constructively
in the collaboration and to provide contributions consistent with the
licenses used by the collaboration. Contact us at contact@stratuslab.eu
to become a member.

The collaboration coordinates its activities primarily through a common
mailing list: stratuslab-devel@googlegroups.com. Developers are expected
to solicit feedback and to announce significant changes on that list.
There is also a weekly teleconference on Thursdays at 11:30 (Paris) to
allow more interactive discussion of progress and problems.

Apache 2 is the primary code license of the collaboration. Although,
exceptions can be made for specific cases (e.g. plugins to libraries
under a different license), all core software must be under the Apache 2
license to ensure that it can be legally integrated into a common
distribution and to ensure the widest possible reuse of the software.

High-level documentation (e.g. User’s Guide) is released under the
Creative Commons Attribution license to ensure its widest possible
distribution. Documentation integrated with the code (e.g. README) are
released under the same license as the code itself.

All non-trivial source code files, must have a comment block at the
beginning of the file declaring the license for the code. This block
must also contain the copyright statement for the file. The copyright is
held by the original author (or author’s institute) and must also appear
in this initial comment block.

To maximize the number of people who can contribute to the maintenance
and development of the StratusLab software, the collaboration attempts
to minimize the number of development languages used within the project.

On the server side, the collaboration prefers the use of Clojure (on the
JVM) and Java. Historically, all of the services developed by the
project have been written in Java; more recently this has been shifting
towards Clojure.

On the client side, Python is the preferred language. The StratusLab
client is nearly entirely written in Python and many of the utility
scripts (e.g. binding to Libvirt) are migrating from shell to Python.

Exceptions are made for specific cases. For example, server startup
scripts are written in bourne shell. If in doubt, ask for feedback via
the developers’ mailing list.

All of the code for the collaboration resides in
GitHub under the “StratusLab” organization.
Generally, each major service resides in its own repository.

All developers have write access to all repositories. This allows
everyone to contribute to any of the services and to correct bugs as
they are found. Nonetheless, major changes in a repository should be
discussed on the developers’ mailing list and with the primary developer
of the service.

The collaboration has chosen to use Maven as its build system.
Consequently, all of the code is built using the standard Maven
workflows. The collaboration maintains a common top-level pom.xml
file to manage plug-ins and dependencies. New dependencies should be
discussed on the developers’ mailing list and then added to the
top-level pom.

Significant changes to the code and specific bug fixes should be tracked
via GitHub issues. These issues should also be tied to milestones so
that release announcements can be prepared. Reference the Issue ID
number in the commit message, so that GitHub will automatically
cross-reference the commit to the issue.

Where possible, static analysis of the code should be integrated with
the build process.

For Java, FindBugs is an excellent tool for finding common errors
through the static analysis of the generated bytecode. All Java-based
project, must run FindBugs as part of the build process. Any “critical”
problems identified by FindBugs must be corrected before committing the
code.

For other languages, you may wish to integrate similar tools in the
build process. For these other languages, we do not have specific
recommendations.

All of the StratusLab code should use unit testing to ensure that the
code behaves as expected. These unit tests are especially critical when
refactoring code (something that happens fairly frequently!).

The code should use the appropriate xUnit framework for the programming
language being used. Ideally, the unit test reports should be formatted
in the JUnit XML format to allow better reporting from the continuous
integration tools.

The collaboration maintains three guides: one for users, one for
administrators, and one for contributors. These should be reviewed and
updated when significant changes are made to the code. These must be
reviewed before each release.

The collaboration uses Jenkins for
continuous integration. Each time a change is committed to a
StratusLab repository, the Hudson server launches a job to rebuild the
software, executing the defined unit tests and repackaging the
software.

Assuming that the unit tests pass, jobs to reinstall a test cloud and to
verify the high-level functionality are also run.

The project currently supports CentOS. All of the builds run on this
platform along with the cloud installation and functionality tests.

All of the code is highly portable and should run on any Linux
platform. Additional operating systems can be supported if there is
enough effort to support the packaging and testing of the code on
the operating system.

The project follows a timed-release policy where a new release is
prepared every quarter. The release numbering follows the Ubuntu-style
format (e.g. 13.05.0 for the May 2013 release). Patch releases may also
be prepared for individual components between the quarterly releases as
necessary.

The releases are made available through yum repositories. Again, Jenkins
is used to create the content of these repositories. They must be copied
by hand to the StratusLab yum repository machine.

There are also a couple of python modules (stratuslab-client and
stratuslab-libcloud-drivers) that must be pushed into PyPi. Once these
are tagged, they should be built by hand and then pushed into PyPi.

All StratusLab services must follow a common configuration scheme where
the core of the configuration is stored in the Couchbase database. Only
the Couchbase configuration parameters are read from a file on the local
filesystem.

This scheme allows the overall system to scale with multiple service
instances while maintaining consistent configurations between them.

Each section corresponds to the parameters for a particular service. The
name of the section is defined by the service. If parameters are not
defined in a specific section, then the ones in the DEFAULT section
will be used. Services may have a default value for the cfg_docid
value.

After reading the Couchbase connection parameters, the service should
read its configuration from a document in Couchbase. The document
identifier containing the configuration is defined by the service, but
may be overridden by the cfg_docid parameter in the local
configuration.

To use Couchbase efficiently, these configuration files should be in
JSON format. This allows them to be pulled into native data structures
easily for our preferred implementation languages.