You can manage your virtual machines using the onevm command or Sunstone. In Sunstone, you can easily instantiate currently defined templates by clicking “New” on the Virtual Machines tab. A dialog will allow you to name the VM and choose the number of instances you want to create:

The life-cycle of a Virtual Machine within OpenNebula includes the following stages:

Note that this is a simplified version. If you are a developer you may want to take a look at the complete diagram referenced in the xml-rpc api page):

• Pending (pend): By default a VM starts in the pending state, waiting for a resource to run on. It will stay in this state until the scheduler decides to deploy it, or the user deploys it using the onevm deploy command.
• Hold (hold): The owner has held the VM and it will not be scheduled until it is released. It can be, however, deployed manually.
• Prolog (prol): The system is transferring the VM files (disk images and the recovery file) to the host in which the virtual machine will be running.
• Running (runn): The VM is running (note that this stage includes the internal virtualized machine booting and shutting down phases). In this state, the virtualization driver will periodically monitor it.
• Migrate (migr): The VM is migrating from one resource to another. This can be a life migration or cold migration (the VM is saved and VM files are transferred to the new resource).
• Epilog (epil): In this phase the system cleans up the Host used to virtualize the VM, and additionally disk images to be saved are copied back to the front-end.
• Stopped (stop): The VM is stopped. VM state has been saved and it has been transferred back along with the disk images to the front-end.
• Suspended (susp): Same as stopped, but the files are left in the host to later restart the VM there (i.e. there is no need to re-schedule the VM).
• Failed (fail): The VM failed.
• Unknown (unknown): The VM couldn't be reached, it is in an unknown state.
• Done (done): The VM is done. VMs in this state won't be shown with “onevm list” but are kept in the database for accounting purposes.

The following sections show the basics of the onevm command with simple usage examples. A complete reference for these commands can be found here.

This command enables Virtual Machine management. Actions offered are:

• create: Adds a new VM in OpenNebula's VM pool from a template file.
• deploy: Starts an existing VM in a specific Host.
• shutdown: Gracefully shuts down a running VM, sending the ACPI signal.
• livemigrate: The Virtual Machine is transferred between Hosts with no noticeable downtime. This action requires a shared file system storage.
• migrate: The VM gets stopped and resumed in the target host.
• hold: Sets the VM to hold state, the scheduler will not deploy it.
• release: Releases a VM from hold state, setting it to pending.
• stop: The Virtual Machine state is transferred back to the front-end for a possible reschedule.
• cancel: The running VM is immediately destroyed. Use this action instead of “shutdown” when the VM doesn't have ACPI support, or when it has become irresponsive. The difference with the “delete” action is that the persistent Images are saved back to the repository.
• suspend: same as stop but the Virtual Machine state is left in the Host for resuming.
• resume: Resumes the execution of a saved VM.
• saveas: Sets the specified VM disk to be saved in a new Image.
• delete: The running VM is immediately destroyed. Using this action instead of “cancel” will set the Images meant to be saved in error state.
• restart: Forces the hypervisor boot action of a VM stuck in UNKNOWN or BOOT state.
• resubmit: Resubmits a VM to PENDING state. This is intended for VMs stuck in a transient state. To re-deploy a fresh copy of the same VM, create a Template and instantiate it.
• list: Outputs all the available VMs.
• show: Outputs information for a specific VM.
• top: Lists VMs continuously.

Assuming we have a VM Template registered called vm-example with ID 6, then we can instantiate the VM issuing a:

<xterm> $ onetemplate list

ID USER     GROUP    NAME                         REGTIME PUB
 6 oneadmin oneadmin vm_example            09/28 06:44:07  No

$ onetemplate instantiate vm-example –name my_vm VM ID: 0 </xterm>

afterwards, the VM can be listed with the onevm list command:

<xterm> $ onevm list

  ID USER     GROUP    NAME         STAT CPU     MEM        HOSTNAME        TIME
   0 oneadmin oneadmin my_vm        pend   0      0K                 00 00:00:03

