Virtual Machine Definition File 3.2

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.

:!: There are some template attributes that can involve compromise the security of the system or the security of other VMs. In the following table these attributes are labeled with *, and can be used only by users in the oneadmin group. See the complete list in the Restricted Attributes section.

Syntax

The syntax of the template file is as follows:

  • Anything behind the pound or hash sign (#) is a comment.
  • Strings are delimited with double quotes (ā€œ), if the a double quote is part of the string it needs to be escaped (\ā€).
  • Single Attributes are in the form:
NAME=VALUE
  • Vector Attributes that contain several values can be defined as follows:
NAME=[NAME1=VALUE1,NAME2=VALUE2]
  • Vector Attributes must contain at least one value.
  • Attribute names are case insensitive, in fact the names are converted to uppercase internally.

Capacity Section

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. NO - 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 - will be set to 1 if omitted, this can be changed in the driver configuration
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

OS and Boot Options Section

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 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"]

Disks Section

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 ways to attach a disk to a VM: using an OpenNebula image from the image repository, or declaring a disk type that can be created from a source disk file in your system. Both kinds of disks can be combined, with some considerations to be taken into account.

Using an Image

The image repository was introduced in OpenNebula v2.0. To use the registered images in your VMs, you need to specify the IMAGE_ID sub-attribute.

Once the VM machine is shut down, the changes made to the images can be saved back to the repository. To do so, use the onevm saveas command.

DISK Sub-Attribute M / O Description
IMAGE_ID M (if no IMAGE) ID of the Image to use
IMAGE M (if no IMAGE_ID) Name of the Image to use (of those owned by user)
IMAGE_UID O (for IMAGE) To select the IMAGE of a given user by her ID
IMAGE_UNAME O (for IMAGE) To select the IMAGE of a given user by her NAME
BUS O Type of disk device to emulate: ide, scsi
TARGET O Device to map image disk. If set, it will overwrite the default device mapping.
DRIVER O Specific image mapping driver. KVM: raw, qcow2. Xen:tap:aio:, file:. VMware unsupported

Declaring the Disk Type

You can define a DISK from a disk file without having to register it first in the image repository. 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 Types that accept this attribute XEN KVM VMWARE
TYPE disk type:floppy, disk, cdrom, swap, fs, block - O (only swap, fs and block) (if not present, disk will be assumed) O M (block, cdrom, file) (defaults to file)
SOURCE* disk file location path or URL floppy disk cdrom block M M M
SIZE size in MB for swap, fs and block images swap fs block M (for swap and fs) M (for swap and fs) M (for swap and fs)
FORMAT filesystem type for the fs images fs M (for fs) M (for fs) M (for fs)
TARGET device to map disk ALL M (O for swap) M (O for swap) M (O for swap)
CLONE clone this image yes (default), or no ALL O O O
SAVE save this image after shutting down the VM yes, or no (default) ALL O O O
READONLY yes, or no (default) ALL O O O
BUS type of disk device to emulate: ide, scsi ALL - O O
DRIVER special disk mapping options. KVM: raw,qcow2. Xen: tap:aio:, file: ALL O O O

* only for users in oneadmin group

:!: When using the Image Catalog (not specifying the SOURCE attribute), these attributes (this note especially applies to SAVE and CLONE attributes) will be overridden and automatically modified by the Image Catalog module.

Disks Device Mapping

When you use images in your VM template, you don't have to define the target device to mount them. OpenNebula will mount the disks as follows:

  • sda: OS type Image.
  • sdb: Contextualization CDROM.
  • sdc: CDROM type Image.
  • sdd: Swap disk.
  • sd[e,f,gā€¦]: DATABLOCK type Images.

This automatic mapping doesn't take into account any disk defined by type (those that do not use an image from the repository), apart from the swap ones.

Only one OS type image per VM template can be declared, the same applies for CDROM type images. You can use as many DATABLOCK images as you need. 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 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.

An Example

This a sample section for disks. There are three disks using the image repository, and two beeing defined by type. The fs disk target has been set to sdg to avoid conflicts with the other disks that are mapped automatically. Note that fs and swap are generated on-the-fly:

# OS image, mapped to sda. Use image with ID 2
DISK = [ IMAGE_ID  = 2 ]
 
# First DATABLOCK image, mapped to sde.
# Use the Image named Data, owned by the user named oneadmin.
DISK = [ IMAGE        = "Data",
         IMAGE_UNAME  = "oneadmin" ]
 
# Second DATABLOCK image, mapped to sdf
# use the Image named Results owned by user with ID 7.
DISK = [ IMAGE        = "Results",
         IMAGE_UID    = 7 ]
 
# Third DATABLOCK image, mapped to sdg
# use the Image named Experiments owned by user instantiating the VM.
DISK = [ IMAGE        = "Experiments" ]
 
# swap, sdd
DISK = [ TYPE     = swap,
         SIZE     = 1024,
         READONLY = "no" ]
 
DISK = [ TYPE   = fs,
         SIZE   = 4096,
         FORMAT = ext3,
         SAVE   = yes,
         TARGET = sdg ]

For more information on image management and moving please check the Storage guide.

Network Section

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 O O O
NETWORK Name of the network to use (of those owned by user). Use if no NETWORK_ID O O O
NETWORK_UID To select the NETWORK of a given user by her ID O O O
NETWORK_UNAME To select the NETWORK of a given user by her NAME O O O
IP Request an specific IP from the NETWORK O O O
MAC* HW address associated with the network interface O O O
BRIDGE Name of the bridge the network device is going to be attached to. O O O
TARGET name for the tun device created for the VM - O O
SCRIPT name of a shell script to be executed after creating the tun device for the VM - O O
MODEL hardware that will emulate this network interface. With Xen this is the type attribute of the vif. O O O
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. O O O
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. O O O
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. O O O
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. O O O
ICMP drop: Blocks ICMP connections to the VM. By default it's set to accept. O O O

* 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.

:!: The PORTS and ICMP attributes require the firewalling functionality to be configured. Please read the firewall configuration guide.

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.

I/O Devices Section

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
- 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"]

:!: 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.

:!: If the user does not specify the port variable, OpenNebula will automatically assign $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 Section

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.

* only for users in oneadmin group

The values referred to by VARIABLE can be defined :

  • Hardcoded values:
    HOSTNAME   = "MAINHOST"
  • Using template variables
    • $<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\"]"
  • Using Virtual Network template variables
    • $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).

  • Using Image template variables
    • $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).

  • Using User template variables
    • $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).

  • Pre-defined variables, apart from those defined in the template you can use:
    • $UID, the uid of the VM owner
    • $TEMPLATE, the whole template in XML format and encoded in base64

