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, using the onevm create
command.
Warning
Some template attributes 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. In the following tables, default attributes are marked with *
. For the complete list, see the Restricted Attributes section.
Note
If not explicitly stated, the described attributes are valid for all supported hypervisors.
Important
The vCenter driver is a legacy component, and no longer receives updates or bug fixes.
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 that the VM will get for description purposes. If NAME is not supplied
a name generated by one will be in the form of |
YES For Templates NO For VMs - will be set to one-<vmid> if omitted |
|
Amount of RAM required for the VM, in Megabytes. |
YES |
|
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 |
|
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
Hotplug Resize VM Capacity¶
Important
Hotplug implemented only for KVM and vCenter
If you need to resize the capacity in RUNNING
state you have to setup some extra attributes in the VM template. These attributes must be set before the VM is started. They are driver-specific, more info for KVM and vCenter.
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 |
---|---|---|
|
Cost of each memory MB per hour. |
NO |
|
Cost of each CPU per hour. |
NO |
|
Cost of each disk MB per hour. |
NO |
OS and Boot Options Section¶
The operating 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 |
LXC |
---|---|---|---|---|
|
CPU architecture to virtualize. |
M (default i686) |
- |
- |
|
libvirt machine type. Check libvirt capabilities for the list of available machine types. |
O |
- |
- |
|
path to the OS kernel to boot the image in the host. |
O |
- |
- |
|
image to be used as kernel (see !!) |
O |
- |
- |
|
path to the initrd image in the host. |
O (for kernel) |
- |
- |
|
image to be used as ramdisk (see !!) |
O (for kernel) |
- |
- |
|
device to be mounted as root. |
O (for kernel) |
- |
- |
|
arguments for the booting kernel. |
O (for kernel) |
- |
- |
|
path to the bootloader executable. |
O |
- |
- |
|
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: |
M |
O |
O |
|
bus for disks with sd prefix, either |
O |
- |
- |
|
unique ID of the VM. It’s referenced as machine ID inside the VM. Could be used to force ID for licensing purposes. |
O |
O |
- |
|
firmware type or firmware path.
Possible values: |
O |
O |
- |
|
enable Secure Boot.
Possible values: |
O |
- |
- |
(!!) 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 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 |
LXC |
---|---|---|---|---|
|
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 |
- |
- |
|
The CPU features required by the guest. This a comma separated list of values of the CPU features in a virtual machine. Available features 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, Mandatory, or -
not supported for that hypervisor.
Sub-Attribute |
Description |
KVM |
vCenter |
LXC |
---|---|---|---|---|
|
Physical address extension mode allows 32-bit guests to address more than 4 GB of memory. |
O |
- |
- |
|
Useful for power management, for example, with KVM guests it is required for graceful shutdown to work. |
O |
- |
- |
|
Enables the advanced programmable IRQ management. Useful for SMP machines. |
O |
- |
- |
|
The guest clock will be synchronized to the host’s configured timezone when booted. Useful for Windows VMs. |
O |
- |
- |
|
Add hyperv extensions to the VM. The options can be
configured in the driver configuration, |
O |
- |
- |
|
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 |
- |
- |
|
Number of queues for the virtio-scsi controller. |
O |
- |
- |
|
Number of dispatch queues for the virtio-blk driver. |
O |
- |
- |
|
Number of iothreads for virtio disks. By default threads
will be assigned to disk by round robin algorithm. Disk
thread id can be forced by disk |
O |
- |
- |
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 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 |
LXC |
---|---|---|---|---|
|
ID of the Image to use. |
M (no |
M (no |
M (no |
|
Name of the Image to use. |
M (no |
M (no |
M (no |
|
To select the IMAGE of a given user by its |
O |
O |
O |
|
To select the IMAGE of a given user by its |
O |
O |
O |
|
Prefix for the emulated device this image will be mounted at. For instance, attribute of the Image will be used. |
O |
O |
- |
|
Device to map image disk. If set, it will overwrite the default device
|
O |
- |
O (where to mount the image inside
the container e.g.: |
|
Specific image mapping driver. |
O e.g.: |
- |
- |
|
Selects the cache mechanism for the disk. Values are |
O |
- |
O (Only for qcow2 disks) |
|
Set how the image is exposed by the hypervisor. |
O e.g.: |
- |
O |
|
Set IO policy. Values are |
O (Needs qemu 1.1) |
- |
- |
|
Iothread id used by this disk. Default is round robin. Can be used only if |
O (Needs qemu 2.1) |
- |
- |
|
Number of queues for the virtio-blk driver. It can be set for all disks, through the |
O (Needs qemu 2.1) |
- |
- |
|
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 |
|
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 |
|
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 |
|
Size of IOPS throttling for the disk. This attribute is effective only if one of the TOTAL_IOPS_SEC, READ_IOPS_SEC, WRITE_IOPS_SEC is defined. By default this parameter is only allowed to be used by oneadmin. |
O (Needs qemu 1.7) |
- |
- |
|
Possible values (warning: case-sensitive): lsiLogic, ide, busLogic. More information in the VMware documentation. |
- |
O (can be inherited from Datastore) |
- |
|
This is the type of the supporting media for the image. Values:
a block device ( |
O |
M (can be inherited from Datastore) FILE is the only accepted value |
O |
|
Possible values (careful with the case): thin, thick, …. More information in the VMware documentation |
- |
O (can be inherited from Datastore) |
- |
|
Controls what’s done with with trim commands to the disk, the values can be
|
O (only with virtio-scsi) |
- |
- |
|
vCenter datastore’s managed object reference. |
- |
M (can be inherited from Datastore) |
- |
|
vCenter instance uuid. | - |
M (can be inherited from Datastore) |
- |
|
|
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¶
Note
The hypervisor column states that the attribute is Optional, Mandatory, or -
not supported for that hypervisor.
Warning
Not supported on LXC.
DISK Sub-Attribute |
Description |
KVM |
vCenter |
---|---|---|---|
|
Type of the disk: |
O |
O |
|
size in MB. |
O |
O |
|
Format of the Image: |
M(for fs) |
M(for fs) |
|
Prefix for the emulated device this image
will be mounted at. For instance, |
O |
O |
|
device to map disk. |
O |
O |
|
special disk mapping options. KVM: |
O |
- |
|
Selects the cache mechanism for the disk.
Values are |
O |
- |
|
Set how the image is exposed by the hypervisor. |
O e.g.: |
- |
|
Set IO policy. Values are |
O |
- |
|
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 |
- |
|
Possible values (careful with the case): lsiLogic, ide, busLogic. More information in the VMware documentation |
- |
O |
|
Possible values (careful with the case): thin, thick, …. More information in the VMware documentation. |
- |
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
andOS
Images, andVolatile
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¶
Note
The hypervisor column states that the attribute is Optional, Mandatory, or -
not supported for that hypervisor.
NIC Sub-Attribute |
Description |
KVM |
vCenter |
LXC |
---|---|---|---|---|
|
|
M (No |
M (No |
M (No |
|
Name of the network to use (of those owned by user). Use if no |
M (No |
M (No |
M (No |
|
To select the |
O |
O |
O |
|
To select the |
O |
O |
O |
|
Request an specific IP from the |
O |
O |
O |
|
Request an specific HW address from the network interface. |
O |
O |
O |
|
Name of the bridge the network device is going to be attached to. |
O |
O |
O |
|
Name for the tun device created for the VM. |
O |
O |
O |
|
Name of a shell script to be executed after creating the tun device for the VM. |
O |
O |
O |
|
Hardware that will emulate this network interface. In KVM you can choose |
O |
O |
- |
|
To define a network filtering rule for the interface. |
O |
O |
O |
|
Command separated list of the ids of the security groups to be applied to this interface. |
O |
- |
- |
|
Average bitrate for the interface in kilobytes/second for inbound traffic. |
O |
O |
O |
|
Maximum bitrate for the interface in kilobytes/second for inbound traffic. |
O |
O |
O |
|
Data that can be transmitted at peak speed in kilobytes. |
O |
- |
- |
|
Average bitrate for the interface in kilobytes/second for outbound traffic. |
O |
O |
O |
|
Maximum bitrate for the interface in kilobytes/second for outbound traffic. |
O |
O |
O |
|
Data that can be transmitted at peak speed in kilobytes. |
O |
- |
- |
|
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 |
|
Define the requirement when |
O |
O |
O |
|
Define the rank when |
O |
O |
O |
|
Name of the NIC. |
O |
O |
O |
|
It is used only on alias, it references the NIC which is alias of. |
O |
O |
O |
Warning
The PORTS
and ICMP
attributes require the firewall functionality to be configured. Please read the firewall configuration guide.
Example, a VM with two NIC’s 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’s 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¶
Note
The hypervisor column states that the attribute is Optional, Mandatory, or -
not supported for that hypervisor.
The following I/O interfaces can be defined for a VM:
Attribute |
Description |
KVM |
vCenter |
LXC |
---|---|---|---|---|
|
Define input devices, available sub-attributes:
|
O |
- |
- |
|
Whether the VM should export its graphical display and how, available sub-attributes: |
O |
O |
O |
|
O |
O |
O (vnc) |
|
|
O |
O |
O |
|
|
O |
O |
O |
|
|
O |
O |
O |
|
|
O |
O |
- |
|
|
O |
O |
O |
|
|
Defines a custom video device, available sub-attributes: |
O |
- |
- |
|
M |
- |
- |
|
|
O |
- |
- |
|
|
O |
- |
- |
|
|
O |
- |
- |
|
|
O |
- |
- |
Note
Password will be truncated if its length exceeds 8 characters for vnc
or 60 characters for spice
.
Example:
GRAPHICS = [
TYPE = "vnc",
LISTEN = "0.0.0.0",
PORT = "5905"]
Warning
For the 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, 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¶
Note
The hypervisor column states that the attribute is Optional, Mandatory, -
not supported for that hypervisor or OS name where it is mandatory.
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 |
KVM/LXC |
vCenter |
---|---|---|---|
|
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 |
|
Space-separated list of paths to include in context device. The location of the files are
restricted by the |
O |
O |
|
Space-separated list of File images to include in context device. (Not supported for vCenter) |
O |
O |
|
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 |
O |
|
Text of the script executed when the machine boots. It can contain shebang in case it is not
a shell script. For example |
O |
O |
|
The same as |
O |
O |
|
Device to attach the context ISO. |
O |
- |
|
Device prefix for the context ISO, either |
O |
- |
|
|
O |
O |
|
OpenNebula will automatically add this variable if |
O |
O |
|
The VM will send the READY signal to the onegate server. After this, the
VM Template will contain |
O |
O |
|
|
Linux |
Linux |
|
Similar to READY_SCRIPT but the script exists in the Guest FS |
Linux |
Linux |
|
|
O |
O |
|
Network configuration service inside guest VM responsible for configuring the NICs:
empty (autodetects suitable service inside VM),
|
Linux |
Linux |
|
Netplan renderer (effective only when |
Linux |
Linux |
|
This parameter value will be the hostname of the VM. |
O |
O |
|
|
O |
O |
|
Specific DNS server for the Virtual Machine. |
O |
O |
|
Used to find the correct interface. |
O |
O |
|
IPv4 address for the interface. |
O |
O |
|
IPv6 address for the interface. Legacy |
O |
O |
|
IPv6 prefix length for the interface. |
O |
O |
|
IPv6 unique local address for the interface |
O |
O |
|
|
Linux |
Linux |
|
IPv6 configuration method for the interface inside VM:
|
O |
O |
|
IPv4 configuration method for the interface inside VM:
empty or |
O |
O |
|
Network address of the interface. |
O |
O |
|
Network mask. |
O |
O |
|
Default IPv4 gateway for the interface. |
O |
O |
|
Default IPv6 gateway for the interface. |
O |
O |
|
Comma separated list of custom routes for the interface.
Format: |
O |
O |
|
|
O |
O |
|
|
O |
O |
|
DNS for the network. |
O |
O |
|
Used to find the correct interface. |
O |
O |
|
IPv4 address for the alias. |
O |
O |
|
IPv6 address for the alias. Legacy |
O |
O |
|
IPv6 prefix length for the alias. |
O |
O |
|
IPv6 unique local address for the alias. |
O |
O |
|
|
- |
- |
|
|
- |
- |
|
Network address of the alias. |
O |
O |
|
Network mask. |
O |
O |
|
Default IPv4 gateway for the alias. |
- |
- |
|
Default IPv6 gateway for the alias. |
- |
- |
|
|
- |
- |
|
|
- |
- |
|
|
- |
- |
|
DNS for the alias. |
- |
- |
|
User to be created in the guest OS. If any password or SSH_PUBLIC_KEY attribute is defined
(see below) it will change this user (defaults to |
Linux |
Linux |
|
Crypted password encoded in base64. To be set for the user |
Linux |
Linux |
|
Password encoded in base64. To be set for the user |
O |
O |
|
Crypted password. To be set for the user |
Linux |
Linux |
|
Password to be set for the user |
O |
O |
|
Key to be added to |
O |
O |
|
Set to |
Windows |
Windows |
|
If set to |
Linux |
Linux |
|
Time zone to set. On Linux, the name must match the zone file name relative to
|
O |
O |
|
If set to |
O |
O |
|
Mountpoints on Linux (e.g.: |
O |
O |
|
If set to |
Linux |
Linux |
|
If set to |
Linux |
Linux |
|
Value |
Windows |
- |
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 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]"
Note
The network MUST be in use 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, for example:
root = "$IMAGE[ROOT_PASS, IMAGE_ID=0]"
Note
The image MUST be in use 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, 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 = [
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:
Attribute |
Description |
---|---|
|
Boolean expression that rules out provisioning hosts from list of machines suitable to run this VM. |
|
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. |
|
Boolean expression that rules out entries from the pool of datastores suitable to run this VM. |
|
States which attribute will be used to sort the suitable datastores for this VM. Basically, it defines which datastores are more suitable than others. |
|
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 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 information. ‘+’, ‘-’, ‘*’, ‘/’ and ‘-’ are arithmetic operators. The rank expression is calculated using floating point arithmetic, and then rounded 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¶
Tip
For more information about vCenter attributes, see also the vCenter Specifics Section.
Predefined Host Attributes¶
There are some predefined Host attributes that can be used in the requirements and rank expressions, valid for all hypervisors:
Attribute |
Description |
---|---|
|
Hostname. |
|
Total CPU in the host, in (# cores * 100). |
|
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. |
|
Real free CPU in (# cores * 100), as returned by the probes. This value is updated each monitorization cycle. |
|
Real used CPU in (# cores * 100), as returned by the probes. USED_CPU = MAX_CPU - FREE_CPU. This value is updated each monitorization cycle. |
|
Total memory in the host, in KB. |
|
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. |
|
Real free memory in KB, as returned by the probes. This value is updated each monitorization cycle. |
|
Real used memory in KB, as returned by the probes. USED_MEMORY = MAX_MEM - FREE_MEMORY. This value is updated each monitorization cycle. |
|
Number of VMs deployed on this host. |
|
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.
Attribute |
Description |
KVM |
vCenter |
LXC |
---|---|---|---|---|
|
Possible values are: |
O |
- |
O |
|
Validate DATA against XML schema, possible values |
O |
- |
- |
|
Raw data to be passed directly to the hypervisor. |
O |
- |
O |
|
Raw data to be added directly to the |
- |
O |
- |
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
Attribute |
Description |
---|---|
|
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:
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/VCENTER_INSTANCE_ID
NIC/VCENTER_NET_REF
NIC/VCENTER_PORTGROUP_TYPE
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_ALIAS/VCENTER_INSTANCE_ID
NIC_ALIAS/VCENTER_NET_REF
NIC_ALIAS/VCENTER_PORTGROUP_TYPE
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/VCENTER_DS_REF
DISK/VCENTER_INSTANCE_ID
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
VCENTER_VM_FOLDER
VCENTER_ESX_HOST
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
:
Types |
Value |
Description |
---|---|---|
text |
<VAR>=”M|text| <desc>| | <default>” |
A string |
text64 |
<VAR>=”M|text64| <desc>| | <default>” |
text64 will encode the user’s response in Base64 |
password |
<VAR>=”M|password| <desc>” |
|
number |
<VAR>=”M|number| <desc>| | <default>” |
An integer |
float |
<VAR>=”M|number-float| <desc>| | <default>” |
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 |
list-multiple |
<VAR>=”M|list-multiple| <desc>|<v1>,<v2>,<v3>|<default>|” |
A list with multiple values |
boolean |
<VAR>=”M|boolean| <desc>| | <default>” |
Yes or not |
fixed |
<VAR>=”M|fixed| <desc>| | <value>” |
A fixed value, cannot be changed. |
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.
Schedule actions Section¶
The following attributes can used to define punctual or relative actions for the VM.
Attribute |
Description |
---|---|
|
Time in seconds to start the action. Can be defined as relative value |
|
Time in seconds (can be relative |
|
Define the granularity of the action [ WEEKLY = 0 , MONTHLY = 1 , YEARLY = 2 , HOURLY = 3 ]. |
|
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 year. |
|
The action that will be executed. |
|
Additional arguments for the action (no need to define the VM_ID) |
|
When the users want end the action [ NEVER = 0 , NUMBER OF REPETITIONS = 1 , DATE = 2 ]. |
|
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",
WARNING="1537567200" ]
NUMA topology Section¶
The following attributes can use to define a NUMA topology for the VM.
TOPOLOGY attribute |
Description |
---|---|
|
vCPU pinning preference: |
|
Number of sockets or NUMA nodes. |
|
Number of cores per node. |
|
Number of threads per core. |
|
Size of the hugepages (MB). If not defined no hugepages will be used. |
|
Control if the memory is to be mapped |
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 setting the NUMA_NODE
attribute:
NUMA_NODE attribute |
Description |
---|---|
|
Memory allocated in the node, in MB. |
|
Total number of CPU units, CORE*THREADS. |
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:
Attribute |
Description |
---|---|
|
Disable interface network type (alias) |
|
Disable interface network selection (Automatic selection) |
|
Disable interface network RDP connection (active) |
|
Disable interface network SSH connection (active) |
|
Disable Network selection for VM on instantiation. |
For example:
SUNSTONE = [
NETWORK_ALIAS = "yes",
NETWORK_AUTO = "no",
NETWORK_RDP = "yes",
NETWORK_SSH = "yes"
]