Virtual Machine Instances

This guide may be considered a continuation of the Virtual Machines Templates guide. Once a Template is instantiated to a Virtual Machine, there are a number of operations that can be performed using the onevm command.

Basic Virtual Machine Operations

Creating and Listing VMs

Assuming we have a VM template registered called vm-example with ID 6, then we can instantiate the VM by issuing a:

onetemplate list
ID USER     GROUP    NAME                         REGTIME
 6 oneadmin oneadmin vm_example            09/28 06:44:07

onetemplate instantiate vm-example --name my_vm
VM ID: 0

If the template has USER INPUTS defined, the CLI will prompt the user for these values:

onetemplate instantiate vm-example --name my_vm
There are some parameters that require user input.
  * (BLOG_TITLE) Blog Title: <my_title>
  * (DB_PASSWORD) Database Password:
VM ID: 0

Afterwards, the VM can be listed with the onevm list command. You can also use the onevm top command to list VMs continuously.

onevm list
ID USER     GROUP    NAME         STAT CPU     MEM        HOSTNAME        TIME
 0 oneadmin oneadmin my_vm        pend   0      0K                 00 00:00:03

The scheduler will automatically deploy the VM in one of the Hosts with enough resources available. The deployment can also be forced by oneadmin using onevm deploy:

onehost list
ID NAME               RVM   TCPU   FCPU   ACPU   TMEM   FMEM   AMEM   STAT
 2 testbed              0    800    800    800    16G    16G    16G     on

onevm deploy 0 2

onevm list
ID USER     GROUP    NAME         STAT CPU     MEM        HOSTNAME        TIME
 0 oneadmin oneadmin my_vm        runn   0      0K         testbed 00 00:02:40

and details about it can be obtained with show:

onevm show 0
VIRTUAL MACHINE 0 INFORMATION
ID                  : 0
NAME                : my_vm
USER                : oneadmin
GROUP               : oneadmin
STATE               : ACTIVE
LCM_STATE           : RUNNING
START TIME          : 04/14 09:00:24
END TIME            : -
DEPLOY ID:          : one-0

PERMISSIONS
OWNER          : um-
GROUP          : ---
OTHER          : ---

VIRTUAL MACHINE MONITORING
NET_TX              : 13.05
NET_RX              : 0
USED MEMORY         : 512
USED CPU            : 0

VIRTUAL MACHINE TEMPLATE
...

VIRTUAL MACHINE HISTORY
 SEQ        HOSTNAME REASON           START        TIME       PTIME
   0         testbed   none  09/28 06:48:18 00 00:07:23 00 00:00:00

Searching for VM Instances

You can search for VM instances by using the --search option of the onevm list command. This is especially useful on large environments with many VMs. The filter must be in a VM.KEY1=VALUE1&VM.KEY2=VALUE2 format and will return all the VMs which fit the filter. The & works as logical AND. You can use *=VALUE to search the full VM body or VM.TEMPLATE=VALUE to search whole template.

Searching is performed using JSON on the whole body of the VM. You can use the MySQL JSON path without the leading $., information about the path structure can be found in the MySQL Documentation or MariaDB Documentation. Currently, the value is wrapped in % for the query, so it will match if it contains the value provided.

The VALUE part of a search query can utilize special characters to create flexible matching patterns:

• %: Matches any string, allowing for wildcard searches. For example, a%a%a matches names containing three “a”s in any position, with any number of characters between them.
• _: Matches any single character, enabling precise pattern matching. For instance, a_a_a matches names with three “a”s, each separated by exactly one character.
• &: Cannot be used in the VALUE part of the search query, as it is always interpreted as logical AND operator and does not support escaping.

To search for strings that contain % or _ literally, escape these characters with a backslash \. For example:

• a\%a will search for “a%a” as an exact sequence.
• a\_a will match “a_a” without interpreting _ as a single-character wildcard.

For example, for to search for a VM with a specific MAC address:

onevm list --search 'VM.TEMPLATE.NIC[*].MAC=02:00:0c:00:4c:dd'
ID    USER     GROUP    NAME    STAT UCPU UMEM HOST TIME
21005 oneadmin oneadmin test-vm pend    0   0K      1d 23h11

Equivalently, if there is more than one VM instance that matches the result they will be shown. For example, VM’s NAME containing a pattern and owned by oneadmin:

onevm list --search 'VM.NAME=test-vm&VM.UNAME=oneadmin'
 ID    USER     GROUP    NAME     STAT UCPU UMEM HOST TIME
 21005 oneadmin oneadmin test-vm  pend    0   0K       1d 23h13
 2100  oneadmin oneadmin test-vm2 pend    0   0K      12d 17h59

Terminating VM Instances

You can terminate an instance with the onevm terminate command, from any state. It will shut down (if needed) and delete the VM. This operation will free the resources (images, networks, etc.) used by the VM.

If the instance is running, there is a --hard option that has the following meaning:

• terminate: Gracefully shuts down and deletes a running VM, sending the ACPI signal. Once the VM is shut down the Host is cleaned and persistent and deferred-snapshot disk will be moved to the associated datastore. If after a given time the VM is still running (e.g., guest ignoring ACPI signals), OpenNebula will return the VM to the RUNNING state.
• terminate --hard: Same as above but the VM is immediately destroyed. Use this action instead of terminate when the VM doesn’t have ACPI support.

Pausing VM Instances

There are two different ways to temporarily stop the execution of a VM: short and long term pauses. A short term pause keeps all the VM resources allocated to the Hosts so it resumes its operation in the same Hosts quickly. Use the following onevm commands or Sunstone actions:

• suspend: the VM state is saved in the running Host. When a suspended VM is resumed, it is immediately deployed in the same Host by restoring its saved state.
• poweroff: Gracefully powers off a running VM by sending the ACPI signal. It is similar to suspend but without saving the VM state. When the VM is resumed it will boot immediately in the same Host.
• poweroff --hard: Same as above but the VM is immediately powered off. Use this action when the VM doesn’t have ACPI support.

You can also plan a long term pause. The Host resources used by the VM are freed and the Host is cleaned. VM disk state is saved in the system datastore. The following actions are useful if you want to preserve network and storage allocations (e.g., IPs, persistent disk images):

• undeploy: Gracefully shuts down a running VM, sending the ACPI signal. The Virtual Machine disks are transferred back to the system datastore. When an undeployed VM is resumed it is moved to the pending state and the scheduler will choose where to re-deploy it.
• undeploy --hard: Same as above but the running VM is immediately destroyed.
• stop: Same as undeploy but also the VM state is saved to resume it later.

When the VM is successfully paused you can resume its execution with:

• resume: Resumes the execution of VMs in the stopped, suspended, undeployed, and poweroff states.

Rebooting VM Instances

Use the following commands to reboot a VM:

• reboot: Gracefully reboots a running VM, sending the ACPI signal.
• reboot --hard: Performs a ‘hard’ reboot.

Delaying VM Instances

The deployment of a PENDING VM (e.g., after creating or resuming it) can be delayed with:

• hold: Sets the VM to hold state. The scheduler will not deploy VMs in the hold state. Please note that VMs can be created directly on hold by using ‘onetemplate instantiate –hold’ or ‘onevm create –hold’.

Then you can resume it with:

• release: Releases a VM from hold state, setting it to pending. Note that you can automatically release a VM by scheduling the operation as explained below.

Hotplug Devices to a Virtual Machine

Disk Hot-plugging

New disks can be hot-plugged to running VMs with the onevm, disk-attach, and disk-detach commands. For example, to attach the Image named storage to a running VM:

onevm disk-attach one-5 --image storage

To detach a disk from a running VM, find the disk ID of the Image you want to detach using the onevm show command, and then simply execute onevm detach vm_id disk_id:

onevm show one-5
...
DISK=[
  DISK_ID="1",
...
  ]
...

onevm disk-detach one-5 1

NIC Hot-plugging

You can hot-plug network interfaces to VMs in the RUNNING, POWEROFF, or SUSPENDED states. Simply specify the network where the new interface should be attached, for example:

onevm show 2

VIRTUAL MACHINE 2 INFORMATION
ID                  : 2
NAME                : centos-server
STATE               : ACTIVE
LCM_STATE           : RUNNING

...

VM NICS
ID NETWORK      VLAN BRIDGE   IP              MAC
 0 net_172        no vbr0     172.16.1.201    02:00:ac:10:0

...

onevm nic-attach 2 --network net_172

After the operation you should see two NICs, 0 and 1:

onevm show 2
VIRTUAL MACHINE 2 INFORMATION
ID                  : 2
NAME                : centos-server
STATE               : ACTIVE
LCM_STATE           : RUNNING

...


VM NICS
ID NETWORK      VLAN BRIDGE   IP              MAC
 0 net_172        no vbr0     172.16.1.201    02:00:ac:10:00:c9
                              fe80::400:acff:fe10:c9
 1 net_172        no vbr0     172.16.1.202    02:00:ac:10:00:ca
                              fe80::400:acff:fe10:ca
...

It is possible to attach (and live-attach) PCI and SR-IOV interfaces. Simply select the device by its address, id, vendor, or class.

onevm nic-attach 2 --network net_172 onevm nic-attach 2 --network net_172 --pci '00:06.1'

Important, predictable PCI addresses for guests will be only generated if PCI bus 1 is present in the Virtual Machine as PCI bridges cannot be hot-plugged.

