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.

Since OpenNebula 3.4, template files can be in XML, with the following syntax:

• The root element must be TEMPLATE
• Single Attributes are in the form:

<NAME>VALUE</NAME>

• Vector Attributes that contain several values can be defined as follows:

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

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

(*) 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. There are three types of disks:

• Persistent disks, uses an Image registered in a Datastore mark as persistent.
• Clone disks, uses an Image registered in a Datastore. Changes to the images will be discarded. A clone disk can be saved as other image.
• Volatile disks, created on-the-fly on the target hosts. Disks are disposed when the VM is shutdown and cannot be saved_as

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:

If the TARGET attribute is not set for a disk, OpenNebula will automatically assign it using the following precedence, starting with dev_prefix + a:

• First OS type Image.
• Contextualization CDROM.
• CDROM type Images.
• The rest of DATABLOCK and OS Images, and Volatile disks.

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

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

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

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

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

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

Example:

REQUIREMENTS = "CPUSPEED > 1000"
RANK         = FREECPU

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

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:

  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.

Example

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

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

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

These attributes can be configured in oned.conf.