Virtual Machine Template

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 instantiated later. For compatibility with previous versions, you can also create a new Virtual Machine directly from a template file by using the onevm create command.

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

XML Syntax

Template files can be expressed 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>

Capacity Section

The following attributes can be defined to specify the capacity of a VM.

For example:

NAME   = test-vm
MEMORY = 128
CPU    = 1

Hotplug Resize VM Capacity

If you need to resize the capacity in RUNNING state you have to set up some extra attributes in the VM template. These attributes must be set before the VM is started. They are driver-specific, here you can find more info for KVM.

Showback Section

The following attributes can be defined to set the cost of a VM. Read the showback documentation for more information.

OS and Boot Options Section

The operating system is defined with the OS vector attribute. The following sub-attributes are supported:

(!!) Use one of KERNEL_DS or KERNEL (and INITRD or INITRD_DS).

KERNEL_DS and INITRD_DS refer to an image registered in a File Datastore and must be of type KERNEL and RAMDISK, respectively. The image should be referred to using one of the following:

• $FILE[IMAGE=<image name>], to select the user’s 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.

Here’s an example of a VM booting from sda1 with kernel /vmlinuz:

OS = [ KERNEL     = /vmlinuz,
       INITRD     = /initrd.img,
       ROOT       = sda1,
       KERNEL_CMD = "ro console=tty1"]

OS = [ KERNEL_DS  = "$FILE[IMAGE=\"kernel 3.6\"]",
       INITRD_DS  = "$FILE[IMAGE=\"initrd 3.6\"]",
       ROOT       = sda1,
       KERNEL_CMD = "ro console=tty1"]

CPU_MODEL Options Section

This section (CPU_MODEL) configures the hardware configuration of the CPU exposed to the guest.

Features Section

This section configures the features enabled for the VM.

When setting up the virtio-scsi or virtio-blk queues, you can use the keyword auto which defaults to the number of vCPUs defined in the Virtual Machine. Also, the virtio-blk queues can be overridden per DISK so you can enable the multi-queue feature for the selected disks only.

FEATURES = [
    PAE = "yes",
    ACPI = "yes",
    APIC = "no",
    GUEST_AGENT = "yes",
    VIRTIO_SCSI_QUEUES = "auto"
    VIRTIO_BLK_QUEUES = "auto"
]

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 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 shut down and cannot be saved_as.

Persistent and Clone Disks

Volatile DISKS

Disks Device Mapping

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.

Network Section

Here’s an example of a VM with two NICs attached to two different networks:

NIC = [ NETWORK_ID = 1 ]

NIC = [ NETWORK     = "Blue",
        NETWORK_UID = 0 ]

NIC = [ NETWORK_MODE = "auto",
        SCHED_REQUIREMENTS = "TRAFFIC_TYPE=\"public\"" ]

And here’s an example of a VM with two NICs attached, one is an alias of the other one:

NIC = [ NETWORK = "Test", NAME = "TestName" ]
NIC_ALIAS = [ NETWORK = "Test", PARENT = "TestName" ]

For more information on setting up virtual networks please check the Managing Virtual Networks guide.

Network Defaults

You can define a NIC_DEFAULT attribute with values that will be copied to each new NIC. This is especially useful for an administrator to define configuration parameters, such as MODEL, that final users may not be aware of.

NIC_DEFAULT = [ MODEL = "virtio" ]

I/O Devices Section

The following I/O interfaces can be defined for a VM:

For example:

GRAPHICS = [
  TYPE    = "vnc",
  LISTEN  = "0.0.0.0",
  PORT    = "5905"]

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:

The values referred to by VARIABLE can be defined as:

Hardcoded values:

SET_HOSTNAME   = "MAINHOST"

Using template variables

$<template_variable>: any single value variable of the VM template, for example:

IP_GEN       = "10.0.0.$VMID"
SET_HOSTNAME = "$NAME"

$<template_variable>[<attribute>]: Any single value contained in a multiple value variable in the VM template, 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, for example:

IP_PUBLIC = "$NIC[IP, NETWORK=\"Public\"]"

Using Virtual Network template variables

$NETWORK[<vnet_attribute>, <NETWORK_ID|NETWORK|NIC_ID>=<vnet_id|vnet_name|nic_id>]: Any single value variable in the Virtual Network template, for example:

DNS = "$NETWORK[DNS, NETWORK_ID=3]"

Using Image template variables

$IMAGE[<image_attribute>, <IMAGE_ID|IMAGE>=<img_id|img_name>]: Any single value variable in the Image template, for example:

root = "$IMAGE[ROOT_PASS, IMAGE_ID=0]"

Using User template variables

$USER[<user_attribute>]: Any single value variable in the user (owner of the VM) template, for example:

ssh_key = "$USER[SSH_KEY]"

Pre-defined variables, apart from those defined in the template you can use:

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

