ONE 3.8 Extending and Integrating Your Cloud Infrastructure

Extending and Integrating your Cloud Infrastructure
OpenNebula 3.8
C12G Labs S.L.
Rev20121022
Copyright
2012 C12G Labs
Although the information in this document has been carefully reviewed, C12G Labs does not warrant it to be free of errors
or omissions. C12G Labs reserves the right to make corrections,
updates, revisions, or changes to the information in this document.
Document redistribution
and translation
Internal redistribution
Trademarks
UNLESS OTHERWISE EXPRESSLY STATED BY C12G

LABS THE SOFTWARE DESCRIBED IN THIS DOCUMENT
IS PROVIDED ON AS IS BASIS, WITHOUT ANY WARRANTIES OF ANY KIND, INCLUDING, BUT NOT LIMITED
TO, WARRANTIES CONCERNING THE INSTALLATION,
USE OR PERFORMANCE OF PRODUCT. C12G AND ITS
SUPPLIERS DISCLAIM ANY AND ALL WARRANTIES,
EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO ANY WARRANTY OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE AND/OR
NON-INFRINGEMENT. C12G AND ITS SUPPLIERS DO
NOT WARRANT THAT PRODUCT WILL MEET USERS
REQUIREMENTS OR THAT THE OPERATION THEREOF
WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT
ERRORS WILL BE CORRECTED. YOU ARE SOLELY
RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING THE WORK AND ASSUME ANY RISKS
ASSOCIATED WITH YOUR EXERCISE OF PERMISSIONS
UNDER THIS LICENSE.
This document is protected by copyright and you may not redistribute it or translate it intro another language, in part or in
whole.
You may only redistribute this document internally within your
organization (for example, on an intranet) provided that you continue to check the C12G Labs Partner Portal site for updates and
update your version of the documentation. You may not make it
available to your organization over the Internet.
C12G and OpenNebula are trademarks in the European Union
and are pending trademarks in the United States. All other tradermakrs are property of their respective owners. Other product
or company names mentioned may be trademarks or trade names
of their respective companies.
Contents
1 Getting Started
1.1 Scalable Architecture and APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1 1. Cloud Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.2 2. System Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2 Cloud Interfaces
2.1 OpenNebula EC2 API . . . . . . . . . .
2.1.1 User Account Configuration . . .
2.1.2 Hello Cloud! . . . . . . . . . . .
2.2 OpenNebula OCCI API . . . . . . . . .
2.2.1 Overview . . . . . . . . . . . . .
2.2.2 Authentication & Authorization
2.2.3 HTTP Headers . . . . . . . . . .
2.2.4 Return Codes . . . . . . . . . . .
2.2.5 Resource Representation . . . . .
2.2.6 Request Methods . . . . . . . . .
2.2.7 Implementation Notes . . . . . .
2.2.8 Examples . . . . . . . . . . . . .
5
5
5
6
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
8
8
9
9
11
11
12
12
12
12
16
20
20
3 System Interfaces
3.1 XML-RPC API . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 Authorization Requests Reference . . . . . . . .
3.1.2 Actions for Templates Management . . . . . . .
3.1.3 Actions for Virtual Machine Management . . . .
3.1.4 Actions for Hosts Management . . . . . . . . . .
3.1.5 Actions for Cluster Management . . . . . . . . .
3.1.6 Actions for Virtual Network Management . . . .
3.1.7 Actions for Datastore Management . . . . . . . .
3.1.8 Actions for Image Management . . . . . . . . . .
3.1.9 Actions for User Management . . . . . . . . . . .
3.1.10 Actions for Group Management . . . . . . . . . .
3.1.11 Actions for ACL Rules Management . . . . . . .
3.1.12 Actions for Document Management . . . . . . .
3.1.13 System Methods . . . . . . . . . . . . . . . . . .
3.1.14 XSD Reference . . . . . . . . . . . . . . . . . . .
3.2 Ruby OpenNebula Cloud API . . . . . . . . . . . . . . .
3.2.1 API Documentation . . . . . . . . . . . . . . . .
3.2.2 Usage . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3 Code Sample: Shutdown all the VMs of the pool
3.2.4 Code Sample: Create a new VirtualNetwork . . .
3.3 Java OpenNebula Cloud API . . . . . . . . . . . . . . .
3.3.1 Download . . . . . . . . . . . . . . . . . . . . . .
3.3.2 Usage . . . . . . . . . . . . . . . . . . . . . . . .
3.3.3 Code Sample . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
21
21
22
26
29
35
38
41
44
46
49
52
53
54
56
57
67
67
67
68
69
69
70
70
70
C12G Labs S.L.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3/93
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Rev20121022
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
71
71
71
72
72
72
72
80
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
83
83
83
84
85
86
86
86
87
89
90
5 References
5.1 Building from Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.1 Compiling the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.2 Ruby Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
91
91
91
92
3.4
3.5
3.3.4 Compilation . . . . . . . . . . .
Ruby OpenNebula Zone API . . . . .
3.4.1 API Documentation . . . . . .
3.4.2 Usage . . . . . . . . . . . . . .
3.4.3 Code Sample . . . . . . . . . .
Sunstone Plugins API . . . . . . . . .
3.5.1 Sunstone configuration objects
3.5.2 Sunstone plugin interface . . .
4 Infrastructure Integration
4.1 Virtualization Manager Driver . .
4.1.1 Driver Configuration . . . .
4.1.2 Actions . . . . . . . . . . .
4.1.3 Poll Information . . . . . .
4.1.4 Deployment file . . . . . . .
4.2 Storage Subsystem . . . . . . . . .
4.2.1 Datastore Drivers Structure
4.2.2 TM Drivers Structure . . .
4.2.3 An example VM . . . . . .
4.2.4 Helper Scripts . . . . . . .
C12G Labs S.L.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4/93
Rev20121022
Chapter 1
Getting Started
1.1
Scalable Architecture and APIs
OpenNebula has been designed to be easily adapted to any infrastructure and easily extended with new
components. The result is a modular system that can implement a variety of Cloud architectures and
can interface with multiple datacenter services. In this document we will review the main interfaces
of OpenNebula (see figure 1 for an overview), their use and give pointers to additional documentation
for each one. We have classified the interfaces in two categories: end-user cloud and system interfaces.
Cloud interfaces are primary used to develop tools targeted to the end-user, and they provide a high level
abstraction of the functionality provided by the Cloud. On the other hand, the system interfaces expose
the full functionality of OpenNebula and are mainly used to adapt and tune the behavior of OpenNebula
to the target infrastructure.
Figure 1: OpenNebula Interfaces
1.1.1
1. Cloud Interfaces
Cloud interfaces enable you to manage virtual machines, networks and images through a simple and
easy-to-use REST API1 . The Cloud interfaces hide most of the complexity of a Cloud and are specially
suited for end-users. OpenNebula implements two different interfaces, namely:
1 Application
Programming Interface
C12G Labs S.L.
5/93
Rev20121022
EC2-Query API1 . OpenNebula implements the functionality offered by the Amazons EC2 API,
mainly those related to virtual machine management. In this way, you can use any EC2 Query tool
to access your OpenNebula Cloud.
OCCI-OGF. This web service enables you to launch and manage virtual machines in your OpenNebula installation using the latest draft of the OGF OCCI API specification.
Use the cloud interface if. . . you are developing portals, tools or specialized solutions for end-users.
You can find more information at. . . EC2-Query reference, and OCCI reference guides.
1.1.2
2. System Interfaces
2.1. The OpenNebula XML-RPC Interface

The XML2 -RPC3 interface is the primary interface for OpenNebula, and it exposes all the functionality
to interface the OpenNebula daemon. Through the XML2 -RPC3 interface you can control and manage
any OpenNebula resource, including virtual machines, networks, images, users, hosts and clusters.
Use the XML2 -RPC3 interface if. . . you are developing specialized libraries for Cloud applications or
you need a low-level interface with the OpenNebula core.
You can find more information at. . . XML-RPC reference guide.
2.2. The OpenNebula Cloud API (OCA)
The OpenNebula Cloud API1 provides a simplified and convenient way to interface the OpenNebula core.
The OCA interfaces exposes the same functionality as that of the XML2 -RPC3 interface. OpenNebula
includes two language bindings for OCA: Ruby and JAVA.
Use the OCA interface if. . . you are developing advanced IaaS tools that need full access to the
OpenNebula functionality.
You can find more information at. . . OCA-Ruby reference guide and the OCA-JAVA reference guide.
2.3. The OpenNebula Drivers Interfaces
The interactions between OpenNebula and the Cloud infrastructure are performed by specific drivers
each one addressing a particular area:
Storage. The OpenNebula core issue abstract storage operations (e.g. clone or delete) that are
implemented by specific programs that can be replaced or modified to interface special storage
backends and file-systems.
Virtualization. The interaction with the hypervisors are also implemented with custom programs
to boot, stop or migrate a virtual machine. This allows you to specialize each VM operation so to
perform custom operations.
Monitoring. Monitoring information is also gathered by external probes. You can add additional
probes to include custom monitoring metrics that can be later used to allocate virtual machines or
for accounting purposes
Authorization. OpenNebula can be also configured to use an external program to authorize and
authenticate user requests. In this way, you can implement any access policy to Cloud resources.
Use the driver interfaces if. . . you need OpenNebula to interface any specific storage, virtualization,
monitoring or authorization system already deployed in your datacenter or to tune the behavior of the
standard OpenNebula drivers.
You can find more information at. . . the storage system, the information system and the Authorization system
guides.
2 Extensible
3 Remote
Markup Language
Procedure Call
C12G Labs S.L.
6/93
Rev20121022
2.4. The OpenNebula DataBase

OpenNebula saves its state and lots of accounting information in a persistent data-base. OpenNebula
can use MySQL or SQLite database that can be easily interfaced with any of DB tool.
Use the OpenNebula DB if. . . you need to generate custom accounting or billing reports.
You can find more information at. . . the database schema page.
C12G Labs S.L.
7/93
Rev20121022
Chapter 2
Cloud Interfaces
2.1
OpenNebula EC2 API
The EC2 Query API offers the functionality exposed by Amazon EC2: upload images, register them,
run, monitor and terminate instances, etc. In short, Query requests are HTTP1 or HTTPS requests that
use the HTTP1 verb GET or POST and a Query parameter.
OpenNebula implements a subset of the EC2 Query interface, enabling the creation of public clouds
managed by OpenNebula. In this last release of the API2 implementation, the methods implemented are:
AMIs
upload image: Uploads an image to OpenNebula
describe images: Lists all registered images belonging to one particular user.
Instances
run instances: Runs an instance of a particular image (that needs to be referenced).
describe instances: Outputs a list of launched images belonging to one particular user.
terminate instances: Shutdowns a set ofvirtual machines (or cancel, depending on its state).
reboot instances: Reboots a set ofvirtual machines.
start instances: Starts a set ofvirtual machines.
stop instances: Stops a set ofvirtual machines.
EBS
create volume: Creates a new DATABLOCK in OpenNebula
delete volume: Deletes an existing DATABLOCK.
describe volumes: Describe all available DATABLOCKs for this user
attach volume: Attaches a DATABLOCK to an instance
detach volume: Detaches a DATABLOCK from an instance
1 Hyper
Text Transfer Protocol

Programming Interface
2 Application
C12G Labs S.L.
8/93
Rev20121022
Elastic IPs
allocate address: Allocates a new elastic IP address for the user
release address: Releases a publicIP of the user
describe addresses: Lists elastic IP addresses
associate address: Associates a publicIP of the user with a given instance
disassociate address: Disasociate a publicIP of the user currently associated with an instance
Keypairs
create keypair: Creates the named keypair
delete keypair: Deletes the named keypair, removes the associated keys
describe keypairs: List and describe the key pairs available to the user
Commands description can be accessed from the Command Line Reference.
2.1.1
User Account Configuration
An account is needed in order to use the OpenNebula cloud. The cloud administrator will be responsible
for assigning these accounts, which have a one to one correspondence with OpenNebula accounts, so all
the cloud administrator has to do is check the configuration guide to setup accounts, and automatically
the OpenNebula cloud account will be created.
In order to use such an account, the end user can make use of clients programmed to access the
services described in the previous section. For this, she has to set up his environment, particularly the
following aspects:
Authentication: This can be achieved in three different ways, here listed in order of priority (i.e.
values specified in the argument line supersede environmental variables)
Using the commands arguments. All the commands accept an Access Key (as the OpenNebula username) and a Secret Key (as the OpenNebula hashed password)
Using EC2 ACCESS KEY and EC2 SECRET KEY environment variables the same way
as the arguments
If none of the above is available, the ONE AUTH variable will be checked for authentication
(with the same used for OpenNebula CLI).
Server location: The command need to know where the OpenNebula cloud service is running.
That information needs to be stored within the EC2 URL3 environment variable (in the form of
a http URL3 , including the port if it is not the standard 80).
The EC2_URL3 has to use the FQDN of the EC2-Query Server
2.1.2
Hello Cloud!
Lets take a walk through a typical usage scenario. In this brief scenario it will be shown how to upload
an image to the OpenNebula image repository, how to register it in the OpenNebula cloud and perform
operations upon it.
upload image
Assuming we have a working Gentoo installation residing in an .img file, we can upload it into the
OpenNebula cloud using the econe-upload command:
3 Uniform
Resource Locator
C12G Labs S.L.
9/93
Rev20121022
$ econe-upload /images/gentoo.img
Success: ImageId ami-00000001
The user should take note of this ImageId, as it will be needed to register the image.
register image
The next step should be registering the image to enable its instantiation. We can do this with the
econe-register command:
$ econe-register ami-00000001
Success: ImageId ami-00000001
describe images
We will need the ImageId to launch the image, so in case we forgotten we can list registered images
using the econe-describe-images command:
$ econe-describe-images -H
Owner
ImageId
Status
Visibility
Location
-----------------------------------------------------------------------------helen
ami-00000001 available
private
19ead5de585f43282acab4060bfb7a07
run instance
Once we recall the ImageId, we will need to use the econe-run-instances command to launch an
Virtual Machine instance of our image:
$ econe-run-instances -H ami-00000001
Owner
ImageId
InstanceId InstanceType
-----------------------------------------------------------------------------helen
ami-00000001
i-15
m1.small
We will need the InstanceId to monitor and shutdown our instance, so we better write down that i-15.
describe instances
If we have too many instances launched and we dont remember everyone of them, we can ask econedescribe-instances to show us which instances we have submitted.
$ econe-describe-instances -H
Owner
Id
ImageId
State
IP
Type
-----------------------------------------------------------------------------------------------------------helen
i-15 ami-00000001 pending
147.96.80.33
m1.small
We can see that the instances with Id i-15 has been launched, but it is still pending, i.e., it still needs to
be deployed into a physical host. If we try the same command again after a short while, we should be
seeing it running as in the following excerpt:
$ econe-describe-instances -H
Owner
Id
ImageId
State
IP
Type
-----------------------------------------------------------------------------------------------------------helen
i-15 ami-00000001 running
147.96.80.33
m1.small
C12G Labs S.L.
10/93
Rev20121022
terminate instances
After we put the Virtual Machine to a good use, it is time to shut it down to make space for other Virtual Machines (and, presumably, to stop being billed for it). For that we can use the econe-terminateinstances passing to it as an argument the InstanceId that identifies our Virtual Machine:
$ econe-terminate-instances i-15
Success: Terminating i-15 in running state
You can obtain more information on how to use the above commands accessing their Usage help
passing them the -h flag
2.2
OpenNebula OCCI API
inlinetoc
2.2.1
Overview
The OpenNebula OCCI API2 is a RESTful service to create, control and monitor cloud resources using
an implementation of the OGF OCCI API specification based on the draft 0.8. This implementation also
includes some extensions, requested by the community, to support OpenNebula specific functionality.
There are two types of resources that resemble the basic entities managed by the OpenNebula system,
namely:
Pool Resources (PR): Represents a collection of elements owned by a given user. In particular
five collections are defined:
1
2
3
4
5
6
7
<COLLECTIONS>
<COMPUTE COLLECTION h r e f= h t t p : // l o c a l h o s t : 4 5 6 7 / compute >
<INSTANCE TYPE COLLECTION h r e f= h t t p : // l o c a l h o s t : 4 5 6 7 / i n s t a n c e t y p e >
<NETWORK COLLECTION h r e f= h t t p : // l o c a l h o s t : 4 5 6 7 / network >
<STORAGE COLLECTION h r e f= h t t p : // l o c a l h o s t : 4 5 6 7 / s t o r a g e >
<USER COLLECTION h r e f= h t t p : // l o c a l h o s t : 4 5 6 7 / u s e r >
</COLLECTIONS>
Entry Resources (ER): Represents a single entry within a given collection: COMPUTE, NETWORK, STORAGE, INSTANCE TYPE and USER.
Each one of ERs in the pool are described by an element (e.g. COMPUTE, INSTANCE_TYPE, NETWORK,
STORAGE or USER) with one attribute:
href, a URI4 for the ER
1
2
3
4
5
<COMPUTE COLLECTION>
<COMPUTE h r e f= h t t p : //www. o p e n n e b u l a . o r g / compute /310 name=TestVM />
<COMPUTE h r e f= h t t p : //www. o p e n n e b u l a . o r g / compute /432 name= S e r v e r 1 />
<COMPUTE h r e f= h t t p : //www. o p e n n e b u l a . o r g / compute /123 name= S e r v e r 2 />
</COMPUTE COLLECTION>
A COMPUTE entry resource can be linked to one or more STORAGE or NETWORK resources and one INSTANCE_TYPE and USER.
4 Uniform
Resource Identifier
C12G Labs S.L.
11/93
Rev20121022
2.2.2
Authentication & Authorization
User authentication will be HTTP Basic access authentication to comply with REST philosophy. The
credentials passed should be the User name and password. If you are not using the occi tools provided
by OpenNebula, the password has to be SHA1 hashed as well as it is stored in the database instead of
using the plain version.
2.2.3
HTTP Headers
The following headers are compulsory:

