Virtual Machine Definition 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 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.

Warning

There are some template attributes that can compromise the security of the system or the security of other VMs, and can be used only by users in the oneadmin group. These attributes can be configured in oned.conf, the default ones are labeled with * in the following tables. See the complete list in the Restricted Attributes section.

Note

If not explicitly stated, the described attributes are valid for all supported hypervisors.

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.

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

Showback Section

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

Attribute Description Mandatory
MEMORY_COST Cost of each memory MB per hour. NO
CPU_COST Cost of each CPU per hour. NO
DISK_COST Cost of each disk MB per hour. NO

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 KVM vCenter LXD
ARCH CPU architecture to virtualize M (default i686) - -
MACHINE libvirt machine type. Check libvirt capabilities for the list of available machine types. O - -
KERNEL path to the OS kernel to boot the image in the host O - -
KERNEL_DS image to be used as kernel (see !!) O - -
INITRD path to the initrd image in the host O (for kernel) - -
INITRD_DS image to be used as ramdisk (see !!) O (for kernel) - -
ROOT device to be mounted as root O (for kernel) - -
KERNEL_CMD arguments for the booting kernel O (for kernel) - -
BOOTLOADER path to the bootloader executable 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: disk#,nic# M O O

(!!) 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 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.

Note the hypervisor column states that the attribute is Optional or - not supported for that hypervisor

Sub-Attribute Description KVM vCenter LXD
MODEL The CPU model exposed to the guest. host-passthrough is the same model as the host. Available modes are stored in the host information and obtained through monitor. O - -

Features Section

This section configures the features enabled for the VM.

Note the hypervisor column states that the attribute is Optional or - not supported for that hypervisor

Sub-Attribute Description KVM vCenter LXD
PAE Physical address extension mode allows 32-bit guests to address more than 4 GB of memory O - -
ACPI Useful for power management, for example, with KVM guests it is required for graceful shutdown to work O - -
APIC Enables the advanced programmable IRQ management. Useful for SMP machines. O - -
LOCALTIME The guest clock will be synchronized to the host’s configured timezone when booted. Useful for Windows VMs O - -
HYPERV Add hyperv extensions to the VM. The options can be configured in the driver configuration, HYPERV_OPTIONS O - -
GUEST_AGENT Enables the QEMU Guest Agent communication. This only creates the socket inside the VM, the Guest Agent itself must be installed and started in the VM. O - -
VIRTIO_SCSI_QUEUES Numer of vCPU queues for the virtio-scsi controller. O - -
FEATURES = [
    PAE = "yes",
    ACPI = "yes",
    APIC = "no",
    GUEST_AGENT = "yes",
    VIRTIO_SCSI_QUEUES = "4"
]

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 shutdown and cannot be saved_as

Persistent and Clone Disks

Note the hypervisor column states that the attribute is Optional, Mandatory, or - not supported for that hypervisor

