XML-RPC API 2.0

This documentation provides a description of the xmlrpc methods exposed by OpenNebula. The methods consist of the name of the method that will be invoked, input values needed to the execution and results of execution as outputs.

The information strings returned by the one.*.info methods (e.g. one.vm.info, one.imagepool.info) are XML-formatted. You can download the XML Schemas (XSD) following this link. 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.

:!: The Session string in the methods below identifies the user as it has to be formed with <username>:<SHA1(password)>

Actions for Virtual Machine Management

VM Allocation

  • Name: one.vm.allocate
  • Description: allocates a virtual machine description from the given template string
  • Parameters
Type Data Type Description
IN String the session string associated to connected the user * *
IN String a string containing the template of the vm
OUT Boolean true or false whenever is successful or not
OUT String/Int if an error occurs this is error message, if successful this is the associated id (int vid) generated

VM Deployment

  • Name: 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 associated to the connected user. * *
IN Int the virtual machine Id (vid)to start
IN Int the host id (hid) of the target host where the VM will be instantiated.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, otherwise it does not exist.

VM Actions

  • Name: one.vm.action
  • Description: submits an action to be performed on a virtual machine.
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN String the action name to be performed, can be: “shutdown”, “hold”, “release”, “stop”, “cancel”, “suspend”, “resume”, “restart”, “finalize”
IN Int the id (vid) of the vm that we want to execute the action on.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, otherwise it does not exist.

VM Migration

  • Name: one.vm.migrate
  • Description: migrates one virtual machine (vid) to the target host (hid).
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the virtual machine Id (vid) of the instance we want to migrate.
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 String if an error occurs this is error message, otherwise it does not exist.

VM Save disk

  • Name: one.vm.savedisk
  • Description: Sets the disk to be saved in the given image.
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the virtual machine Id (vid) of the instance.
IN Int disk id of the disk we want to save.
IN Int image id where the disk will be saved.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, otherwise it does not exist.

VM Information

  • Name: one.vm.info
  • Description: gets information on a virtual machine
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the virtual machine Id (vid) of the instance we want information about.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, if successful this is the information string.

VM Pool Information

  • Name: one.vmpool.info
  • Description: Retrieves all or part of the VMs in the pool. This method can be called with only the first two parameters for compatibility with previous versions.
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int Filter flag
- < = -2: All VMs
- -1: Connected user's VMs
- > = 0: UID User's VMs
IN Boolean True for extended information. If not present, default is true.
IN Int Include only VMs in this state. -1 means any state, except DONE. If not present, default is -1.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, if successful this is the information string.

Actions for Hosts Management

Host Allocation

  • Name: one.host.allocate
  • Description: adds a host to the host list
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
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 transfer manager mad name to be used with this host * *
IN Boolean this is the “managed” flag of the host, that indicates whenever this host is part of our administrative domain or not
OUT Boolean true or false whenever is successful or not
OUT String/Int if an error occurs this is error message, if successful this is the associated id (int hid) generated for this host

Host Information

  • Name: one.host.info
  • Description: retrieves the information of the given host
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the host id (hid) of the target machine.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, if successful this is the string with the information returned by OpenNebula.

Host Delete

  • Name: one.host.delete
  • Description: deletes a host from the host list
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the host id (hid) of the target host we want to delete.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, otherwise it does not exist.

Host Enable

  • Name: one.host.enable
  • Description: Enables or disables a given host
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the target host id (hid) of the machine you want to enable/disable.
IN Boolean if set true OpenNebula will enable the target host, if set false it will disable it.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, otherwise it does not exist.

Host Pool Information

  • Name: one.hostpool.info
  • Description: retrieves all the hosts in the pool
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, if successful this is the information string.

Actions for Virtual Network Management

Virtual Network Allocation

  • Name: one.vn.allocate
  • Description: allocates a new virtual network in OpenNebula
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user * *
IN String a string containing the template of the virtual network
OUT Boolean true or false whenever is successful or not
OUT String/Int if an error occurs this is error message, if successful this is the associated id (int nid) generated for this virtual network

Virtual Network Information

  • Name: one.vn.info
  • Description: retrieves the information of the given virtual network
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the virtual network id (nid)
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, if successful this is the string with the information about the virtual network returned by OpenNebula

Virtual Network Delete

  • Name: one.vn.delete
  • Description: deletes a virtual network from the virtual network pool
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the virtual network id (nid) of the target virtual network we want to delete.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, otherwise it does not exist.

Virtual Network Publish

  • Name: one.vn.publish
  • Description: Publishes or unpublishes a virtual network.
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the virtual network id (nid)
IN Boolean true for publishing, false for unpublishing.
OUT Boolean true or false whenever is successful or not
OUT String/Int if an error occurs this is error message, otherwise it is the virtual network id.