Content-Length: The size of the Entity Body in octets
Content-Type: application/xml
Uploading images needs HTTP1 multi part support, and also the following header
Content-Type: multipart/form-data
2.2.4
Return Codes
The OpenNebula Cloud API2 uses the following subset of HTTP1 Status codes:
200 OK : The request has succeeded.
201 Created : Request was successful and a new resource has being created
202 Accepted : The request has been accepted for processing, but the processing has not been
completed
204 No Content : The request has been accepted for processing, but no info in the response
400 Bad Request : Malformed syntax
401 Unauthorized : Bad authentication
403 Forbidden : Bad authorization
404 Not Found : Resource not found
500 Internal Server Error : The server encountered an unexpected condition which prevented
it from fulfilling the request.
501 Not Implemented : The functionality requested is not supported
The methods specified below are described without taking into account 4xx (can be inferred from authorization information in section above) and 5xx errors (which are method independent). HTTP1 verbs
not defined for a particular entity will return a 501 Not Implemented.
2.2.5
Resource Representation
Network
The NETWORK element defines a virtual network that interconnects those COMPUTES with a network interface
card attached to that network. The traffic of each network is isolated from any other network, so it
constitutes a broadcasting domain.
The following elements define a NETWORK:
ID, the uuid of the NETWORK
NAME describing the NETWORK
USER link to the USER owner of the NETWORK
C12G Labs S.L.
12/93
Rev20121022
GROUP of the NETWORK

DESCRIPTION of the NETWORK
ADDRESS, of the NETWORK
SIZE, of the network, defaults to C
The elements in bold can be provided in a POST request in order to create a new NETWORK resource
based on those parameters.
Example:
1
2
3
4
5
6
7
8
9
<NETWORK h r e f= h t t p : //www. o p e n n e b u l a . o r g / network /123 >

<ID>123</ID>
<NAME>BlueNetwork</NAME>
<USER h r e f= h t t p : //www. o p e n n e b u l a . o r g / u s e r /33 name= c l o u d u s e r />
<GROUP>c l o u d g r o u p</GROUP>
<DESCRIPTION>T h i s NETWORK i s b l u e<DESCRIPTION>
<ADDRESS>1 9 2 . 1 6 8 . 0 . 1</ADDRESS>
<SIZE>C</ SIZE>
</NETWORK>
Storage
The STORAGE is a resource containing an operative system or data, to be used as a virtual machine disk:
ID the uuid of the STORAGE
NAME describing the STORAGE
USER link to the USER owner of the STORAGE
GROUP of the STORAGE
DESCRIPTION of the STORAGE
TYPE, type of the image
OS5 : contains a working operative system

CDROM: readonly data
DATABLOCK: storage for data, which can be accessed and modified from different Computes
SIZE, of the image in MBs
FSTYPE, in case of DATABLOCK, the type of filesystem desired
The elements in bold can be provided in a POST request in order to create a new NETWORK resource
based on those parameters.
Example:
1
2
3
4
5
6
7
8
9
<STORAGE h r e f= h t t p : //www. o p e n n e b u l a . o r g / s t o r a g e /123 >

<ID>123</ID>
<NAME>Ubuntu Desktop</NAME>
<USER h r e f= h t t p : //www. o p e n n e b u l a . o r g / u s e r /33 name= c l o u d u s e r />
<DESCRIPTION>Ubuntu 1 0 . 0 4 d e s k t o p f o r s t u d e n t s .</DESCRIPTION>
<TYPE>OS</TYPE>
<SIZE>2048</ SIZE>
</STORAGE>
5 Operating
System
C12G Labs S.L.
13/93
Rev20121022
Compute
The COMPUTE element defines a virtual machine by specifying its basic configuration attributes such as
NIC or DISK.
The following elements define a COMPUTE:
ID, the uuid of the COMPUTE.
NAME, describing the COMPUTE.
USER link to the USER owner of the COMPUTE
GROUP of the COMPUTE
CPU number of CPUs of the COMPUTE
MEMORY MBs of MEMORY of the COMPUTE
INSTANCE_TYPE, ink to a INSTANCE TYPE resource
DISK, the block devices attached to the virtual machine.
STORAGE link to a STORAGE resource

TARGET
SAVE_AS link to a STORAGE resource to save the disk image when the COMPUTE is DONE
TYPE
NIC, the network interfaces.
NETWORK link to a NETWORK resource

IP
MAC
CONTEXT, key value pairs to be passed on creation to the COMPUTE.
KEY1 VALUE1
KEY2 VALUE2
STATE, the state of the COMPUTE. This can be one of:
Example:
C12G Labs S.L.
14/93
Rev20121022
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<COMPUTE h r e f= h t t p : //www. o p e n n e b u l a . o r g / compute /32 >

<ID>32</ID>
<NAME>Web S e r v e r</NAME>
<CPU>1</CPU>
<MEMORY>1024</MEMORY>
<USER h r e f= h t t p : / / 0 . 0 . 0 . 0 : 4 5 6 7 / u s e r /310 name= c l o u d u s e r />
<INSTANCE TYPE h r e f= h t t p : / / 0 . 0 . 0 . 0 : 4 5 6 7 / i n s t a n c e t y p e / s m a l l >s m a l l</INSTANCE TYPE>
<STATE>ACTIVE</STATE>
<DISK>
<STORAGE h r e f= h t t p : //www. o p e n n e b u l a . o r g / s t o r a g e /34 name=Ubuntu10 . 0 4 />
<TYPE>OS</TYPE>
<TARGET>hda</TARGET>
</DISK>
<DISK>
<STORAGE h r e f= h t t p : //www. o p e n n e b u l a . o r g / s t o r a g e /24 name= t e s t i n g D B />
<SAVE AS h r e f= h t t p : //www. o p e n n e b u l a . o r g / s t o r a g e /54 />
<TYPE>CDROM</TYPE>
<TARGET>hdc</TARGET>
</DISK>
<NIC>
<NETWORK h r e f= h t t p : //www. o p e n n e b u l a . o r g / network /12 name=Private LAN />
<MAC>00 : f f : 7 2 : 3 1 : 2 3 : 1 7</MAC>
<IP>1 9 2 . 1 6 8 . 0 . 1 2</ IP>
</NIC>
<NIC>
<NETWORK h r e f= h t t p : //www. o p e n n e b u l a . o r g / network /10 name= P u b l i c I P s />
<MAC>00 : f f : 7 2 : 1 7 : 2 0 : 2 7</MAC>
<IP>1 9 2 . 1 6 8 . 0 . 2 5</ IP>
</NIC>
<CONTEXT>
<PUB KEY>FDASF324DSFA3241DASF</PUB KEY>
</CONTEXT>
</COMPUTE>
Instance type
An INSTANCE TYPE specifies the COMPUTE capacity values
ID, the uuid of the INSTANCE TYPE.
NAME, describing the INSTANCE TYPE.
CPU number of CPUs of the INSTANCE TYPE
MEMORY MBs of MEMORY of the INSTANCE TYPE
Example:
1
2
3
4
5
6
<INSTANCE TYPE h r e f= h t t p : //www. o p e n n e b u l a . o r g / i n s t a n c e t y p e / s m a l l >

<ID>s m a l l</ID>
<NAME>s m a l l</NAME>
<CPU>1</CPU>
</INSTANCE TYPE>
User
A USER specifies the COMPUTE capacity values
ID, the uuid of the INSTANCE TYPE.
NAME, describing the INSTANCE TYPE.
GROUP, fo the USER
QUOTA,
CPU:
MEMORY:
NUM_VMS:
C12G Labs S.L.
15/93
Rev20121022
STORAGE
USAGE,
CPU:
MEMORY:
NUM_VMS:
STORAGE
Example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<USER h r e f= h t t p : //www. o p e n n e b u l a . o r g / u s e r /42 >

<ID>42</ID>
<NAME>c l o u d u s e r</NAME>
<QUOTA>
<CPU>8</CPU>
<NUM VMS>10</NUM VMS>
<STORAGE>0</STORAGE>
</QUOTA>
<USAGE>
<CPU>2</CPU>
<NUM VMS>2</NUM VMS>
<STORAGE>0</STORAGE>
</USAGE>
</USER>
2.2.6
Request Methods
Method
URL3
Meaning / Entity Body
Response
GET
List the available collections in the cloud.
200 OK: An XML6

representation of the
the available collections in the http body
6 Extensible
Markup Language
C12G Labs S.L.
16/93
Rev20121022
Network
Method
URL3
GET
/network
POST
/network
GET
/network/<id>
PUT
/network/<id>
DELETE
/network/<id>
C12G Labs S.L.
Meaning / Entity Response

Body
List
the
contents 200 OK: An XML6
of the NETWORK representation of the
collection.
Option- collection in the http
ally a verbose param body
(/network?verbose=true)
can be provided to retrieve an extended
version of the collection
Create a new NET- 201 Created:
An
WORK. An XML6 rep- XML6 representation of
resentation of a NET- the new NETWORK
WORK without the with the ID
ID element should be
passed in the http body
Show the NETWORK 200 OK : An XML6
resource identified by representation of the
<id>
NETWORK in the http
body
Update the NET- 202 Accepted : The
WORK
resource update request is beidentified by <id>
ing process, polling required to confirm update
Delete the NET- 204 No Content:
WORK
resource
identified by <id>
17/93
Rev20121022
Storage
Method
URL3
GET
/storage
POST
/storage
GET
/storage/<id>
PUT
/storage/<id>
DELETE
/storage/<id>
C12G Labs S.L.

Body
List
the
of the STORAGE representation of the
collection.
(/storage?verbose=true)
Create an new STOR- 201 Created:
An
AGE. An XML6 repre- XML6 representation of
sentation of a STOR- the new NETWORK
AGE without the ID el- with the ID
ement should be passed
in the http body
Show the STORAGE 200 OK : An XML6
<id>
STORAGE in the http
body
Update the STOR- 202 Accepted : The
AGE resource identi- update request is befied by <id>
Delete the STORAGE 204 No Content:
resource identified by
<id>
18/93
Rev20121022
Compute
Method
URL3
GET
/compute
POST
/compute
GET
/compute/<id>
PUT
/compute/<id>
DELETE
/compute/<id>

Body
List
the
of the COMPUTE representation of the
collection.
Option- pool in the http body
ally a verbose param
(/compute?verbose=true)
Create a new COM- 201 Created:
An
PUTE. An XML6 XML6 representation of
representation of a the new COMPUTE
COMPUTE without with the ID
the ID element should
be passed in the http
body
Show the COMPUTE 200 OK : An XML6
<id>
network in the http
body
Update the COMM- 202 Accepted : The
PUTE resource identi- update request is befied by <id>
Delete the COM- 204 No Content: The
PUTE resource identi- Network has been sucfied by <id>
cessfully deleted
Instance type
Method
GET
GET
C12G Labs S.L.
URL3

Body
/instance_type
List the contents of 200 OK: An XML6
the INSTANCE TYPE representation of the
collection.
(/instance_type?verbose=true)
/instance_type/<id> Show
the
IN- 200 OK : An XML6
STANCE TYPE
resource identified by INSTANCE TYPE in
the http body
<id>
19/93
Rev20121022
User
Method
URL3
GET
/user
GET
/user/<id>
2.2.7
Meaning / Entity
Body
List
the
contents
of the USER collection.
Optionally
a
verbose
param
(/user?verbose=true)
Show the USER resource identified by
<id>
Response
200 OK: An XML6
collection in the http
body
200 OK : An XML6
USER in the http body
Implementation Notes
Authentication
It is recommended that the server-client communication is performed over HTTPS to avoid sending user
authentication information in plain text.
Notifications
HTTP1 protocol does not provide means for notification, so this API2 relies on asynchronous polling to
find whether a RESOURCE update is successful or not.
2.2.8
Examples
C12G Labs S.L.
20/93
Rev20121022
Chapter 3
System Interfaces
3.1
XML-RPC API
This reference documentation describes the xml-rpc methods exposed by OpenNebula. Each description
consists of the method name and the input and output values.
All xml-rpc responses share a common structure.
Type
OUT
OUT
OUT
Data Type
Boolean
String
Int
Description
True or false whenever is successful or not.
If an error occurs this is the error message.
Error code.
The output will always consist of three values. The first and third ones are fixed, but the second one
will contain the String error message only in case of failure. If the method is successful, the returned
value may be of another Data Type.
The Error Code will contain one of the following values:
Value
0x0000
0x0100
Code
SUCCESS
AUTHENTICATION
0x0200
AUTHORIZATION
0x0400
NO EXISTS
0x0800
0x1000
0x2000
ACTION
XML1 RPC2 API3
INTERNAL
Success response.
User could not be
authenticated.
User is not authorized to perform
the requested action.
The requested resource does not
exist.
All methods expect a session string associated to the connected user as the first parameter. It has
to be formed with the contents of the ONE AUTH file, which will be <username>:<password> with
the default core auth driver.
Each XML1 -RPC2 request has to be authenticated and authorized. See the Auth Subsystem documentation
for more information.
The information strings returned by the one.*.info methods are XML1 -formatted. The complete
1 Extensible
Markup Language
Procedure Call
3 Application Programming Interface
2 Remote
C12G Labs S.L.
21/93
Rev20121022
XML1 Schemas (XSD4 ) reference is included at the end of this page. We encourage you to use the -x
option of the command line interface to collect sample outputs from your own infrastructure.
The methods that accept XML1 templates require the root element to be TEMPLATE. For instance,
this template:
1
2
3
NAME = abc
MEMORY = 1024
ATT1 = v a l u e 1
Can be also given to OpenNebula with the following XML1 :

1
2
3
4
5
<TEMPLATE>
<NAME>abc</NAME>
<ATT1>v a l u e 1</ATT1>
</TEMPLATE>
inlinetoc
3.1.1
Authorization Requests Reference
For each XML1 -RPC2 request, the session token is authenticated, and after that the Request Manager
generates an authorization request that can include more than one operation. The following tables
document these requests.
onevm
onevm command
XML1 -RPC2 Method
deploy
one.vm.deploy
delete restart shutdown suspend

hold resubmit stop resume release cancel reset
resched unresched
migrate livemigrate
one.vm.action
saveas
one.vm.savedisk
attachdisk
one.vm.attach
detachdisk
create
one.vm.detach
one.vm.allocate
show
chown chgrp
one.vm.info
one.vm.chown
chmod
list top
one.vm.chmod
one.vmpool.info
one.vm.action
one.vm.migrate
Auth. Request
VM:ADMIN
HOST:MANAGE
VM:MANAGE
VM:ADMIN
VM:ADMIN
HOST:MANAGE
VM:MANAGE
IMAGE:CREATE
VM:MANAGE
IMAGE:USE
VM:MANAGE
VM:CREATE
IMAGE:USE
NET:USE
VM:USE
VM:MANAGE
[USER:MANAGE]
[GROUP:USE]
VM:<MANAGEADMIN>
VM:USE
The deploy action requires the user issuing the command to have VM:ADMIN rights. This user
will usually be the scheduler with the oneadmin credentials.
The scheduler deploys VMs to the Hosts over which the VM owner has MANAGE rights.
4 XML
(Extensible Markup Language) Schema Definition
C12G Labs S.L.
22/93
Rev20121022
onetemplate
onetemplate
command
update
instantiate
XML1 -RPC2 Method
Auth. Request
one.template.update
one.template.instantiate
create
clone
one.template.allocate
one.template.clone
delete
show
chown chgrp
one.template.delete
one.template.info
one.template.chown
chmod
list top
one.template.chmod
one.templatepool.info
TEMPLATE:MANAGE
TEMPLATE:USE
[IMAGE:USE] [NET:USE]
TEMPLATE:CREATE
TEMPLATE:CREATE
TEMPLATE:USE
TEMPLATE:MANAGE
TEMPLATE:USE
TEMPLATE:MANAGE
[USER:MANAGE]
[GROUP:USE]
TEMPLATE:<MANAGE
TEMPLATE:USE
ADMIN>
onehost
onehost
command
enable disable
update
create
delete
show
list top
XML1 -RPC2 Method
Auth. Request
one.host.enable
HOST:ADMIN
one.host.update
one.host.allocate
one.host.delete
one.host.info
one.hostpool.info
HOST:ADMIN
HOST:CREATE
HOST:ADMIN
HOST:USE
HOST:USE
onehost sync is not performed by the core, it is done by the ruby command onehost.
onecluster
onecluster command
create
delete
update
addhost
delhost
adddatastore
XML1 -RPC2 Method
Auth. Request
one.cluster.allocate
one.cluster.delete
one.cluster.update
one.cluster.addhost
one.cluster.delhost
one.cluster.adddatastore
deldatastore
one.cluster.deldatastore
addvnet
delvnet
show
list
one.cluster.addvnet
one.cluster.delvnet
one.cluster.info
one.clusterpool.info
CLUSTER:CREATE
CLUSTER:ADMIN
CLUSTER:MANAGE
CLUSTER:ADMIN HOST:ADMIN
CLUSTER:ADMIN HOST:ADMIN
CLUSTER:ADMIN
DATASTORE:ADMIN
CLUSTER:ADMIN
DATASTORE:ADMIN
CLUSTER:ADMIN NET:ADMIN
CLUSTER:ADMIN NET:ADMIN
CLUSTER:USE
CLUSTER:USE
C12G Labs S.L.
23/93
Rev20121022
onegroup
onegroup
command
create
delete
show
quota
list
XML1 -RPC2 Method
Auth. Request
one.group.allocate
one.group.delete
one.group.info
one.group.quota
one.grouppool.info
GROUP:CREATE
GROUP:ADMIN
GROUP:USE
GROUP:ADMIN
GROUP:USE
onevnet
onevnet
command
addleases
rmleases
hold
release
update
create
delete
show
chown chgrp
XML1 -RPC2 Method
Auth. Request
one.vn.addleases
one.vn.rmleases
one.vn.hold
one.vn.release
one.vn.update
one.vn.allocate
one.vn.delete
one.vn.info
one.vn.chown
chmod
list
one.vn.chmod
one.vnpool.info
NET:MANAGE
NET:MANAGE
NET:MANAGE
NET:MANAGE
NET:MANAGE
NET:CREATE
NET:MANAGE
NET:USE
NET:MANAGE
[USER:MANAGE]
[GROUP:USE]
NET:<MANAGE
NET:USE
ADMIN>
oneuser
oneuser
command
create
delete
show
passwd
update
chauth
quota
chgrp
encode
list
XML1 -RPC2 Method
Auth. Request
one.user.allocate
one.user.delete
one.user.info
one.user.passwd
one.user.update
one.user.chauth
one.user.quota
one.user.chgrp
one.userpool.info
USER:CREATE
USER:ADMIN
USER:USE
USER:MANAGE
USER:MANAGE
USER:ADMIN
USER:ADMIN
USER:MANAGE GROUP:USE
USER:USE
C12G Labs S.L.
24/93
Rev20121022
onedatastore
oneimage
command
create
delete
show
update
chown chgrp
XML1 -RPC2 Method
Auth. Request
one.datastore.allocate
one.datastore.delete
one.datastore.info
one.datastore.update
one.datastore.chown
chmod
list
one.datastore.chmod
one.datastorepool.info
DATASTORE:CREATE
DATASTORE:ADMIN
DATASTORE:USE
DATASTORE:MANAGE
DATASTORE:MANAGE
[USER:MANAGE]
[GROUP:USE]
DATASTORE:<MANAGE
DATASTORE:USE
ADMIN>
oneimage
oneimage command
persistent nonpersistent
enable disable
chtype
update
create
clone
XML1 -RPC2 Method