DISK Sub-Attribute Description KVM vCenter LXD
IMAGE_ID ID of the Image to use M (no IMAGE) M (no IMAGE) M (no IMAGE)
IMAGE Name of the Image to use M(no IMAGE_ID) M (no IMAGE_ID) M (no IMAGE_ID)
IMAGE_UID To select the IMAGE of a given user by her ID O O O
IMAGE_UNAME To select the IMAGE of a given user by her NAME O O O
DEV_PREFIX Prefix for the emulated device this image will be mounted at. For instance, attribute of the Image will be used O O -
TARGET Device to map image disk. If set, it will overwrite the default device hd, sd, or vd for KVM virtio. If omitted, the dev_prefix mapping. O - O (where to mount the image inside the container e.g.: /mnt. Only applies fot non root devices
DRIVER Specific image mapping driver O 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 O - -
READONLY Set how the image is exposed by the hypervisor O e.g.: yes, no. This attribute should only be used for special storage configurations - O
IO Set IO policy. Values are threads, native O (Needs qemu 1.1) - -
TOTAL_BYTES_SEC, READ_BYTES_SEC, WRITE_BYTES_SEC TOTAL_IOPS_SEC, READ_IOPS_SEC, WRITE_IOPS_SEC IO throttling attributes for the disk. They are specified in bytes or IOPS (IO Operations) and can be specified for the total (read+write) or specific for read or write. Total and read or write can not be used at the same time. By default these parameters are only allowed to be used by oneadmin. O (Needs qemu 1.1) - O
TOTAL_BYTES_SEC_MAX, READ_BYTES_SEC_MAX, WRITE_BYTES_SEC_MAX TOTAL_IOPS_SEC_MAX, READ_IOPS_SEC_MAX, WRITE_IOPS_SEC_MAX Maximum IO throttling attributes for the disk. They are specified in bytes or IOPS (IO Operations) and can be specified for the total (read+write) or specific for read or write. Total and read or write can not be used at the same time. By default these parameters are only allowed to be used by oneadmin. O (Needs qemu 1.1) - O
TOTAL_BYTES_SEC_MAX_LENGTH, READ_BYTES_SEC_MAX_LENGTH, WRITE_BYTES_SEC_MAX_LENGTH TOTAL_IOPS_SEC_MAX_LENGTH, READ_IOPS_SEC_MAX_LENGTH, WRITE_IOPS_SEC_MAX_LENGTH Maximum length IO throttling attributes for the disk. They are specified in bytes or IOPS (IO Operations) and can be specified for the total (read+write) or specific for read or write. Total and read or write can not be used at the same time. By default these parameters are only allowed to be used by oneadmin. O (Needs qemu 1.1) - O
VCENTER_ADAPTER_TYPE Possible values (careful with the case): lsiLogic, ide, busLogic. More information in the VMware documentation - O (can be inherited from Datastore) -
DISK_TYPE This is the type of the supporting media for the image. Values: a block device (BLOCK) an ISO-9660 file or readonly block device (CDROM) or a plain file (FILE) O M (can be inherited from Datastore) FILE is the only accepted value O
VCENTER_DISK_TYPE Possible values (careful with the case): lsiLogic, ide, busLogic. More information in the VMware documentation - O (can be inherited from Datastore) -
DISCARD Controls what’s done with with trim commands to the disk, the values can be ignore or discard. O (only with virtio-scsi) - -
VCENTER_DS_REF vCenter datastore’s managed object reference - M (can be inherited from Datastore) -
VCENTER_INSTANCE_ID vCenter intance uuid - M (can be inherited from Datastore) -
OPENNEBULA_MANAGED If set to yes, in vCenter this DISK represents a virtual disk that was imported when a template or wild VM was imported. - O (can be inherited from Datastore) -

Volatile DISKS

Warning

Not supported on LXD

DISK Sub-Attribute Description KVM vCenter
TYPE Type of the disk: swap or fs. Type swawp is not supported in vcenter. O O
SIZE size in MB O O
FORMAT Format of the Image: raw or qcow2. M(for fs) M(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 O O
TARGET device to map disk O O
DRIVER special disk mapping options. KVM: raw, qcow2. O -
CACHE Selects the cache mechanism for the disk. Values are default, none, writethrough, writeback, directsync and unsafe. More info in the libvirt documentation O -
READONLY Set how the image is exposed by the hypervisor O e.g.: yes, no. This attribute should only be used for special storage configurations -
IO Set IO policy. Values are threads, native O -
TOTAL_BYTES_SEC, READ_BYTES_SEC, WRITE_BYTES_SEC, TOTAL_IOPS_SEC, READ_IOPS_SEC, WRITE_BYTES_SEC IO throttling attributes for the disk. They are specified in bytes or IOPS (IO Operations) and can be specified for the total (read+write) or specific for read or write. Total and read or write can not be used at the same time. By default these parameters are only allowed to be used by oneadmin. O -
VCENTER_ADAPTER_TYPE Controller that will handle this image in vCenter. Possible values: lsiLogic, ide, busLogic. - O
VCENTER_DISK_TYPE The vCenter Disk Type of the image. Possible values: THIN, THICK, ZEROEDTHICK - O

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.

An Example

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

NIC Sub-Attribute Description KVM vCenter LXD
NETWORK_ID ID of the network to attach this device, as defined by onevnet. Use if no NETWORK M (No NETWORK) M (No NETWORK) M (No NETWORK)
NETWORK Name of the network to use (of those owned by user). Use if no NETWORK_ID M (No NETWORK_ID) M (No NETWORK_ID) M (No NETWORK_ID)
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* Request an specific HW address from 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 O
SCRIPT name of a shell script to be executed after creating the tun device for the VM O O O
MODEL hardware that will emulate this network interface. In KVM you can choose virtio to select its specific virtualization IO framework O O -
FILTER to define a network filtering rule for the interface O O O
SECURITY_GROUPS command separated list of the ids of the security groups to be applied to this interface. O - -
INBOUND_AVG_BW Average bitrate for the interface in kilobytes/second for inbound traffic. O O O
INBOUND_PEAK_BW Maximum bitrate for the interface in kilobytes/second for inbound traffic. O O O
INBOUND_PEAK_KB Data that can be transmitted at peak speed in kilobytes. O - -
OUTBOUND_AVG_BW Average bitrate for the interface in kilobytes/second for outbound traffic. O O O
OUTBOUND_PEAK_BW Maximum bitrate for the interface in kilobytes/second for outbound traffic. O O O
OUTBOUND_PEAK_KB Data that can be transmitted at peak speed in kilobytes. O - -
NETWORK_MODE To let the Scheduler pick the VNET if set to auto), any other value will be ignored By default, the network mode is not set. O O O
SCHED_REQUIREMENTS Define the requirement when NETMORW_MODE is auto. O O O
SCHED_RANK Define the rank when NETMORW_MODE is auto. O O O
NAME Name of the nic. O - -
PARENT It is used only on alias, it references the nic which is alias of. O - -
EXTERNAL It is used only on alias, it indicates if the alias is external to the VM or not. If it is set to “yes” it will call pre, post, clean and reconfigure actions. If it set to “no” or it is empty, it will just call reconfigure action. O - -

Warning

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 ]

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

