XML-RPC API 3.0

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 Data Type Description
OUT Boolean True or false whenever is successful or not.
OUT String If an error occurs this is the error message.
OUT Int 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 Code
0x0000 SUCCESS Success response.
0x0100 AUTHENTICATION User could not be authenticated.
0x0200 AUTHORIZATION User is not authorized to perform the requested action.
0x0400 NO_EXISTS The requested resource does not exist.
0x0800 ACTION FIXME
0x1000 XML_RPC_API FIXME
0x2000 INTERNAL FIXME

:!: All methods expect a session string associated to the connected user as the first parameter. It has to be formed with <username>:<SHA1(password)>

:!: Each XML-RPC 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 XML-formatted. You can download the XML Schemas (XSD) following this link FIXME. This tar.gz file contains also some sample outputs, but they are modified to include the schema location and namespace.

We encourage you to use the -x option of the command line interface to collect sample outputs from your own infrastructure.

inlinetoc

Authorization Requests Reference

For each XML-RPC request, the session token has been authenticated, and after that the Request Manager generates an authorization request that can include more than one operation. The following tables document these requests.

:!: INFO_POOL* can be INFO_POOL or INFO_POOL_MINE

onevm

onevm command XML-RPC Method Auth. Request
deploy one.vm.deploy VM:DEPLOY
HOST:USE
delete
restart
shutdown
suspend
hold
resubmit
stop
resume
release
cancel 		one.vm.action VM:MANAGE
migrate
livemigrate 		one.vm.migrate VM:DEPLOY
HOST:USE
saveas one.vm.savedisk VM:MANAGE
IMAGE:CREATE
create one.vm.allocate VM:CREATE
IMAGE:USE
NET:USE
show one.vm.info VM:INFO
chown
chgrp 		one.vm.chown VM:CHOWN
list
top 		one.vmpool.info VM:INFO_POOL*

onetemplate

onetemplate command XML-RPC Method Auth. Request
update one.template.update TEMPLATE:MANAGE
instantiate one.template.instantiate TEMPLATE:INSTANTIATE
IMAGE:USE
NET:USE
create one.template.allocate TEMPLATE:CREATE
publish
unpublish 		one.template.publish TEMPLATE:MANAGE
delete one.template.delete TEMPLATE:DELETE
show one.template.info TEMPLATE:INFO
chown
chgrp 		one.template.chown TEMPLATE:CHOWN
list
top 		one.templatepool.info TEMPLATE:INFO_POOL*

onehost

onehost command XML-RPC Method Auth. Request
enable
disable 		one.host.enable HOST:MANAGE
update one.host.update HOST:MANAGE
create one.host.allocate HOST:CREATE
delete one.host.delete HOST:DELETE
show one.host.info HOST:INFO
list
top 		one.hostpool.info HOST:INFO_POOL

:!: onehost sync is not performed by the core, it is done by the ruby command onehost.

onegroup

onegroup command XML-RPC Method Auth. Request
create one.group.allocate GROUP:CREATE
delete one.group.delete GROUP:DELETE
show one.group.info GROUP:INFO
list one.grouppool.info GROUP:INFO_POOL

onevnet

onevnet command XML-RPC Method Auth. Request
addleases one.vn.addleases NET:MANAGE
rmleases one.vn.rmleases NET:MANAGE
create one.vn.allocate NET:CREATE
publish
unpublish 		one.vn.publish NET:MANAGE
delete one.vn.delete NET:DELETE
show one.vn.info NET:INFO
chown
chgrp 		one.vn.chown NET:CHOWN
list one.vnpool.info NET:INFO_POOL*

oneuser

oneuser command XML-RPC Method Auth. Request
create one.user.allocate USER:CREATE
delete one.user.delete USER:DELETE
show one.user.info USER:INFO
passwd one.user.passwd USER:MANAGE
chgrp one.user.chgrp USER:CHOWN
list one.userpool.info USER:INFO_POOL

oneimage