Example:

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",
  TARGET     = "sdc"
]

Placement Section

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
REQUIREMENTS Boolean expression that rules out provisioning hosts from list of machines suitable to run this VM. O 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 O

Example:

REQUIREMENTS = "CPUSPEED > 1000"
RANK         = FREECPU

Requirement Expression Syntax

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 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: NAME, TOTALCPU, TOTALMEMORY, FREEMEMORY, FREECPU, USEDMEMORY, USEDCPU, HYPERVISOR

Examples:

  REQUIREMENTS = "NAME = \"aquila*\"" #Only aquila nodes, note the quotes
  REQUIREMENTS = FREECPU > 0.6          #Only those resources with more than 60% of free CPU

:!: 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.

REQUIREMENTS = "HYPERVISOR=\"vmware\""

:!: Template variables can be used in the 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.

REQUIREMENTS = "MAC=\"$NIC[MAC]\""

Rank Expression Syntax

The syntax of the rank expressions is defined as:

  stmt::= expr';'
  expr::= VARIABLE
        | NUMBER
        | expr '+' expr
        | expr '-' expr
        | expr '*' expr
        | expr '/' expr
        | '-' expr
        | '(' expr ')'

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:

  RANK = FREECPU                     # First those resources with a higher Free CPU
  RANK = FREECPU * 100 - TEMPERATURE # Consider also the CPU temperature

RAW Section

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 O O O
DATA Raw data to be passed directly to the hypervisor O O O

Example

RAW     = [
      TYPE  = "xen",
      DATA  = "builder=\"linux\"
               bootloader=\"/usr/lib/xen/boot/domUloader.py\"
               bootargs=\"--entry=xvda2:/boot/vmlinuz-xenpae,/boot/vmlinuz-xenpae\""]

Restricted Attributes

All the restricted attributes to users in the oneadmin group are summarized in the following list:

  • CONTEXT/FILES
  • DISK/SOURCE
  • NIC/MAC
  • NIC/VLAN_ID
  • RANK