Example, a VM with two NIC 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 specially 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:

Note the hypervisor column states that the attribute is Optional, Mandatory, or - not supported for that hypervisor

Attribute Description KVM vCenter LXD
INPUT

Define input devices, available sub-attributes:

  • TYPE: values are mouse or tablet
  • BUS: values are usb, ps2
O - -
GRAPHICS Wether the VM should export its graphical display and how, available sub-attributes: O O O
  • TYPE: values: vnc, sdl, spice
    O (vnc)
  • LISTEN: IP to listen on.
    O
  • PORT: port for the VNC server
    O
  • PASSWD: password for the VNC server
    O
  • KEYMAP: keyboard configuration locale to use in the VNC display
    -
  • RANDOM_PASSWD: if “YES”, generate a random password for each VM
    O

Example:

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

Warning

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.

Warning

OpenNebula will prevent VNC port collision within a cluster to ensure that a VM can be deployed or migrated to any host in the selected cluster. If the selected port is in use the VM deployment will fail. If the user does not specify the port variable, OpenNebula will try to assign VNC_PORTS[START] + VMID, or the first lower available port. The VNC_PORTS[START] 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:

Note the hypervisor column states that the attribute is Optional, - not supported for that hypervisor or only valid for Linux guests.

Attribute Description KVM/LXD vCenter EC2
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). O O O
FILES * space-separated list of paths to include in context device. O - -
FILES_DS space-separated list of File images to include in context device. (Not supported for vCenter) O - -
INIT_SCRIPTS If the VM uses the OpenNebula contextualization package the init.sh file is executed by default. When the init script added is not called init.sh or more than one init script is added, this list contains the scripts to run and the order. Ex. “init.sh users.sh mysql.sh” O - -
START_SCRIPT Text of the script executed when the machine starts up. It can contain shebang in case it is not shell script. For example START_SCRIPT="yum upgrade" O O O
START_SCRIPT_BASE64 The same as START_SCRIPT but encoded in Base64 O O O
TARGET device to attach the context ISO. O - -
TOKEN YES to create a token.txt file for OneGate monitorization O O O
NETWORK YES to fill automatically the networking parameters for each NIC, used by the Contextualization packages O O -
SET_HOSTNAME This parameter value will be the hostname of the VM. O O -
DNS_HOSTNAME YES to set the VM hostname to the reverse dns name (from the first IP) Linux Linux -
GATEWAY_IFACE This variable can be set to the interface number you want to configure the gateway. It is useful when several networks have GATEWAY parameter and you want yo choose the one that configures it. For example to set the first interface to configure the gateway you use GATEWAY_IFACE=0 Linux Linux -
DNS Specific DNS server for the Virtual Machine Linux Linux -
ETHx_MAC Used to find the correct interface O O -
ETHx_IP IPv4 address for the interface O O -
ETHx_IPV6 IPv6 address for the interface Linux Linux -
ETHx_NETWORK Network address of the interface O O -
ETHx_MASK Network mask O O -
ETHx_GATEWAY Default IPv4 gateway for the interface O O -
ETHx_GATEWAY6 Default IPv6 gateway for the interface Linux Linux -
ETHx_MTU MTU value for the interface O O -
ETHx_DNS DNS for the network O O -
ETHx_ALIASy_MAC Used to find the correct interface O O -
ETHx_ALIASy_IP IPv4 address for the alias O O -
ETHx_ALIASy_IP6 IPv6 address for the alias. Legacy ETHx_ALIASy_IPV6 is also valid O O -
ETHx_ALIASy_IP6_PREFIX_LENGTH IPv6 prefix length for the alias O O -
ETHx_ALIASy_IP6_ULA IPv6 unique local address for the alias O O -
ETHx_ALIASy_NETWORK Network address of the alias O O -
ETHx_ALIASy_MASK Network mask O O -
ETHx_ALIASy_GATEWAY Default IPv4 gateway for the alias - - -
ETHx_ALIASy_GATEWAY6 Default IPv6 gateway for the alias - - -
ETHx_ALIASy_MTU MTU value for the alias - - -
ETHx_ALIASy_DNS DNS for the alias - - -
ETHx_ALIASy_EXTERNAL Indicates if the alias is external to the VM or not O O -
USERNAME User to be created in the guest OS. If any password attribute is defined (see below) it will change this user (defaults to root). O O -
CRYPTED_PASSWORD_BASE64 Crypted password encoded in base64. To be set for the user USERNAME. Linux Linux -
PASSWORD_BASE64 Password encoded in base64. To be set for the user USERNAME. O O -
CRYPTED_PASSWORD Crypted password. To be set for the user USERNAME. This parameter is not recommended, use CRYPTED_PASSWORD_BASE64 instead. Linux Linux -
PASSWORD Password to be set for the user USERNAME. This parameter is not recommended, use PASSWORD_BASE64 instead. O O -
SSH_PUBLIC_KEY Key to be added to USERNAME authorized_keys file or root in case USERNAME is not set. Linux Linux O
EC2_PUBLIC_KEY Same as SSH_PUBLIC_KEY Linux Linux O
SECURETTY If set to NO it will disable securetty validation on PAM. If set to YES it will restore system defaults. Defaults: LXD -> YES, KVM -> NO. Linux Linux Linux Linux O O