oneimage command XML-RPC Method Auth. Request
persistent
nonpersistent 		one.image.persistent IMAGE:MANAGE
enable
disable 		one.image.enable IMAGE:MANAGE
update one.image.update IMAGE:MANAGE
create one.image.allocate IMAGE:CREATE
publish
unpublish 		one.image.publish IMAGE:MANAGE
delete one.image.delete IMAGE:DELETE
show one.image.info IMAGE:INFO
chown
chgrp 		one.image.chown IMAGE:CHOWN
list
top 		one.imagepool.info IMAGE:INFO_POOL*

oneacl

oneacl command XML-RPC Method Auth. Request
create one.acl.addrule ACL:MANAGE
delete one.acl.delrule ACL:MANAGE
list one.acl.info ACL:MANAGE

Actions for Templates Management

one.template.allocate

  • Description: Allocates a new template in OpenNebula.
  • Parameters
Type Data Type Description
IN String The session string.
IN String A string containing the template contents
OUT Boolean true or false whenever is successful or not
OUT Int/String The allocated resource ID / The error string.
OUT Int Error code.

one.template.delete

  • Description: Deletes the given template from the pool.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.template.instantiate

  • Description: Instantiates a new virtual machine from a template.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN String Name for the new VM instance. If it is an empty string, OpenNebula will assign one automatically.
OUT Boolean true or false whenever is successful or not
OUT Int/String The new virtual machine ID / The error string.
OUT Int Error code.

one.template.update

  • Description: Replaces the template contents.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN String The new template contents.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.template.publish

  • Description: Publishes or unpublishes a Resource.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN Boolean true for publishing, false for unpublishing.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.template.chown

  • Description: Changes the ownership of a template.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN Int The User ID of the new owner. If set to -1, the owner is not changed.
IN Int The Group ID of the new group. If set to -1, the group is not changed.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.template.info

  • Description: Retrieves information for the template.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT Int Error code.

one.templatepool.info

  • Description: Retrieves information for all or part of the Resources in the pool.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int Filter flag
- < = -3: Connected user's resources
- -2: All resources
- -1: Connected user's and his group's resources
- > = 0: UID User's Resources
IN Int Range start ID. Can be -1.
IN Int Range end ID. Can be -1.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT 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>).

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 Data Type Description
IN String The session string.
IN String A string containing the template for the vm
OUT Boolean true or false whenever is successful or not
OUT Int/String The allocated resource ID / The error string.
OUT Int Error code.

one.vm.deploy

  • Description: initiates the instance of the given vmid on the target host.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN Int The Host ID of the target host where the VM will be deployed.
OUT Boolean true or false whenever is successful or not
OUT Int/String The VM ID / The error string.
OUT Int Error code.

one.vm.action

  • Description: submits an action to be performed on a virtual machine.
  • Parameters
Type Data Type Description
IN String The session string.
IN String the action name to be performed, see below.
IN Int The object ID.
OUT Boolean true or false whenever is successful or not
OUT Int/String The VM ID / The error string.
OUT Int Error code.

The action String must be one of the following:

Action Description
shutdown
hold
release
stop
cancel
suspend
resume
restart
finalize
resubmit

one.vm.migrate

  • Description: migrates one virtual machine (vid) to the target host (hid).
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN Int the target host id (hid) where we want to migrate the vm.
IN Boolean if true we are indicating that we want livemigration, otherwise false.
OUT Boolean true or false whenever is successful or not
OUT Int/String The VM ID / The error string.
OUT Int Error code.

one.vm.savedisk

  • Description: Sets the disk to be saved in the given image.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN Int Disk ID of the disk we want to save.
IN String Name for the new Image where the disk will be saved.
OUT Boolean true or false whenever is successful or not
OUT Int/String The new allocated Image ID / The error string.
OUT Int Error code.

one.vm.chown

  • Description: Changes the ownership of a virtual machine.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN Int The User ID of the new owner. If set to -1, the owner is not changed.