one.image.persistent
one.image.enable
one.image.chtype
one.image.update
one.image.allocate
one.image.clone
delete
show
chown chgrp
one.image.delete
one.image.info
one.image.chown
chmod
list top
one.image.chmod
one.imagepool.info
Auth. Request
IMAGE:MANAGE
IMAGE:MANAGE
IMAGE:MANAGE
IMAGE:MANAGE
IMAGE:CREATE
IMAGE:CREATE
AGE:USE
IMAGE:MANAGE
IMAGE:USE
IMAGE:MANAGE
[USER:MANAGE]
[GROUP:USE]
IMAGE:<MANAGE
IMAGE:USE
IM-
ADMIN>
oneacl
oneacl
command
create
delete
list
XML1 -RPC2 Method
Auth. Request
one.acl.addrule
one.acl.delrule
one.acl.info
ACL5 :MANAGE
ACL5 :MANAGE
ACL5 :MANAGE
oneacct
command
oneacct
5 Access
XML1 -RPC2 Method

one.vmpool.accounting
Auth. Request
VM:USE
Control List
C12G Labs S.L.
25/93
Rev20121022
documents
XML1 -RPC2 Method
one.document.update
one.document.allocate
one.document.delete
one.document.info
one.document.chown
Auth. Request
DOCUMENT:MANAGE
DOCUMENT:CREATE
DOCUMENT:MANAGE
DOCUMENT:USE
DOCUMENT:MANAGE
[USER:MANAGE] [GROUP:USE]
DOCUMENT:<MANAGE
DOCUMENT:USE
one.document.chmod
one.documentpool.info
ADMIN>
system
command
-
3.1.2
XML1 -RPC2 Method

one.system.version
Auth. Request
-
Actions for Templates Management
one.template.allocate
Description: Allocates a new template in OpenNebula.
Parameters
Type
IN
IN
Data Type
String
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
A string containing the template contents. Syntax can be the usual
attribute=value or XML1 .
true or false whenever is successful or not
The allocated resource ID / The error string.
Error code.
one.template.clone
Description: Clones an existing virtual machine template.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
String
Boolean
Int/String
Int
Description
The session string.
The ID of the template to be cloned.
Name for the new template.
The new template ID / The error string.
Error code.
one.template.delete
Description: Deletes the given template from the pool.
Parameters
C12G Labs S.L.
26/93
Rev20121022
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
The resource ID / The error string.
Error code.
one.template.instantiate
Description: Instantiates a new virtual machine from a template.
Parameters
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
Name for the new VM instance. If it is an empty string, OpenNebula
will assign one automatically.
The new virtual machine ID / The error string.
Error code.
one.template.update
Description: Replaces the template contents.
Parameters
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
The new template contents. Syntax can be the usual attribute=value
or XML1 .
Error code.
one.template.chmod
Description: Changes the permission bits of a template.
Parameters
C12G Labs S.L.
27/93
Rev20121022
Type
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Int
Int
Int
Int
Int
Int
Int
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
USER USE bit. If set to -1, it will not change.
USER MANAGE bit. If set to -1, it will not change.
USER ADMIN bit. If set to -1, it will not change.
GROUP USE bit. If set to -1, it will not change.
GROUP MANAGE bit. If set to -1, it will not change.
GROUP ADMIN bit. If set to -1, it will not change.
OTHER USE bit. If set to -1, it will not change.
OTHER MANAGE bit. If set to -1, it will not change.
OTHER ADMIN bit. If set to -1, it will not change.
Error code.
one.template.chown
Description: Changes the ownership of a template.
Parameters
Type
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
The User ID of the new owner. If set to -1, the owner is not changed.
The Group ID of the new group. If set to -1, the group is not changed.
Error code.
one.template.info
Description: Retrieves information for the template.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
String
Int
Description
The session string.
The object ID.
The information string / The error string.
Error code.
one.templatepool.info
Description: Retrieves information for all or part of the Resources in the pool.
Parameters
C12G Labs S.L.
28/93
Rev20121022
Type
IN
IN
IN
IN
OUT
OUT
OUT
Data
Type
String
Int
Description
The session string.

Filter flag - < = -3: Connected users resources - -2: All resources - -1: Connected users and his groups resources - > = 0: UID Users Resources
Int
Range start ID. Can be -1.
Int
Range end ID. Can be -1.
Boolean true or false whenever is successful or not
String
Int
Error code.
The range can be used to retrieve a subset of the pool, from the start to the end ID. To retrieve
the complete pool, use (-1, -1); to retrieve all the pool from a specific ID to the last one, use (<id>,
-1), and to retrieve the first elements up to an ID, use (0, <id>).
3.1.3
Actions for Virtual Machine Management
The VM Life Cycle is explained in this diagram:.

It contains all the LifeCycleManager states, and the transitions triggered by the onevm commands.
It is intended to be consulted by developers.
The simplified diagram used in the Virtual Machine Instances documentation uses a smaller number of state names. These names are the ones used by onevm list, e.g. prolog, prolog migrate and
prolog resume are all presented as prol. It is intended as a reference for end-users.
one.vm.allocate
Description: Allocates a new virtual machine in OpenNebula.
Parameters
Type
IN
IN
Data Type
String
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
A string containing the template for the vm. Syntax can be the usual
Error code.
one.vm.deploy
Description: initiates the instance of the given vmid on the target host.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Boolean
Int/String
Int
C12G Labs S.L.
Description
The session string.
The object ID.
The Host ID of the target host where the VM will be deployed.
The VM ID / The error string.
Error code.
29/93
Rev20121022
one.vm.action
Description: submits an action to be performed on a virtual machine.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
String
Int
Boolean
Int/String
Int
Description
The session string.
the action name to be performed, see below.
The object ID.
Error code.
The action String must be one of the following:

C12G Labs S.L.
30/93
Rev20121022
Action
shutdown
hold
release
stop
cancel
suspend
poweroff
resume
restart
reboot
finalize
resubmit
resched
unresched
reset
Description
one.vm.migrate
Description: migrates one virtual machine (vid) to the target host (hid).
Parameters
Type
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Boolean
Boolean
Int/String
Int
Description
The session string.
The object ID.
the target host id (hid) where we want to migrate the vm.
if true we are indicating that we want livemigration, otherwise false.
Error code.
one.vm.savedisk
Description: Sets the disk to be saved in the given image.
Parameters
Type
IN
IN
IN
IN
IN
Data Type
String
Int
Int
String
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
Disk ID of the disk we want to save.
Name for the new Image where the disk will be saved.
Type for the new Image. If it is an empty string, then the default one
will be used. See the existing types in the Image template reference.
The new allocated Image ID / The error string.
Error code.
one.vm.attach
Description: Attaches a new disk to the virtual machine
Parameters
C12G Labs S.L.
31/93
Rev20121022
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
A string containing a single DISK vector attribute. Syntax can be the
usual attribute=value or XML1 .
Error code.
one.vm.detach
Description: Detaches a disk from a virtual machine
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
The disk ID.
Error code.
one.vm.chmod
Description: Changes the permission bits of a virtual machine.
Parameters
Type
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Int
Int
Int
Int
Int
Int
Int
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.vm.chown
Description: Changes the ownership of a virtual machine.
Parameters
C12G Labs S.L.
32/93
Rev20121022
Type
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.vm.info
Description: Retrieves information for the virtual machine.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
String
Int
Description
The session string.
The object ID.
Error code.
one.vm.monitoring
Description: Returns the virtual machine monitoring records.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
String
Int
Description
The session string.
The object ID.
The monitoring information string / The error string.
Error code.
The monitoring information returned is a list of VM elements. Each VM element contains the complete
xml of the VM with the updated information returned by the poll action.
For example:
1
2
3
4
5
6
7
8
9
10
11
12
<MONITORING DATA>
<VM>
...
<LAST POLL>123</LAST POLL>
...
</VM>
<VM>
...
...
</VM>
</MONITORING DATA>
one.vmpool.info
Description: Retrieves information for all or part of the VMs in the pool.
Parameters
C12G Labs S.L.
33/93
Rev20121022
Type
IN
IN
IN
IN
IN
OUT
OUT
OUT
Data
Type
String
Int
Description
The session string.

Int
Int
Int
VM state to filter by.
String
Int
Error code.
The state filter can be one of the following:
Value
-2
-1
0
1
2
3
4
5
6
7
State
Any state, including DONE
Any state, except DONE
INIT
PENDING
HOLD
ACTIVE
STOPPED
SUSPENDED
DONE
FAILED
one.vmpool.monitoring
Description: Returns all the virtual machine monitoring records.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data
Type
String
Int
Description
The session string.

String
Int
Error code.
See one.vm.monitoring.
Sample output:
1
2
3
4
5
6
7
8
9
10
11
12
13
<MONITORING DATA>
<VM>
<ID>0</ID>
...
</VM>
<VM>
<ID>0</ID>
...
</VM>
<VM>
<ID>3</ID>
C12G Labs S.L.
34/93
Rev20121022
14
15
16
17
18
19
20
21
22

...
</VM>
<VM>
<ID>3</ID>
...
</VM>
</MONITORING DATA>
one.vmpool.accounting
Description: Returns the virtual machine history records.
Parameters
Type
IN
IN
IN
IN
OUT
OUT
OUT
Data
Type
String
Int
Description
The session string.

Int
Start time for the time interval. Can be -1, in which case the time interval wont
have a left boundary.
Int
End time for the time interval. Can be -1, in which case the time interval wont
have a right boundary.
String
Int
Error code.
The XML1 output is explained in detail in the accountingoneacct guide.
3.1.4
Actions for Hosts Management
one.host.allocate
Description: Allocates a new host in OpenNebula
Parameters
Type
IN
IN
IN
Data Type
String
String
String
IN
String
IN
String
IN
OUT
OUT
OUT
Int
Boolean
Int/String
Int
Description
The session string.
Hostname of the machine we want to add
The name of the information manager (im mad name), this values are
taken from the oned.conf with the tag name IM MAD (name)
The name of the virtual machine manager mad name
(vmm mad name), this values are taken from the oned.conf with the
tag name VM MAD (name)
The name of the virtual network manager mad name (vnm mad name),
see the Networking Subsystem documentation
The cluster ID. If it is -1, this host wont be added to any cluster.
The allocated Host ID / The error string.
Error code.
one.host.delete
Description: Deletes the given host from the pool
C12G Labs S.L.
35/93
Rev20121022
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.host.enable
Description: Enables or disables the given host
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Boolean
Int/String
Int
Description
The session string.
The Host ID.
Set it to true/false to enable or disable the target Host.
Error code.
one.host.update
Description: Replaces the hosts template contents.
Parameters
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
or XML1 .
Error code.
one.host.info
Description: Retrieves information for the host.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
String
Int
C12G Labs S.L.
Description
The session string.
The object ID.
Error code.
36/93
Rev20121022
one.host.monitoring
Description: Returns the host monitoring records.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
String
Int
Description
The session string.
The object ID.
The monitoring information string / The error string.
Error code.
The monitoring information returned is a list of HOST elements. Each HOST element contains the
complete xml of the host with the updated information returned by the poll action.
For example:
1
2
3
4
5
6
7
8
9
10
11
12
<MONITORING DATA>
<HOST>
...
<LAST MON TIME>123</LAST MON TIME>
...
</HOST>
<HOST>
...
...
</HOST>
</MONITORING DATA>
one.hostpool.info
Description: Retrieves information for all the hosts in the pool.
Parameters
Type
IN
OUT
OUT
OUT
Data Type
String
Boolean
String
Int
Description
The session string.
Error code.
one.hostpool.monitoring
Description: Returns all the host monitoring records.
Parameters
Type
IN
OUT
OUT
OUT
Data Type
String
Boolean
String
Int
Description
The session string.
Error code.
See one.host.monitoring.
Sample output:
1
2
3
4
5
6
7
<MONITORING DATA>
<HOST>
<ID>0</ID>
...
</HOST>
<HOST>
C12G Labs S.L.
37/93
Rev20121022
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<ID>0</ID>
...
</HOST>
<HOST>
<ID>3</ID>
...
</HOST>
<HOST>
<ID>3</ID>
...
</HOST>
</MONITORING DATA>
3.1.5
Actions for Cluster Management
one.cluster.allocate
Description: Allocates a new cluster in OpenNebula.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
String
Boolean
Int/String
Int
Description
The session string.
Name for the new cluster.
The allocated cluster ID / The error string.
Error code.
one.cluster.delete
Description: Deletes the given cluster from the pool.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.cluster.update
Description: Replaces the cluster template contents.
Parameters
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
C12G Labs S.L.
Description
The session string.
The object ID.
or XML1 .
Error code.
38/93
Rev20121022
one.cluster.addhost
Description: Adds a host to the given cluster.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Boolean
Int/String
Int
Description
The session string.
The cluster ID.
The host ID.
Error code.
one.cluster.delhost
Description: Removes a host from the given cluster.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Boolean
Int/String
Int
Description
The session string.
The cluster ID.
The host ID.
Error code.
one.cluster.adddatastore
Description: Adds a datastore to the given cluster.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Boolean
Int/String
Int
Description
The session string.
The cluster ID.
The datastore ID.
Error code.
one.cluster.deldatastore
Description: Removes a datastore from the given cluster.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Boolean
Int/String
Int
C12G Labs S.L.
Description
The session string.
The cluster ID.
The datastore ID.
Error code.
39/93
Rev20121022
one.cluster.addvnet
Description: Adds a vnet to the given cluster.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Boolean
Int/String
Int
Description
The session string.
The cluster ID.
The vnet ID.
Error code.
one.cluster.delvnet
Description: Removes a vnet from the given cluster.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Boolean
Int/String
Int
Description
The session string.
The cluster ID.
The vnet ID.
Error code.
one.cluster.info
Description: Retrieves information for the cluster.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
String
Int
Description
The session string.
The object ID.
Error code.
one.clusterpool.info
Description: Retrieves information for all the clusters in the pool.
Parameters
Type
IN
OUT
OUT
OUT
Data Type
String
Boolean
String
Int
C12G Labs S.L.
Description
The session string.
Error code.
40/93
Rev20121022
3.1.6
Actions for Virtual Network Management
one.vn.allocate
Description: Allocates a new virtual network in OpenNebula.
Parameters
Type
IN
IN
Data Type
String
String
IN
Int
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
A string containing the template of the virtual network. Syntax can
be the usual attribute=value or XML1 .
The cluster ID. If it is -1, this virtual network wont be added to any
cluster.
Error code.
one.vn.delete
Description: Deletes the given virtual network from the pool.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.vn.addleases
Description: Adds a new lease to the virtual network. Only available for FIXED networks.
Parameters
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
template of the lease to add. Syntax can be the usual attribute=value
or XML1 , see below.
Error code.
Examples of valid templates:

1
LEASES=[ IP = 1 9 2 . 1 6 8 . 0 . 5 ]
LEASES=[ IP = 1 9 2 . 1 6 8 . 0 . 5 , MAC= 5 0 : 2 0 : 2 0 : 2 0 : 2 0 : 2 0 ]
1
2
3
4
5
<TEMPLATE>
<LEASES>
<IP>1 9 2 . 1 6 8 . 0 . 5</ IP>
</LEASES>
</TEMPLATE>
C12G Labs S.L.
41/93
Rev20121022
1
2
3
4
5
6
<TEMPLATE>
<LEASES>
<IP>1 9 2 . 1 6 8 . 0 . 5</ IP>
<MAC>MAC=50 : 2 0 : 2 0 : 2 0 : 2 0 : 2 0</MAC>
</LEASES>
</TEMPLATE>
one.vn.rmleases
Description: Removes a lease from the virtual network. Only available for FIXED networks.
Parameters
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
template of the lease to remove. Syntax can be the usual attribute=value or XML1 , see one.vn.addleases.
Error code.
one.vn.hold
Description: Holds a virtual network Lease as used.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
String
Boolean
Int/String
Int
Description
The session string.
The object ID.
template of the lease to hold, e.g. LEASES=[IP=192.168.0.5].
Error code.
one.vn.release
Description: Releases a virtual network Lease on hold.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
String
Boolean
Int/String
Int
Description
The session string.
The object ID.
template of the lease to release, e.g. LEASES=[IP=192.168.0.5].
Error code.
one.vn.update
Description: Replaces the virtual network template contents.
Parameters
C12G Labs S.L.
42/93
Rev20121022
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
or XML1 .
Error code.
one.vn.chmod
Description: Changes the permission bits of a virtual network.
Parameters
Type
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Int
Int
Int
Int
Int
Int
Int
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.vn.chown
Description: Changes the ownership of a virtual network.
Parameters
Type
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.vn.info
Description: Retrieves information for the virtual network.
Parameters
C12G Labs S.L.
43/93
Rev20121022
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
String
Int
Description
The session string.
The object ID.
Error code.
one.vnpool.info
Description: Retrieves information for all or part of the virtual networks in the pool.
Parameters
Type
IN
IN
IN
IN
OUT
OUT
OUT
Data
Type
String
Int
Description
The session string.

Int
Int
String
Int
Error code.
3.1.7
Actions for Datastore Management
one.datastore.allocate
Description: Allocates a new datastore in OpenNebula.
Parameters
Type
IN
IN
Data Type
String
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
A string containing the template of the datastore. Syntax can be the
usual attribute=value or XML1 .
Error code.
one.datastore.delete
Description: Deletes the given datastore from the pool.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Int/String
Int
C12G Labs S.L.
Description
The session string.
The object ID.
Error code.
44/93
Rev20121022
one.datastore.update
Description: Replaces the datastore template contents.
Parameters
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
or XML1 .
Error code.
one.datastore.chmod
Description: Changes the permission bits of a datastore.
Parameters
Type
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Int
Int
Int
Int
Int
Int
Int
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.datastore.chown
Description: Changes the ownership of a datastore.
Parameters
Type
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Int
Boolean
Int/String
Int
C12G Labs S.L.
Description
The session string.
The object ID.
Error code.
45/93
Rev20121022
one.datastore.info
Description: Retrieves information for the datastore.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
String
Int
Description
The session string.
The object ID.
Error code.
one.datastorepool.info
Description: Retrieves information for all or part of the datastores in the pool.
Parameters
Type
IN
OUT
OUT
OUT
3.1.8
Data Type
String
Boolean
String
Int
Description
The session string.
Error code.
Actions for Image Management
one.image.allocate
Description: Allocates a new image in OpenNebula.
Parameters
Type
IN
IN
Data Type
String
String
IN
OUT
OUT
OUT
Int
Boolean
Int/String
Int
Description
The session string.
A string containing the template of the image. Syntax can be the usual
The datastore ID.
Error code.
one.image.clone
Description: Clones an existing image.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
String
Boolean
Int/String
Int
C12G Labs S.L.
Description
The session string.
The ID of the image to be cloned.
Name for the new image.
The new image ID / The error string.
Error code.
46/93
Rev20121022
one.image.delete
Description: Deletes the given image from the pool.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.image.enable
Description: Enables or disables an image.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Boolean
Int/String
Int
Description
The session string.
The Image ID.
True for enabling, false for disabling.
true or false whenever is successful or not.
The Image ID / The error string.
Error code.
one.image.persistent
Description: Sets the Image as persistent or not persistent.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Boolean
Int/String
Int
Description
The session string.
The Image ID.
True for persistent, false for non-persisent.
Error code.
one.image.chtype
Description: Changes the type of an Image.
Parameters
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
C12G Labs S.L.
Description
The session string.
The Image ID.
New type for the Image.
See the existing types in the
Image template reference.
Error code.
47/93
Rev20121022
one.image.update
Description: Replaces the image template contents.
Parameters
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
or XML1 .
Error code.
one.image.chmod
Description: Changes the permission bits of an image.
Parameters
Type
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Int
Int
Int
Int
Int
Int
Int
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.image.chown
Description: Changes the ownership of an image.
Parameters
Type
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Int
Boolean
Int/String
Int
C12G Labs S.L.
Description
The session string.
The object ID.
Error code.
48/93
Rev20121022
one.image.info
Description: Retrieves information for the image.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
String
Int
Description
The session string.
The object ID.
Error code.
one.imagepool.info
Description: Retrieves information for all or part of the images in the pool.
Parameters
Type
IN
IN
IN
IN
OUT
OUT
OUT
Data
Type
String
Int
Description
The session string.

Int
Int
String
Int
Error code.
3.1.9
Actions for User Management
one.user.allocate
Description: Allocates a new user in OpenNebula
Parameters
Type
IN
IN
IN
IN
Data Type
String
String
String
String
OUT
OUT
OUT
Boolean
Int/String
Int
C12G Labs S.L.
Description
The session string.
username for the new user
password for the new user
authentication driver for the new user. If it is an empty string, then
the default (core) is used
The allocated User ID / The error string.
Error code.
49/93
Rev20121022
one.user.delete
Description: Deletes the given user from the pool.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.user.passwd
Description: Changes the password for the given user.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
String
Boolean
Int/String
Int
Description
The session string.
The object ID.
The new password
The User ID / The error string.
Error code.
one.user.update
Description: Replaces the user template contents.
Parameters
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
or XML1 .
Error code.
one.user.chauth
Description: Changes the authentication driver and the password for the given user.
Parameters
Type
IN
IN
IN
IN
Data Type
String
Int
String
String
OUT
OUT
OUT
Boolean
Int/String
Int
C12G Labs S.L.
Description
The session string.
The object ID.
The new authentication driver.
The new password. If it is an empty string, the password is not
changed.
Error code.
50/93
Rev20121022
one.user.quota
Description: Sets the user quota limits.
Parameters
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
The new quota template contents. Syntax can be the usual attribute=value or XML1 .
Error code.
one.user.chgrp
Description: Changes the group of the given user.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Boolean
Int/String
Int
Description
The session string.
The User ID.
The Group ID of the new group.
Error code.
one.user.info
Description: Retrieves information for the user.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data
Type
String
Int
Boolean
String
Int
Description
The session string.
The object ID. If it is -1, then the connected users own info info is returned
Error code.
one.userpool.info
Description: Retrieves information for all the users in the pool.
Parameters
C12G Labs S.L.
51/93
Rev20121022
Type
IN
OUT
OUT
OUT
3.1.10
Data Type
String
Boolean
String
Int
Description
The session string.
Error code.
Actions for Group Management
one.group.allocate
Description: Allocates a new group in OpenNebula.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
String
Boolean
Int/String
Int
Description
The session string.
Name for the new group.
The allocated Group ID / The error string.
Error code.
one.group.delete
Description: Deletes the given group from the pool.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.group.info
Description: Retrieves information for the group.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data
Type
String
Int
Boolean
String
Int
Description
The session string.
The object ID. If it is -1, then the connected users group info info is returned
Error code.
one.group.quota
Description: Sets the group quota limits.
Parameters
C12G Labs S.L.
52/93
Rev20121022
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
The new quota template contents. Syntax can be the usual attribute=value or XML1 .
Error code.
one.grouppool.info
Description: Retrieves information for all the groups in the pool.
Parameters
Type
IN
OUT
OUT
OUT
3.1.11
Data Type
String
Boolean
String
Int
Description
The session string.
Error code.
Actions for ACL Rules Management
one.acl.addrule
Description: Adds a new ACL5 rule.
Parameters
Type
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
String
String
String
Boolean
Int/String
Int
Description
The session string.
User component of the new rule. A string containing a hex number.
Resource component of the new rule. A string containing a hex number.
Rights component of the new rule. A string containing a hex number.
The allocated ACL5 rule ID / The error string.
Error code.
To build the hex. numbers required to create a new rule we recommend you to read the ruby or java
code.
one.acl.delrule
Description: Deletes an ACL5 rule.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Int/String
Int
C12G Labs S.L.
Description
The session string.
ACL5 rule ID.
The ACL5 rule ID / The error string.
Error code.
53/93
Rev20121022
one.acl.info
Description: Returns the complete ACL5 rule set.
Parameters
Type
IN
IN
OUT
OUT
OUT
3.1.12
Data Type
String
Int
Boolean
String
Int
Description
The session string.
ACL5 rule ID.
Error code.
Actions for Document Management
one.document.allocate
Description: Allocates a new document in OpenNebula.
Parameters
Type
IN
IN
Data Type
String
String
IN
OUT
OUT
OUT
Int
Boolean
Int/String
Int
Description
The session string.
A string containing the document template contents. Syntax can be
the usual attribute=value or XML1 .
The document type (*).
Error code.
(*) Type is an integer value used to allow dynamic pools compartmentalization.

Lets say you want to store documents representing Chef recipes, and EC2 security groups; you would
allocate documents of each kind with a different type. This type is then used in the one.documentpool.info
method to filter the results.
one.document.clone
Description: Clones an existing virtual machine document.
Parameters
Type
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
String
Boolean
Int/String
Int
Description
The session string.
The ID of the document to be cloned.
Name for the new document.
The new document ID / The error string.
Error code.
one.document.delete
Description: Deletes the given document from the pool.
Parameters
C12G Labs S.L.
54/93
Rev20121022
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.document.update
Description: Replaces the document template contents.
Parameters
Type
IN
IN
IN
Data Type
String
Int
String
OUT
OUT
OUT
Boolean
Int/String
Int
Description
The session string.
The object ID.
The new document template contents. Syntax can be the usual attribute=value or XML1 .
Error code.
one.document.chmod
Description: Changes the permission bits of a document.
Parameters
Type
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Int
Int
Int
Int
Int
Int
Int
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.document.chown
Description: Changes the ownership of a document.
Parameters
C12G Labs S.L.
55/93
Rev20121022
Type
IN
IN
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Int
Int
Boolean
Int/String
Int
Description
The session string.
The object ID.
Error code.
one.document.info
Description: Retrieves information for the document.
Parameters
Type
IN
IN
OUT
OUT
OUT
Data Type
String
Int
Boolean
String
Int
Description
The session string.
The object ID.
Error code.
one.documentpool.info
Description: Retrieves information for all or part of the Resources in the pool.
Parameters
Type
IN
IN
IN
IN
IN
OUT
OUT
OUT
Data
Type
String
Int
Description
The session string.

Int
Int
Int
The document type. See one.document.allocate
String
Int
Error code.
3.1.13
System Methods
one.system.version
Description: Returns the OpenNebula core version
Parameters
Type
IN
OUT
OUT
OUT
Data Type
String
Boolean
String
Int
C12G Labs S.L.
Description
The session string.
The OpenNebula version, e.g. 3.8.0
Error code.
56/93
Rev20121022
3.1.14
The
XML1
XSD Reference
schemas describe the XML1 returned by the one.*.info methods
Schemas for Cluster

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<?xml version= 1 . 0 e n c o d i n g=UTF8 ?>

<x s : s c h e m a x m l n s : x s= h t t p : //www. w3 . o r g /2001/XMLSchema e l e m e n t F o r m D e f a u l t= q u a l i f i e d
t a r g e t N a m e s p a c e= h t t p : // o p e n n e b u l a . o r g /XMLSchema xmlns= h t t p : // o p e n n e b u l a . o r g /XMLSchema>
<x s : e l e m e n t name=CLUSTER>
<x s : c o m p l e x T y p e>
<x s : s e q u e n c e>
<x s : e l e m e n t name=ID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=NAME t y p e= x s : s t r i n g />
<x s : e l e m e n t name=HOSTS>
<x s : e l e m e n t name=ID t y p e= x s : i n t e g e r minOccurs=0 maxOccurs=unbounded />
</ x s : s e q u e n c e>
</ x s : c o m p l e x T y p e>
</ x s : e l e m e n t>
<x s : e l e m e n t name=DATASTORES>
</ x s : e l e m e n t>
<x s : e l e m e n t name=VNETS>
</ x s : e l e m e n t>
<x s : e l e m e n t name=TEMPLATE t y p e=x s : a n y T y p e />
</ x s : e l e m e n t>
</ x s : s c h e m a>
1
2
3
4
5
6
7
8
9
10
11
12

< x s : i n c l u d e s c h e m a L o c a t i o n= c l u s t e r . xsd />
<x s : e l e m e n t name=CLUSTER POOL>
<x s : s e q u e n c e maxOccurs=1 minOccurs=1 >
<x s : e l e m e n t r e f=CLUSTER maxOccurs=unbounded minOccurs=0 />
</ x s : e l e m e n t>
</ x s : s c h e m a>
Schemas for Datastore

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<x s : s c h e m a x m l n s : x s= h t t p : //www. w3 . o r g /2001/XMLSchema xmlns= h t t p : // o p e n n e b u l a . o r g /XMLSchema
e l e m e n t F o r m D e f a u l t= q u a l i f i e d t a r g e t N a m e s p a c e= h t t p : // o p e n n e b u l a . o r g /XMLSchema>
<x s : e l e m e n t name=DATASTORE>
<x s : e l e m e n t name=UID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=GID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=UNAME t y p e= x s : s t r i n g />
<x s : e l e m e n t name=GNAME t y p e= x s : s t r i n g />
<x s : e l e m e n t name=PERMISSIONS minOccurs=0 maxOccurs=1 >
<x s : e l e m e n t name=OWNER U t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=OWNER M t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=OWNER A t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=GROUP U t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=GROUP M t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=GROUP A t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=OTHER U t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=OTHER M t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=OTHER A t y p e= x s : i n t e g e r />
C12G Labs S.L.
57/93
Rev20121022
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
</ x s : e l e m e n t>
<x s : e l e m e n t name=DS MAD t y p e= x s : s t r i n g />
<x s : e l e m e n t name=TM MAD t y p e= x s : s t r i n g />
<x s : e l e m e n t name=BASE PATH t y p e= x s : s t r i n g />
<x s : e l e m e n t name=SYSTEM t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=DISK TYPE t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=CLUSTER ID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=CLUSTER t y p e= x s : s t r i n g />
<x s : e l e m e n t name=IMAGES>
</ x s : e l e m e n t>
</ x s : e l e m e n t>
</ x s : s c h e m a>
1
2
3
4
5
6
7
8
9
10
11
12

< x s : i n c l u d e s c h e m a L o c a t i o n= d a t a s t o r e . xsd />
<x s : e l e m e n t name=DATASTORE POOL>
<x s : e l e m e n t r e f=DATASTORE maxOccurs=unbounded minOccurs=0 />
</ x s : e l e m e n t>
</ x s : s c h e m a>
Schemas for Group

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

<x s : e l e m e n t name=GROUP>
<x s : e l e m e n t name=USERS>
</ x s : e l e m e n t>
<x s : e l e m e n t name=DATASTORE QUOTA minOccurs=0 maxOccurs=1 >
<x s : e l e m e n t name=DATASTORE minOccurs=0 maxOccurs=unbounded >
<x s : e l e m e n t name=ID t y p e= x s : s t r i n g />
<x s : e l e m e n t name=IMAGES t y p e= x s : s t r i n g />
<x s : e l e m e n t name=IMAGES USED t y p e= x s : s t r i n g />
<x s : e l e m e n t name=SIZE t y p e= x s : s t r i n g />
<x s : e l e m e n t name=SIZE USED t y p e= x s : s t r i n g />
</ x s : e l e m e n t>
</ x s : e l e m e n t>
<x s : e l e m e n t name=NETWORK QUOTA minOccurs=0 maxOccurs=1 >
<x s : e l e m e n t name=NETWORK minOccurs=0 maxOccurs=unbounded >
<x s : e l e m e n t name=LEASES t y p e= x s : s t r i n g />
<x s : e l e m e n t name=LEASES USED t y p e= x s : s t r i n g />
</ x s : e l e m e n t>
C12G Labs S.L.
58/93
Rev20121022
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
</ x s : e l e m e n t>
<x s : e l e m e n t name=VM QUOTA minOccurs=0 maxOccurs=1 >
<x s : e l e m e n t name=VM minOccurs=0 maxOccurs=1 >
<x s : e l e m e n t name=CPU t y p e= x s : s t r i n g />
<x s : e l e m e n t name=CPU USED t y p e= x s : s t r i n g />
<x s : e l e m e n t name=MEMORY t y p e= x s : s t r i n g />
<x s : e l e m e n t name=MEMORY USED t y p e= x s : s t r i n g />
<x s : e l e m e n t name=VMS t y p e= x s : s t r i n g />
<x s : e l e m e n t name=VMS USED t y p e= x s : s t r i n g />
</ x s : e l e m e n t>
</ x s : e l e m e n t>
<x s : e l e m e n t name=IMAGE QUOTA minOccurs=0 maxOccurs=1 >
<x s : e l e m e n t name=IMAGE minOccurs=0 maxOccurs=unbounded >
<x s : e l e m e n t name=RVMS t y p e= x s : s t r i n g />
<x s : e l e m e n t name=RVMS USED t y p e= x s : s t r i n g />
</ x s : e l e m e n t>
</ x s : e l e m e n t>
</ x s : e l e m e n t>
</ x s : s c h e m a>
1
2
3
4
5
6
7
8
9
10
11
12