Virtual Network Pool Information

  • Name: one.vnpool.info
  • Description: retrieves all or part of the Virtual Networks in the pool
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int Filter flag
- < = -2: All VNs
- -1: Connected user's VNs and Public ones
- > = 0: UID User's VNs
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, if successful this is the information string.

Actions for User Management

User Allocation

  • Name: one.user.allocate
  • Description: allocates a new user in OpenNebula
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user * *
IN String username for the new user
IN String password for the new user
OUT Boolean true or false whenever the allocation is successful or not
OUT String/Int if an error occurs this is the error message, if successful this is the associated id (int uid) generated for this user

User password change

  • Name: one.user.passwd
  • Description: Changes the password for the given user.
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the user id (uid) for the user to update the password
IN String The new password
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, otherwise it does not exist.

User Delete

  • Name: one.user.delete
  • Description: deletes a user from the user pool
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the user id (uid) of the target user we want to delete.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, otherwise it does not exist.

User Pool Information

  • Name: one.userpool.info
  • Description: retrieves all or part of the users in the pool
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, if successful this is the information string.

Actions for Image Management

Image Allocation

  • Name: one.image.allocate
  • Description: allocates a new image in OpenNebula
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user * *
IN String a string containing the template of the image
OUT Boolean true or false whenever the allocation is successful or not
OUT String/Int if an error occurs this is the error message, if successful this is the associated id (int id) generated for this image

Image Information

  • Name: one.image.info
  • Description: retrieves the information of the given image
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the image id for the image to retrieve the information from
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, if successful this is the string with the information about the image returned by OpenNebula

Image Delete

  • Name: one.image.delete
  • Description: deletes an image from the image pool
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the image id of the target image we want to delete.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, otherwise it does not exist.

Image attribute update

  • Name: one.image.update
  • Description: Modifies an image attribute
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the image id of the target image we want to modify.
IN String the name of the attribute to update.
IN String the new value for the attribute.
OUT Boolean true or false whenever is successful or not
OUT String/Int if an error occurs this is error message, otherwise it is the image id.

Image attribute remove

  • Name: one.image.rmattr
  • Description: Removes an image attribute
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the image id of the target image we want to modify.
IN String the name of the attribute to remove.
OUT Boolean true or false whenever is successful or not
OUT String/Int if an error occurs this is error message, otherwise it is the image id.

Image enable

  • Name: one.image.enable
  • Description: Enables or disables an image
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the image id of the image.
IN Boolean true for enabling, false for disabling.
OUT Boolean true or false whenever is successful or not
OUT String/Int if an error occurs this is error message, otherwise it is the image id.

Image publish

  • Name: one.image.publish
  • Description: Publishes or unpublishes an image
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the image id of the image.
IN Boolean true for publishing, false for unpublishing.
OUT Boolean true or false whenever is successful or not
OUT String/Int if an error occurs this is error message, otherwise it is the image id.

Image Pool Information

  • Name: one.imagepool.info
  • Description: retrieves all or part of the images in the pool
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int Filter flag
· < = -2: All Images
· -1: Images belonging to the connected user and Public ones
· > = 0: UID User's Images
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, if successful this is the information string.

Actions for Cluster Management

Cluster Allocation

  • Name: one.cluster.allocate
  • Description: Creates a new cluster in the pool
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN String name for the cluster we want to add
OUT Boolean true or false whenever is successful or not
OUT String/Int if an error occurs this is error message, if successful this is the associated id (int clid) generated for this cluster.

Cluster Information

  • Name: one.cluster.info
  • Description: Retrieves the information of the given cluster
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the cluster id for the cluster to retrieve the information from
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, if successful this is the string with the information about the cluster returned by OpenNebula

Cluster Delete

  • Name: one.cluster.delete
  • Description: Deletes a cluster from the cluster pool
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the cluster id of the target cluster we want to delete.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, otherwise it does not exist.

Cluster host addition

  • Name: one.cluster.add
  • Description: Adds a host to a cluster.
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the host id (hid) of the host.
IN Int the cluster id of the cluster where the host will be assigned.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, otherwise it does not exist.

Cluster host removal

  • Name: one.cluster.remove
  • Description: Removes a host from its cluster.
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
IN Int the host id (hid) of the host.
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, otherwise it does not exist.

Cluster Pool Information

  • Name: one.clusterpool.info
  • Description: Returns the cluster pool information.
  • Parameters
Type Data Type Description
IN String the session string associated to the connected user. * *
OUT Boolean true or false whenever is successful or not
OUT String if an error occurs this is error message, if successful this is the information string.