IN Int The Group ID of the new group. If set to -1, the group is not changed.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.vm.info

  • Description: Retrieves information for the virtual machine.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT Int Error code.

one.vmpool.info

  • Description: Retrieves information for all or part of the VMs in the pool.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int Filter flag
- < = -3: Connected user's resources
- -2: All resources
- -1: Connected user's and his group's resources
- > = 0: UID User's Resources
IN Int Range start ID. Can be -1.
IN Int Range end ID. Can be -1.
IN Int VM state to filter by.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT 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>).

The state filter can be one of the following:

Value State
-2 Any state, including DONE
-1 Any state, except DONE
0 INIT
1 PENDING
2 HOLD
3 ACTIVE
4 STOPPED
5 SUSPENDED
6 DONE
7 FAILED

Actions for Hosts Management

one.host.allocate

  • Description: Allocates a new host in OpenNebula
  • Parameters
Type Data Type Description
IN String The session string.
IN String Hostname of the machine we want to add
IN String The name of the information manager (im_mad_name), this values are taken from the oned.conf with the tag name IM_MAD (name)
IN String 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)
IN String The name of the transfer manager mad name (tm_mad_name), this values are taken from the oned.conf with the tag name TM_MAD (name)
OUT Boolean true or false whenever is successful or not
OUT Int/String The allocated Host ID / The error string.
OUT Int Error code.

one.host.delete

  • Description: Deletes the given host from the pool
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.host.enable

  • Description: Enables or disables the given host
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The Host ID.
IN Boolean Set it to true/false to enable or disable the target Host.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.host.update

  • Description: Replaces the host's template contents.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN String The new template contents.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.host.info

  • Description: Retrieves information for the host.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT Int Error code.

one.hostpool.info

  • Description: Retrieves information for all the hosts in the pool.
  • Parameters
Type Data Type Description
IN String The session string.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT Int Error code.

Actions for Virtual Network Management

one.vn.allocate

  • Description: Allocates a new virtual network in OpenNebula.
  • Parameters
Type Data Type Description
IN String The session string.
IN String A string containing the template of the virtual network
OUT Boolean true or false whenever is successful or not
OUT Int/String The allocated resource ID / The error string.
OUT Int Error code.

one.vn.delete

  • Description: Deletes the given virtual network from the pool.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.vn.addleases

  • Description: Adds a new lease to the virtual network. Only available for FIXED networks.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN String template of the lease to add, e.g. “LEASES=[IP=192.168.0.5]” or “LEASES=[IP=192.168.0.5, MAC=50:20:20:20:20:20]”.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.vn.rmleases

  • Description: Removes a lease from the virtual network. Only available for FIXED networks.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN String template of the lease to remove, e.g. “LEASES=[IP=192.168.0.5]”.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.vn.publish

  • Description: Publishes or unpublishes a virtual network.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN Boolean true for publishing, false for unpublishing.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.vn.chown

  • Description: Changes the ownership of a virtual network.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN Int The User ID of the new owner. If set to -1, the owner is not changed.
IN Int The Group ID of the new group. If set to -1, the group is not changed.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.vn.info

  • Description: Retrieves information for the virtual network.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT Int Error code.

one.vnpool.info

  • Description: Retrieves information for all or part of the virtual networks in the pool.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int Filter flag
- < = -3: Connected user's resources
- -2: All resources
- -1: Connected user's and his group's resources
- > = 0: UID User's Resources
IN Int Range start ID. Can be -1.
IN Int Range end ID. Can be -1.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT 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>).

Actions for Image Management

one.image.allocate

  • Description: Allocates a new image in OpenNebula.
  • Parameters
Type Data Type Description
IN String The session string.
IN String A string containing the template of the image.
OUT Boolean true or false whenever is successful or not
OUT Int/String The allocated resource ID / The error string.
OUT Int Error code.

one.image.delete

  • Description: Deletes the given image from the pool.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.image.enable

  • Description: Enables or disables an image.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The Image ID.