< x s : i n c l u d e s c h e m a L o c a t i o n=group . xsd />
<x s : e l e m e n t name=GROUP POOL>
<x s : e l e m e n t r e f=GROUP maxOccurs=unbounded minOccurs=0 />
</ x s : e l e m e n t>
</ x s : s c h e m a>
Schemas for Host

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<x s : e l e m e n t name=HOST>
< ! STATE v a l u e s
INIT
= 0
I n i t i a l s t a t e for enabled hosts
MONITORING MONITORED = 1
Monitoring t h e h o s t ( from monitored )
MONITORED
= 2 The h o s t has been s u c c e s s f u l l y monitored
ERROR
= 3 An e r r o r o c u r r e r w h i l e m o n i t o r i n g t h e h o s t
DISABLED
= 4 The h o s t i s d i s a b l e d won t be m o n i t o r e d
MONITORING ERROR
= 5
M o n i t o r i n g t h e h o s t ( from e r r o r )
>
<x s : e l e m e n t name=STATE t y p e =x s : i n t e g e r />
<x s : e l e m e n t name=IM MAD t y p e =x s : s t r i n g />
<x s : e l e m e n t name=VM MAD t y p e =x s : s t r i n g />
<x s : e l e m e n t name=VN MAD t y p e =x s : s t r i n g />
<x s : e l e m e n t name=LAST MON TIME t y p e =x s : i n t e g e r />
<x s : e l e m e n t name=CLUSTER ID t y p e =x s : i n t e g e r />
<x s : e l e m e n t name=CLUSTER t y p e =x s : s t r i n g />
<x s : e l e m e n t name=HOST SHARE>
<xs:complexType>
<x s : s e q u e n c e >
<x s : e l e m e n t name=DISK USAGE t y p e =x s : i n t e g e r />
C12G Labs S.L.
59/93
Rev20121022
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
<x s : e l e m e n t name=MEM USAGE t y p e =x s : i n t e g e r />

<! KB, Usage o f MEMORY c a l c u l a t e d by ONE a s t h e summatory MEMORY r e q u e s t e d by a l l
VMs r u n n i n g i n t h e h o s t
>
<x s : e l e m e n t name=CPU USAGE t y p e =x s : i n t e g e r />
<! P e r c e n t a g e , Usage o f CPU c a l c u l a t e d by ONE a s t h e summatory CPU r e q u e s t e d by
a l l VMs r u n n i n g i n t h e h o s t
>
<x s : e l e m e n t name=MAX DISK t y p e =x s : i n t e g e r />
<x s : e l e m e n t name=MAX MEM t y p e =x s : i n t e g e r />
<! KB, T o t a l memory i n t h e h o s t
>
<x s : e l e m e n t name=MAX CPU t y p e =x s : i n t e g e r />
<! P e r c e n t a g e , T o t a l CPU i n t h e h o s t (# c o r e s * 1 0 0 ) >
<x s : e l e m e n t name=FREE DISK t y p e =x s : i n t e g e r />
<x s : e l e m e n t name=FREE MEM t y p e =x s : i n t e g e r />
<! KB, F r e e MEMORY r e t u r n e d by t h e p r o b e s
>
<x s : e l e m e n t name=FREE CPU t y p e =x s : i n t e g e r />
<! P e r c e n t a g e , F r e e CPU a s r e t u r n e d by t h e p r o b e s
>
<x s : e l e m e n t name=USED DISK t y p e =x s : i n t e g e r />
<x s : e l e m e n t name=USED MEM t y p e =x s : i n t e g e r />
<! KB, Memory u s e d by a l l h o s t p r o c e s s e s ( i n c l u d i n g VMs) o v e r a t o t a l o f MAX MEM
>
<x s : e l e m e n t name=USED CPU t y p e =x s : i n t e g e r />
<! P e r c e n t a g e o f CPU u s e d by a l l h o s t p r o c e s s e s ( i n c l u d i n g VMs) o v e r a t o t a l o f #
c o r e s * 100
>
<x s : e l e m e n t name=RUNNING VMS t y p e =x s : i n t e g e r />
</ x s : s e q u e n c e >
</xs:complexType>
</ x s : e l e m e n t >
<x s : e l e m e n t name=TEMPLATE t y p e =x s : a n y T y p e />
</ x s : s e q u e n c e >
</xs:complexType>
</ x s : e l e m e n t >
</x s : s c h e m a >
1
2
3
4
5
6
7
8
9
10
11
12

< x s : i n c l u d e s c h e m a L o c a t i o n= h o s t . xsd />
<x s : e l e m e n t name=HOST POOL>
<x s : e l e m e n t r e f=HOST maxOccurs=unbounded minOccurs=0 />
</ x s : e l e m e n t>
</ x s : s c h e m a>
Schemas for Image

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

<x s : e l e m e n t name=IMAGE>
</ x s : e l e m e n t>
<x s : e l e m e n t name=TYPE t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=DISK TYPE t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=PERSISTENT t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=REGTIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=SOURCE t y p e= x s : s t r i n g />
<x s : e l e m e n t name=PATH t y p e= x s : s t r i n g />
<x s : e l e m e n t name=FSTYPE t y p e= x s : s t r i n g />
<x s : e l e m e n t name=SIZE t y p e= x s : i n t e g e r />
C12G Labs S.L.
60/93
Rev20121022
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
< ! STATE v a l u e s ,
INIT
= 0, Initialization state
READY
= 1 , Image ready t o use
USED
= 2 , Image i n use
DISABLED = 3 , Image can not be i n s t a n t i a t e d by a VM
LOCKED
= 4 , FS o p e r a t i o n f o r t h e Image i n p r o c e s s
ERROR
= 5 , Error s t a t e t h e o p e r a t i o n FAILED
CLONE
= 6 , Image i s b e i n g c l o n e d
DELETE
= 7 , DS i s d e l e t i n g t h e image
USED PERS = 8 , Image i s i n use and p e r s i s t e n t
>
<x s : e l e m e n t name=STATE t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=RUNNING VMS t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=CLONING OPS t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=CLONING ID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=DATASTORE ID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=DATASTORE t y p e= x s : s t r i n g />
</ x s : e l e m e n t>
</ x s : s c h e m a>
1
2
3
4
5
6
7
8
9
10
11
12

< x s : i n c l u d e s c h e m a L o c a t i o n=image . xsd />
<x s : e l e m e n t name=IMAGE POOL>
<x s : e l e m e n t r e f=IMAGE maxOccurs=unbounded minOccurs=0 />
</ x s : e l e m e n t>
</ x s : s c h e m a>
Schemas for User

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

<x s : e l e m e n t name=USER>
<x s : e l e m e n t name=PASSWORD t y p e= x s : s t r i n g />
<x s : e l e m e n t name=AUTH DRIVER t y p e= x s : s t r i n g />
<x s : e l e m e n t name=ENABLED t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=DATASTORE QUOTA minOccurs=0 maxOccurs=1 >
<x s : e l e m e n t name=DATASTORE minOccurs=0 maxOccurs=unbounded >
<x s : e l e m e n t name=IMAGES t y p e= x s : s t r i n g />
<x s : e l e m e n t name=IMAGES USED t y p e= x s : s t r i n g />
<x s : e l e m e n t name=SIZE t y p e= x s : s t r i n g />
<x s : e l e m e n t name=SIZE USED t y p e= x s : s t r i n g />
</ x s : e l e m e n t>
</ x s : e l e m e n t>
<x s : e l e m e n t name=NETWORK QUOTA minOccurs=0 maxOccurs=1 >
<x s : e l e m e n t name=NETWORK minOccurs=0 maxOccurs=unbounded >
<x s : e l e m e n t name=LEASES t y p e= x s : s t r i n g />
<x s : e l e m e n t name=LEASES USED t y p e= x s : s t r i n g />
</ x s : e l e m e n t>
C12G Labs S.L.
61/93
Rev20121022
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
</ x s : e l e m e n t>
<x s : e l e m e n t name=VM QUOTA minOccurs=0 maxOccurs=1 >
<x s : e l e m e n t name=VM minOccurs=0 maxOccurs=1 >
<x s : e l e m e n t name=CPU t y p e= x s : s t r i n g />
<x s : e l e m e n t name=CPU USED t y p e= x s : s t r i n g />
<x s : e l e m e n t name=MEMORY t y p e= x s : s t r i n g />
<x s : e l e m e n t name=MEMORY USED t y p e= x s : s t r i n g />
<x s : e l e m e n t name=VMS t y p e= x s : s t r i n g />
<x s : e l e m e n t name=VMS USED t y p e= x s : s t r i n g />
</ x s : e l e m e n t>
</ x s : e l e m e n t>
<x s : e l e m e n t name=IMAGE QUOTA minOccurs=0 maxOccurs=1 >
<x s : e l e m e n t name=IMAGE minOccurs=0 maxOccurs=unbounded >
<x s : e l e m e n t name=RVMS t y p e= x s : s t r i n g />
<x s : e l e m e n t name=RVMS USED t y p e= x s : s t r i n g />
</ x s : e l e m e n t>
</ x s : e l e m e n t>
</ x s : e l e m e n t>
</ x s : s c h e m a>
1
2
3
4
5
6
7
8
9
10
11
12

< x s : i n c l u d e s c h e m a L o c a t i o n= u s e r . xsd />
<x s : e l e m e n t name=USER POOL>
<x s : e l e m e n t r e f=USER maxOccurs=unbounded minOccurs=0 />
</ x s : e l e m e n t>
</ x s : s c h e m a>
Schemas for Virtual Machine

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<x s : e l e m e n t name=VM>
</ x s : e l e m e n t>
<x s : e l e m e n t name=LAST POLL t y p e= x s : i n t e g e r />
C12G Labs S.L.
62/93
Rev20121022
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
s e e h t t p : // o p e n n e b u l a . o r g / media / d o c u m e n t a t i o n : r e l 3 . 6 : s t a t e s c o m p l e t e . png
INIT
PENDING
HOLD
ACTIVE
STOPPED
SUSPENDED
DONE
FAILED
POWEROFF
>
<x s : e l e m e n t
=
=
=
=
=
=
=
=
=
0
1
2
3 In t h i s s t a t e , t h e L i f e C y c l e Manager s t a t e
4
5
6
7
8
is
relevant
name=STATE t y p e= x s : i n t e g e r />
< ! LCM STATE v a l u e s ,

ACTIVE ( 4 )
t h i s sub s t a t e
is
r e l e v a n t o n l y when STATE i s
LCM INIT
= 0
PROLOG
= 1
BOOT
= 2
RUNNING
= 3
MIGRATE
= 4
SAVE STOP
= 5
SAVE SUSPEND
= 6
SAVE MIGRATE
= 7
PROLOG MIGRATE
= 8
PROLOG RESUME
= 9
EPILOG STOP
= 10
EPILOG
= 11
SHUTDOWN
= 12
CANCEL
= 13
FAILURE
= 14
CLEANUP
= 15
UNKNOWN
= 16
HOTPLUG
= 17
SHUTDOWNPOWEROFF = 18
BOOTUNKNOWN
= 19
BOOT POWEROFF
= 20
BOOT SUSPENDED
= 21
BOOT STOPPED
= 22
>
<x s : e l e m e n t name=LCM STATE t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=RESCHED t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=STIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=ETIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=DEPLOY ID t y p e= x s : s t r i n g />
< ! MEMORY consumption i n k i l o b y t e s >
<x s : e l e m e n t name=MEMORY t y p e= x s : i n t e g e r />
< ! P e r c e n t a g e o f 1 CPU consumed ( two f u l l y consumed cpu i s 200) >
<x s : e l e m e n t name=CPU t y p e= x s : i n t e g e r />
< ! NET TX: Sent b y t e s t o t h e network >
<x s : e l e m e n t name=NET TX t y p e= x s : i n t e g e r />
< ! NET RX: R e c e i v e d b y t e s from t h e network >
<x s : e l e m e n t name=NET RX t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=HISTORY RECORDS>
<x s : e l e m e n t name=HISTORY maxOccurs=unbounded minOccurs=0 >
<x s : e l e m e n t name=OID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=SEQ t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=HOSTNAME t y p e= x s : s t r i n g />
<x s : e l e m e n t name=HID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=VMMMAD t y p e= x s : s t r i n g />
<x s : e l e m e n t name=VNMMAD t y p e= x s : s t r i n g />
<x s : e l e m e n t name=TMMAD t y p e= x s : s t r i n g />
<x s : e l e m e n t name=DS ID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=PSTIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=PETIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=RSTIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=RETIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=ESTIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=EETIME t y p e= x s : i n t e g e r />
C12G Labs S.L.
63/93
Rev20121022
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
1
2
3
4
5
6
7
8
9
10
11
12
< ! REASON v a l u e s :
NONE
= 0 Normal t e r m i n a t i o n
ERROR
= 1 The VM ended i n e r r o r
STOP RESUME = 2 Stop / resume r e q u e s t
USER
= 3
Migration r e q u e s t
CANCEL
= 4 Cancel r e q u e s t
>
<x s : e l e m e n t name=REASON t y p e= x s : i n t e g e r />
</ x s : e l e m e n t>
</ x s : e l e m e n t>
</ x s : e l e m e n t>
</ x s : s c h e m a>
<x s : s c h e m a x m l n s : x s= h t t p : //www. w3 . o r g /2001/XMLSchema e l e m e n t F o r m D e f a u l t= u n q u a l i f i e d
< x s : i n c l u d e s c h e m a L o c a t i o n=vm . xsd />
<x s : e l e m e n t name=VM POOL>
<x s : e l e m e n t r e f=VM maxOccurs=unbounded minOccurs=0 />
</ x s : e l e m e n t>
</ x s : s c h e m a>
Schemas for Virtual Machine Template

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

<x s : e l e m e n t name=VMTEMPLATE>
</ x s : e l e m e n t>
<x s : e l e m e n t name=REGTIME t y p e= x s : i n t e g e r />
</ x s : e l e m e n t>
</ x s : s c h e m a>
1
2
3
4
5
6
7
8
9
10
11
12

< x s : i n c l u d e s c h e m a L o c a t i o n=vmtemplate . xsd />
<x s : e l e m e n t name=VMTEMPLATE POOL>
<x s : e l e m e n t r e f=VMTEMPLATE maxOccurs=unbounded minOccurs=0 />
</ x s : e l e m e n t>
</ x s : s c h e m a>
Schemas for Virtual Network

C12G Labs S.L.
64/93
Rev20121022
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

<x s : e l e m e n t name=VNET>
</ x s : e l e m e n t>
<x s : e l e m e n t name=CLUSTER ID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=CLUSTER t y p e= x s : s t r i n g />
<x s : e l e m e n t name=TYPE t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=BRIDGE t y p e= x s : s t r i n g />
<x s : e l e m e n t name=VLAN t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=PHYDEV t y p e= x s : s t r i n g />
<x s : e l e m e n t name=VLAN ID t y p e= x s : s t r i n g />
<x s : e l e m e n t name=RANGE minOccurs=0 maxOccurs=1 >
<x s : e l e m e n t name=IP START t y p e= x s : s t r i n g />
<x s : e l e m e n t name=IP END t y p e= x s : s t r i n g />
</ x s : e l e m e n t>
<x s : e l e m e n t name=TOTAL LEASES t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=LEASES minOccurs=0 maxOccurs=1 >
<x s : s e q u e n c e minOccurs=0 >
<x s : e l e m e n t name=LEASE minOccurs=0 maxOccurs=unbounded >
<x s : e l e m e n t name=IP t y p e= x s : s t r i n g />
<x s : e l e m e n t name=MAC t y p e= x s : s t r i n g />
<x s : e l e m e n t name=USED t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=VID t y p e= x s : i n t e g e r />
</ x s : e l e m e n t>
</ x s : e l e m e n t>
</ x s : e l e m e n t>
</ x s : s c h e m a>
1
2
3
4
5
6
7
8
9
10
11
12

< x s : i n c l u d e s c h e m a L o c a t i o n= v n e t . xsd />
<x s : e l e m e n t name=VNET POOL>
<x s : e l e m e n t r e f=VNET maxOccurs=unbounded minOccurs=0 />
</ x s : e l e m e n t>
</ x s : s c h e m a>
Schemas for Accounting

1
2
3

C12G Labs S.L.
65/93
Rev20121022
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

<x s : e l e m e n t r e f=HISTORY maxOccurs=unbounded minOccurs=0 />
</ x s : e l e m e n t>
<x s : e l e m e n t name=HISTORY>
<x s : e l e m e n t name=OID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=SEQ t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=HOSTNAME t y p e= x s : s t r i n g />
<x s : e l e m e n t name=HID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=VMMMAD t y p e= x s : s t r i n g />
<x s : e l e m e n t name=VNMMAD t y p e= x s : s t r i n g />
<x s : e l e m e n t name=TMMAD t y p e= x s : s t r i n g />
<x s : e l e m e n t name=DS ID t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=PSTIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=PETIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=RSTIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=RETIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=ESTIME t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=EETIME t y p e= x s : i n t e g e r />
< ! REASON v a l u e s :
NONE
= 0 Normal t e r m i n a t i o n
ERROR
= 1 The VM ended i n e r r o r
STOP RESUME = 2 Stop / resume r e q u e s t
USER
= 3
Migration r e q u e s t
CANCEL
= 4 Cancel r e q u e s t
>
<x s : e l e m e n t name=REASON t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=VM>
</ x s : e l e m e n t>
<x s : e l e m e n t name=LAST POLL t y p e= x s : i n t e g e r />
see
h t t p : // o p e n n e b u l a . o r g / d o c u m e n t a t i o n : d o c u m e n t a t i o n : a p i#a c t i o n s f o r v i r t u a l m a c h i n e m a n a g e m e n t
INIT
PENDING
HOLD
ACTIVE
STOPPED
SUSPENDED
DONE
FAILED
POWEROFF
>
<x s : e l e m e n t
=
=
=
=
=
=
=
=
=
0
1
2
3 In t h i s
4
5
6
7
8
C12G Labs S.L.
is
relevant
name=STATE t y p e= x s : i n t e g e r />
< ! LCM STATE v a l u e s ,

ACTIVE ( 4 )
LCM INIT
s t a t e , t h e L i f e C y c l e Manager s t a t e
t h i s sub s t a t e
is
r e l e v a n t o n l y when STATE i s
= 0
66/93
Rev20121022
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
PROLOG
= 1
BOOT
= 2
RUNNING
= 3
MIGRATE
= 4
SAVE STOP
= 5
SAVE SUSPEND
= 6
SAVE MIGRATE
= 7
PROLOG MIGRATE
= 8
PROLOG RESUME
= 9
EPILOG STOP
= 10
EPILOG
= 11
SHUTDOWN
= 12
CANCEL
= 13
FAILURE
= 14
CLEANUP
= 15
UNKNOWN
= 16
HOTPLUG
= 17
SHUTDOWNPOWEROFF = 18
BOOTUNKNOWN
= 19
BOOT POWEROFF
= 20
BOOT SUSPENDED
= 21
BOOT STOPPED
= 22
>
<x s : e l e m e n t name=LCM STATE t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=RESCHED t y p e= x s : i n t e g e r />
<x s : e l e m e n t name=DEPLOY ID t y p e= x s : s t r i n g />
< ! MEMORY consumption i n k i l o b y t e s >
<x s : e l e m e n t name=MEMORY t y p e= x s : i n t e g e r />
< ! P e r c e n t a g e o f 1 CPU consumed ( two f u l l y consumed cpu i s 200) >
<x s : e l e m e n t name=CPU t y p e= x s : i n t e g e r />
< ! NET TX: Sent b y t e s t o t h e network >
<x s : e l e m e n t name=NET TX t y p e= x s : i n t e g e r />
< ! NET RX: R e c e i v e d b y t e s from t h e network >
<x s : e l e m e n t name=NET RX t y p e= x s : i n t e g e r />
</ x s : e l e m e n t>
</ x s : e l e m e n t>
</ x s : e l e m e n t>
</ x s : s c h e m a>
3.2
Ruby OpenNebula Cloud API
This page contains the OpenNebula Cloud API3 Specification for Ruby. It has been designed as a
wrapper for the XML-RPC methods, with some basic helpers. This means that you should be familiar
with the XML1 -RPC2 API3 and the XML1 formats returned by the OpenNebula core. As stated in the
XML-RPC documentation, you can download the XML Schemas (XSD) here.
3.2.1
API Documentation
You can consult the doc online.
3.2.2
Usage
You can use the Ruby OCA included in the OpenNebula distribution by adding the OpenNebula Ruby
library path to the search path:
##############################################################################
# Environment Configuration
##############################################################################
ONE_LOCATION=ENV["ONE_LOCATION"]
if !ONE_LOCATION
RUBY_LIB_LOCATION="/usr/lib/one/ruby"
C12G Labs S.L.
67/93
Rev20121022
else
RUBY_LIB_LOCATION=ONE_LOCATION+"/lib/ruby"
end
$: << RUBY_LIB_LOCATION
##############################################################################
# Required libraries
##############################################################################
require OpenNebula
3.2.3
Code Sample: Shutdown all the VMs of the pool
This is a small code snippet. As you can see, the code flow would be as follows:
Create a new Client, setting up the authorization string. You only need to create it once.
Get the VirtualMachine pool that contains the VirtualMachines owned by this User.
You can perform actions over these objects right away, like myVNet.delete();. In this example
all the VirtualMachines will be shut down.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
#! / u s r / b i n / env ruby
##############################################################################
# Environment C o n f i g u r a t i o n
##############################################################################
ONE LOCATION=ENV[ ONE LOCATION ]
! ONE LOCATION
RUBY LIB LOCATION=/ u s r / l i b / one / ruby
else
RUBY LIB LOCATION=ONE LOCATION+/ l i b / ruby
end
if
$ : << RUBY LIB LOCATION

##############################################################################
# Required l i b r a r i e s
##############################################################################
r e q u i r e OpenNebula
i n c l u d e OpenNebula
# OpenNebula c r e d e n t i a l s
CREDENTIALS = o n e u s e r : o n e p a s s
# XML RPC e n d p o i n t where OpenNebula i s l i s t e n i n g
ENDPOINT
= h t t p : / / l o c a l h o s t : 2 6 3 3 /RPC2
c l i e n t = C l i e n t . new (CREDENTIALS, ENDPOINT)
vm pool = V i r t u a l M a c h i n e P o o l . new ( c l i e n t , 1)
r c = vm pool . i n f o
i f OpenNebula . i s e r r o r ? ( r c )
p u t s r c . message
e x i t 1
end
vm pool . e a c h do | vm |
r c = vm . shutdown
p u t s V i r t u a l Machine #{vm . i d } : #{r c . message }
else
p u t s V i r t u a l Machine #{vm . i d } : S h u t t i n g down
end
end
exit 0
C12G Labs S.L.
68/93
Rev20121022
3.2.4
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
Code Sample: Create a new VirtualNetwork
##############################################################################
##############################################################################
! ONE LOCATION
else
end
if

##############################################################################
##############################################################################
r e q u i r e OpenNebula
i n c l u d e OpenNebula
# OpenNebula c r e d e n t i a l s
CREDENTIALS = o n e u s e r : o n e p a s s
# XML RPC e n d p o i n t where OpenNebula i s l i s t e n i n g
ENDPOINT
= h t t p : / / l o c a l h o s t : 2 6 3 3 /RPC2
c l i e n t = C l i e n t . new (CREDENTIALS, ENDPOINT)
t e m p l a t e = <<EOT
NAME
= Red LAN
TYPE
= RANGED
# Now we l l use t h e h o s t p r i v a t e network ( p h y s i c a l )
BRIDGE = vbr0
NETWORK SIZE
= C
NETWORK ADDRESS = 1 9 2 . 1 6 8 . 0 . 0
# Custom A t t r i b u t e s t o be used i n Con text
GATEWAY = 1 9 2 . 1 6 8 . 0 . 1
DNS
= 192.168.0.1
LOAD BALANCER = 1 9 2 . 1 6 8 . 0 . 3
EOT
xml = OpenNebula : : V i r t u a l N e t w o r k . b u i l d x m l
vn = OpenNebula : : V i r t u a l N e t w o r k . new ( xml , @ c l i e n t )
r c = vn . a l l o c a t e ( t e m p l a t e )
e x i t 1 , r c . message
else
p u t s ID : #{vn . i d . t o s }
end
puts Before i n f o :
p u t s vn . t o x m l
puts
vn . i n f o
puts After i n f o :
p u t s vn . t o x m l
3.3
Java OpenNebula Cloud API
This page contains the OpenNebula Cloud API3 Specification for Java. It has been designed as a wrapper
for the XML-RPC methods, with some basic helpers. This means that you should be familiar with
the XML1 -RPC2 API3 and the XML1 formats returned by the OpenNebula core. As stated in the
XML-RPC documentation, you can download the XML Schemas (XSD) here.
C12G Labs S.L.
69/93
Rev20121022
3.3.1
Download
The Java OCA is part of the OpenNebula core distribution. If you installed from the Debian, Ubuntu
or CentOS packages it should be already installed in /usr/share/java/org.opennebula.client.jar.
You also can download the .jar file compiled using Java OpenJDK 1.7, the required libraries, and the
javadoc packaged in a tar.gz file following this link.
You can also consult the javadoc online.
3.3.2
Usage
To use the OpenNebula Cloud API3 for Java in your Java project, you have to add to the classpath the
org.opennebula.client.jar file and the xml-rpc libraries located in the lib directory.
3.3.3
Code Sample
Create a org.opennebula.client.Client object, setting up the authorization string and the endpoint. You only need to create it once.
Create a pool (e.g. HostPool) or element (e.g. VirtualNetwork) object.
You can perform actions over these objects right away, like myVNet.delete();
If you want to query any information (like what objects the pool contains, or one of the element
attributes), you have to issue an info() call before, so the object retrieves the data from OpenNebula.
For more complete examples, please check the src/oca/java/share/examples directory included.
You may be also interested in the java files included in src/oca/java/test.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// F i r s t o f a l l , a C l i e n t o b j e c t has t o be c r e a t e d .
// Here t h e c l i e n t w i l l t r y t o c o n n e c t t o OpenNebula u s i n g t h e d e f a u l t
// o p t i o n s : t h e auth . f i l e w i l l be assumed t o be a t $ONE AUTH, and t h e
// e n d p o i n t w i l l be s e t t o t h e environment v a r i a b l e $ONE XMLRPC.
Client oneClient ;
try
{
o n e C l i e n t = new C l i e n t ( ) ;
// This VM t e m p l a t e i s a v a l i d one , b u t i t w i l l p r o b a b l y f a i l t o run
// i f we t r y t o d e p l o y i t ; t h e p a t h f o r t h e image i s u n l i k e l y t o
// e x i s t .
S t r i n g vmTemplate =
NAME
= vm from java
CPU = 0 . 1
MEMORY = 64\ n
+ DISK
= [\n
+ \ t s o u r c e
= \ / home/ u s e r / vmac h i n e s / t t y l i n u x / t t y l i n u x . img \ , \ n
+ \ t t a r g e t
= \ hda \ , \ n
+ \ t r e a d o n l y = \ no \ ] \ n
+ FEATURES = [ a c p i =\no \ ] ;
System . o u t . p r i n t ( T r y i n g t o a l l o c a t e t h e v i r t u a l machine . . . ) ;
OneResponse r c = V i r t u a l M a c h i n e . a l l o c a t e ( o n e C l i e n t , vmTemplate ) ;
i f ( rc . isError () )
{
System . o u t . p r i n t l n ( f a i l e d ! ) ;
throw new E x c e p t i o n ( r c . g e t E r r o r M e s s a g e ( )
}
);
// The r e s p o n s e message i s t h e new VM s ID

i n t newVMID = I n t e g e r . p a r s e I n t ( r c . g e t M e s s a g e ( ) ) ;
System . o u t . p r i n t l n ( ok , ID + newVMID + . ) ;
// We can c r e a t e a r e p r e s e n t a t i o n f o r t h e new VM, u s i n g t h e r e t u r n e d
// VMID
V i r t u a l M a c h i n e vm = new V i r t u a l M a c h i n e (newVMID , o n e C l i e n t ) ;
// Let s h o l d t h e VM, so t h e s c h e d u l e r won t t r y t o d e p l o y
System . o u t . p r i n t ( T r y i n g t o h o l d t h e new VM . . . ) ;
r c = vm . h o l d ( ) ;
C12G Labs S.L.
70/93
it
Rev20121022
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
i f ( rc . isError ())
{
System . o u t . p r i n t l n ( f a i l e d ! ) ;
}
// And now we can r e q u e s t
r c = vm . i n f o ( ) ;
its
);
information .
i f ( rc . isError ())
);
System . o u t . p r i n t l n ( ) ;
System . o u t . p r i n t l n (
T h i s i s t h e i n f o r m a t i o n OpenNebula s t o r e s
System . o u t . p r i n t l n ( r c . g e t M e s s a g e ( ) + \n ) ;
f o r t h e new VM: ) ;
// This V i r t u a l M a c h i n e o b j e c t has some h e l p e r s , so we can a c c e s s i t s