Note

Limitations apply in vCenter alias for attach/detach nic operations.

Note

If more than one of the password changing attributes listed above is defined, only the one with highest priority will be applied. The priority is the same as the order of appearance in this table.

The values referred to by VARIABLE can be defined :

Hardcoded values:

SET_HOSTNAME   = "MAINHOST"

Using template variables

$<template_variable>: any single value variable of the VM template, like 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, 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|NIC_ID>=<vnet_id|vnet_name|nic_id>]: Any single value variable in the Virtual Network template, like for example:

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

Note

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

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

Note

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

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

Placement Section

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

Attribute Description
SCHED_REQUIREMENTS Boolean expression that rules out provisioning hosts from list of machines suitable to run this VM.
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.
SCHED_DS_REQUIREMENTS Boolean expression that rules out entries from the pool of datastores suitable to run this VM.
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.
USER_PRIORITY Alter the standard FIFO ordering to dispatch VMs. VMs with a higher USER_PRIORITY will be dispatched first.

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"

Warning

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

SCHED_REQUIREMENTS = "HYPERVISOR=\"vcenter\""

Warning

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

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.

Warning

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.

Warning

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

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

vCenter Section

You have more information about vCenter attributes in the vCenter Specifics Section:

Public Cloud Section

To define a Virtual Machine in the supported cloud providers, the following attributes can be used in the PUBLIC_CLOUD section:

Amazon EC2 Attributes

More information in the Amazon EC2 Driver Section:

Attribute Description Mandatory
TYPE Needs to be set to “EC2” YES
AMI Unique ID of a machine image, returned by a call to ec2-describe-images. YES
AKI The ID of the kernel with which to launch the instance. NO
CLIENTTOKEN Unique, case-sensitive identifier you provide to ensure idem-potency of the request. NO
INSTANCETYPE Specifies the instance type. YES
KEYPAIR The name of the key pair, later will be used to execute commands like ssh -i id_keypair or scp -i id_keypair NO
LICENSEPOOL --license-pool NO
BLOCKDEVICEMAPPING The block device mapping for the instance. More than one can be specified in a space-separated list. Check the –block-device-mapping option of the EC2 CLI Reference for the syntax NO
PLACEMENTGROUP Name of the placement group. NO
PRIVATEIP If you’re using Amazon Virtual Private Cloud, you can optionally use this parameter to assign the instance a specific available IP address from the subnet. NO
RAMDISK The ID of the RAM disk to select. NO
SUBNETID If you’re using Amazon Virtual Private Cloud, this specifies the ID of the subnet you want to launch the instance into. This parameter is also passed to the command ec2-associate-address -i i-0041230 -a elasticip. NO
TENANCY The tenancy of the instance you want to launch. NO
USERDATA Specifies Base64-encoded MIME user data to be made available to the instance(s) in this reservation. NO
SECURITYGROUPS Name of the security group. You can specify more than one security group (comma separated). NO
SECURITYGROUPIDS Ids of the security group. You can specify more than one security group (comma separated). NO
ELASTICIP EC2 Elastic IP address to assign to the instance. This parameter is passed to the command ec2-associate-address -i i-0041230 elasticip. NO
TAGS Key and optional value of the tag, separated by an equals sign ( = ).You can specify more than one tag (comma separated). NO
AVAILABILITYZONE The Availability Zone in which to run the instance. NO
HOST Defines which OpenNebula host will use this template NO
EBS_OPTIMIZED Obtain a better I/O throughput for VMs with EBS provisioned volumes NO

Azure Attributes

More information in the Azure Driver Section:

Attribute Description Mandatory
TYPE Needs to be set to “AZURE” YES
INSTANCE_TYPE Specifies the capacity of the VM in terms of CPU and memory YES
IMAGE Specifies the base OS of the VM. There are various ways to obtain the list of valid images for Azure, the simplest one is detailed here YES
VM_USER If the selected IMAGE is prepared for Azure provisioning, a username can be specified here to access the VM once booted NO
VM_PASSWORD Password for VM_USER NO
LOCATION Azure datacenter where the VM will be sent. See /etc/one/az_driver.conf for possible values (use the name of the section, not the region names). Spaces are not supported in this value. NO
STORAGE_ACCOUNT Specify the storage account where this VM will belong NO
WIN_RM Comma-separated list of possible protocols to access this Windows VM NO
CLOUD_SERVICE Specifies the name of the cloud service where this VM will be linked. Defaults to “csn<vid>, where vid is the id of the VM”. NO
TCP_ENDPOINTS Comma-separated list of TCP ports to be accesible from the public internet to this VM NO
SSHPORT Port where the VMs ssh server will listen on NO
VIRTUAL_NETWORK_NAME Name of the virtual network to which this VM will be connected NO
SUBNET NAme of the particular Subnet where this VM will be connected to NO
AVAILABILITY_SET Name of the availability set to which this VM will belong NO
AFFINITY_GROUP Affinity groups allow you to group your Azure services to optimize performance. All services and VMs within an affinity group will be located in the same region belong NO