You can also detach a NIC by its ID. If you want to detach interface 1 (MAC 02:00:ac:10:00:ca), execute:

onevm nic-detach 2 1

NIC Update

Qos attributes can be updated by the command onevm nic-update. If the Virtual Machine is running, the action triggers the driver action to live-update the network parameters.

cat update_nic.txt
NIC = [
    INBOUND_AVG_BW = "512",
    INBOUND_PEAK_BW = "1024"
]

onevm nic-update 0 0 update_nic.txt

Security Group Hot-plugging

You can live attach or detach security groups to VMs. Simply specify the VM, network interface, and security group to attach, for example:

onevm sg-attach centos-server 0 101

Similarly to detach a security group execute:.

onevm sg-detach centos-server 0 101

On Sunstone, you can attach and detach security groups to an NIC on a running or powered off VM by going to the Network tab, select the NIC and open the dropdown menu (with the ellipsis icon), then select Security Groups:

To attach a new security group, you need to click on the shield on the NIC row. A dialog will be displayed where you can find all the security groups that do not belong to the selected network.

To detach the security group, you must click on the Trash button next to the security group. A confirm dialog will be displayed to ensure that you want to detach the security group.

PCI Devices

You can attach or detach a PCI to/from a Virtual Machine in the POWEROFF and UNDEPLOYED state. For example:

onevm pci-attach alpine01 --pci_class 0c03 --pci_device 0015 --pci_vendor 1912
onevm pci-detach alpine01 0

Virtual Machine System Snapshots

onevm snapshot-create 4 "just in case"

onevm show 4
...
SNAPSHOTS
  ID         TIME NAME                                           HYPERVISOR_ID
   0  02/21 16:05 just in case                                   onesnap-0

onevm snapshot-revert 4 0 --verbose
VM 4: snapshot reverted

Virtual Machine Disk Snapshots

There are two kinds of operations related to disk snapshots:

• disk-snapshot-create, disk-snapshot-revert, disk-snapshot-delete, disk-snapshot-rename: Allows the user to take snapshots of the disk states and return to them during the VM life-cycle. It is also possible to rename or delete snapshots.
• disk-saveas: Exports VM disk (or a previously created snapshot) to an Image in an OpenNebula Datastore. This is a live action.

Managing Disk Snapshots

A user can take snapshots of VM disks to create a checkpoint of the state of a specific disk at any time. Depending on the storage backend, these snapshots can be organized:

• In a tree-like structure, meaning that every snapshot has a parent, except for the first snapshot whose parent is -1. The active snapshot, the one the user has last reverted to or taken, will act as the parent of the next snapshot. It’s possible to delete snapshots that are not active and that have no children.
• Flat structure, without parent/child relationship. In that case, snapshots can be freely removed.

Disk snapshots are managed with the following commands:

• disk-snapshot-create <vmid> <diskid> <name>: Creates a new snapshot of the specified disk.
• disk-snapshot-revert <vmid> <diskid> <snapshot_id>: Reverts to the specified snapshot. The snapshots are immutable, therefore users can revert to the same snapshot as many times as they want; the disk will always return to the state of the snapshot at the time it was taken.
• disk-snapshot-delete <vmid> <diskid> <snapshot_id>: Deletes a snapshot if it has no children and is not active.

disk-snapshot-create can take place when the VM is in RUNNING state, provided that the drivers support it, while disk-snapshot-revert requires the VM to be in POWEROFF or SUSPENDED. Live snapshots are only supported for some hypervisors and storage drivers:

• Hypervisor VM_MAD=kvm combined with TM_MAD=qcow2 datastores. In this case OpenNebula will request that the hypervisor executes virsh snapshot-create.
• Hypervisor VM_MAD=kvm with Ceph datastores (TM_MAD=ceph). In this case OpenNebula will initially create the snapshots as Ceph snapshots in the current volume.

With these combinations (CEPH and qcow2 datastores, and KVM hypervisor) you can enable QEMU Guest Agent. With this agent enabled the filesystem will be frozen while the snapshot is being taken.

See the Storage Driver guide for a reference on the driver actions invoked to perform live and non-live snapshots.

Persistent Images and Disk Snapshots

These actions are available for both persistent and non-persistent Images. In the case of persistent Images the snapshots will be preserved upon VM termination and will be able to be used by other VMs using that Image. See the snapshots section in the Images guide for more information.

Saving a VM Disk to an Image (disk-saveas)

Any VM disk can be saved to a new Image (if the VM is in RUNNING, POWEROFF, SUSPENDED, UNDEPLOYED, or STOPPED states). This is a live operation that happens immediately. This operation accepts --snapshot <snapshot_id> as an optional argument, which specifies a disk snapshot to use as base of the new Image, instead of the current disk state (value by default).

Resizing VM Resources