FILES_DS, each file must be registered in a FILE_DS datastore and has to be of type CONTEXT. Use the following to select files from Files Datastores:

• $FILE[IMAGE=<image name>], to select the user’s 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.

For example:

CONTEXT = [
  SET_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"
]

Placement Section

The following attributes sets placement constraints and preferences for the VM, valid for all hypervisors:

For example:

SCHED_REQUIREMENTS    = "CPUSPEED > 1000"
SCHED_RANK            = "FREE_CPU"
SCHED_DS_REQUIREMENTS = "NAME=GoldenCephDS"
SCHED_DS_RANK         = FREE_MB

Requirement Expression Syntax

The syntax of the requirement expressions is defined as:

stmt::= expr';'
expr::= VARIABLE '=' NUMBER
      | VARIABLE '!=' NUMBER
      | VARIABLE '>' NUMBER
      | VARIABLE '<' NUMBER
      | VARIABLE '@>' NUMBER
      | VARIABLE '=' STRING
      | 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. Additionally, the ‘@>’ operator means contains, if the variable evaluates to an array the expression will be true if that array contains the given number or string (or any string that matches the provided pattern).

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 ‘!=’.

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 = "FREE_CPU > 60"

# Deploy only in the Host where VM 5 is running. Two different forms:
SCHED_REQUIREMENTS = "CURRENT_VMS = 5"
SCHED_REQUIREMENTS = "\"HOST/VMS/ID\" @> 5"

# Deploy in any Host, except the ones where VM 5 or VM 7 are running
SCHED_REQUIREMENTS = "(CURRENT_VMS != 5) & (CURRENT_VMS != 7)"

# Use any datastore that is in cluster 101 (it list of cluster IDs contains 101)
SCHED_DS_REQUIREMENTS = "\"CLUSTERS/ID\" @> 101"

SCHED_REQUIREMENTS = "HYPERVISOR=\"LXC\""

• $<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 attribute 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]\""

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’s information. ‘+’, ‘-’, ‘*’, ‘/’ and ‘-’ are arithmetic operators. The rank expression is calculated using floating point arithmetic and then rounded to an integer value.

Here are some examples:

# First those resources with a higher Free CPU
  SCHED_RANK = "FREE_CPU"

# Consider also the CPU temperature
  SCHED_RANK = "FREE_CPU * 100 - TEMPERATURE"

Predefined Host Attributes

There are some predefined Host attributes that can be used in the requirements and rank expressions, valid for all hypervisors:

You can execute onehost show <id> -x to see all the attributes and their values.

Hypervisor Section

You can also tune several low-level hypervisor attributes.

The RAW attribute (optional) section of the VM template is used pass VM information directly to the underlying hypervisor. Anything placed in the data attribute gets passed straight to the hypervisor unmodified.

For example:

RAW = [
    type = "kvm",
    validate = "yes",
    data = "<devices><serial type=\"pty\"><source path=\"/dev/pts/5\"/><target port=\"0\"/></serial><console type=\"pty\" tty=\"/dev/pts/5\"><source path=\"/dev/pts/5\"/><target port=\"0\"/></console></devices>"
]

RAW = [
    type = "lxc",
    data = "boot.autostart": "true", "limits.processes": "10000"
]

Additionally the following can be also set for KVM:

For example:

EMULATOR="/usr/bin/qemu-system-aarch64"

Restricted Attributes

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

• CONTEXT/FILES
• NIC/VLAN_ID
• NIC/BRIDGE
• NIC/FILTER
• NIC/FILTER_IP_SPOOFING
• NIC/FILTER_MAC_SPOOFING
• NIC/INBOUND_AVG_BW
• NIC/INBOUND_PEAK_BW
• NIC/INBOUND_PEAK_KB
• NIC/OUTBOUND_AVG_BW
• NIC/OUTBOUND_PEAK_BW
• NIC/OUTBOUND_PEAK_KB
• NIC/OPENNEBULA_MANAGED
• NIC/EXTERNAL
• NIC_ALIAS/MAC
• NIC_ALIAS/VLAN_ID
• NIC_ALIAS/BRIDGE
• NIC_ALIAS/INBOUND_AVG_BW
• NIC_ALIAS/INBOUND_PEAK_BW
• NIC_ALIAS/INBOUND_PEAK_KB
• NIC_ALIAS/OUTBOUND_AVG_BW
• NIC_ALIAS/OUTBOUND_PEAK_BW
• NIC_ALIAS/OUTBOUND_PEAK_KB
• NIC_ALIAS/OPENNEBULA_MANAGED
• NIC_DEFAULT/MAC
• NIC_DEFAULT/VLAN_ID
• NIC_DEFAULT/BRIDGE
• NIC_DEFAULT/FILTER
• NIC_DEFAULT/EXTERNAL
• DISK/TOTAL_BYTES_SEC
• DISK/TOTAL_BYTES_SEC_MAX_LENGTH
• DISK/TOTAL_BYTES_SEC_MAX
• DISK/READ_BYTES_SEC
• DISK/READ_BYTES_SEC_MAX_LENGTH
• DISK/READ_BYTES_SEC_MAX
• DISK/WRITE_BYTES_SEC
• DISK/WRITE_BYTES_SEC_MAX_LENGTH
• DISK/WRITE_BYTES_SEC_MAX
• DISK/TOTAL_IOPS_SEC
• DISK/TOTAL_IOPS_SEC_MAX_LENGTH
• DISK/TOTAL_IOPS_SEC_MAX
• DISK/READ_IOPS_SEC
• DISK/READ_IOPS_SEC_MAX_LENGTH
• DISK/READ_IOPS_SEC_MAX
• DISK/WRITE_IOPS_SEC
• DISK/WRITE_IOPS_SEC_MAX_LENGTH
• DISK/WRITE_IOPS_SEC_MAX
• DISK/SIZE_IOPS_SEC
• DISK/OPENNEBULA_MANAGED
• DISK/SIZE
• DISK/ORIGINAL_SIZE
• DISK/SIZE_PREV
• DEPLOY_ID
• CPU_COST
• MEMORY_COST
• DISK_COST
• PCI
• EMULATOR
• RAW
• USER_PRIORITY
• USER_INPUTS/CPU
• USER_INPUTS/MEMORY
• USER_INPUTS/VCPU
• TOPOLOGY/PIN_POLICY
• TOPOLOGY/HUGEPAGE_SIZE