// a t t r i b u t e s e a s i l y ( remember t o l o a d t h e d a t a f i r s t u s i n g t h e i n f o
// method ) .
System . o u t . p r i n t l n ( The new VM +
vm . getName ( ) + h as s t a t u s : + vm . s t a t u s ( ) ) ;
// And we can a l s o use x p a t h e x p r e s s i o n s
System . o u t . p r i n t l n ( The path o f t h e d i s k i s ) ;
System . o u t . p r i n t l n ( \ t + vm . xpath ( t e m p l a t e / d i s k / s o u r c e )
);
// We have a l s o some u s e f u l h e l p e r s f o r t h e a c t i o n s you can perform

// on a v i r t u a l machine , l i k e c a n c e l or f i n a l i z e :
r c = vm . f i n a l i z e V M ( ) ;
System . o u t . p r i n t l n ( \ nTrying t o f i n a l i z e
vm . g e t I d ( ) + . . . ) ;
( d e l e t e ) t h e VM +
}
catch ( E x c e p t i o n e )
{
System . o u t . p r i n t l n ( e . g e t M e s s a g e ( ) ) ;
}
3.3.4
Compilation
To compile the Java OCA, untar the OpenNebula source, cd to the java directory and use the build
script:
$ cd src/oca/java
$ ./build.sh -d
Compiling java files into class files...
Packaging class files in a jar...
Generating javadocs...
This command will compile and package the code in jar/org.opennebula.client.jar, and the javadoc
will be created in share/doc/.
You might want to copy the .jar files to a more convenient directory. You could use /usr/lib/one/java/
$ sudo mkdir /usr/lib/one/java/
$ sudo cp jar/* lib/* /usr/lib/one/java/
3.4
Ruby OpenNebula Zone API
This page contains the OpenNebula Zone API3 (ZONA) Specification for Ruby. It has been designed as
a wrapper for the OpenNebula Zone REST server, with some basic helpers. This means that you should
be familiar with the XML1 -RPC2 API3 and the JSON formats returned by the OpenNebula Zone server.
3.4.1
API Documentation
You can consult the doc online.

C12G Labs S.L.
71/93
Rev20121022
3.4.2
Usage
You can use the Ruby ZONA included in the OpenNebula distribution by adding the OpenNebula Ruby
library path to the search path:
##############################################################################
# Environment Configuration
##############################################################################
ONE_LOCATION=ENV["ONE_LOCATION"]
if !ONE_LOCATION
RUBY_LIB_LOCATION="/usr/lib/one/ruby"
else
RUBY_LIB_LOCATION=ONE_LOCATION+"/lib/ruby"
end
$: << RUBY_LIB_LOCATION
##############################################################################
# Required libraries
##############################################################################
require zona
3.4.3
Code Sample
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
##############################################################################
##############################################################################
! ONE LOCATION
else
end
if

##############################################################################
##############################################################################
r e q u i r e zona
TDB
3.5
Sunstone Plugins API
This document is intended to provide a detailed description for sunstone.js configuration objects and
methods regarding the creation and use of plugins.
For information on how to write a plugin for Sunstone please read the Sunstone Plugin Guide
Sunstone plugins are part of the client-side of Sunstone. Therefore, they are written in Javascript
and allow customization and extension of the user interface, which is fully on the client-side.
In this document, JSON notation is used to describe Javascript objects in the following way:
{ key: value }
3.5.1
Sunstone configuration objects
Configuration objects are used to setup elements and capabilities of the Sunstone user interface. They
are added, updated and removed from Sunstone via the Sunstone plugin interface.
C12G Labs S.L.
72/93
Rev20121022
Action objects
Action objects are used to define actions. The keys callback, error, element are optional depending
on the action type. The keys notify and condition are optional in all cases.
Action object
Key
Value
type
type
string
call
function
callback
function
error
function
elements
function
notify
condition
boolean
function
Description
create, list, single, multiple, custom. Types are explained below.
The function that will be executed when the action is run.
Callback function for create, single and multiple action types. Will be
set as the success calback function for the Ajax calls made through opennebula.js.
Callback function for create, single and multiple action types. Will be
set as the error callback function for the Ajax calls made through opennebula.js
A function returning an array of elements on which multiple actions will
be run. Only useful for actions of type multiple, which are run from an
action button.
If set to true, user will be notified when the action is run. Defaults to false.
Function must return true or false. If present, condition function is run
right before calling the call function. If the result is false, the call function
is not run. If notify is set to true the user will be notified if the condition
is not met.
Action types There are five action types which define several particular ways of running their call
function. Action types are intended to ease the use of opennebula.js methods. opennebula.js offers
an interface to interact with the sever side of Sunstone (that is, with OpenNebula). Actions not willing
to do so or not fully adapting to the pre-defined types should be declared as type "custom".
Remember actions are run via Sunstone.runAction(action_name,parameter,extra_parameter).
Here is a detailed description of every type:
"custom"
Custom actions simply execute the call function defined in the configuration object. If a parameter
is passed to the Sunstone.runAction() method, it is passed directly to the call function. Same applies
for extra_parameters. Normally, Sunstone.runAction("myAction",A,B) would end up running:
call(A,B); //call is extracted from "myAction" configuration object.
"create", "register"
This type of actions perform a create or register operation on OpenNebula via opennebula.js.
They must have a callback and an error function defined in their configuration object and they must
include a data_argument when run. sunstone.js runs this action as:
call({data:data_argument, success: callback, error:err});
therefore it uses the notation needed to call methods such Image.register or VM.create from opennebula.js.
"single"
This type of actions use an opennebula.js method run on a single element (host, VM, user. . . ). They
must have a callback and an error function defined in their configuration and they must include the
OpenNebula ID of the affected element as data_argument when run. sunstone.js runs this action as:
call({data:{id:data_argument}, success: callback,error:err});
C12G Labs S.L.
73/93
Rev20121022
therefore it uses the notation needed to call methods such Host.enable or User.delete from opennebula.js.
"multiple"
This type of actions use a opennebula.js method afecting a single element repeteadly for each element
of an array passed as data_argument. They must have a callback and an error functions defined in
their configuration. The data_argument array contains the OpenNebula IDs of the elements on which
the action should be run. sunstone.js runs this action for each ID as:
call({data:{id:this}, success: callback, error:err});
If an optional extra_parameter the action is performed as:

call({data:{id:this,extra_param:extra_param}, success: callback, error: err});
A multiple action is equivalent to calling a single action repeatedly on different elements.

"list"
This type of actions use a opennebula.js list method, which retrieves a pool of OpenNebula elements in JSON format (hosts, VMs, users. . . ). They must have a callback and an error functions
defined in their configuration. sunstone.js runs this action as:
call({success: callback, error:err});
Objects for actions Sunstone accepts objects containing 1 or several actions in the following form.
This way, action names are associated to their configuration objects.
{
"myAction1" : action_object1,
...
}
Action objects examples Here is an example of an object containing several actions:

{
"Host.create" : {
type: "create",
call : OpenNebula.Host.create,
callback : addHostElement,
error : onError,
notify: true
},
"Host.show" : {
type: "single",
call: OpenNebula.Host.show,
callback: updateHostElement,
error: onError
},
"Host.showinfo" : {
type: "single",
call: OpenNebula.Host.show,
callback: updateHostInfo,
C12G Labs S.L.
74/93
Rev20121022
error: onError
},
"Host.enable" : {
type: "multiple",
call : OpenNebula.Host.enable,
callback : function (req) {
Sunstone.runAction("Host.show",req.request.data[0]);
},
elements: function() { return getSelectedNodes(dataTable_hosts); },
error : onError,
notify: true
},
//This "list" action doesnt adapt to the "list" type as we want to
//make two calls. Therefore we use a "custom" action and do the
//and Cluster.list manually
"Host.list" : {
type: "custom",
call : function() {
OpenNebula.Host.list({success: updateHostsView, error: onError});
OpenNebula.Cluster.list({success: updateClustersView, error: onError});
}
},
"Cluster.list" : {
type: "list",
call: OpenNebula.Cluster.list,
callback: updateClustersView,
error: onError,
},
}
Button objects
Button objects define a clickable element associated to an action. Button objects are planed inside
button-set objects, which are part of main tabs.
Buttons are automatically generated and included in a special div (of class action blocks in the
content of the main tab of which they are part of. Buttons allow users to perform actions.
Each button object, part of a button-set, can be described as follows:

C12G Labs S.L.
75/93
Rev20121022
Button Object
Key
Value type
type
string
text
condition
string
function
img
tip
string
string
alwaysActive Boolean
select
HTML6 string
actions
button-set object
Description
action, image, confirm, confirm_with_select or select. The
button type defines the class which will be added to the button
HTML6 : action_button, confirm_button. . . and so on. if a custom string is included a button with custom_string_button class
will be generated. Standard types are handled differently by Sunstone and explained below.
A optional function that returns true or false. The function is
run before adding the button HTML6 to the DOM7 . If it returns
false, the button is skipped.
Image path for image type buttons.
For confirm and confirm_with_select type buttons, this is the
text that will be shown as a tip in the confirmation dialog for the
action.
Adds the class alwaysActive to the button, meaning the button
will not be deactivated when no elements of a dataTable are selected. Useful for New + buttons in the standard plugins.
This is the select input which is shown in the confirm_with_select buttons confirmation dialog. It allows the user
to select an element. This elements ID will be passed as extra_parameter to the associated action.
For buttons of type select. Actions is another button-set. This
button-set object will be turned into the options of a select input
field (see explanation below).
Button types Buttons type generally defines a class to be added to the button HTML6 generated
code, apart from other things. There are five special types. According to their type/class, buttons
produce different effects. select buttons are special, as they produce a select input field. Find here a
detailed description of each type:
"action"
Buttons of this type are standard buttons which run their associated action directly when clicked (the
associated action is the button name).
"image"
Buttons of this type are turned into image links. For the rest, they act like action buttons. Please
include a img path pointing to the image for the button.
"confirm"
Buttons of this type show a standard confirmation dialog before running their associated action.
Please define an explanatory tip along so it can give further hints to the user.
"confirm_with_select"
Buttons of this type show a standard confirmation dialog which contains a select input field before
running their associated action. For example, Add several hosts to one cluster shows a confirmation dialog allowing the user to select a cluster. The option ID is passed as extra_parameter to Sunstone.runAction(). Please define an explanatory tip along so it can give further hints to the user and
provide a select function returning a well formed HTML6 code for the select input field.
6 HyperText
7 Document
Markup Language
Object Model
C12G Labs S.L.
76/93
Rev20121022
"select"
Select buttons define a select input field containing several options. These options are defined as a
second button-set which is the value of the actions field of the button. These buttons can be of type
action, confirm and confirm_with_select. The rest of options remain the same as for normal buttons.
Lets illustrate this type of button with a select button object:
{ //Special select button
type: "select",
actions: { "Cluster.addhost": {
type: "confirm_with_select",
text: "Add host to cluster",
select: function(){return clusters_select;},
tip: "Select the cluster in which you would like to place the hosts",
condition: True
},
"Cluster.removehost" : {
type: "action",
text: "Remove host from cluster",
condition: True
}},
condition : True
}
Note that Sunstone replaces these select input fields with nice-looking dropdown lists of actions
attached to a run last action button. This is done automatically during the first initialization of the
interface. So far, this improvement is not done after a refresh of the button-set at any other moment, so
then the initial select input field will be shown.
Button-set objects Button objects are grouped in button-set objects in the following way:
{
"action1": button_obj1,
"action2": button_obj2,
...
}
The name of the button must be the name of the action it is associated to. Buttons of type select
can have any name though.
Button examples Find here some examples on how a button-set object formed by buttons looks like:
{
"Host.refresh" : {
type: "image",
text: "Refresh list",
img: "/images/Refresh-icon.png",
condition: True
},
"Host.enable" : {
type: "action",
text: "Enable",
condition : True
},
"Cluster.delete" : {
type: "confirm_with_select",
text: "Delete cluster",
C12G Labs S.L.
77/93
Rev20121022
select: function(){return clusters_select},

tip: "Select the cluster you want to remove",
condition : True
},
"VM.hold" : {
type: "confirm",
text: "Hold",
tip: "This will hold selected pending VMs from being deployed",
condition: True
}
}
Main Tab objects

Main tab objects define a main tab, that is a element of the left-side menu which shows certain content
in the main window when it is clicked. This is their detailed description:
Main tab objects
Key
Value type
title
string
content
HTML6 string
buttons
button-set object
condition
function
showOnTopMenu
boolean
class
string
parentTab
string
Desctiption
The name of the left-side menu link.
The HTML6 content shown when clicking on this tab.
An optional button-set object (as explained above), associated to
this tab.
A function returning true or false. If present, condition is
called before adding the tab. If it returns false the tab will not
be added.
Shows this menu item in a menu in the top bar. Currently not
used in Sunstone but implemented nevertheless
The string will be added as class attribute to the menu element.
By default, topTab is used if no class is defined. Use "subTab"
if menu item is part of a submenu. You can use "topTab subTab"
when the menu item is part of a submenu, but also has other menu
items hanging from it.
When the menu item is part of a submenu, this indicates the id
of the parent node.
Main tab example Here is an example of a main tab object:
var clusters_tab = {
title: tr("Clusters"), //allows translation of the title
content: clusters_tab_content, //html code for the view
buttons: cluster_buttons, //buttons to place as top action
showOnTopMenu: false, //show tap on a top menu bar, on the top panel
tabClass: "topTab subTab", //this tab is a submenu, and has itself submenus
parentTab: "infra_tab", //parent menu is the infraestructure dashboard tab
};
Info panel objects

Info panels are the panels that pop up from the button of the Sunstone interface, for example, when
clicking on a host element in the Host & Clusters main tab. Info panels are formed by one or several
tabs.
Each tab is an object defined as follows:
C12G Labs S.L.
78/93
Rev20121022
Figure 3.1:
Info panel tab objects
Key
Value type
Desctiption
title
string
Title of the tab.
content HTML6 string Contents of the tab.
Info panel example This is an info panel object:
{
"vm_info_tab" : {
title: "Virtual Machine information",
content: "This is the info tab"
},
"vm_template_tab" : {
title: "VM template",
content: "This is the template tab"
},
"vm_log_tab" : {
title: "VM log",
content: "This is the log tab"
}
}
Where are the real contents of the tabs? Sometimes, you do not know the content of the info
panel tabs if it is not completely static. It can be added later via Sunstone.updateInfoPanelTab().
C12G Labs S.L.
79/93
Rev20121022
How do these panels work? There can be many info panels which can be shown in very different
moments. Sunstone offers a Sunstone.popUpInfoPanel(panel_name) method that will a) Create the
HTML6 code for the panel on the fly b) Pop it up. That way, you only have to worry about maintaining
your info panel tabs updated and you will always get a nice looking panel popping up from the button.
3.5.2
Sunstone plugin interface
Sunstone offers several functions to add, update, and remove configuration objects, along with some other
features. These functions are meant to be used by the plugins. Here is a detailed description of each one
of them and their purpose.
Sunstone.addAction(action name,action obj)
Adds an action object to the Sunstone configuration.
Parameter
action name
action obj
Type
String
Object
Mandatory
Yes
Yes
Description
Name of this action.
Action object as defined above.
Sunstone.updateAction(action name,action obj)

Updates an action object in the Sunstone configuration.
Parameter
action name
action obj
Type
String
Object
Mandatory
Yes
Yes
Description
Action object as defined above.
Sunstone.removeAction(action name)
Removes an action object from the Sunstone configuration.
Parameter
action name
Type
String
Mandatory
Yes
Description
Sunstone.addActions(actions)
Adds several actions to the configuration. See Objects for actions.
Parameter
actions
Type
Object
Mandatory
Yes
Description
An object containing several actions.
Sunstone.addMainTab(tab id,tab obj,[refresh])

Adds a main tab to the configuration. Optionally, refreshes the DOM7 (if the tab is added after
initialization).
Parameter
tab id
tab obj
refresh
Type
String
Object
boolean
Mandatory
Yes
Yes
No
Description
id for this tab.
Main tab object as defined above.
Refresh the DOM7 to add the new tab.
Sunstone.updateMainTabContent(tab id,content arg,[refresh])

Updates the contents of an existing main tab. Optionally refreshes it in the DOM7 .
Parameter
tab id
content arg
refresh
Type
String
String
boolean
Mandatory
Yes
Yes
No
Description
id of the updated tab
New HTML6 contents.
Refresh the DOM7 with the new content.
Sunstone.updateMainTabButtons(tab id,buttons arg,[refresh])

Updates the buttons of an existing main tab. Optionally regenerates them it in the DOM7 .
C12G Labs S.L.
80/93
Rev20121022
Parameter
tab id
buttons arg
Type
String
Object
Mandatory
Yes
Yes
refresh
boolean
No
Description
id of the updated tab
The new button-set object containing buttons as
defined above.
Refresh the DOM7 with the new buttons.
Sunstone.removeMainTab(tab id,[refresh])
Removes a main tab from the configuration. Optionally, refreshes the DOM7 to remove the tab link
and contents from it.
Parameter
tab id
refresh
Type
String
boolean
Mandatory
Yes
No
Description
id of the tab.
Refresh the DOM7 to remove the tab.
Sunstone.addInfoPanel(panel name,panel obj)

Adds an info panel to the configuration. From this point, the panel is ready to be popped up.
Parameter
panel name
panel obj
Type
String
Object
Mandatory
Yes
Yes
Description
name for this panel.
An info panel object as described above.
Sunstone.updateInfoPanel(panel name,panel obj)

Replaces an info panel.
Parameter
panel name
panel obj
Type
String
Object
Mandatory
Yes
Yes
Description
name of the panel.
An info panel object as described above.
Sunstone.removeInfoPanel(panel name)
Deletes an info panel from the configuration.
Parameter
panel name
Type
String
Mandatory
Yes
Description
name of the panel.
Sunstone.popUpInfoPanel(panel name,[selected tab])

Pops up an info panel from the bottom of the interface. Optionally, you can indicate which tab should
be selected when it does.
Parameter
panel name
selected tab
Type
String
Integer
Mandatory
Yes
No
Description
Number of initially selected tab (>0). Defaults to 0.
Sunstone.getInfoPanelHTML(panel name,[selected tab])

Returns an HTML6 string containing with the HTML6 of the desired info panel. Useful if wanting to
do things with it, like putting the information on a dialog.
Parameter
panel name
selected tab
Type
String
Integer
Mandatory
Yes
No
Description
Number of initially selected tab (>0). Defaults to 0.
Sunstone.addInfoPanelTab(panel name,panel tab id,panel tab obj)

Adds an new tab in an existing info panel.
Parameter
panel name
panel tab id
panel tab obj
Type
String
Object
Object
Mandatory
Yes
Yes
Yes
Description
The id of the info panel tab.
A info panel tab object as described above.
Sunstone.updateInfoPanelTab(panel name,panel tab id,panel tab obj,[refresh])

C12G Labs S.L.
81/93
Rev20121022
Updates an info panel tab. Also useful for refreshing its content. If refresh is set it will try to refresh
the contents directly if they are in the DOM7 .
Parameter
panel name
panel tab id
panel tab obj
Type
String
Object
Object
Mandatory
Yes
Yes
Yes
refresh
boolean
No
Description
The id of the info panel tab.
A info panel tab object as described above.
Tries to refresh the tab content if
it is somewhere in the DOM7 .
Sunstone.removeInfoPanelTab(panel name,panel tab id)

Removes a tab from an info panel.
Parameter
panel name
panel tab id
Type
String
Object
Mandatory
Yes
Yes
Description
The id of the info panel tab to be removed.
Sunstone.runAction(action, [data arg], [extra param])

Runs the predifined call of an action. Handles checking if condition is met and makes sure to pop
if a notication dialog if notify is set to true. All this parameters are extracted from the action object
indicated by the action parameter. There are different types of actions producing different effects.
Parameter
action
data arg
extra param
C12G Labs S.L.
Type
String
Any/Array
any
Any
of
Mandatory
Yes
No
No
82/93
Description
Name of the action that will be run.
data argument. It can be an array for multiple actions.
Extra parameter.
Rev20121022
Chapter 4
Infrastructure Integration
4.1
Virtualization Manager Driver
The component that deals with the hypervisor to create, manage and get
machine objects is called Virtual Machine Manager (VMM for short). This
The first one resides in the core and holds most of the general functionality
(and some specific), the second is the driver that is the one able to translate
hypervisor.
inlinetoc
4.1.1
information about virtual

component has two parts.
common to all the drivers
basic VMM actions to the
Driver Configuration
There are two main drivers one_vmm_exec and one_vmm_sh. Both take commands from OpenNebula and
execute a set of scripts for those actions, the main difference is that one_vmm_exec executes the commands
remotely (logging into the host where VM is being or is going to be executed) and one_vmm_sh does the
execution of the scripts in the frontend.
The driver takes some parameters, described here:
parameter
-r <num>
-t <num
-l <actions>
description
number of retries when executing an action
number of threads, i.e. number of actions done at the same time
(one_vmm_exec only) actions executed locally, command can be overridden for each
action
<driver directory>where in the remotes directory the driver can find the action scripts
These are the actions valid in the -l parameter:
deploy
shutdown
cancel
save
restore
migrate
poll
You can also provide an alternative script name for local execution, by default the script is called the
same as the action, in this fashion action=script_name. As an example:
-l migrate,poll=poll_ganglia,save
C12G Labs S.L.
83/93
Rev20121022
These arguments are specified in the oned.conf file, arguments variable:

1
2
3
4
5
6
VM MAD = [
name
executable
arguments
default
type
4.1.2
=
=
=
=
=
vmm kvm ,
one vmm e x e c ,
t 15 r 0 l m i g r a t e , s a v e kvm ,
vmm e x e c /vmm e x e c kvm . c o n f ,
kvm ]
Actions
Every action should have an executable program (mainly scripts) located in the remote dir (remotes/vmm/<driver_direct
that performs the desired action. These scripts receive some parameters (and in the case of DEPLOY also
STDIN) and give back the error message or information in some cases writing to STDOUT.
The basic actions the Virtual Machine Manager Driver should understand are these:
Action
DEPLOY
SHUTDOWN
CANCEL
SAVE
RESTORE
MIGRATE
POLL
Description
Tells the hypervisor to create a new VM
Sends shutdown signal to a VM
Destroys a VM
Saves the state of a VM (suspend)
Restores a VM to a previous saved state
Performs live migration of a VM
Gets information about a VM
Monitoring actions for one_vmm_ssh:

DEPLOY : Tells the hypervisor to create a new VM
Arguments
* deployment_file: where to write the deployment file. The body of this file is provided
in STDIN.
Response
* Success: The VM identifier for the hypervisor
* Failure: Error message
SHUTDOWN : Sends shutdown signal to a VM
Arguments
* deploy_id: VM identifier for the hypervisor
Response
* Success: * Failure: Error message
CANCEL : Destroys a VM
Arguments
Response
SAVE : Saves the state of a VM (suspend)
Arguments
* file: file name where to save the state
C12G Labs S.L.
84/93
Rev20121022
Response
RESTORE : Restores a VM to a previous saved state
Arguments
* file: file name where to restore the VM from
Response
MIGRATE : Performs live migration of a VM
Arguments
* host: host where to migrate the VM
Response
POLL : Gets information about a VM
Arguments
Response
* Success: Monitoring data (described in next section)
* Failure: Error message
one_vmm_sh has the same script actions and meanings but an argument more that is the host where
the action is going to be performed. This argument is always the first one. If you use -p parameter
in one_vmm_ssh the poll action script is called with one more argument that is the host where the VM
resides, also it is the same parameter.
4.1.3
Poll Information
POLL is the action that gets monitoring info from the running VMs. The format it is supposed to give
back information is a line with KEY=VALUE pairs separated by spaces. Like this:
STATE=a USEDMEMORY=554632
The poll action can give back any information and it will be added to the VM information hold but there
are some variables that should be given back as they are meaningful to OpenNebula:
Variable
STATE
USEDCPU
USEDMEMORY
NETRX
NETTX
Description
State of the VM (explained later)
Percentage of 1 CPU consumed (two fully consumed cpu is 200)
Memory consumption in kilobytes
Received bytes from the network
Sent bytes to the network
STATE is a single character that tells OpenNebula the status of the VM, the states are the ones in this
table:
C12G Labs S.L.
85/93
Rev20121022
state
a
p
e
d
4.1.4
description
Detecting state error. The monitoring could be done, but it returned an unexpected
output.
Active. The VM is alive, but not necessary running. Could be blocked, booting, etc.
Paused. Self-explanatory.
Error. The VM crashed or somehow its deployment failed.
Disappeared. The VM is not known by the hypervisor anymore.
Deployment file
The deployment file is a text file written by OpenNebula core that holds the information of a VM. It is
used when deploying a new VM. OpenNebula is able to generate three formats of deployment files:
xen: deployment file suitable to be used with xen tools
kvm: libvirt format used to create kvm VMs
xml: xml representation of the VM
If the target hypervisor is not xen nor libvirt/kvm the best format to use is xml as it holds more
information than the two others. It has all the template information encoded as xml. This is an example:
1
2
3
4
5
6
7
8
9
10
11
<TEMPLATE>
<CPU>< ! [CDATA[ 1 . 0 ] ] ></CPU>
<DISK>
<DISK ID>< ! [CDATA[ 0 ] ] ></DISK ID>
<SOURCE>< ! [CDATA[ / home/ u s e r /vm . img ] ] ></SOURCE>
<TARGET>< ! [CDATA[ s d a ] ] ></TARGET>
</DISK>
<MEMORY>< ! [CDATA[ 5 1 2 ] ] ></MEMORY>
<NAME>< ! [CDATA[ t e s t ] ] ></NAME>
<VMID>< ! [CDATA[ 0 ] ] ></VMID>
</TEMPLATE>
There are some information added by OpenNebula itself like the VMID and the DISK_ID for each disk.
DISK_ID is very important as the disk images are previously manipulated by the TM driver and the disk
should be accessible at VM_DIR/VMID/images/disk.DISK_ID.
4.2
Storage Subsystem
The Storage subsystem is highly modular. These drivers are separated into two logical sets:
DS: Datastore drivers. They serve the purpose of managing images: register, delete, and create
empty datablocks.
TM: Transfer Manager drivers. They manage images associated to instantiated VMs.
4.2.1
Datastore Drivers Structure
Located under /var/lib/one/remotes/datastore/<ds_mad>

cp: copies/dumps the image to the datastore
ARGUMENTS: datastore_image_dump image_id

RETURNS: image_source size
datastore_image_dump is an XML1 dump of the driver action encoded in Base 64. See a
decoded example.
image_source is the image source which will be later sent to the transfer manager
1 Extensible
Markup Language
C12G Labs S.L.
86/93
Rev20121022
mkfs: creates a new empty image in the datastore

RETURNS: image_source size
decoded example.
image_source is the image source which will be later sent to the transfer manager.
rm: removes an image fromthe datastore

RETURNS: datastore_image_dump is an XML1 dump of the driver action encoded in Base 64. See a
decoded example.
stat: returns the size of an image in Mb

RETURNS: size
decoded example.
size the size of the image in Mb.
clone: clones an image.
ARGUMENTS: datastore_action_dump image_id

RETURNS: source
decoded example.
source the new source for the image.
image_source has to be dynamically generated by the cp and mkfs script. It will be passed later on
to the transfer manager, so it should provide all the information the transfer manager needs to locate the
image. To illustrate a few examples:
FS driver: DATASTORE_BASE_PATH + md5sum(date + id)
iSCSI driver: <base_iqn>:<host>.<vg-name>.<lv-name>
4.2.2
TM Drivers Structure
This is a list of the TM drivers and their action. Note that they dont return anything. If the exit code
is not 0, the driver will have failed.
Located under /var/lib/one/remotes/tm/<tm_mad>. There are two types of action scripts: the
first group applies to general image datastores and includes (clone, ln, mv and mvds); the second one is
only used in conjunction with the system datastore.
Action scripts for generic image datastores:
clone: clones the image from the datastore (non-persistent images)
ARGUMENTS: clone fe:SOURCE host:remote_system_ds/disk.i size

fe is the front-end hostname
SOURCE is the path of the disk image in the form DS BASE PATH/disk
host is the target host to deploy the VM
remote_system_ds is the path for the system datastore in the host
C12G Labs S.L.
87/93
Rev20121022
ln: Links the image from the datastore (persistent images)
ARGUMENTS: clone fe:SOURCE host:remote_system_ds/disk.i size

mvds: moves an image back to its datastore (persitent images or save as)
ARGUMENTS: host:remote_system_ds/disk.i fe:SOURCE

mv: moves images/directories across system ds in different hosts. When used for an image datastore, only the image argument format is used.
ARGUMENTS: hostA:system_ds/disk.i|hostB:system_ds/disk.i <OR> hostA:system_ds/|hostB:s

hostA is the host the VM is in.
hostB is the target host to deploy the VM
system_ds is the path for the system datastore in the host
Action scripts needed when the TM is used for the system datastore:
context: creates an ISO2 that contains all the files passed as an argument.
ARGUMENTS: file1 file2 ...
fileN host:remote_system_ds/disk.i

delete: removes the eithr system datastores directory of the VM or a disk itself.
ARGUMENTS: host:remote_system_ds/disk.i|host:remote_system_ds/
mkimage: creates an image on-the-fly bypassing the datastore/image workflow
ARGUMENTS: size format host:remote_system_ds/disk.i size

size size in MB3 of the image
format format for the image
mkswap: creates a swap image
ARGUMENTS: size host:remote_system_ds/disk.i size

size size in MB3 of the image
2 International
Organization for Standardization
3 Megabyte
C12G Labs S.L.
88/93
Rev20121022
mv: moves images/directories across system ds in different hosts. When used for the system
datastore the script will received the directory ARGUMENT
ARGUMENTS: hostA:system_ds/disk.i|hostB:system_ds/disk.i <OR> hostA:system_ds/|hostB:s

hostA is the host the VM is in.
hostB is the target host to deploy the VM
system_ds is the path for the system datastore in the host
premigrate: It is executed before a livemigration operation is issued to the hypervisor.
ARGUMENTS: source_host dst_host remote_system_dir vmid dsid template

src_host is the host the VM is in.
dst_host is the target host to migrate the VM to
remote_system_ds_dir is the path for the VM directory in the system datastore in the host
vmid is the id of the VM
dsid is the target datastore
template is the template of the VM in XML1 and base64 encoded
postmigrate: It is executed after a livemigration operation.
ARGUMENTS: source_host dst_host remote_system_dir vmid dsid template

see premigrate description.
You only need to implement one mv script, but consider the arguments received when the TM is used
for the system datastore, a regular image datastore or both.
If the TM is only for regular images you only need to implement the first group.
4.2.3
An example VM
Consider a VM with two disks:

1
2
3
4
5
6
NAME
= vm01
CPU
= 0.1
MEMORY = 64
DISK
DISK
= [ IMAGE ID = 0 ] # non p e r s i s t e n t d i s k
= [ IMAGE ID = 1 ] # p e r s i s t e n t d i s k
This a list of TM actions that will be called upon the events listed:
CREATE
<tm_mad>/clone <frontend>:<non_pers_image_source> <host01>:<ds_path>/<vm_id>/disk.0
<tm_mad>/ln <frontend>:<pers_image_source> <host01>:<ds_path>/<vm_id>/disk.1
STOP
<tm_mad>/mv <host01>:<ds_path>/<vm_id>/disk.0 <frontend>:<ds_path>/<vm_id>/disk.0
<tm_mad>/mv <host01>:<ds_path>/<vm_id>/disk.1 <frontend>:<ds_path>/<vm_id>/disk.1
<tm_mad_sysds>/mv <host01>:<ds_path>/<vm_id> <frontend>:<ds_path>/<vm_id>
RESUME
<tm_mad>/mv <frontend>:<ds_path>/<vm_id>/disk.0 <host01>:<ds_path>/<vm_id>/disk.0
<tm_mad>/mv <frontend>:<ds_path>/<vm_id>/disk.1 <host01>:<ds_path>/<vm_id>/disk.1
<tm_mad_sysds>/mv <frontend>:<ds_path>/<vm_id> <host01>:<ds_path>/<vm_id>
C12G Labs S.L.
89/93
Rev20121022
MIGRATE host01 host02

<tm_mad>/mv <host01>:<ds_path>/<vm_id>/disk.0 <host02>:<ds_path>/<vm_id>/disk.0
<tm_mad>/mv <host01>:<ds_path>/<vm_id>/disk.1 <host02>:<ds_path>/<vm_id>/disk.1
<tm_mad_sysds>/mv <host01>:<ds_path>/<vm_id> <host02>:<ds_path>/<vm_id>
SHUTDOWN
<tm_mad>/delete <host02>:<ds_path>/<vm_id>/disk.0
<tm_mad>/mvds <host02>:<ds_path>/<vm_id>/disk.1 <pers_image_source>
<tm_mad_sysds>/delete <host02>:<ds_path>/<vm_id>
non_pers_image_source: Source of the non persistent image.

pers_image_source : Source of the persistent image.
frontend: hostname of the frontend
host01: hostname of host01
host02: hostname of host02
tm_mad: TM driver of the datastore where the image is registered
tm_mad_sysds: TM driver of the system datastore
4.2.4
Helper Scripts
There is a helper shell script with some functions defined to do some common tasks. It is located in
/var/lib/one/remotes/scripts_common.sh
Here are the description of those functions.
log: Takes one parameter that is a message that will be logged into the VM log file.
1
l o g C r e a t i n g d i r e c t o r y $DST DIR
error message: sends an exit message to oned surrounding it by separators, use to send the error
message when a command fails.
1
e r r o r message F i l e
$ FILE n o t f o u n d
arg host: gets the hostname part from a parameter

1
SRC HOST= a r g h o s t $SRC
arg path: gets the path part from a parameter

1
SRC PATH= a r g path $SRC
exec and log: executes a command and logs its execution. If the command fails the error message
is sent to oned and the script ends
1
e x e c and l o g chmod g+w $DST PATH
ssh exec and log: This function executes $2 at $1 host and report error $3
1
s s h e x e c and l o g $HOST chmod g+w $DST PATH E r r o r message
timeout exec and log: like exec_and_log but takes as first parameter the max number of seconds
the command can run
1
t i m e o u t e x e c and l o g 15 cp $SRC PATH $DST PATH
C12G Labs S.L.
90/93
Rev20121022
Chapter 5
References
5.1
Building from Source Code
This page will show you how to compile and install OpenNebula from the sources.
If you want to install it from your package manager, visit the software menu to find out if OpenNebula
is included in your official distribution package repositories.
Do not forget to check the Building Dependecies for a list of specific software requirements to build
OpenNebula.
5.1.1
Compiling the Software
Follow these simple steps to install the OpenNebula software:

Download and untar the OpenNebula tarball.
Change to the created folder and run scons to compile OpenNebula
$ scons [OPTION=VALUE]
the argument expression [OPTION=VALUE] is used to set non-default values for :

OPTION
sqlite db
sqlite
mysql
xmlrpc
parsers
VALUE
path-to-sqlite-install
no if you dont want to build sqlite support
yes if you want to build mysql support
path-to-xmlrpc-install
yes if you want to rebuild flex/bison files
OpenNebula can be installed in two modes: system-wide, or in self-contained directory. In

either case, you do not need to run OpenNebula as root. These options can be specified when
running the install script:
./install.sh <install_options>
where <install options> can be one or more of:

C12G Labs S.L.
91/93
Rev20121022
OPTION
VALUE
-u
-g
-k
user that will run OpenNebula, defaults to user executing install.sh

group of the user that will run OpenNebula, defaults to user executing install.sh
keep configuration files of existing OpenNebula installation, useful when upgrading. This
flag should not be set when installing OpenNebula for the first time
target installation directory. If defined, it will specified the path for the self-contained
install. If not defined, the installation will be performed system wide
only install client utilities: OpenNebula cli, occi and ec2 client files
remove Opennebula, only useful if -d was not specified, otherwise rm -rf
$ONE_LOCATION would do the job
prints installer help
-d
-c
-r
-h
We will do a self-contained installation. As oneadmin user:

oneadmin@frontend:~/ $> wget <opennebula tar gz>
oneadmin@frontend:~/ $> tar xzf <opennebula tar gz>
oneadmin@frontend:~/ $> cd one-3.0
oneadmin@frontend:~/one-3.0/ $> scons -j2
[ lots of compiling information ]
scons: done building targets.
oneadmin@frontend:~/one-3.0 $> ./install.sh -d /srv/cloud/one
5.1.2
Ruby Dependencies
Ruby version needs to be:

ruby >= 1.8.7
Some OpenNebula components need ruby libraries. Some of these libraries are interfaces to binary
libraries and the development packages should be installed in your machine. This is the list of the ruby
libraries that need a development package:
sqlite3: sqlite3 development library
mysql: mysql client development library
curb: curl development library
nokogiri: expat development librarie
xmlparse: libxml2 and libxslt development libraries
You will also need ruby development package to be able to compile these gems.
We provide a script to ease the installation of these gems. it is located in /usr/share/one/install_gems (system-wide mode) or $ONE_LOCATION/share/install_gems (self-contained mode). It can
be called with the components you want the gem dependencies to be installed. Here are the options:
optional: libraries that make CLI and OCA faster
quota: quota system
sunstone: sunstone graphical interface
cloud: ec2 and occi interfaces
ozones client: CLI of ozones
ozones server: server part of ozones, both mysql and sqlite support
C12G Labs S.L.
92/93
Rev20121022
ozones server sqlite: ozones server, only sqlite support

ozones server mysql: ozones server, only mysql support
acct: accounting collector, both mysql and sqlite support
acct sqlite: accounting collector, only sqlite support
acct mysql: accounting collector, only mysql support
The tool can be also called without parameters and all the packages will be installed.
For example, to install only requirements for sunstone, ec2 and occi interfaces youll issue:
oneadmin@frontend: $> ./install_gems sunstone cloud
C12G Labs S.L.
93/93
Rev20121022

ONE 3.8 Extending and Integrating Your Cloud Infrastructure

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ONE 3.8 Extending and Integrating Your Cloud Infrastructure

Uploaded by

Copyright:

Available Formats

Extending and Integrating your Cloud Infrastructure

C12G Labs S.L.

2012 C12G Labs

UNLESS OTHERWISE EXPRESSLY STATED BY C12G

C12G Labs S.L.

C12G Labs S.L.

Scalable Architecture and APIs

Figure 1: OpenNebula Interfaces

C12G Labs S.L.

2.1. The OpenNebula XML-RPC Interface

C12G Labs S.L.

2.4. The OpenNebula DataBase

C12G Labs S.L.

OpenNebula EC2 API

Text Transfer Protocol

C12G Labs S.L.

Commands description can be accessed from the Command Line Reference.

User Account Configuration

The EC2_URL3 has to use the FQDN of the EC2-Query Server

C12G Labs S.L.

C12G Labs S.L.

OpenNebula OCCI API

C12G Labs S.L.

Authentication & Authorization

The following headers are compulsory:

GROUP of the NETWORK

<NETWORK h r e f= h t t p : //www. o p e n n e b u l a . o r g / network /123 >

OS5 : contains a working operative system

<STORAGE h r e f= h t t p : //www. o p e n n e b u l a . o r g / s t o r a g e /123 >

C12G Labs S.L.

STORAGE link to a STORAGE resource

NETWORK link to a NETWORK resource

<COMPUTE h r e f= h t t p : //www. o p e n n e b u l a . o r g / compute /32 >

<INSTANCE TYPE h r e f= h t t p : //www. o p e n n e b u l a . o r g / i n s t a n c e t y p e / s m a l l >

<USER h r e f= h t t p : //www. o p e n n e b u l a . o r g / u s e r /42 >

Meaning / Entity Body

List the available collections in the cloud.

200 OK: An XML6

C12G Labs S.L.

C12G Labs S.L.

Meaning / Entity Response

C12G Labs S.L.

Meaning / Entity Response

Meaning / Entity Response

C12G Labs S.L.

Meaning / Entity Response

C12G Labs S.L.

C12G Labs S.L.

Can be also given to OpenNebula with the following XML1 :

Authorization Requests Reference

XML1 -RPC2 Method

delete restart shutdown suspend

(Extensible Markup Language) Schema Definition

C12G Labs S.L.

XML1 -RPC2 Method

XML1 -RPC2 Method

XML1 -RPC2 Method

C12G Labs S.L.

XML1 -RPC2 Method

XML1 -RPC2 Method

XML1 -RPC2 Method

C12G Labs S.L.

XML1 -RPC2 Method

XML1 -RPC2 Method