You may resize the capacity assigned to a Virtual Machine in terms of the virtual CPUs, memory, and CPU allocated. VM resizing can be done in any of the following states: POWEROFF, UNDEPLOYED and, with some limitations, also live in RUNNING state.

If you have created a Virtual Machine and you need more resources, the following procedure is recommended:

• Perform any operation needed to prepare your Virtual Machine for shutting down, e.g., you may want to manually stop some services
• Power off the Virtual Machine
• Resize the VM
• Resume the Virtual Machine using the new capacity

Note that using this procedure the VM will preserve any resource assigned by OpenNebula, such as IP leases.

The following is an example of the previous procedure from the command line:

onevm poweroff web_vm
onevm resize web_vm --memory 2G --vcpu 2
onevm resume web_vm

Live Resize of Capacity

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

Resizing VM Disks

If the disks assigned to a Virtual Machine need more size, this can achieved at instantiation time of the VM. The SIZE parameter of the disk can be adjusted and, if it is bigger than the original size of the Image, OpenNebula will:

• Increase the size of the disk container prior to launching the VM
• Using the contextualization packages, at boot time the VM will grow the filesystem to adjust to the new size.

You can override the size of a DISK in a VM template at instantiation:

onetemplate instantiate <template> --disk u2104:size=20000 # Image u2104 will be resized to 2 GB

You can also resize VM disks for both RUNNING and POWEROFF VMs:

onevm disk-resize <vm_id> <disk_id> <new_size> # <new_size> must be greater than current disk size

This will make the VM disk grow on the hypervisor node. Then the contextualization service running inside the guest OS will expand the filesystem with the newly available free space. The support for this filesystem expansion depends on the Guest OS.

Updating the Virtual Machine Configuration

Some of the VM configuration attributes defined in the VM template can be updated after the VM is created. The onevm updateconf command will allow you to change the following attributes:

Visit the Virtual Machine Template reference for a complete description of each attribute. Visit the VM Update Methods Reference for additional details on all available VM configuration update methods.

Cloning a Virtual Machine

A VM template or VM instance can be copied to a new VM template. This copy will preserve the changes made to the VM disks after the instance is terminated. The template is private and will only be listed to the owner user.

There are two ways to create a persistent private copy of a VM:

• Instantiate a VM template with the to persistent option.
• Save an existing VM instance with onevm save.

Instantiate to Persistent

When instantiating to persistent the template is cloned recursively (a private persistent clone of each disk Image is created), and that new template is instantiated.

To “instantiate to persistent” use the --persistent option:

onetemplate instantiate web_vm --persistent --name my_vm
VM ID: 31

onetemplate list
  ID USER            GROUP           NAME                                REGTIME
   7 oneadmin        oneadmin        web_vm                       05/12 14:53:11
   8 oneadmin        oneadmin        my_vm                        05/12 14:53:38

oneimage list
  ID USER       GROUP      NAME            DATASTORE     SIZE TYPE PER STAT RVMS
   7 oneadmin   oneadmin   web-img         default       200M OS   Yes used    1
   8 oneadmin   oneadmin   my_vm-disk-0    default       200M OS   Yes used    1

To “instantiate multiple persistent” VMs use the options -m N and --name. You must provide --name when -m > 1. Include %i in the name to insert the VM index (0..N-1) at a custom place:

onetemplate instantiate -m 2 --persistent --name 'test'
VM ID: 0
VM ID: 1

onetemplate instantiate -m 2 --persistent --name '%i-test'
VM ID: 2
VM ID: 3

onevm list
  ID USER         GROUP        NAME       STAT     CPU      MEM     HOST      TIME
   3 oneadmin     oneadmin     1-test     hold       1     768M           0d 00h00
   2 oneadmin     oneadmin     0-test     hold       1     768M           0d 00h00
   1 oneadmin     oneadmin     test-1     hold       1     768M           0d 00h00
   0 oneadmin     oneadmin     test-0     hold       1     768M           0d 00h00

Equivalently, in Sunstone activate the “Persistent” switch next to the Create button. Include %i in the name to insert the VM index (0..N-1) at a custom place.

Please bear in mind the following ontemplate instantiate --persistent limitation: volatile disks cannot be persistent. The contents of the disks will be lost when the VM is terminated. The cloned VM template will contain the definition for an empty volatile disk.

Save a VM Instance

Alternatively, a VM that was not created as persistent can be saved before it is destroyed. To do so, the user has to poweroff the VM first and then use the save operation.

This action clones the VM source template, replacing the disks with copies of the current disks (see the disk-snapshot action). If the VM instance was resized, the current capacity is also used. The new cloned Images can be made persistent with the --persistent option. NIC interfaces are also overwritten with the ones from the VM instance, to preserve any attach/detach action.

onevm save web_vm copy_of_web_vm --persistent
Template ID: 26