These attributes can be configured in oned.conf.

User Inputs

USER_INPUTS provides the template creator with the possibility to dynamically ask the user instantiating the template for dynamic values that must be defined.

USER_INPUTS = [
  BLOG_TITLE="M|text|Blog Title",
  MYSQL_PASSWORD="M|password|MySQL Password",
  INIT_HOOK="M|text64|You can write a script that will be run on startup",
  <VAR>="M|<type>|<desc>"
]

CONTEXT=[
  BLOG_TITLE="$BLOG_TITLE",
  MYSQL_PASSWORD="$MYSQL_PASSWORD" ]

Note that the CONTEXT references the variables defined in the USER_INPUTS so the value is injected into the VM.

Valid types:

There is the possibility of making the USER_INPUT mandatory or not mandatory. If it is mandatory, we will see a letter ‘M’ but if it is not mandatory a letter ‘O’ will appear. For example:

• <VAR>=”M|... This is mandatory
• <VAR>=”O|... This is not mandatory

In Sunstone, the USER_INPUTS can be ordered with the mouse.

USER_INPUTS_METADATA provides the template creator with the possibility to add titles and descriptions to the user inputs. To understand how Sunstone renders user inputs metadata, see User Inputs in Sunstone.

Here’s an example:

USER_INPUTS_METADATA=[
  DESCRIPTION="This tab includes all the information about the blog section in this template.",
  NAME="BLOG",
  TITLE="Blog",
  TYPE="APP" ]
USER_INPUTS_METADATA=[
  NAME="MYSQL",
  TITLE="MySQL",
  TYPE="APP" ]
USER_INPUTS_METADATA=[
  DESCRIPTION="MySQL configuration parameters",
  NAME="CONFIG",
  TITLE="Configuration",
  TYPE="GROUP" ]
USER_INPUTS_METADATA=[
  DESCRIPTION="Additional MySQL parameters",
  NAME="ADDITIONAL",
  TITLE="Additional parameters",
  TYPE="GROUP" ]

Schedule Actions Section

The following attributes can used to define punctual or relative actions for the VM.

For example:

SCHED_ACTION=[
    ACTION="suspend",
    DAYS="1,5",
    END_TYPE="1",
    END_VALUE="5",
    ID="0",
    REPEAT="0",
    TIME="1537653600",
    WARNING="1537567200" ]

NUMA topology Section

The following attributes can use to define a NUMA topology for the VM.

For example:

TOPOLOGY = [
  HUGEPAGE_SIZE = "2",
  MEMORY_ACCESS = "shared",
  NUMA_NODES    = "2",
  PIN_POLICY    = "THREAD" ]

Asymmetric NUMA configurations, i.e., not distributing the VM resources evenly across the nodes, can be defined manually by setting the NUMA_NODE attribute:

For example:

TOPOLOGY = [ PIN_POLICY = CORE, SOCKETS = 2 ]

NUMA_NODE = [ MEMORY = 1024, TOTAL_CPUS = 2 ]
NUMA_NODE = [ MEMORY = 2048, TOTAL_CPUS = 4 ]

Please check the NUMA guide for more information.

Sunstone Section

The following attributes are used to display elements in Sunstone:

For example:

SUNSTONE = [
  NETWORK_ALIAS = "yes",
  NETWORK_AUTO = "no",
  NETWORK_RDP = "yes",
  NETWORK_SSH = "yes"
]

Next page >