Virtual Machine Definition File 4.4
A template file consists of a set of attributes that defines a Virtual Machine. Using the command onetemplate create
, a template can be registered in OpenNebula to be later instantiated. For compatibility with previous versions, you can also create a new Virtual Machine directly from a template file, using the onevm create
command.
*
in the following tables. See the complete list in the Restricted Attributes section.
The syntax of the template file is as follows:
NAME=VALUE
NAME=[NAME1=VALUE1,NAME2=VALUE2]
Since OpenNebula 3.4, template files can be in XML, with the following syntax:
TEMPLATE
<NAME>VALUE</NAME>
<NAME> <NAME1>VALUE1</NAME1> <NAME2>VALUE2</NAME2> </NAME>
A simple example:
<TEMPLATE> <NAME>test_vm</NAME> <CPU>2</CPU> <MEMORY>1024</MEMORY> <DISK> <IMAGE_ID>2</IMAGE_ID> </DISK> <DISK> <IMAGE>Data</IMAGE> <IMAGE_UNAME>oneadmin</IMAGE_UNAME> </DISK> </TEMPLATE>
The following attributes can be defined to specified the capacity of a VM.
Attribute | Description | Mandatory |
---|---|---|
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> . NOTE: When defining a Template it is the name of the VM Template. The actual name of the VM will be set when the VM Template is instantiated. | YES For Templates NO For VMs - will be set to one-<vmid> if omitted |
MEMORY | Amount of RAM required for the VM, in Megabytes. | YES |
CPU | Percentage of CPU divided by 100 required for the Virtual Machine, half a processor is written 0.5. This value is used by OpenNebula and the scheduler to guide the host overcommitment. | YES |
VCPU | Number of virtual cpus. This value is optional, the default hypervisor behavior is used, usually one virtual CPU. | YES - will be set to 1 if omitted, this can be changed in the driver configuration |
Example:
NAME = test-vm MEMORY = 128 CPU = 1
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 | VMWARE |
---|---|---|---|---|
ARCH | CPU architecture to virtualize | - | M (default i686) | M (default i686) |
KERNEL | path to the OS kernel to boot the image in the host | O see (*) | O | - |
KERNEL_DS | image to be used as kernel (see !!) | O see (*) | O | - |
INITRD | path to the initrd image in the host | O (for kernel) | O (for kernel) | - |
INITRD_DS | image to be used as ramdisk (see !!) | 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 | O see (*) | O | - |
BOOT | comma separated list of boot devices types, by order of preference (first device in the list is the first device used for boot). Possible values: hd ,fd ,cdrom ,network | O (only HVM) | M | - |
(*) If no kernel
/initrd
or bootloader
are specified a Xen HVM will be created.
(!!) Use one of KERNEL_DS or KERNEL (and INITRD or INITRD_DS).
KERNEL_DS and INITRD_DS refer to and image registered in a File Datastore and must be of type KERNEL and RAMDISK, respectively. The image should be refer using one of the following:
$FILE[IMAGE=<image name>]
, to select own files$FILE[IMAGE=<image name>, <IMAGE_UNAME|IMAGE_UID>=<owner name|owner id>]
, to select images owned by other users, by user name or uid.$FILE[IMAGE_ID=<image id>]
, global file selection
Example, a VM booting from sda1
with kernel /vmlinuz
:
OS = [ KERNEL = /vmlinuz, INITRD = /initrd.img, ROOT = sda1, KERNEL_CMD = "ro xencons=tty console=tty1"]
OS = [ KERNEL_DS = "$FILE[IMAGE=\"kernel 3.6\"]", INITRD_DS = "$FILE[IMAGE=\"initrd 3.6\"]", 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. There are three types of disks:
DISK Sub-Attribute | Description | Xen | KVM | VMware |
---|---|---|---|---|
IMAGE_ID | ID of the Image to use | Mandatory (no IMAGE) | ||
IMAGE | Name of the Image to use | Mandatory (no IMAGE_ID) | ||
IMAGE_UID | To select the IMAGE of a given user by her ID | Optional | ||
IMAGE_UNAME | To select the IMAGE of a given user by her NAME | Optional | ||
DEV_PREFIX | Prefix for the emulated device this image will be mounted at. For instance, “hd”, “sd”, or “vd” for KVM virtio. If omitted, the dev_prefix attribute of the Image will be used | Optional | ||
TARGET | Device to map image disk. If set, it will overwrite the default device mapping. | Optional | ||
DRIVER | Specific image mapping driver | Optional e.g.: tap:aio: ,file: | Optional e.g.: raw , qcow2 | - |
CACHE | Selects the cache mechanism for the disk. Values are default , none , writethrough , writeback , directsync and unsafe . More info in the libvirt documentation | - | Optional | - |
READONLY | Set how the image is exposed by the hypervisor | Optional e.g.: yes , no . This attribute should only be used for special storage configurations |
||
IO | Set IO policy. Values are threads , native | - | Optional | - |
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:
DISK Sub-Attribute | Description | XEN | KVM | VMWARE |
---|---|---|---|---|
TYPE | Type of the disk:swap , fs | Optional | ||
SIZE | size in MB | Mandatory | ||
FORMAT | filesystem for fs images: ext2 , ext3 … raw will not format the image. | Mandatory (for fs) | ||
DEV_PREFIX | Prefix for the emulated device this image will be mounted at. For instance, “hd”, “sd”. If omitted, the default dev_prefix set in oned.conf will be used | Optional | ||
TARGET | device to map disk | Optional | ||
DRIVER | special disk mapping options. KVM: raw ,qcow2 . Xen: tap:aio: , file: | Optional | ||
CACHE | Selects the cache mechanism for the disk. Values are default , none , writethrough , writeback , directsync and unsafe . More info in the libvirt documentation | - | Optional | - |
READONLY | Set how the image is exposed by the hypervisor | Optional e.g.: yes , no . This attribute should only be used for special storage configurations |
||
IO | Set IO policy. Values are threads , native | - | Optional | - |
If the TARGET attribute is not set for a disk, OpenNebula will automatically assign it using the following precedence, starting with dev_prefix + a
:
Please visit the guide for managing images and the image template reference to learn more about the different image types.
You can find a complete description of the contextualization features in the contextualization guide.
The default device prefix sd
can be changed to hd
or other prefix that suits your virtualization hypervisor requirements. You can find more information in the daemon configuration guide.
This a sample section for disks. There are four disks using the image repository, and two volatile ones. Note that fs
and swap
are generated on-the-fly:
# First OS image, will be mapped to sda. Use image with ID 2 DISK = [ IMAGE_ID = 2 ] # First DATABLOCK image, mapped to sdb. # Use the Image named Data, owned by the user named oneadmin. DISK = [ IMAGE = "Data", IMAGE_UNAME = "oneadmin" ] # Second DATABLOCK image, mapped to sdc # Use the Image named Results owned by user with ID 7. DISK = [ IMAGE = "Results", IMAGE_UID = 7 ] # Third DATABLOCK image, mapped to sdd # Use the Image named Experiments owned by user instantiating the VM. DISK = [ IMAGE = "Experiments" ] # Volatile filesystem disk, sde DISK = [ TYPE = fs, SIZE = 4096, FORMAT = ext3 ] # swap, sdf DISK = [ TYPE = swap, SIZE = 1024 ]
Because this VM did not declare a CONTEXT or any disk using a CDROM Image, the first DATABLOCK found is placed right after the OS Image, in sdb
. 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 | VMWARE |
---|---|---|---|---|
NETWORK_ID | ID of the network to attach this device, as defined by onevnet . Use if no NETWORK | Mandatory (No NETWORK) | ||
NETWORK | Name of the network to use (of those owned by user). Use if no NETWORK_ID | Mandatory (No NETWORK_ID) | ||
NETWORK_UID | To select the NETWORK of a given user by her ID | Optional | ||
NETWORK_UNAME | To select the NETWORK of a given user by her NAME | Optional | ||
IP | Request an specific IP from the NETWORK | Optional | ||
MAC* | Request an specific HW address from the network interface | Optional | ||
BRIDGE | Name of the bridge the network device is going to be attached to. | Optional | ||
TARGET | name for the tun device created for the VM | - | Optional | Optional |
SCRIPT | name of a shell script to be executed after creating the tun device for the VM | Optional | ||
MODEL | hardware that will emulate this network interface. With Xen this is the type attribute of the vif. In KVM you can choose virtio to select its specific virtualization IO framework | Optional | ||
WHITE_PORTS_TCP | iptables_range : Permits access to the VM only through the specified ports in the TCP protocol. Supersedes BLACK_PORTS_TCP if defined. | Optional | ||
BLACK_PORTS_TCP | iptables_range : Doesn't permit access to the VM through the specified ports in the TCP protocol. Superseded by WHITE_PORTS_TCP if defined. | Optional | ||
WHITE_PORTS_UDP | iptables_range : Permits access to the VM only through the specified ports in the UDP protocol. Supersedes BLACK_PORTS_UDP if defined. | Optional | ||
BLACK_PORTS_UDP | iptables_range : Doesn't permit access to the VM through the specified ports in the UDP protocol. Superseded by WHITE_PORTS_UDP if defined. | Optional | ||
ICMP | drop: Blocks ICMP connections to the VM. By default it's set to accept. | Optional |
* only for users in oneadmin group
iptables_range
is a list of ports separated by commas or a ranges separated by semilocolons, e.g.: 22,80,5900:6000
.
Example, a VM with two NIC attached to two different networks:
NIC = [ NETWORK_ID = 1 ] NIC = [ NETWORK = "Blue", NETWORK_UID = 0 ]
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 | VMWARE |
---|---|---|---|---|
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 , spice - 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:
GRAPHICS = [ TYPE = "vnc", LISTEN = "0.0.0.0", PORT = "5"]
$VNC_BASE_PORT + $VMID
, allowing to generate different ports for VMs so they do not collide. The VNC_BASE_PORT
is specified inside the oned.conf
file.
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 | Mandatory |
---|---|---|
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). | Optional |
FILES * | space-separated list of paths to include in context device. | Optional |
FILES_DS | space-separated list of File images to include in context device. | Optional |
TARGET | device to attach the context ISO. | Optional |
TOKEN | “YES” to create a token.txt file for OneGate monitorization | Optional |
NETWORK | “YES” to fill automatically the networking parameters for each NIC, used by the Contextualization packages | Optional |
* only for users in oneadmin group
The values referred to by VARIABLE can be defined :
HOSTNAME = "MAINHOST"
$<template_variable>
: any single value variable of the VM template, like for example:IP_GEN = "10.0.0.$VMID"
$<template_variable>[<attribute>]
: Any single value contained in a multiple value variable in the VM template, like for example:IP_PRIVATE = $NIC[IP]
$<template_variable>[<attribute>, <attribute2>=<value2>]
: Any single value contained in the variable of the VM template, setting one attribute to discern between multiple variables called the same way, like for example:IP_PUBLIC = "$NIC[IP, NETWORK=\"Public\"]"
$NETWORK[<vnet_attribute>, <NETWORK_ID|NETWORK>=<vnet_id|vnet_name>]
: Any single value variable in the Virtual Network template, like for example:dns = "$NETWORK[DNS, NETWORK_ID=3]"
Note that the network MUST be in used by any of the NICs defined in the template. The vnet_attribute can be TEMPLATE
to include the whole vnet template in XML (base64 encoded).
$IMAGE[<image_attribute>, <IMAGE_ID|IMAGE>=<img_id|img_name>]
: Any single value variable in the Image template, like for example:root = "$IMAGE[ROOT_PASS, IMAGE_ID=0]"
Note that the image MUST be in used by any of the DISKs defined in the template. The image_attribute can be TEMPLATE
to include the whole image template in XML (base64 encoded).
$USER[<user_attribute>]
: Any single value variable in the user (owner of the VM) template, like for example:ssh_key = "$USER[SSH_KEY]"
The user_attribute can be TEMPLATE
to include the whole user template in XML (base64 encoded).
$UID
, the uid of the VM owner$UNAME
, the name of the VM owner$GID
, the id of the VM owner's group$GNAME
, the name of the VM owner's group$TEMPLATE
, the whole template in XML format and encoded in base64$FILE[IMAGE=<image name>]
, to select own files$FILE[IMAGE=<image name>, <IMAGE_UNAME|IMAGE_UID>=<owner name|owner id>]
, to select images owned by other users, by user name or uid.$FILE[IMAGE_ID=<image id>]
, global file selectionExample:
CONTEXT = [ HOSTNAME = "MAINHOST", IP_PRIVATE = "$NIC[IP]", DNS = "$NETWORK[DNS, NAME=\"Public\"]", IP_GEN = "10.0.0.$VMID", FILES = "/service/init.sh /service/certificates /service/service.conf", FILES_DS = "$FILE[IMAGE_ID=34] $FILE[IMAGE=\"kernel\"]", TARGET = "sdc" ]
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 | VMWARE |
---|---|---|---|---|
SCHED_REQUIREMENTS | Boolean expression that rules out provisioning hosts from list of machines suitable to run this VM. | O | O | O |
SCHED_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 | O |
SCHED_DS_REQUIREMENTS | Boolean expression that rules out entries from the pool of datastores suitable to run this VM. | O | O | O |
SCHED_DS_RANK | States which attribute will be used to sort the suitable datastores for this VM. Basically, it defines which datastores are more suitable than others. | O | O | O |
Example:
SCHED_REQUIREMENTS = "CPUSPEED > 1000" SCHED_RANK = "FREECPU" SCHED_DS_REQUIREMENTS = "NAME=GoldenCephDS" SCHED_DS_RANK = FREE_MB
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 included in the Host template or its Cluster template can be used in the requirements. You may also use an XPath expression to refer to the attribute.
There is a special variable, CURRENT_VMS
, that can be used to deploy VMs in a Host where other VMs are (not) running. It can be used only with the operators '=' and '!='
Check the Monitoring Subsystem guide to find out how to extend the information model and add any information probe to the Hosts.
There are some predefined variables that can be used: NAME
, TOTALCPU
, TOTALMEMORY
, FREEMEMORY
, FREECPU
,
USEDMEMORY
, USEDCPU
, HYPERVISOR
Examples:
# Only aquila hosts (aquila0, aquila1...), note the quotes SCHED_REQUIREMENTS = "NAME = \"aquila*\"" # Only those resources with more than 60% of free CPU SCHED_REQUIREMENTS = "FREECPU > 60" # Deploy only in the Host where VM 5 is running SCHED_REQUIREMENTS = "CURRENT_VMS = 5" # Deploy in any Host, except the ones where VM 5 or VM 7 are running SCHED_REQUIREMENTS = "(CURRENT_VMS != 5) & (CURRENT_VMS != 7)"
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.
SCHED_REQUIREMENTS = "HYPERVISOR=\"vmware\""
Template variables can be used in the SCHED_REQUIREMENTS section.
$<template_variable>
: any single value variable of the VM template.$<template_variable>[<attribute>]
: Any single value contained in a multiple value variable in the VM template.$<template_variable>[<attribute>, <attribute2>=<value2>]
: Any single value contained in a multiple value variable in the VM template, setting one atribute to discern between multiple variables called the same way.For example, if you have a custom probe that generates a MACS attribute for the hosts, you can do short of a MAC pinning, so only VMs with a given MAC runs in a given host.
SCHED_REQUIREMENTS = "MAC=\"$NIC[MAC]\""
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:
# First those resources with a higher Free CPU SCHED_RANK = "FREECPU" # Consider also the CPU temperature SCHED_RANK = "FREECPU * 100 - 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 | VMWARE |
---|---|---|---|---|
TYPE | Possible values are: kvm , xen , vmware | O | O | O |
DATA | Raw data to be passed directly to the hypervisor | O | O | O |
DATA_VMX | Raw data to be added directly to the .vmx file | - | - | O |
Example:
Add a custom builder and bootloader to a Xen VM:
RAW = [ TYPE = "xen", DATA = "builder=\"linux\" bootloader=\"/usr/lib/xen/boot/domUloader.py\" bootargs=\"--entry=xvda2:/boot/vmlinuz-xenpae,/boot/vmlinuz-xenpae\"" ]
Add a guest type and a specific scsi controller to a vmware VM:
RAW = [ TYPE = "vmware", DATA = "<devices><controller type='scsi' index='0' model='lsilogic'/></devices>", DATA_VMX = "pciBridge0.present = \"TRUE\"\nguestOS=\"windows7srv-64\"" ]
All the default restricted attributes to users in the oneadmin group are summarized in the following list:
These attributes can be configured in oned.conf.