Please bear in mind the following onevm save limitations:

• The VM’s source template will be used. If this template was updated since the VM was instantiated, the new contents will be used.
• Volatile disks cannot be saved and the current contents will be lost. The cloned VM template will contain the definition for an empty volatile disk.
• Disks and NICs will only contain the target Image/Network NAME and UNAME if defined. If your template requires extra configuration, you will need to update the new template.

Scheduled Actions for Virtual Machines

Scheduled actions lets you program operations over a VM to be performed in the future, e.g., Shutdown the VM after 5 hours. OpenNebula supports two types of schedule actions:

• punctual, that can be also periodic.
• relative actions.

One-Time Punctual Actions

Most of the onevm commands accept the --schedule option, allowing users to delay the actions until a given date and time.

Here is an usage example:

onevm suspend 0 --schedule "09/20"
VM 0: suspend scheduled at 2016-09-20 00:00:00 +0200

onevm resume 0 --schedule "09/23 14:15"
VM 0: resume scheduled at 2016-09-23 14:15:00 +0200

onevm show 0
VIRTUAL MACHINE 0 INFORMATION
ID                  : 0
NAME                : one-0

[...]

SCHEDULED ACTIONS
ID    ACTION  ARGS   SCHEDULED REPEAT   END STATUS
 0   suspend     - 09/20 00:00              Next in 12.08 days
 1    resume     - 09/23 14:15              Next in 15.67 days

These actions can be deleted or edited using the onevm sched-delete and onevm sched-update command. The time attributes use Unix time internally.

onevm sched-update 0 0

ID="0"
PARENT_ID="0"
TYPE="VM"
ACTION="suspend"
TIME="1703164454"
REPEAT="-1"
END_TYPE="-1"
END_VALUE="-1"
DONE="-1"

Periodic Punctual Actions

To schedule periodic actions you can also use the option –schedule. However this command also needs more options to define the periodicity of the action:

• --weekly: defines a weekly periodicity, so the action will be executed every week on the days that the user defines.
• --monthly: defines a monthly periodicity, so the action will be executed every month, on the days that the user defines.
• --yearly: defines a yearly periodicity, so the action will be executed every year, on the days that the user defines.
• --hourly: defines an hourly periodicity, so the action will be executed each ‘x’ hours.
• --end: defines when you want the relative action to finish.

The option --weekly, --monthly, and --yearly need the index of the days that the users wants to execute the action.

• --weekly: days separated with commas between 0 (Sunday) and 6 (Saturday). [0,6]
• --monthly: days separated with commas between 1 and 31. [1,31]
• --yearly: days separated with commas between 0 and 365. [0,365]

The option --hourly needs a number with the number of hours. [0,168] (1 week)

The option --end can be a number or a date:

• Number: defines the number of repetitions.
• Date: defines the date that the user wants to finish the action.

Here is a usage example:

onevm suspend 0 --schedule "09/20" --weekly "1,5" --end 5
VM 0: suspend scheduled at 2018-09-20 00:00:00 +0200

onevm resume 0 --schedule "09/23 14:15" --weekly "2,6" --end 5
VM 0: resume scheduled at 2018-09-23 14:15:00 +0200

onevm snapshot-create 0 snap-01 --schedule "09/23" --hourly 5 --end "12/25"
VM 0: snapshot-create scheduled at 2018-09-23 14:15:00 +0200

onevm show 0
VIRTUAL MACHINE 0 INFORMATION
ID                  : 0
NAME                : one-0

[...]

SCHEDULED ACTIONS
ID           ACTION     ARGS    SCHEDULED        REPEAT            END  STATUS
 0          suspend        -  09/20 00:00    Weekly 1,5  After 5 times  Next in 1.08 days
 1           resume        -  09/23 14:15    Weekly 2,6  After 5 times  Next in 4.67 days
 2  snapshot-create  snap-01  09/19 21:16  Each 5 hours    On 12/25/18  Next in 4.78 hours

These actions can be deleted or edited using the onevm sched-delete and onevm sched-update command. The time attributes use Unix time internally.

onevm sched-update 0 2

ID="2"
PARENT_ID="0"
TYPE="VM"
ACTION="snapshot-create"
ARGS="snap-01"
TIME="1701998190"
REPEAT="3"
DAYS="5"
END_TYPE="2"
END_VALUE="1893452400"
DONE="1701980968"

Relative Actions

Scheduled actions can be also relative to the Start Time of the VM. That is, it can be set on a VM Template and apply to the number of seconds after the VM is instantiated.

For instance, a VM Template with the following SCHED_ACTION will spawn VMs that will automatically shut down after 1 hour of being instantiated:

onetemplate update 0

SCHED_ACTION=[
   ACTION="terminate",
   ID="0",
   TIME="+3600" ]

