~~NOTOC~~
====== Overview ======
The OpenNebula OCCI is a web service that enables you to launch and manage virtual machines in your OpenNebula installation using the [[http://forge.ogf.org/sf/go/doc15731|latest draft]] of the [[http://www.occi-wg.org|OGF OCCI API specification]]. The OpenNebula OCCI service is implemented upon the new **OpenNebula Cloud API** (OCA) layer that exposes the full capabilities of an OpenNebula private cloud; and [[http://www.sinatrarb.com/ | Sinatra]], a widely used light web framework.
{{ documentation:rel1.4:occi_diagram.png |}}
The current implementation includes all the resource referenced in the latest draft of the OGF OCCI API specification, namely:
* **Compute**: launching, retrieve, update and deletion
* **Network**: creation, retrieve and deletion
* **Storage**: upload, retrieve and deletion
The following sections explain how to install and configure the OCCI service on top of a running OpenNebula cloud.
:!: The OpenNebula OCCI service provides an OCCI interface to your cloud instance, that can be used alongside the native OpenNebula CLI, the libvirt interface or even the EC2 Query API
:!: The OpenNebula distribution includes the tools needed to use the OpenNebula OCCI service
====== Requirements & Installation ======
You must have an OpenNebula site properly configured and running to install the OpenNebula OCCI service, be sure to check the [[.#virtual_infrastructure_management|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 OpenNebula OCCI service was installed during the OpenNebula installation, so you just need to install the following packages to meet the runtime dependencies:
* The Sinatra web framework and the thin web server:
$ sudo gem install thin
$ sudo gem install sinatra
* The libraries for the Storage Repository and Client Tools:
$ sudo gem install curb
$ sudo gem install multipart-post
$ apt-get install ruby-sqlite3
$ apt-get install libopenssl-ruby
:!: ''curb'' is just neccessary to upload files faster. If not installed, upload file with ''occi-storage -M'' that uses the ''multipart-post'' library
====== Configuration ======
The service is configured through the ''$ONE_LOCATION/etc/occi-server.conf'' file, where you can set up the basic operational parameters for the OCCI service, namely:
* **Connection Parameters**, the xml-rpc service of the ''oned'' daemon; and the server and port for the OpenNebula OCCI service web server. This will be the URL of your cloud.
* **Computes**, the name of the bridge that the VM needs to connect to in the physical host to get network connection. See the [[.:vgg|Managing Virtual Networks guide]] for more details.
* **Compute Types**, a ''VM_TYPE'' defines the name and the OpenNebula templates for each type of Compute, to enable different //sizes// of Computes.
The following table summarizes the available options:
^ VARIABLE ^ VALUE ^
|ONE_XMLRPC| oned xmlrpc service, http://localhost:2633/RPC2|
|SERVER | FQDN for your cloud |
|PORT | for incoming connections |
|BRIDGE | Name of the bridge needed to create Networks |
|VM_TYPE | The Computes types for your cloud|
:!: The ''SERVER'' **must** be a FQDN, do not use IP's here
:!: Preserve bash syntax in the ''occi-server.conf'' file
Example:
# OpenNebula server contact information
ONE_XMLRPC=http://localhost:2633/RPC2
# Host and port where OCCI service will run
SERVER=cloud.opennebula.org
PORT=4567
# Configuration for OpenNebula's Virtual Networks
BRIDGE=eth0
# VM types allowed and its template file (inside templates directory)
VM_TYPE=[NAME=small, TEMPLATE=small.erb]
VM_TYPE=[NAME=medium, TEMPLATE=medium.erb]
VM_TYPE=[NAME=large, TEMPLATE=large.erb]
===== Configuring a SSL proxy =====
OpenNebula OCCI 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 OCCI 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
* OCCI 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 OCCI Service.
Let's assume the server were the lighttpd proxy is going to be started is called ''cloudserver.org''. Therefore, the steps are:
==== 1. Snakeoil server certificate ====
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
$ sudo apt-get install ssl-cert
* Generate the certificate
$ sudo /usr/sbin/make-ssl-cert generate-default-snakeoil
* As we are using lighttpd, we need to append the private key with the certificate to obtain a server certificate valid to lighttpd
$ sudo cat /etc/ssl/private/ssl-cert-snakeoil.key /etc/ssl/certs/ssl-cert-snakeoil.pem > /etc/lighttpd/server.pem
==== 2. lighttpd as a SSL HTTP proxy ====
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.
==== 3.OCCI Service configuration ====
The ''occi.conf'' needs to define the following:
# Host and port where the occi server will run
SERVER=
PORT=4567
# SSL proxy that serves the API (set if is being used)
SSL_SERVER=https://localhost:443
Once the lighttpd server is started, OCCI 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.
===== Defining Compute types =====
You can define as many Compute types as you want, just:
* Create a template for the new type and place it in ''$ONE_LOCATION/etc/occi_templates''. This template will be //completed// with the data for each cloud //occi-vm create// request, and then submitted to OpenNebula.
CPU = 1
MEMORY = 1024
OS = [ kernel = /vmlinuz,
initrd = /initrd.img,
root = sda1,
kernel_cmd = "ro xencons=tty console=tty1"]
* You can add common attributes for your cloud templates modifying the ''$ONE_LOCATION/etc/occi_templates/common.erb'' file.
:!: The templates are processed by the OCCI service to include specific data for the instance, you should not need to modify the <%= ... %> compounds inside the ''common.erb'' file.
====== Starting the Cloud Service ======
To start the OCCI service just issue the following command
occi-server start
You can find the OCCI server log file in ''$ONE_LOCATION/var/occi-server.log'' if OpenNebula has been installed in standalone, or in ''/var/log/one/occi-server.log'' if installed in system-wide.
To stop the OCCI service:
occi-server stop
====== Cloud Users ======
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 [[http://tools.ietf.org/html/rfc1945#section-11.1|HTTP basic authentication]] with ''user-ID'' their OpenNebula's username and ''password'' their OpenNebula's password.