</xterm>

After a Scheduling cycle, the VM will be automatically deployed. But the deployment can also be forced by oneadmin using onevm deploy:

<xterm> $ onehost list

ID NAME               RVM   TCPU   FCPU   ACPU   TMEM   FMEM   AMEM   STAT
 2 testbed              0    800    800    800    16G    16G    16G     on

$ onevm deploy 0 2

$ onevm list

  ID USER     GROUP    NAME         STAT CPU     MEM        HOSTNAME        TIME
   0 oneadmin oneadmin my_vm        runn   0      0K         testbed 00 00:02:40

</xterm>

and details about it can be obtained with show:

<xterm> $ onevm show 0 VIRTUAL MACHINE 0 INFORMATION ID : 0 NAME : my_vm USER : oneadmin GROUP : oneadmin STATE : ACTIVE LCM_STATE : RUNNING START TIME : 04/14 09:00:24 END TIME : - DEPLOY ID: : one-0

VIRTUAL MACHINE MONITORING NET_TX : 13.05 NET_RX : 0 USED MEMORY : 512 USED CPU : 0

VIRTUAL MACHINE TEMPLATE CONTEXT=[

FILES=/service/init.sh /service/certificates /service/service.conf,
TARGET=hdb ]

CPU=1 DISK=[

CLONE=YES,
DISK_ID=0,
IMAGE=Debian 6.0,
IMAGE_ID=3,
READONLY=NO,
SAVE=NO,
SOURCE=/home/cloud/opennebula/var/images/147f94ddb708851e71651f05caf81da0131cc904,
TARGET=hda,
TYPE=DISK ]

DISK=[

CLONE=YES,
DISK_ID=1,
IMAGE=Testing results
IMAGE_ID=5,
READONLY=NO,
SAVE=NO,
SOURCE=/home/cloud/opennebula/var/images/6478ab2b7f839538c6dc4d525ea0153387a91f1c,
TARGET=hde,
TYPE=DISK ]

DISK=[

DISK_ID=2,
READONLY=no,
SIZE=1024,
TARGET=hdd,
TYPE=swap ]

MEMORY=512 NAME=my_vm NIC=[

BRIDGE=vbr2,
IP=192.168.30.1,
MAC=02:00:c0:a8:1e:01,
NETWORK=Private lab 3,
NETWORK_ID=6 ]

OS=[

INITRD=/initrd.img,
KERNEL=/vmlinuz,
ROOT=sda ]

RANK=FREECPU REQUIREMENTS=CPUSPEED > 1000 VMID=0

VIRTUAL MACHINE HISTORY SEQ HOSTNAME REASON START TIME PTIME

 0         testbed   none  09/28 06:48:18 00 00:07:23 00 00:00:00

</xterm>

The following is a quick example of the onevm suspend and onevm stop commands. Using suspend, the VM state is left in the Host. So a resume action restores the VM in the same Host it was running before.

<xterm> $ onevm suspend 0 $ onevm list

  ID USER     GROUP    NAME         STAT CPU     MEM        HOSTNAME        TIME
   0 oneadmin oneadmin my_vm        susp   0    512K         testbed 00 00:11:13

$ onevm resume 0 $ onevm list

  ID USER     GROUP    NAME         STAT CPU     MEM        HOSTNAME        TIME
   0 oneadmin oneadmin my_vm        runn   0    512K         testbed 00 00:15:18

</xterm>

On the other hand, onevm stop saves the VM's status back to the front-end. After a resume action, the VM is set to pending, waiting for the Scheduler to deploy it.

<xterm> $ onevm stop 0 $ onevm list

  ID USER     GROUP    NAME         STAT CPU     MEM        HOSTNAME        TIME
   0 oneadmin oneadmin my_vm        stop   0    512K         testbed 00 00:32:35

$ onevm list

  ID USER     GROUP    NAME         STAT CPU     MEM        HOSTNAME        TIME
   0 oneadmin oneadmin my_vm        pend   0    512K         testbed 00 00:33:46

</xterm>