Simplified Virtual Machine Definition File 3.2

This is the simplified version of the complete definition file reference. In this guide, only the basic attributes and functionality are described.

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.

Syntax

The syntax of the template file is as follows:

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

An Example

This template uses the most common functionality. The following sections briefly explain each attribute.

#### Capacity ####
 
NAME   = test-vm
MEMORY = 128 
CPU    = 1
 
#### Disks ####
 
# OS image, mapped to sda.
DISK = [ IMAGE_ID  = 2 ]
 
# First DATABLOCK image, mapped to sde
DISK = [ IMAGE_ID  = 3 ]
 
# Second DATABLOCK image, mapped to sdf
DISK = [ IMAGE_ID  = 12 ]
 
# swap, sdd
DISK = [ TYPE     = swap,
         SIZE     = 1024 ]
 
#### Network interfaces ####
 
NIC = [ NETWORK_ID = 1 ]
 
#### I/O Devices ####
 
GRAPHICS = [ 
  TYPE    = "vnc",
  LISTEN  = "0.0.0.0",
  PORT    = "5"]

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. NO - will be set to one-<vmid> if omitted
MEMORY Amount of RAM required for the VM, in Megabytes. YES
CPU Percentage of CPU divided by 100 required for the Virtual Machine, half a processor is written 0.5. This value is used by OpenNebula and the scheduler to guide the host overcommitment. YES - will be set to 1 if omitted, this can be changed in the driver configuration
VCPU Number of virtual cpus. This value is optional, the default hypervisor behavior is used, usually one virtual CPU. YES - will be set to 1 if omitted, this can be changed in the driver configuration

Disks Section

The disks of a VM are defined with the DISK vector attribute. You can define as many DISK attributes as you need.

There are two ways to attach a disk to a VM: using an OpenNebula image from the image repository, or declaring a disk type that can be created from a source disk file in your system. This guide assumes that you will only use Images from the repository (can be listed with oneimage list).

Using an Image

To use the registered images in your VMs, you need to specify the IMAGE_ID or the IMAGE name sub-attribute. See the example snippet below.

DISK Sub-Attribute M / O Description
IMAGE_ID M (if no IMAGE) ID of the Image to use
DISK Sub-Attribute M / O Description
IMAGE M (if no IMAGE_ID) Name of the Image to use (of those owned by user)
IMAGE_UID O (for IMAGE) To select the IMAGE of a given user by her ID
IMAGE_UNAME O (for IMAGE) To select the IMAGE of a given user by her NAME
# use image with ID 23
DISK = [ IMAGE_ID     = 23 ]
 
# use the Image named ubuntu, owned by the user named oneadmin.
DISK = [ IMAGE        = "Ubuntu",
         IMAGE_UNAME  = "oneadmin" ]
 
# use the ubuntu Image owned by user with ID 7.
DISK = [ IMAGE        = "Ubuntu",
         IMAGE_UID    = 7 ]
 
# use the ubuntu Image owned by the user instantiating the VM.
DISK = [ IMAGE        = "Ubuntu" ]

Once the VM machine is shut down, the changes made to the images can be saved back to the repository. To do so, make your Images persistent, or use the onevm saveas command to save the changes as a new Image.

Swap Disks

In a similar way that you can create empty datablock Images, VM disks can be created on the fly. This is specially useful to create swap disks.

DISK Sub-Attribute Description
TYPE Set to “swap”
SIZE size in MB

Disks Device Mapping

When you use images in your VM template, OpenNebula will mount the disks as follows:

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

Only one OS type image per VM template can be declared, the same applies for CDROM type images. You can use as many DATABLOCK images as you need. Please visit the guide for managing images and the image template reference to learn more about the different image types.

You can find a complete description of the contextualization features in the contextualization guide.

The device prefix sd can be changed to hd or other prefix that suits your virtualization hypervisor requirements. You can find more information in the configuration guide and the daemon configuration guide.

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

Network Section

Each network interface of a VM is defined with the NIC vector attribute. You can define as many NIC attributes as you need.

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

NIC Sub-Attribute M / O Description
NETWORK_ID M (if no NETWORK) ID of the network to attach this device, as defined by onevnet
NIC Sub-Attribute M / O Description
NETWORK M (if no NETWORK_ID) Name of the network to use (of those owned by user)
NETWORK_UID O (for NETWORK) To select the NETWORK of a given user by her ID
NETWORK_UNAME O (for NETWORK) To select the NETWORK of a given user by her NAME

The NETWORK and NETWORK_ID attributes are used in the same way as the IMAGE and IMAGE_ID ones, see the Using an Image section above for an example.

I/O Devices Section

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

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

Attribute Description XEN KVM VMWARE
INPUT Define input devices, available sub-attributes:
- TYPE: values are mouse or tablet
- BUS: values are usb, ps2 or xen
- O -
GRAPHICS Wether the VM should export its graphical display and how, available sub-attributes:
- TYPE: values: vnc sdl
- LISTEN: IP to listen on.
- PORT: port for the VNC server
- PASSWD: password for the VNC server
- KEYMAP: keyboard configuration locale to use in the VNC display
O O -

:!: For KVM hypervisor the port number is a real one, not the VNC port. So for VNC port 0 you should specify 5900, for port 1 is 5901 and so on.

:!: If the user does not specify the port variable, OpenNebula will automatically assign $VNC_BASE_PORT + $VMID, allowing to generate different ports for VMs so they do not collide. The VNC_BASE_PORT is specified inside the oned.conf file.