Virtual Machine Definition File 1.4
A template file consists of a set of attributes that defines a Virtual Machine. The syntax of the template file is as follows:
<xterm> NAME=VALUE </xterm>
<xterm> NAME=[NAME1=VALUE1,NAME2=VALUE2…] </xterm>
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> . |
MEMORY | Amount of RAM required for the VM, in Megabytes. |
CPU | Percentage of CPU divided by 100 required for the Virtual Machine. Half a processor is written 0.5. |
VCPU | Number of virtual cpus. This value is optional, the default hypervisor behavior is used, usually one virtual CPU |
Example: <xterm>
NAME = test-vm MEMORY = 128
CPU = 1
</xterm>
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
:
<xterm>
OS = [ kernel = /vmlinuz,
initrd = /initrd.img, root = sda1, kernel_cmd = "ro xencons=tty console=tty1"]
</xterm>
The disks of a VM are defined with the DISK
vector attribute. You can define as many DISK
attributes as you need. There are two special disk types that are created on-the-fly in the target resource: swap
and fs
. 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 , fs , block | O (only swap , fs and block ) (if not present, disk will be assumed) | O |
SOURCE | disk file location path or URL | M | M |
SIZE | size in Mb for swap, fs and block images | M (for swap and fs ) | M (for swap and fs ) |
FORMAT | filesystem type for the fs images | M (for fs ) | M (for fs ) |
TARGET | device to map disk | M | M |
CLONE | clone this image yes (default), or no | O | O |
SAVE | save this image after shutting down the VM yes , or no (default) | O | O |
READONLY | yes , or no (default) | O | O |
BUS | type of disk device to emulate: ide , scsi | - | O |
Example, a VM with three disks: the base system attached to sda1
, a clean filesystem attached to sda2
, and a swap partition attached to sda3
. Note that fs
and swap
are generated on-the-fly:
<xterm>
DISK = [ source = /images/vm.img,
clone = no, target = sda1, readonly = no]
DISK = [ type = fs,
size = 4096, format = ext3, save = yes, target = sda2]
DISK = [ type = swap,
size = 2048, target = sda3]
</xterm>
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 |
MODEL | hardware that will emulate this network interface | - | O |
Example, a VM with two NIC attached to two different networks, one make use of the Virtual Network Manager lease feature: <xterm> NIC = [ network = “Public” ]
NIC = [ MAC = “00:11:22:33:44:55”
bridge = eth0 ]
</xterm>
For more information on setting up virtual networks please check the Managing Virtual Networks guide.
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 - KEYMAP: keyboard configuration locale to use in the VNC display | O | O |
Example: <xterm> GRAPHICS = [
type = "vnc", listen = "127.0.0.1", port = "5"]
</xterm>
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: <xterm> REQUIREMENTS = “CPUSPEED > 1000” RANK = FREECPU </xterm>
Context information is passed to the Virtual Machine via an ISO mounted as a partition. This information can be defined in the VM template in the optional section called Context, with the following attributes:
Attribute | Description |
---|---|
VARIABLE | Variables that store values related to this virtual machine or others. The name of the variable is arbitrary (in the example, we use hostname). |
FILES | space-separated list of paths to include in context device. |
TARGET | device to attach the context ISO. |
The values referred to by VARIABLE can be:
Example: <xterm> CONTEXT = [
hostname = "$NAME", ip_private = "$NIC[IP, NETWORK=\"Private LAN\"]", ip_gen = "10.0.0.$VMID"]
</xterm>
The syntax of the requirement expressions is defined as:
<xterm>
stmt::= expr';' expr::= VARIABLE '=' NUMBER | VARIABLE '!''=' NUMBER | VARIABLE '>' NUMBER | VARIABLE '<' NUMBER | VARIABLE '=' STRING | VARIABLE '!''=' STRING | expr '&' expr | expr '|' expr | '!' expr | '(' expr ')'
</xterm>
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 work 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
If using OpenNebula's default match-making scheduler in a hypervisor heterogeneous environment, it is a good idea to add an extra line like the following to the VM template to ensure its placement in a VMWare hypervisor enabled machine.
<xterm> REQUIREMENTS=“HYPERVISOR=\”vmware\“” </xterm>
Examples:
<xterm>
REQUIREMENTS = "HOSTNAME = \"aquila*\"" #Only aquila nodes, note the quotes REQUIREMENTS = FREECPU > 0.6 #Only those resources with more than 60% of free CPU
</xterm>
The syntax of the rank expressions is defined as:
<xterm>
stmt::= expr';' expr::= VARIABLE | NUMBER | expr '+' expr | expr '-' expr | expr '*' expr | expr '/' expr | '-' expr | '(' expr ')'
</xterm>
Rank expressions are evaluated using each host information. '+', '-', '*', '/' and '-' are arithmetic operators. The rank expression is calculated using floating point arithmetics, and then round to an integer value.
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 number (integer or float) attribute defined for the host can be used in the rank attribute
Examples:
<xterm>
RANK = FREECPU # First those resources with a higher Free CPU RANK = FREECPU * 100 - TEMPERATURE # Consider also the CPU temperature
</xterm>
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 |
Example <xterm>
RAW = [
type = "xen", data = "builder=\"linux\" bootloader=\"/usr/lib/xen/boot/domUloader.py\" bootargs=\"--entry=xvda2:/boot/vmlinuz-xenpae,/boot/vmlinuz-xenpae\""]
</xterm>