Warning: This document describes an old release. Check here for the current version.

Nimbus 2.7 Administrator Walkthrough

This guide provides a hands-on overview of Nimbus administrative functionality. It is intended to give new and prospective users a feel for the features and philosophy behind Nimbus. It is complementary to the Zero to Cloud Guide and the reference manual. It steps through a simple install of the service node but doesn't cover configuring backend nodes. It then demonstrates some administrative tools and procedures.

Installation (#)

The first step is to make a basic installation of the Nimbus services. Since we are just messing around, we will install to a temporary location, /tmp/nimbus. The installer will place all files in this location and will not affect any other part of your system. You can install to any path you like, just make sure to adjust the example commands in this document appropriately. You do not need to be root to install and run the Nimbus services.

Before you proceed, make sure your system has the required dependencies. These are detailed in the Service Dependencies page of the Zero to Cloud guide. The short version is: Java 1.5+, Python 2.5+ plus development headers (but not Python 3.x), Apache ant, and gcc.

First download and unpack the Nimbus service source package:

$ wget https://www.nimbusproject.org/downloads/nimbus-2.7-src.tar.gz
$ tar xzf nimbus-2.7-src.tar.gz
$ cd nimbus-2.7-src/

Now run the installer, specifying the destination directory as an argument.

$ ./install /tmp/nimbus

rm -fr /tmp/nimbus

The installation will take a minute or two and you will be asked a couple of questions at the end.

-----------------------------------------------------------------
 Configuring installed services
-----------------------------------------------------------------

Nimbus uses an internal Certificate Authority (CA) for some services. This CA
is also used to generate host and user certificates if you do not have your own.

This CA will be created in /tmp/nimbus/var/ca

Please pick a unique, one word CA name or hit ENTER to use a UUID.

For example, if you are installing this on the "Jupiter" cluster, you might use
"JupiterNimbusCA" as the name.

CA Name:
You did not enter a name, using 'ab75d05b-87ae-4f60-9b4c-c32d207d1f29'

This gives you a chance to customize the name of your certificate authority. For the purposes of this tutorial you can just press [Enter] and let the installer pick a unique name for you.

The next question asks you for the hostname you would like to use. It is important that this is correct because it is used internally by Nimbus. In most cases the installer will guess correctly. For the purposes of this tutorial you can just either press [Enter] to use the detected hostname or type in localhost

What is the fully qualified hostname of this machine?

Press ENTER to use the detected value (vmtroll32)

Hostname: localhost
Cannot find configured certificate and key for HTTPS, creating these for you.

Once the installer has completed you are ready to start the Nimbus services. Notice the final lines of output from the installer:

-----------------------------------------------------------------
 Nimbus installation succeeded!
-----------------------------------------------------------------

Additional configuration may be necessary, refer to this URL for information:

    https://www.nimbusproject.org/docs/2.7/admin/z2c/

You can start/stop Nimbus services with the nimbusctl command. e.g:

    /tmp/nimbus/bin/nimbusctl start

This tells you exactly what you need to do next and where to find more information. Go ahead and start the Nimbus services:

$ /tmp/nimbus/bin/nimbusctl start
Launching Nimbus services...   OK
Launching Cumulus services...  OK

For more details on the installation process, check out the Service Installation page of the Zero to Cloud guide.

Tour of the installation (#)

Nimbus should now be running, but in fake mode. This means that the services run and respond to requests as normal, but there are no actual backend nodes: no virtual machines are ever started. This is great for testing and for our purposes. In a real Nimbus installation you would proceed to install and configure backend nodes, establish communication between them and the service node, and then turn off fake mode. These steps are detailed in the Zero to Cloud guide.

Let's quickly examine what we just installed. Change to the destination directory and look around.

$ cd /tmp/nimbus
$ ls
bin             libexec             ve
cumulus         nimbus-setup.conf   web
install.log     services
lantorrent      var

There are a couple directories you should notice here. bin/ contains most of the command-line tools used to manage Nimbus services and users.

$ ls bin/
cumulus-rebase		nimbus-new-cert		nimbus-reset-state
nimbus-configure	nimbus-new-user		nimbus-version
nimbus-edit-user	nimbus-nodes		nimbusctl
nimbus-import-users	nimbus-public-image
nimbus-list-users	nimbus-remove-user

services/ contains the core Nimbus Java services. Inside of it, services/etc/nimbus/ holds many of the important configuration files.

Managing users (#)

There are four user management command line tools in bin/: nimbus-new-user, nimbus-list-users, nimbus-edit-user, and nimbus-remove-user. To get detailed information about each of these tools, run them with the --help option.

To begin with, we will create a new user. To do this we run the nimbus-new-user command and provide it with the email address of the user we wish to create. The email address is just used as a unique friendly name (no email is sent).

$ ./bin/nimbus-new-user [email protected]
cert            : /tmp/nimbus/var/ca/tmpk8NmStcert/usercert.pem
key             : /tmp/nimbus/var/ca/tmpk8NmStcert/userkey.pem
dn              : /O=Auto/OU=ab75d05b-87ae-4f60-9b4c-c32d207d1f29/[email protected]
canonical id    : dc1b51f6-f73c-11df-87a3-000c292f4ae6
access id       : e1qrC9MyqRUU33INiL7D3
access secret   : TuR5Mrdrl3eAC0tiyCF83hhnxkYL9Udi29U7k1VrvO
url             : None
web id          : None
cloud properties : /tmp/nimbus/var/ca/tmpk8NmStcert/cloud.properties

Notice the output of this command. Every bit of user information is displayed here, some of which is secret information (which can be turned off if needed, check out the --report option). In this case, all of the critical information is placed in the newly created temporary directory under /tmp/nimbus/var/ca/. In that directory you will find the following files:

cloud.properties  usercert.pem  userkey.pem

These files need to be securely transferred to your users. In our case, lets grab a cloud client and try to query the service with these credentials. If you are not familiar with the Nimbus cloud client, review the quickstart. First, download a cloud client package and unpack it somewhere on your system.

$ wget https://www.nimbusproject.org/downloads/nimbus-cloud-client-019.tar.gz
$ tar xzf nimbus-cloud-client-019.tar.gz
$ cd nimbus-cloud-client-019/

Next copy the cloud.properties file generated by the nimbus-new-user call into the conf/ directory. Note that the actual path will differ slightly from this example, but it will have been printed out.

$ cp /tmp/nimbus/var/ca/tmpk8NmStcert/cloud.properties conf/

We also need to copy the generated key and certificate to ~/.nimbus/ in your home directory. Be careful not to overwrite any existing files you may have in this directory.

$ mkdir ~/.nimbus
$ cp /tmp/nimbus/var/ca/tmpk8NmStcert/*.pem ~/.nimbus/

There is one final step in configuring the cloud client. We must allow it to trust the service's certificate authority, by copying some certificates into the client.

$ cp /tmp/nimbus/var/ca/trusted-certs/* lib/certs/

Now try out the cloud client. Query the service for running instances and available VM images (of course there will be none of either).

$ ./bin/cloud-client.sh --status
Querying for ALL instances.

There's nothing running on this cloud that you own.

$ ./bin/cloud-client.sh --list
No files.

The other user management tools are fairly self-explanatory. If you run nimbus-list-users %, you should see your new user listed. With the other tools, you can edit or remove this user.

Node Management (#)

Another important aspect of Nimbus administration is node management. Nodes are the physical machines that user VMs run on. The pool of available nodes can be altered on-the-fly using the nimbus-nodes command line tool. Nodes are specified by hostname, and they must be fully configured with the Nimbus backend software before you add them. Since we are running in fake mode, the nodes we add here will never be contacted and don't need to exist. So let's just make up some hostnames, n1 and n2.

$ ./bin/nimbus-nodes --add n1,n2 --memory 2048
hostname :  n1
pool     :  default
memory   :  2048
networks :  *
in_use   :  false
active   :  true
result   :  ADDED

hostname :  n2
pool     :  default
memory   :  2048
networks :  *
in_use   :  false
active   :  true
result   :  ADDED

This command adds two new nodes, each with 2048MB of memory available for virtual machines. Take a look a the output of --help. There are several other commands you can run to edit existing nodes, or remove them from the pool. One important constraint is you cannot edit or remove nodes that have running VMs (in_use : true). However, you can make them inactive, which means that no new VMs will be started on the specifled nodes. But existing VMs can continue until their leases expire.

Run a fake VM (#)

Now let's go back to the cloud client we set up earlier. We can send a launch request and since the service is still in fake mode, it will pretend to start a VM and send its information back to the client.

$ echo "ceci n'est pas une image de VM" > myfakevm
$ bin/cloud-client.sh --transfer --sourcefile myfakevm

Transferring
  - Source: myfakevm
  - Destination: cumulus://Repo/VMS/5c01dfac-fe2c-11df-875b-00264a0eb5ca/myfakevm

Preparing the file for transfer:
  23.0 B [XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX] 100%

Transferring the file:
  23.0 B [XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX] 100%

Done.

Now let's try to "start" this fake image.

$ ./bin/cloud-client.sh --run --name myfakevm --hours 1

Launching workspace.

Workspace Factory Service:
    https://localhost:8443/wsrf/services/WorkspaceFactoryService

Creating workspace "vm-001"... done.


       IP address: 192.168.0.2
         Hostname: pub02
       Start time: Thu Dec 02 13:37:09 EST 2010
    Shutdown time: Thu Dec 02 14:37:09 EST 2010
 Termination time: Thu Dec 02 14:47:09 EST 2010

Waiting for updates.


"vm-001" reached target state: Running

Running: 'vm-001'

Now our fake VM is running. We can take a look at a few state files in the service to verify this. Back in the service, switch to the /tmp/nimbus/services/var/nimbus directory.

$ cd /tmp/nimbus/services/var/nimbus
$ tail current-reservations.txt
dn="/O=Auto/OU=85da03df-cf74-4e05-82b9-d20eae9e92aa/[email protected]",
minutes=60, uuid="56cf2992-d9ab-4070-94dc-79e3812f11ba", eprkey=1, creation="Dec 2, 2010 1:37:09 PM"

The current-reservations.txt file shows the running VM. We can also look at the accounting log to see more information.

$ tail accounting-events.txt
CREATED: time="Dec 2, 2010 1:37:09 PM", uuid="56cf2992-d9ab-4070-94dc-79e3812f11ba",
 eprkey=1, dn="/O=Auto/OU=85da03df-cf74-4e05-82b9-d20eae9e92aa/[email protected]",
 requestMinutes=60, charge=60, CPUCount=1, memory=256, vmm='n2',
 clientLaunchName='https://sandwich:8443/vm-001',
 network='eth0;public;A2:AA:BB:50:EB:8B;Bridged;AllocateAndConfigure;192.168.0.2;192.168.0.1;
 null;null;192.168.0.1;pub02;null;null;null;null'

If you like, you can now terminate your fake VM with the cloud client. It will disappear from the reservations file and there will be a new accounting log entry.

$ ./bin/cloud-client.sh --terminate --handle vm-001

Terminating workspace.
  - Workspace handle (EPR): '/tmp/nimbus-cloud-client-017/history/vm-001/vw-epr.xml'

Destroying vm-001... destroyed.