Predefined Host Attributes

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

Attribute Meaning
NAME Hostname.
MAX_CPU Total CPU in the host, in (# cores * 100).
CPU_USAGE Allocated used CPU in (# cores * 100). This value is the sum of all the CPU requested by VMs running on the host, and is updated instantly each time a VM is deployed or undeployed.
FREE_CPU Real free CPU in (# cores * 100), as returned by the probes. This value is updated each monitorization cycle.
USED_CPU Real used CPU in (# cores * 100), as returned by the probes. USED_CPU = MAX_CPU - FREE_CPU. This value is updated each monitorization cycle.
MAX_MEM Total memory in the host, in KB.
MEM_USAGE Allocated used memory in KB. This value is the sum of all the memory requested by VMs running on the host, and is updated instantly each time a VM is deployed or undeployed.
FREE_MEM Real free memory in KB, as returned by the probes. This value is updated each monitorization cycle.
USED_MEM Real used memory in KB, as returned by the probes. USED_MEM = MAX_MEM - FREE_MEM. This value is updated each monitorization cycle.
RUNNING_VMS Number of VMs deployed on this host.
HYPERVISOR Hypervisor name.

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

Note

Check the Monitoring Subsystem guide to find out how to extend the information model and add any information probe to the Hosts.

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.

RAW Attribute Description KVM vCenter LXD
TYPE Possible values are: kvm, lxd, vmware O - O
DATA Raw data to be passed directly to the hypervisor O - O
DATA_VMX Raw data to be added directly to the .vmx file - - -

Example:

RAW = [
    type = "kvm",
    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>"
]

Additionally the following can be also set for KVM

Attribute Description
EMULATOR Path to the emulator binary to use with this VM

Example:

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

Restricted Attributes

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

  • CONTEXT/FILES
  • NIC/MAC
  • NIC/VLAN_ID
  • NIC/BRIDGE
  • 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_DEFAULT/MAC
  • NIC_DEFAULT/VLAN_ID
  • NIC_DEFAULT/BRIDGE
  • NIC/OPENNEBULA_MANAGED
  • DISK/TOTAL_BYTES_SEC
  • DISK/READ_BYTES_SEC
  • DISK/WRITE_BYTES_SEC
  • DISK/TOTAL_IOPS_SEC
  • DISK/READ_IOPS_SEC
  • DISK/WRITE_IOPS_SEC
  • DISK/OPENNEBULA_MANAGED
  • CPU_COST
  • MEMORY_COST
  • DISK_COST
  • DEPLOY_FOLDER

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:

Types Value Description
text <VAR>=”M|text| <desc>” A string
text64 <VAR>=”M|text64| <desc>” text64 will encode the user’s response in Base64
password <VAR>=”M|password| <desc>”  
number <VAR>=”M|number| <desc>” An integer
float <VAR>=”M|number-float| <desc>” A float
range <VAR>=”M|range| <desc>|<min>..<max>||<default>|” A range of integers
range (float) <VAR>=”M|range-float| <desc>|<min>..<max>||<default>|” A range of floats
list <VAR>=”M|list| <desc>|<v1>,<v2>,<v3>||<default>|” A list
boolean <VAR>=”M|boolean| <desc>|<default>|” Yes or not

There is the possibility of making the USER_INPUT mandatory or not. If it is mandatory, we will see a letter ‘M’ but if it is not mandatory a letter ‘O’ will appear. 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

Schedule actions Section

The following attributes can use to define puntual or relative actions for the VM.

Attribute Description
TIME Time in seconds to start the action.
REPEAT Define the granularity of the action [ WEEKLY = 0 , MONTHLY = 1 , YEARLY = 2 , HOURLY = 3 ].
DAYS Sets the frequency for recurring actions. The specific values depends on the REPEAT mode, i.e. for yearly periods DAYS=”1,365” would mean the first and last day of the a year
ACTION The action that will be executed.
END_TYPE When the users want end the action [ NEVER = 0 , NUMBER OF REPETITIONS = 1 , DATE = 2 ].
END_VALUE The value for END_TYPE attribute, can be a number or a date.

Example:

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