This functionality is present graphically in Sunstone in the VM template creation and update wizard, on the second step Advanced options, under Schedule Action tab.

The following table summarizes the actions that can be scheduled. Note that some of the above actions need some parameters to run (e.g., a disk ID or a snapshot name).

You can pass arguments to the scheduled actions by using the parameter ARGS in the action definition. For example:

onevm sched-update 0 0

ID="2"
PARENT_ID="0"
TYPE="VM"
ACTION="disk-snapshot-create",
ARGS="0, disksnap_example",
DAYS="1,5",
END_TYPE="1",
END_VALUE="5",
ID="0",
REPEAT="0",
TIME="1537653600"

In this example, the first argument would be the disk and the second the snapshot name.

Command Execution Inside the Virtual Machine

Prerequisites:

• The VM Template must have the QEMU Guest Agent communication channel enabled with GUEST_AGENT = "YES" in FEATURES, and the agent must be installed and running inside the VM. See Enabling QEMU Guest Agent for more information.
• The VM must be in the RUNNING state.

With OpenNebula, run commands inside a Virtual Machine. Commands are sent to the VM through the QEMU Guest Agent, and results are stored in the VM template under QEMU_GA_EXEC. The following diagram depicts how commands are executed within a VM:

The VM_EXEC monitor probe collects the results and updates the QEMU_GA_EXEC block. To find more details on configuring the monitor probe, refer to Monitoring System.

Options

The QEMU_GA_EXEC section in the VM template contains the following fields:

Executing a command from Sunstone

The Exec tab in the Virtual Machine details view lets you execute commands inside a VM from Sunstone. Enter a command in the Command field and click Run. The tab displays the execution status, return code, when the command was executed, and its standard output and standard error. You can also copy the output, re-run the last command, or cancel a command that is still running.

The prerequisites and the restriction of one command at a time described above also apply when commands are executed from Sunstone. The user must have VM:MANAGE permission for the Virtual Machine.

To enable the tab, add the following block under info-tabs in the vm-tab.yaml file of the corresponding Sunstone view:

info-tabs:
  # Other information tabs

  exec:
    enabled: true
    actions:
      exec: true
      exec-retry: true
      exec-cancel: true

The standard view configuration files are:

• /etc/one/fireedge/sunstone/views/admin/vm-tab.yaml
• /etc/one/fireedge/sunstone/views/cloud/vm-tab.yaml
• /etc/one/fireedge/sunstone/views/groupadmin/vm-tab.yaml
• /etc/one/fireedge/sunstone/views/user/vm-tab.yaml

The enabled attribute controls whether the Exec tab is displayed. The actions can be configured independently: exec displays the command form and Run button, exec-retry displays the Re-run button, and exec-cancel displays the Cancel button while a command is running. An omitted action behaves as if it were set to false.

After modifying the view configuration, reload Sunstone in the browser to fetch the updated view.

Executing a command from the CLI

To execute a command inside a VM, use the onevm exec command. For example, to list files in the home directory of VM 0:

onevm exec 0 'ls -l'

Check the status of the command with:

onevm show 0

When still executing:

VIRTUAL MACHINE TEMPLATE
...
QEMU_GA_EXEC=[
  COMMAND="ls -l",
  STDIN="",
  STATUS="EXECUTING" ]

After the execution is complete, details are updated:

VIRTUAL MACHINE TEMPLATE
...
QEMU_GA_EXEC=[
  COMMAND="ls -l",
  STDIN="",
  PID="3864",
  RETURN_CODE="0",
  STATUS="DONE",
  STDERR="",
  STDOUT="dG90Y..." ]

To retry the execution of the last command executed, use onevm exec-retry:

onevm exec-retry 0

To cancel the command being executed, use onevm exec-cancel:

onevm exec-cancel 0

Virtual Machine States

The life-cycle of a Virtual Machine within OpenNebula includes the following stages:

Virtual Machine Datastore Migration

Datastore Migration allows the transfer of a VM’s disk images and associated files from one system datastore to another. This is a critical operation for storage maintenance, balancing disk I/O load across different storage tiers, or evacuating hardware for decommissioning.

Depending on the state of the VM and the underlying storage drivers, OpenNebula supports two primary methods:

• Cold Storage Migration: Performed when the VM is in a POWEROFF or UNDEPLOYED state. The disks are moved physically between datastores before the VM is resumed.

• Live Storage Migration: Performed while the VM is RUNNING. OpenNebula coordinates with the hypervisor to mirror disk writes to the new destination in real-time, ensuring zero downtime for the workload.

Basic Syntax

You can migrate a VM’s disks to a different datastore by specifying the target datastore ID when running onevm migrate:

onevm migrate [--live] <VM_ID> <TARGET_HOST_ID> <TARGET_DATASTORE_ID>

