Cloud Client Quickstart


Download the cloud client (#)

In order to use the client you will need to have Java (1.5+) installed on your system.

Note that using the cloud client requires access to a Nimbus cloud. If you are a member of the academic community, you can gain access to one of several science clouds.

Download the latest nimbus cloud client, untar the file, and change to the cloud client directory (older versions of the cloud client).

Congratulations -- you are now the happy owner of a brand new cloud client! At any time, get help like so:

$ ./bin/cloud-client.sh --help

Make sure to subscribe to [email protected] (see the contact page for instruction on how to subscribe) to hear about client version updates.


Configure and prepare for deployment (#)

First, see if you have configured the desired certificate:

$ ./bin/grid-cert-info.sh

Then create a proxy credential:

$ ./bin/grid-proxy-init.sh

Alternatively, if you have access to a MyProxy credential you can use the "./bin/myproxy.sh" program.

Test the security setup:

$ ./bin/cloud-client.sh --security

Issues? See the help resources for help.

Not enabled on a cloud yet?

If you have not yet given your DN to the cloud administrators, this would be a good time to do so -- just send the text printed after 'Identity:' in the output of the ./bin/cloud-client.sh --security command.

Does your cloud require VPN?

Some clouds require the use of virtual private networks. Check the configuration notes for the cloud you want to use and if private networks are required first follow the VPN installation steps.

Configure cloud and SSH public key:

The default client configuration should handle your initial needs.

You might want to change things in the conf/cloud.properties file, probably not.

Most of the time a configuration file tailored to the cloud you want to use should have been made available to you from the administrator or cloud website.

  • You can point the client at the cloud you will be using by redefining the specific service and repository endpoints (obtain them from the cloud administrator).

  • You can set up an alternate location of the ssh public key that you want to put on the VM. This will allow you to log in after launching. The default is what you'd want usually, ~/.ssh/id_rsa.pub

  • Note that you can override options via commandline if desired (see the --extrahelp option)

If you do nothing (a highly recommended and undervalued course of action) these things will be picked up from default locations specified in the file.


Pick a virtual machine image to deploy (#)

In order to deploy a VM with custom configuration you need to upload an image to the cloud. To make it easy for you we already uploaded many images to your personal repository directory that you can launch. You can find more detailed descriptions of those images at the Nimbus marketplace. To see what is available for running, list the images as follows:

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

If you are feeling adventurous you could also create an image yourself and upload them to the cloud, see this appendix entry. You may as well explore that capability later if this is your first time using the cloud (in order to just get a feel for the cloud client).


Deploy a workspace (#)

To launch, use the --run option of the client. There are two required run options: (1) --name defines the name of an image and (2) --hours specifies the number of hours for which the image will be deployed. For example, if you want to run the image in your personal repository called "hello-cloud" for 1 hour, run the following command:

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

If successful, the run command should produce roughly this output: 

SSH public keyfile contained tilde:
  - '~/.ssh/id_rsa.pub' --> '/home/guest/.ssh/id_rsa.pub'

Launching workspace.

Using workspace factory endpoint:
    https://cloudurl.edu:8443/wsrf/services/WorkspaceFactoryService

Creating workspace "vm-023"... done.

       IP address: 123.123.123.123
         Hostname: ahostname.cloudurl.edu
       Start time: Fri Feb 29 09:36:39 CST 2008
    Shutdown time: Fri Feb 29 10:36:39 CST 2008
 Termination time: Fri Feb 29 10:46:39 CST 2008

Waiting for updates.

State changed: Running

Running: 'vm-023'

The output prints out the endpoint information of the Nimbus service associated with the cloud you are using. This is followed by information about the deployed VM which includes: the name you will use to terminate the VM, the instantiation/termination times, and the contact information for the workspace.

Note that the information printed contains the network address for the VM. You will need this in order to log in.


Interact with a workspace (#)

Recall that your public key has been configured in the conf/cloud.properties file. At launch time, the public key file was installed to /root/.ssh/authorized_keys on the VM image, so that after it boots you should be able to log in by typing:

$ ssh root@ahostname.cloudurl.edu

Make sure that you log in to the root account -- that's the only one that gets set up with the key. You can create and configure other accounts once you log in.

Another useful tip: if you don't want SSH to remember the generated host key in the known-hosts file (and complain when this name is taken by a different VM later), use SSH with the option "-o StrictHostKeyChecking=no" (later you will learn how to be more secure)

Enjoy! And may we ask that you send us a postcard ([email protected]).


Querying a workspace (#)

Should you ever find yourself somewhat out of touch with your VMs there is an easy way to reestablish relations:

$ ./bin/cloud-client.sh --status --handle vm-023

If you don't recall what the handle you need is, there are running logs of each run kept in the "history" directory. The highest numbered subdirectory name in the history directory is probably a good guess.


Saving workspace changes (#)

You can save a template image's changes after use, this command will shutdown the workspace and send the altered file back to your personal repository directory.

$ ./bin/cloud-client.sh --save --handle vm-023 --newname custom-1

Note that without the --newname parameter this will overwrite the source file. If you do not have permissions to overwrite the source file (for example, you are using the pre-populated template images that are provided), you must use the --newname parameter which is kind of like the "save as" option for documents in a word processor.

Failing to do so will cause a permissions error and you will lose the changes on that run. If you uploaded the image personally, you will have the permissions to overwrite the source file (i.e., the ability to use the --save option without also using --newname).

As explained in the query section above, if you do not know the handle you need, have a look in the history directory.


Terminate a workspace (#)

All good things come to an end. So it is with workspaces which come to an end in the following way:

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

As explained in the query section above, if you do not know the handle you need, have a look in the history directory.


Advanced Topics (#)

You have now earned your stripes: you have deployed a VM (or two) and got a taste for cloud computing. How do we now move on to something useful? One of the most commonly voiced requirements is to be able to deploy "one-click virtual clusters" -- see our guide to deploying virtual clusters to learn more.

Also, you can find information on miscellaneous topics in the Cloud Client Appendix


Help resources (#)

For questions (and to see others' questions answered), make sure to subscribe to [email protected] (see the contact page for instruction on how to subscribe).

For help with security issues, you should also inquire to the list. Before doing so, note that the cloud-client has a "--security" flag for a basic trust check. And other programs under the "bin" directory have their own help system, for example if you run "./bin/grid-proxy-init.sh -help" this may solve a problem your having right away.

For problems you'd like to keep quiet about (for example security with specific IP adresses etc.), you should email your administrator contact privately.

Troubleshooting:

  • Problem: grid-proxy-init reports that it cannot find your credential's certificate authority (CA) files.

    You may be using a credential that was only recently trusted by the cloud. In this case, add the CA certificate to the "lib/certs" directory which is where "./bin/grid-proxy-init.sh" looks for CA certificates.