IN Boolean True for enabling, false for disabling.
OUT Boolean true or false whenever is successful or not.
OUT Int/String The Image ID / The error string.
OUT Int Error code.

one.image.persistent

  • Description: Sets the Image as persistent or not persistent.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The Image ID.
IN Boolean True for persistent, false for non-persisent.
OUT Boolean true or false whenever is successful or not.
OUT Int/String The Image ID / The error string.
OUT Int Error code.

one.image.update

  • Description: Replaces the image template contents.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN String The new template contents.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.image.publish

  • Description: Publishes or unpublishes an image.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN Boolean true for publishing, false for unpublishing.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.image.chown

  • Description: Changes the ownership of an image.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN Int The User ID of the new owner. If set to -1, the owner is not changed.
IN Int The Group ID of the new group. If set to -1, the group is not changed.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.image.info

  • Description: Retrieves information for the image.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT Int Error code.

one.imagepool.info

  • Description: Retrieves information for all or part of the images in the pool.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int Filter flag
- < = -3: Connected user's resources
- -2: All resources
- -1: Connected user's and his group's resources
- > = 0: UID User's Resources
IN Int Range start ID. Can be -1.
IN Int Range end ID. Can be -1.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT 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>).

Actions for User Management

one.user.allocate

  • Description: Allocates a new user in OpenNebula
  • Parameters
Type Data Type Description
IN String The session string.
IN String username for the new user
IN String password for the new user
OUT Boolean true or false whenever is successful or not
OUT Int/String The allocated User ID / The error string.
OUT Int Error code.

one.user.delete

  • Description: Deletes the given user from the pool.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.user.passwd

  • Description: Changes the password for the given user.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
IN String The new password
OUT Boolean true or false whenever is successful or not
OUT Int/String The User ID / The error string.
OUT Int Error code.

one.user.chgrp

  • Description: Changes the group of the given user.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The User ID.
IN Int The Group ID of the new group.
OUT Boolean true or false whenever is successful or not
OUT Int/String The User ID / The error string.
OUT Int Error code.

one.user.info

  • Description: Retrieves information for the user.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID. If it is -1, then the connected user's own info info is returned
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT Int Error code.

one.userpool.info

  • Description: Retrieves information for all the users in the pool.
  • Parameters
Type Data Type Description
IN String The session string.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT Int Error code.

Actions for Group Management

one.group.allocate

  • Description: Allocates a new group in OpenNebula.
  • Parameters
Type Data Type Description
IN String The session string.
IN String Name for the new group.
OUT Boolean true or false whenever is successful or not
OUT Int/String The allocated Group ID / The error string.
OUT Int Error code.

one.group.delete

  • Description: Deletes the given group from the pool.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID.
OUT Boolean true or false whenever is successful or not
OUT Int/String The resource ID / The error string.
OUT Int Error code.

one.group.info

  • Description: Retrieves information for the group.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int The object ID. If it is -1, then the connected user's group info info is returned
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT Int Error code.

one.grouppool.info

  • Description: Retrieves information for all the groups in the pool.
  • Parameters
Type Data Type Description
IN String The session string.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT Int Error code.

Actions for ACL Rules Management

one.acl.addrule

  • Description: Adds a new ACL rule.
  • Parameters
Type Data Type Description
IN String The session string.
IN String User component of the new rule. A string containing a hex number.
IN String Resource component of the new rule. A string containing a hex number.
IN String Rights component of the new rule. A string containing a hex number.
OUT Boolean true or false whenever is successful or not
OUT Int/String The allocated ACL rule ID / The error string.
OUT Int 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 ACL rule.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int ACL rule ID.
OUT Boolean true or false whenever is successful or not
OUT Int/String The ACL rule ID / The error string.
OUT Int Error code.

one.acl.info

  • Description: Returns the complete ACL rule set.
  • Parameters
Type Data Type Description
IN String The session string.
IN Int ACL rule ID.
OUT Boolean true or false whenever is successful or not
OUT String The information string / The error string.
OUT Int Error code.