If the target Host is the same as the current one, only the datastore changes. If you also change the Host, both the Host and the datastore are migrated simultaneously, although changing both is only supported for offline migrations.

Cold and live migrations cannot be performed between different TM_MAD drivers (for example, from ceph to lvm).

Cold Storage Migration

Cold migration is the simplest form of datastore migration. The VM is automatically stopped by OpenNebula before migrating it, saving its running state across the process. OpenNebula copies the disk files from the source datastore to the destination datastore using the Transfer Manager.

onevm migrate <VM_ID> <HOST_ID> <TARGET_DATASTORE_ID>

You can also use --poff or --poff-hard to power off the VM during migration:

onevm migrate <VM_ID> <HOST_ID> <TARGET_DATASTORE_ID> --poff

As the VM is powered off before any disk operations take place, libvirt is not involved in the actual data transfer. The Transfer Manager handles all file-level operations (copying disk images, updating symlinks, etc.) through the TM_MAD scripts. Once the disk files are in place on the destination datastore, the VM is simply resumed and its disk device paths point to the new location.

Live Storage Migration

Live storage migration allows the VM disks to be migrated while the VM remains in the RUNNING state. OpenNebula coordinates with the hypervisor (KVM) to mirror disk writes to the new destination in real-time.

onevm migrate --live <VM_ID> <HOST_ID> <TARGET_DATASTORE_ID>

At the libvirt level, live datastore migration uses the virsh blockcopy command on the same Host. Read-only disks (such as CD-ROM or read-only qcow2 images) are copied by OpenNebula, after which libvirt’s change-media command is used to update their paths.

There are some limitations to keep in mind when performing live datastore migration:

• You cannot change both the Host and the datastore simultaneously. For that case, you need to perform each of those operations in order.
• Disk snapshots are only preserved with qcow2-based drivers (qcow2, ssh, local); they are lost with other drivers (LVM, raw disks, shared NFS).

Virtual Machine Charters

This functionality automatically adds scheduling actions in VM templates. To enable the creation of Charters in Sunstone, you only need to add the following to the vm-tab.yaml file in the corresponding Sunstone view:

info-tabs:
  sched_actions:
    enabled: true
    actions:
      charter_create: true

After enabling the creation of Charters, you have to define the schedule actions that have a Charter. To do that, you only need to modify the file sunstone-server.conf in the FireEdge configuration.

To explain this, we’ll use an example:

leases:
  terminate:
    edit: false
    execute_after_weeks: 3
  poweroff:
    edit: true
    execute_after_minutes: 5

The previous example will create two schedule actions:

• The Virtual Machine will be terminated 3 weeks after it was instantiated and you cannot edit this action before creating it.
• The Virtual Machine will be powered off after 5 minutes after it was instantiated and you can edit the action before creating it.

So, when the user clicks on the Charter button, the following info will appear:

The first action cannot be edited but in the second one, you can change the action and the time. Also, you can tune the definition of a Charter:

This functionality is also available in the CLI through the following commands:

• onevm create-chart
• onevm sched-update
• onevm sched-delete

The Charters can be added into the onevm configuration file /etc/one/cli/onevm.yaml:

:charters:
  :suspend:
    :time: "+1209600"
    :warning:
        :time: "+1123200"
  :terminate:
    :time: "+1209600"
    :warning:
        :time: "+1123200"

The information about the Charters can be checked with the command onevm show, the * in front of the ID indicates that the warning time passed:

SCHEDULED ACTIONS
ID     ACTION     ARGS    SCHEDULED        REPEAT            END  STATUS
*0  suspend          -  01/01 03:00                               Next in 1.25 hours
 1  terminate        -  15/01 03:00                               Next in 14 days

User-defined Data

Custom attributes can be added to a VM to store metadata related to this specific VM instance. To add custom attributes simply use the onevm update command:

onevm show 0
...

VIRTUAL MACHINE TEMPLATE
...
VMID="0"

onevm update 0
ROOT_GENERATED_PASSWORD="1234"
~
~

onevm show 0
...

VIRTUAL MACHINE TEMPLATE
...
VMID="0"

USER TEMPLATE
ROOT_GENERATED_PASSWORD="1234"

Virtual Machine VM Permissions

OpenNebula comes with an advanced ACL rules permission mechanism intended for administrators, but each VM object has also implicit permissions that can be managed by the VM owner. To share a VM instance with other users or to allow them to list and show its information, use the onevm chmod command:

onevm show 0
...
PERMISSIONS
OWNER          : um-
GROUP          : ---
OTHER          : ---

onevm chmod 0 640

onevm show 0
...
PERMISSIONS
OWNER          : um-
GROUP          : u--
OTHER          : ---

Administrators can also change the VM’s group and owner with the chgrp and chown commands.

