The OpenNebula EC2 Query is a web service that enables you to launch and manage virtual machines in your OpenNebula installation through the Amazon EC2 Query Interface. In this way, you can use any EC2 Query tool or utility to access your Private Cloud. The EC2 Query web service is implemented upon the new OpenNebula Cloud API (OCA) layer that exposes the full capabilities of an OpenNebula private cloud; and Sinatra, a widely used light web framework.

The current implementation includes the basic routines to use a Cloud, namely: image upload and registration, and the VM run, describe and terminate operations. The following sections explains you how to install and configure the EC2 Query web service on top of a running OpenNebula cloud.

The OpenNebula EC2 Query service provides a Amazon EC2 Query API compatible interface to your cloud, that can be used alongside the native OpenNebula CLI or the libvirt interface.

The OpenNebula distribution includes the tools needed to use the EC2 Query service.

You must have an OpenNebula site properly configured and running to install the EC2 Query service, be sure to check the OpenNebula Installation and Configuration Guides to set up your private cloud first. This guide also assumes that you are familiar with the configuration and use of OpenNebula.

The EC2 Query service was installed during the OpenNebula installation, so you just need to install the following packages to meet the runtime dependencies:

• The Amazon EC2 Query API library:

<xterm>$ sudo gem install amazon-ec2</xterm>

• The Sinatra web framework and the thin web server:

<xterm>$ sudo gem install sinatra $ sudo gem install thin</xterm>

• The libraries for the Image Repository and Client Tools (packages names are taken from the Ubuntu distribution):

<xterm> $ sudo gem install sequel $ sudo gem install curb $ apt-get install libsqlite3-ruby $ sudo apt-get install libcurl4-gnutls-dev $ sudo apt-get install libopenssl-ruby1.8 $ sudo gem install sqlite3-ruby</xterm>

The service is configured through the $ONE_LOCATION/etc/econe.conf file, where you can set up the basic operational parameters for the EC2 Query web service, namely:

• Administration Account, the web server need to perform some operation using the oneadmin account, mainly to check the identity of the cloud users. You have to specify the USER and PASSWORD of oneadmin.
• Connection Parameters, the xml-rpc service of the oned daemon; and the server and port for the EC2_URL. This will be the URL of your cloud.
• Image Repository, the image repository provides a easy-to-use and simple replacement of the S3 service to store and upload images. You need to specify the DATABASE and IMAGE_DIR for this service.
• Virtual Machine Types, a VM_TYPE defines the name and the OpenNebula templates for each type.

The following table summarizes the available options:

The SERVER must be a FQDN, do not use IP's here.

IMAGE_DIR must be an existing directory

Preserve bash syntax in the econe.conf file

Example:

# OpenNebula administrator user
USER=oneadmin
PASSWORD=mypass

# OpenNebula sever contact information
ONE_XMLRPC=http://localhost:2633/RPC2

# Host and port where OCA server will run
SERVER=cloud.opennebula.org
PORT=4567	
# SSL proxy that serves the API (set if is being used)
#SSL_SERVER=fqdn.of.the.server


# Configuration for the image repository
DATABASE=/srv/cloud/one/var/ec2.db
IMAGE_DIR=/srv/cloud/images/

# VM types allowed and its template file (inside templates directory)
VM_TYPE=[NAME=m1.small, TEMPLATE=m1.small.erb]
VM_TYPE=[NAME=m1.medium, TEMPLATE=m1.medium.erb]

OpenNebula EC2 Query Service runs natively just on normal HTTP connections. If the extra security provided by SSL is needed, a proxy can be set up to handle the SSL connection that forwards the petition to the EC2 Query Service and takes back the answer to the client.

This set up needs:

• A server certificate for the SSL connections
• An HTTP proxy that understands SSL
• EC2Query Service configuration to accept petitions from the proxy

If you want to try out the SSL setup easily, you can find in the following lines an example to set a self-signed certificate to be used by a lighttpd configured to act as an HTTP proxy to a correctly configured EC2 Query Service.

Let's assume the server were the lighttpd proxy is going to be started is called cloudserver.org. Therefore, the steps are:

We are going to generate a snakeoil certificate. If using an Ubuntu system follow the next steps (otherwise your milleage may vary, but not a lot):

• Install the ssl-cert package

<xterm> $ sudo apt-get install ssl-cert </xterm>

• Generate the certificate

<xterm> $ sudo /usr/sbin/make-ssl-cert generate-default-snakeoil </xterm>

• As we are using lighttpd, we need to append the private key with the certificate to obtain a server certificate valid to lighttpd

<xterm> $ sudo cat /etc/ssl/private/ssl-cert-snakeoil.key /etc/ssl/certs/ssl-cert-snakeoil.pem > /etc/lighttpd/server.pem </xterm>

You will need to edit the /etc/lighttpd/lighttpd.conf configuration file and

• Add the following modules (if not present already)
  • mod_access
  • mod_alias
  • mod_proxy
  • mod_accesslog
  • mod_compress
• Change the server port to 443 if you are going to run lighttpd as root, or any number above 1024 otherwise:

server.port               = 8443

• Add the proxy module section:

#### proxy module
## read proxy.txt for more info
proxy.server               = ( "" =>
                                ("" =>
                                 (
                                   "host" => "127.0.0.1",
                                   "port" => 4567
                                 )
                                 )
                             )


#### SSL engine
ssl.engine                 = "enable"
ssl.pemfile                = "/etc/lighttpd/server.pem"

The host must be the server hostname of the computer running the EC2Query Service, and the port the one that the EC2Query Service is running on.

The econe.conf needs to define the following:

# Host and port where OCA server will run
SERVER=127.0.0.1
PORT=4567	
# SSL proxy that serves the API (set if is being used)
SSL_SERVER=cloudserver.org

Once the lighttpd server is started, EC2Query petitions using HTTPS uris can be directed to https://cloudserver.org:8443, that will then be unencrypted, passed to localhost, port 4567, satisfied (hopefully), encrypted again and then passed back to the client.

You can define as many Virtual Machine types as you want, just:

• Create a template for the new type and place it in $ONE_LOCATION/etc/ec2query_templates. This template will be completed with the data for each cloud run-instance request, and then submitted to OpenNebula. You can start by modifying the m1.small.erb example, to adjust it to your cloud:

NAME   = eco-vm

CPU    = 1
MEMORY = 1024

OS = [ kernel     = /vmlinuz,
       initrd     = /initrd.img,
       root       = sda1,
       kernel_cmd = "ro xencons=tty console=tty1"]

DISK = [ source   = <%= @vm_info[:img_path] %>,
         clone    = no,
         target   = sda1,
         readonly = no]

NIC = [ network = "Public EC2" ]

IMAGE_ID = <%= @vm_info[:img_id] %>
INSTANCE_TYPE = <%= @vm_info[:instance_type ]%>

• Add a VM_TYPE attribute to $ONE_LOCATION/etc/eco.conf with the NAME for the new type and the TEMPLATE that should be use:

VM_TYPE=[NAME=m1.large, TEMPLATE=m1.large.erb]

The templates are processed by the EC2 server to include specific data for the instance, you should not need to modify the <%= … %> compounds. Start by adjusting the OS, CPU and MEMORY to your needs.

By default, the templates used to instantiate the virtual machines includes a NIC interface to be attached to a virtual network named Public EC2. You have to create this network using the onevnet utility with the IP's you want to lease to the VMs created with the EC2 Query service.

To start the EC2 Query service just issue the following command <xterm> $ $ONE_LOCATION/bin/econe-server start </xterm> You can find the econe server log file in $ONE_LOCATION/var/econe-server.log if OpenNebula has been installed in standalone, or in /var/log/one/econe-server.log if installed in system-wide.

To stop the EC2 Query service: <xterm> $ $ONE_LOCATION/bin/econe-server stop </xterm>

The cloud users have to be created in the OpenNebula system by oneadmin using the oneuser utility. Once a user is registered in the system, using the same procedure as to create private cloud users, they can start using the system. The users will authenticate using the Amazon EC2 procedure with AWSAccessKeyId their OpenNebula's username and AWSSecretAccessKey their OpenNebula's password.