User Guide 1.2
OpenNebula is a VM manager that is executed and configured by a cluster administrator. This cluster administrator would be also the ONE administrator, and therefore he should be the holder of the <oneadmin>
account. This guide assumes that the cluster administrator is the only user for oned
, although the system has been designed to support several users.
OpenNebula is able to assign, deploy, monitor and control VMs. This guide explains how to describe the wanted-to-be-ran Virtual Machine, and how users typically interact with the system.
A Virtual Machine within the OpenNebula system consists of:
The above items, plus some additional VM attributes like the OS kernel, are specified in a VM template file.
Each VM in OpenNebula is identified by an unique number, the <VID>
. Also, the user can assign it a name in the VM template, the default name for each VM is one-<VID>
.
The life-cycle of a virtual machine within the system includes the following stages (note that this is a simplified version):
pend
): By default a VM starts in the pending state, waiting for a resource to run on.hold
): The owner has held the VM and it will not be scheduled until it is released. prol
): The system is transferring the VM files (disk images and the recovery file).runn
): The VM is running (note that this stage includes booting and shutting down phases). In this state, the virtualization driver will periodically monitor it.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).epil
): In this phase the system clean ups the cluster node used to host the VM, and additionally disk images to be saved are copied back to the cluster front-end.stop
): The VM is stopped. VM state has been saved and it has been transferred back along with the disk images.susp
): Same as stopped, but the files are left in the remote resource to later restart the VM there (i.e. there is no need to re-schedule the VM).fail
): The VM failed. done
): The VM is done. VMs in this state wont be shown with “onevm list” but are kept in the database for accounting purposes.
In order to use OpenNebula, you need to set the following variables in your environment. You may want to place them, in the .bashrc of the <oneadmin>
account for commodity:
ONE_LOCATION | If OpenNebula was installed in self-contained mode, this variable must be set to <destination_folder>. Otherwise, in system wide mode, this variable must be unset. More info on installation modes can be found here |
---|---|
ONE_XMLRPC | http://localhost:2633/RPC2 |
PATH | $ONE_LOCATION/bin:$PATH if self-contained. Otherwise this is not needed. |
A template file consists of a set of attributes that defines a Virtual Machine. The syntax of the template file is as follows:
NAME=VALUE
NAME=[NAME1=VALUE1,NAME2=VALUE2...]
OpenNebula templates were designed to be hypervisor-agnostic, but still there are some peculiarities to be taken into account, and mandatory attributes change depending on the target hypervisor. Hypervisor specific information for this attributes can be found in the drivers configuration guides, here listed in.
OpenNebula has been designed to be easily extended, so any attribute name can be defined for later use in any OpenNebula module. There are some pre-defined attributes, though.
The following attributes can be defined to specified the capacity of a VM.
Attribute | Description |
---|---|
NAME | Name that the VM will get for description purposes. If NAME is not supplied a name generated by one will be in the form of one-<VID> . |
CPU | Percentage of CPU divided by 100 required for the Virtual Machine. Half a processor is written 0.5. |
MEMORY | Amount of RAM required for the VM, in Megabytes. |
Example:
NAME = test-vm CPU = 1 MEMORY = 128
The OS system is defined with the OS
vector attribute. The following sub-attributes are supported:
Note the hypervisor column states that the attribute is Optional, Mandatory, or -
not supported for that hypervisor
OS Sub-Attribute | Description | XEN | KVM |
---|---|---|---|
KERNEL | path to the OS kernel to boot the image | M see (*) | O |
INITRD | path to the initrd image | O (for kernel) | O (for kernel) |
ROOT | device to be mounted as root | O (for kernel) | O (for kernel) |
KERNEL_CMD | arguments for the booting kernel | O (for kernel) | O (for kernel) |
BOOTLOADER | path to the bootloader executable | M see (*) | O |
BOOT | boot device type: hd ,fd ,cdrom ,network | - | M |
(*) Xen needs a kernel or a bootloader to be specified. If both are set in the template, the kernel boot method will be used.
Example, a VM booting from sda1
with kernel /vmlinuz
:
OS = [ kernel = /vmlinuz, initrd = /initrd.img, root = sda1, kernel_cmd = "ro xencons=tty console=tty1"]
The disks of a VM are defined with the DISK
vector attribute. You can define as many DISK
attributes as you need. The following sub-attributes for DISK
are supported:
Note the hypervisor column states that the attribute is Optional, Mandatory, or -
not supported for that hypervisor
DISK Sub-Attribute | Description | XEN | KVM |
---|---|---|---|
TYPE | disk type:floppy , disk , cdrom , swap | O (only swap ) | O |
SOURCE | disk file location path or URL | M | M |
SIZE | size in Mb for swap images | M (for swap ) | M (for swap ) |
TARGET | device to map disk | M | M |
CLONE | clone this image yes (default), or not no | O | O |
SAVE | save this image after stopping the VM yes , or not no (default) | O | O |
SAVE | save this image after stopping the VM yes , or not no | O | O |
READONLY | yes , or not no (default) | O | O |
BUS | type of disk device to emulate: ide , scsi | - | O |
Example, a VM with two disks the base system attached to sda1
, and the other a swap partition generated on-the-fly attached to sda2
:
DISK = [ source = /images/vm.img, clone = no, target = sda1, readonly = no] DISK = [ type = swap, size = 2048, target = sda2]
For more information on image management and moving please check the Storage guide.
Each network interface of a VM is defined with the NIC
vector attribute. You can define as many NIC
attributes as you need. The following sub-attributes for NIC
are supported:
Note the hypervisor column states that the attribute is Optional, Mandatory, or -
not supported for that hypervisor
NIC Sub-Attribute | Description | XEN | KVM |
---|---|---|---|
NETWORK | Name of the network, as defined by onevnet to attach this device | O | O |
IP | Request an specific IP from the NETWORK | O | O |
MAC | HW address associated with the network interface | O | O |
BRIDGE | Name of the bridge the network device is going to be attached to. | O | O |
TARGET | name for the tun device created for the VM | - | O |
SCRIPT | name of a shell script to be executed after creating the tun device for the VM | - | O |
Example, a VM with two NIC attached to two different networks, one make use of the Virtual Network Manager lease feature:
NIC = [ network = "Public" ] NIC = [ MAC = "00:11:22:33:44:55" bridge = eth0 ]
For more information on setting up virtual networks please check the Networking guide. Also you may be interested in how to set up your VMs to make use of this feature.
The following I/O interfaces can be defined for a VM:
Note the hypervisor column states that the attribute is Optional, Mandatory, or -
not supported for that hypervisor
Attribute | Description | XEN | KVM |
---|---|---|---|
INPUT | Define input devices, available sub-attributes: - TYPE: values are mouse or tablet - BUS: values are usb , ps2 or xen | - | O |
GRAPHICS | Wether the VM should export its graphical display and how, available sub-attributes: - TYPE: values: vnc sdl - LISTEN: IP to listen on. - PORT: port for the VNC server - PASSWD: password for the VNC server | O | O |
Example:
GRAPHICS = [ type = "vnc", listen = "127.0.0.1", port = "5"]
Note For KVM hypervisor the port number is a real one, not the VNC port. So for VNC port 0 you should specify 5900, for port 1 is 5901 and so on.
The following attributes placement constraints and preferences for the VM:
Note the hypervisor column states that the attribute is Optional, Mandatory, or -
not supported for that hypervisor
Attribute | Description | XEN | KVM |
---|---|---|---|
REQUIREMENTS | Boolean expression that rules out provisioning hosts from list of machines suitable to run this VM. | O | O |
RANK | This field sets which attribute will be used to sort the suitable hosts for this VM. Basically, it defines which hosts are more suitable than others. | O | O |
Example:
REQUIREMENTS = "CPUSPEED > 1000" RANK = FREECPU
The syntax of the requirement expressions is defined as:
stmt::= expr';' expr::= VARIABLE '=' NUMBER | VARIABLE '!''=' NUMBER | VARIABLE '>' NUMBER | VARIABLE '<' NUMBER | VARIABLE '=' STRING | VARIABLE '!''=' STRING | expr '&' expr | expr '|' expr | '!' expr | '(' expr ')'
Each expression is evaluated to 1 (TRUE) or 0 (FALSE). Only those hosts for which the requirement expression is evaluated to TRUE will be considered to run the VM.
Logical operators are as expected ( less '<', greater '>', '&' AND, '|' OR, '!' NOT), '=' means equals with numbers (floats and integers). When you use '=' operator with strings, it performs a shell wildcard pattern matching.
Any variable defined by the Information Manager driver can be used in the requirements. Check the configuration guide to find out how to extend the information model
There are some predefined variables that can be used: HOSTNAME
, TOTALCPU
, TOTALMEMORY
, FREEMEMORY
, FREECPU
,
USEDMEMORY
, USEDCPU
, HYPERVISOR
Examples:
REQUIREMENTS = "HOSTNAME = \"aquila*\"" #Only aquila nodes, note the quotes REQUIREMENTS = FREECPU > 0.6 #Only those resources with more than 60% of free CPU
The syntax of the rank expressions is defined as:
stmt::= expr';' expr::= VARIABLE | INTEGER | expr '+' expr | expr '-' expr | expr '*' expr | expr '/' expr | '-' expr | '(' expr ')'
Rank expressions are evaluated using each host information. '+', '-', '*', '/' and '-' are arithmetic operators, so only integer values should be used in rank expressions.
The rank expression is evaluated for each host, those hosts with a higher rank are used first to start the VM. The rank policy must be implemented by the scheduler. Check the configuration guide to configure the scheduler.
Similar to the requirements attribute, any integer attribute defined for the host can be used in the rank attribute
Examples:
RANK = FREECPU # First those resources with a higher Free CPU RANK = FREECPU * 100 - TEMPERATURE # Consider also the CPU temperature
This optional section of the VM template is used whenever the need to pass special attributes to the underlying hypervisor arises. Anything placed in the data attribute gets passed straight to the hypervisor, unmodified.
RAW Sub-Attribute | Description | XEN | KVM |
---|---|---|---|
TYPE | Possible values are: kvm ,xen | O | O |
DATA | Raw data to be passed directly to the hypervisor | O | O |
For example, the following template defines a VM with 512MB of memory and one CPU. The VM has two disks: sda supported by an image file; and sdb (a swap partition). Only one NIC is defined with a predefined MAC address. In this case, between all the suitable hosts (those that meets CPU and MEMORY requirements, and also CPUSPEED > 1000 requirement), OpenNebula will pick the host with more free CPU.
#--------------------------------------- # VM definition example #--------------------------------------- NAME = vm-example CPU = 1 MEMORY = 512 # --- kernel & boot device --- OS = [ kernel = "/vmlinuz", initrd = "/initrd.img", root = "sda" ] # --- 2 disks --- DISK = [ source = "/local/xen/domains/etch/disk.img", target = "sda", readonly = "no" ] DISK = [ type = swap, size = 1024 target = "sdb", readonly = "no" ] # --- 1 NIC --- NIC = [ mac="00:ff:72:17:20:27"] # --- VNC server --- GRAPHICS = [ type = "vnc", listen = "127.0.0.1", port = "5"] # Scheduling Attributes for the rank policy REQUIREMENTS = "CPUSPEED > 1000" RANK = FREECPU
Note that you can add as many DISK
and NIC
attributes as you need
OpenNebula comes with a rich command line interface intended for users and sysadmins fond of consoles. There are commands to manage the three basic aspects of OpenNebula: virtual machines, hosts and virtual networks.
A complete reference for these three commands can be found here. The following subsections show the basics of the available commands with simple usage exmaples.
This command enables virtual machine management. Actions offered are:
create
( a VM in OpenNebula's VM pool ) deploy
(on a particular cluster node) shutdown
livemigrate
(the virtual machine is transferred between cluster nodes with no noticeable downtime)migration
(machine gets stopped and resume elsewhere)hold
release
(from hold state)stop
(virtual machine state is transferred back to OpenNebula for a possible reschedule)cancel
suspend
(virtual machine state is left in the cluster node for resuming)resume
delete
list
(outputs all the available VMs)show
(outputs information for a specific VM)top
(lists VMs continously) history
(gets VMs history of execution on the cluster nodes)Assuming we have a VM template called myVM.one describing a virtual machine. Then, we can allocate the VM in OpenNebula issuing a:
$ onevm create myVM.one
afterwards, the VM can be listed with the list
option:
$ onevm list ID NAME STAT CPU MEM HOSTNAME TIME 0 myVM runn 0 2097152 ursa 00 00:00:07
and details about it can be obtained with show
:
$ onevm show myVM VID : 0 UID : 0 STATE : ACTIVE LCM STATE : RUNNING DEPLOY ID : one-0 MEMORY : 2097152 CPU : 0 LAST POLL : 1228318438 START TIME : 03/25 18:17:09 STOP TIME : 01/01 01:00:00 NET TX : 0 NET RX : 0 ....: Template :.... CPU : 1 DISK : CLONE=no,READONLY=no,SOURCE=/images/myVM/myVM.img,TARGET=hda DISK : SIZE=1024,TARGET=hdb,TYPE=swap MEMORY : 2048 NAME : myVM NIC : BRIDGE=eth1,IP=147.96.81.252,MAC=00:02:93:60:51:fc,NETWORK=myNetwork,VNID=0 OS : BOOT=hd,INITRD=/initrd.img,KERNEL=/vmlinuz,KERNEL_CMD=ro,ROOT=sda
This command enables cluster nodes management. Actions offered are:
create
( a node in OpenNebula's host pool ) show
(details of a particular cluster node) delete
list
(lists nodes in the host pool)enable
disable
top
(lists host continuously)
Assuming a cluster node called hosts01 running the XEN
hypervisor and without shared folders, we can let OpenNebula know about it using:
$ onehost create host01 im_xen vmm_xen tm_ssh
then we can list
the recently added node:
$ onehost list HID NAME RVM TCPU FCPU ACPU TMEM FMEM STAT 5 ursa05 3 800 766 500 8387584 6157312 on
and retrieve more detailed information for this node using show
:
$ onehost show host01 HID = 0 HOSTNAME = host01 IM MAD = im_xen VMM MAD = vmm_xen TM MAD = tm_ssh MANAGED = 1 ATTRIBUTES ARCH=x86_64 CPUSPEED=1995 FREECPU=766 FREEMEMORY=6157312 HOSTNAME=host01 MODELNAME=Intel(R) Xeon(R) CPU L5335 @ 2.00GHz NETRX=26008308 NETTX=7961198 TOTALCPU=800 TOTALMEMORY=8387584 USEDCPU=34 USEDMEMORY=2230272 HOST SHARES HID = 5 ENDPOINT = MAX_CPU = 800 MAX_MEMORY = 8387584 MAX_DISK = 0 CPU_USAGE = 300 MEMORY_USAGE = 1572864 DISK_USAGE = 0 RUNNING_VMS = 0
This command enables the management of virtual networks. Actions offered are:
create
( a virtual network in OpenNebula's VN pool ) show
(details of a particular virtual network) delete
list
(lists all the VNs in the VN pool)Assuming a virtual network template called myVN.net, we can create the virtual network within OpenNebula issuing:
$ onevnet create myVN.net
and then list
it using:
$ onevnet list NID NAME TYPE BRIDGE 0 myVN 1 eth1
and obtain details about it with:
$ onevnet show 0 NID : 0 UID : 0 Network Name : myVN Type : Fixed Size : 10 Bridge : eth1 ....: Template :.... BRIDGE=eth1 LEASES=IP=147.96.80.143 NAME=myVN TYPE=FIXED ....: Leases :.... IP = 147.96.80.143 MAC = 00:02:93:60:50:8f USED = 0 VID = -1
OpenNebula can be used to deploy different solutions for on-demand execution of services. We have prepared the following use cases to illustrate its functionality in typical computing scenarios: