Skip to content

F OpenNebula/one#7299: Add new API calls to execute commands on a Virtual Machine #436

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rsmontero merged 6 commits into from
Dec 15, 2025
Merged

F OpenNebula/one#7299: Add new API calls to execute commands on a Virtual Machine #436

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
72e0c40
F OpenNebula/one#7299: add release notes to master
MarioRobres Nov 26, 2025
6c6496a
F OpenNebula/one#7299: add missing requirement
MarioRobres Dec 1, 2025
84f8b2a
M #-:: remove last requirement
MarioRobres Dec 3, 2025
a2c6680
Apply suggestions from code review
MarioRobres Dec 15, 2025
338cc00
M #-: fix format and remove suggested lines
MarioRobres Dec 15, 2025
db0c423
Merge branch 'master' into f-7299-master
rsmontero Dec 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added assets/images/vm_exec_architecture.png
View file
Open in desktop
Copy link
Contributor

@prisorue prisorue Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll open a request to have this image adjusted to OpenNebula's look and feel.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
5 changes: 5 additions & 0 deletions ...nt/product/cloud_system_administration/resource_monitoring/monitoring_system.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ For a quick view of any changes in configuration file options in maintenance rel
| `SYSTEM_HOST` | Time in seconds to send Host static/configuration information | |
| `MONITOR_HOST` | Time in seconds to send Host variable information | |
| `STATE_VM` | Time in seconds to send VM status (ie. running, error, stopped…) | |
| `EXEC_VM` | Time in seconds to send VM command execution result | |
| `MONITOR_VM` | Time in seconds to send VM resource usage metrics | |
| `SYNC_STATE_VM` | Send a complete VM report if probes stopped more than `SYNC_STATE_VM` seconds | |

Expand Down Expand Up @@ -273,6 +274,9 @@ Probes are structured in different directories that determine the frequency in w
| |-- monitor_ds_vm.rb
| |-- ...
|
|-- execution
| |-- exec.rb
|
`-- status
`-- state.rb
```
Expand All @@ -286,6 +290,7 @@ The purpose of each directory is described in the following table:
| `host/system` | General quasi-static info. about Host (e.g. NUMA nodes) stored in `HOST/TEMPLATE` and `HOST/SHARE` | `SYSTEM_HOST` (600s) |
| `vm/monitor` | Monitor information (variable) (e.g. used cpu, network usage) stored in `VM/MONITORING` | `MONITOR_VM` (30s) |
| `vm/state` | State change notification, only send when a change is detected | `STATE_VM` (30s) |
| `vm/execution` | Retrieve results from the command executed inside the VMs | `EXEC_VM` (5s) |

If you need to add custom metrics, the procedure is:

Expand Down
40 changes: 40 additions & 0 deletions content/product/integration_references/system_interfaces/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,9 @@ Commands with marked with \* are asynchronous. The success response for these co
| pci-attach | one.vm.attachpci | VM:MANAGE |
| pci-detach | one.vm.detachpci | VM:MANAGE |
| restore | one.vm.restore | VM:MANAGE |
| exec | one.vm.exec | VM:MANAGE |
| exec-retry | one.vm.retryexec | VM:MANAGE |
| exec-cancel | one.vm.cancelexec | VM:MANAGE |

{{< alert title="Note" color="success" >}}
The **deploy** action requires the user issuing the command to have VM:ADMIN rights. This user will usually be the scheduler with the oneadmin credentials.
Expand Down Expand Up @@ -1384,6 +1387,43 @@ For example:
| OUT | Int/String | The VM ID / The error string. |
| OUT | Int | Error code. |

### one.vm.exec

- **Description**: Executes a command inside a Virtual Machine. The VM needs to be in RUNNING state.
- **Parameters**

| Type | Data Type | Description |
|--------|-------------|----------------------------------------------------|
| IN | Int | The VM ID. |
| IN | String | The command to be run inside the VM. |
| OUT | Boolean | `true` or `false` whenever it is successful or not |
| OUT | Int/String | The VM ID / The error string. |
| OUT | Int | Error code. |

### one.vm.retryexec

- **Description**: Attempts to run the last command executed inside a Virtual Machine. The VM needs to be in RUNNING state.
- **Parameters**

| Type | Data Type | Description |
|--------|-------------|-------------------------------------------------|
| IN | Int | The VM ID. |
| OUT | Boolean | `true` or `false` whenever is successful or not |
| OUT | Int/String | The VM ID / The error string. |
| OUT | Int | Error code. |

### one.vm.cancelexec

- **Description**: Cancels the execution of last command inside a Virtual Machine. The VM needs to be in RUNNING state.
- **Parameters**

| Type | Data Type | Description |
|--------|-------------|-------------------------------------------------|
| IN | Int | The VM ID. |
| OUT | Boolean | `true` or `false` whenever is successful or not |
| OUT | Int/String | The VM ID / The error string. |
| OUT | Int | Error code. |

### one.vmpool.info

{{< alert title="Note" color="success" >}}
Expand Down
78 changes: 77 additions & 1 deletion content/product/virtual_machines_operation/virtual_machines/vm_instances.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -757,6 +757,82 @@ In this example, the first argument would be the disk and the second the snapsho
{{< alert title="Note" color="success" >}}
The arguments are mandatory. If you use the CLI or Sunstone they are generated automatically for the actions.{{< /alert >}}

## Command Execution Inside the Virtual Machine
Prerequisites:
* Running commands within a VM rely on the QEMU Guest Agent, which must be installed and running on the VM.
* 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:

![Architecture Outlining How Command Execution Operates Within the VM](/images/vm_exec_architecture.png)

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](../../../product/cloud_system_administration/resource_monitoring/monitoring_system.md).

{{< alert title="Warning" color="warning" >}}
Run only one command at a time for every Virtual Machine. If a current command is still in `EXECUTING` status, even if finished but not yet updated by the monitor probe, new commands will not be executed until the current one is fully completed.{{< /alert >}}

### Options
The `QEMU_GA_EXEC` section in the VM template contains the following fields:

| Field | Description |
|---------------|-----------------------------------------------------------------|
| `COMMAND` | The command to be executed in the VM. |
| `STDIN` | Stdin data to pass to the command executed on the VM |
| `PID` | (Hypervisor-side) PID handling the exec request. |
| `RETURN_CODE` | Numeric exit code produced by the command (e.g. `0` = success). |
| `STATUS` | Execution state: `EXECUTING`, `CANCELLED`, `DONE` or `ERROR`. |
| `STDOUT` | Command standard output (base64-encoded). |
| `STDERR` | Command standard error (base64-encoded). |


### 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:
```bash
$ onevm exec 0 'ls -l'
```

Check the status of the command with:
```bash
$ onevm show 0
```

When still executing:

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

After the execution is complete, details are updated:

```bash
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`:
```bash
$ onevm exec-retry 0
```

To cancel the command being executed, use `onevm exec-cancel`:
```bash
$ onevm exec-cancel 0
```

<a id="vm-life-cycle-and-states"></a>

## Virtual Machine States
Expand All @@ -775,7 +851,7 @@ Note that this is a simplified version. If you are a developer you may want to t
| `boot` | `Boot` | OpenNebula is waiting for the hypervisor to create the VM. |
| `runn` | `Running` | The VM is running (note that this stage includes the internal virtualized machine booting and shutting down phases). In this state, the virtualization driver will periodically monitor it. |
| `migr` | `Migrate` | The VM is migrating from one resource to another. This can be a life migration or cold migration (the VM is saved, powered off or powered off hard and VM files are transferred to the new resource). |
| `hotp` | `Hotplug` | A disk attach/detach, nic attach/detach, save as or resize operation is in process. |
| `hotp` | `Hotplug` | A disk attach/detach, nic attach/detach, save as, resize or exec operation is in process. |
| `snap` | `Snapshot` | A system snapshot is being taken. |
| `save` | `Save` | The system is saving the VM files after a migration, stop, or suspend operation. |
| `epil` | `Epilog` | In this phase the system cleans up the Host used to virtualize the VM, and additionally disk images to be saved are copied back to the system datastore. |
Expand Down
4 changes: 2 additions & 2 deletions content/software/release_information/release_notes_72/whats_new.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ We encourage you to review the [Known Issues]({{% relref "known_issues" %}}) and
## Monitoring
<!--keeping some examples-->
- [Resource Usage Forecast](../../../product/cloud_system_administration/resource_monitoring/forecast/): Introduces predictive analytics for Host and VM resource consumption, enabling proactive infrastructure management. By analyzing trends in CPU, memory, disk, and network usage, OpenNebula 7.0 supports improved capacity planning, optimized workload scheduling, and early detection of performance bottlenecks.
- [New monitor message `EXEC_VM`to retrieve the result of commands executed inside a Virtual Machine](../../../product/cloud_system_administration/resource_monitoring/monitoring_system.md)

## Scheduler
<!--keeping some examples-->
Expand Down Expand Up @@ -59,6 +60,7 @@ We encourage you to review the [Known Issues]({{% relref "known_issues" %}}) and
## API and CLI
<!--keeping some examples-->
- [The `onedb purge-history` command now removes history records only within the specified `–start`, `–end` range for the `–id`, instead of deleting all records](https://github.com/OpenNebula/one/issues/6699).
- [New API calls (`one.vm.exec`, `one.vm.retryexec` and `one.vm.cancelexec`) to execute commands on a Virtual Machine](../../../product/virtual_machines_operation/virtual_machines/vm_instances.md#execute-commands-inside-the-virtual-machine)
- The output of `onemarketapp list` list now contains 2 extra columns displaying **HYPERVISOR** and **ARCHITECTURE**.
- [Add automatic VM index for multiple persistent VM instantiation](../../../product/virtual_machines_operation/virtual_machines/vm_instances.md#instantiate-to-persistent)

Expand All @@ -68,10 +70,8 @@ We encourage you to review the [Known Issues]({{% relref "known_issues" %}}) and
- [Virtual Machine memory encryption](../../../product/virtual_machines_operation/virtual_machines/vm_templates#memory-encryption) allows VM workloads whose memory cannot be read by the hypervisor.

## LXC

- NIC Hotplugging, recontextualization and NIC PCI passthrough are now available [driver features](../../../product/operation_references/hypervisor_configuration/lxc_driver.md).


## OpenNebula Flow
<!--keeping some examples-->
- [Oneflow clients include content-type header to make them work with Sinatra 4.0.0](https://github.com/OpenNebula/one/issues/6508).
Expand Down