Advanced Operations for Administrators

There are some onevm commands operations meant for cloud administrators:

Scheduling:

• resched: Sets the reschedule flag for the VM. The Scheduler will migrate (or live-migrate, depending on the Scheduler configuration) the VM in the next monitorization cycle to a Host that better matches the requirements and rank restrictions. Read more in the Scheduler documentation.

• unresched: Clears the reschedule flag for the VM, canceling the rescheduling operation.

Deployment:

• deploy: Starts an existing VM in a specific Host.
• migrate --live: The Virtual Machine is transferred between Hosts with no noticeable downtime. The VM storage cannot be migrated to other system datastores.
• migrate: The VM is stopped and resumed in the target Host. In an infrastructure with multiple system datastores, VM storage can also be migrated (by specifying the datastore ID).

Note: By default, the above operations do not check the target Host capacity. You can use the --enforce option to be sure that the Host capacity is not overcommitted.

Troubleshooting:

• recover: If the VM is stuck in any other state (or the boot operation does not work), you can recover the VM with the following options. Read the Virtual Machine Failures guide for more information.
  • --success: simulates the success of the missing driver action
  • --failure: simulates the failure of the missing driver action
  • --retry: tries to perform the current driver action again. Optionally the --interactive can be combined if it’s a Transfer Manager problem
  • --delete: Deletes the VM, moving it to the DONE state immediately
  • --recreate: Deletes the VM and moves it to the PENDING state
• migrate or resched: A VM in the UNKNOWN state can be booted in a different Host manually (migrate) or automatically by the scheduler (resched). This action must be performed only if the storage is shared, or manually transferred by the administrator. OpenNebula will not perform any action on the storage for this migration.

Accessing VM Console and Desktop

Sunstone provides several different methods to access your VM console and desktop: VNC, RDP, and SSH. If configured in the VM, these methods can be used to access the VM console through Sunstone. This section shows how these different technologies can be configured and what each requirement is.

FireEdge automatically installs dependencies for Guacamole connections which are necessary to use VNC, RDP, and SSH.

Configuring Your VM for VNC

VNC is a graphical console with wide support among many hypervisors and clients.

To enable the VNC console service you must have a GRAPHICS section in the VM template, as stated in the documentation. Make sure the attribute IP is set correctly (0.0.0.0 to allow connections from everywhere), otherwise no connections will be allowed from the outside.

For example, to configure this in the Virtual Machine template:

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

Your browser must support websockets, and have them enabled.

To configure it via Sunstone, you need to update the VM template. In the second step, Advanced options, under the Input/Output tab, you can see the graphics section where you can add the IP, the port, a connection password, or define your keymap.

Configure VM for RDP

Short for Remote Desktop Protocol, it allows one computer to connect to another computer over a network in order to use it remotely.

To enable RDP connections to the VM, you must have one NIC with RDP attribute equal to YES in the template.

Via Sunstone, you need to enable an RDP connection on one of the VM template networks, after or before its instantiation. Update the template and select Attach NIC in the Network tab and activate RDP:

To configure this in the Virtual Machine template in advanced mode:

NIC=[
    ...
    RDP = "YES"
]

Once the VM is instantiated, users will be able to connect via browser. Click on the ellipsis icon, Console -> RDP:

RDP connection permits users to choose the screen resolution from Sunstone interface.

If the VM template has a PASSWORD and USERNAME set in the contextualization section, this will be reflected in the RDP connection. You can read about them in the Virtual Machine Definition File reference section.

netsh advfirewall firewall set rule group="Remotedesktop" new enable=yes

Configure VM for SSH

Unlike VNC or RDP, SSH is a text protocol. SSH connections require a hostname or IP address to define the destination machine. As with the RDP connections, you need to enable the SSH connection on one of the VM template networks.

For example, to configure this in the Virtual Machine template in advanced mode:

NIC=[
    ...
    SSH = "YES"
]

SSH is standardized to use port 22 and this will be the proper value in most cases. You only need to specify the SSH port in the contextualization section as SSH_PORT if you are not using the standard port.

For example, to allow connection by username and password to a guest VM, first make sure you have SSH root access to the VM, check more info here.

After that you can access the VM and configure the SSH service:

oneadmin@frontend:~$ ssh root@<guest-vm>

# Allow authentication with password: PasswordAuthentication yes
root@<guest-VM>:~$ vi /etc/ssh/sshd_config

# Restart SSH service
root@<guest-VM>:~$ service sshd restart

# Add user: username/password
root@<guest-VM>:~$ adduser <username>

This will open the SSH console in another tab:

The onevm command

The onevm command manages OpenNebula Virtual Machines. The general structure of the command is as follows:

onevmcommand[args] [options]

Back to The onevm Command

Back to The onevm Command

Back to The onevm Command