How to install an OpenNebula KVM node

An OpenNebula KVM node is a Linux hypervisor that runs virtual machines for a front-end host. Installing the node package prepares libvirt, QEMU, SSH access, and the oneadmin account so the scheduler can later place workloads on the host.

The package source is the OpenNebula 7.2 Community Edition repository for Ubuntu 24.04. Use the matching Enterprise repository when deploying Enterprise Edition, and keep the same major OpenNebula release on the front-end and every hypervisor node.

The front-end must already be installed, reachable by DNS or static hostnames, and able to SSH to the node. The node also needs hardware virtualization enabled in firmware, a bridge or equivalent networking layer prepared for VM traffic, and storage paths that match the datastore design used by the cluster.

Steps to install an OpenNebula KVM node on Ubuntu:

Open a terminal on the KVM node with sudo privileges.
Confirm that the CPU exposes virtualization support.
```
$ lscpu
Architecture:             x86_64
##### snipped #####
Virtualization:           VT-x
```
VT-x, AMD-V, or an enabled ARM virtualization extension must be present before KVM can run guest VMs with hardware acceleration.
Refresh package metadata.
```
$ sudo apt update
```

Install the repository helper packages.

$ sudo apt install --assume-yes ca-certificates gnupg wget apt-transport-https

Create the APT keyring directory.

$ sudo install -d -m 0755 /etc/apt/keyrings

Add the OpenNebula repository signing key.

$ wget -q -O- https://downloads.opennebula.io/repo/repo2.key | sudo gpg --dearmor --yes --output /etc/apt/keyrings/opennebula.gpg

Add the OpenNebula 7.2 repository for Ubuntu 24.04.

$ echo "deb [signed-by=/etc/apt/keyrings/opennebula.gpg] https://downloads.opennebula.io/repo/7.2/Ubuntu/24.04 stable opennebula" | sudo tee /etc/apt/sources.list.d/opennebula.list
deb [signed-by=/etc/apt/keyrings/opennebula.gpg] https://downloads.opennebula.io/repo/7.2/Ubuntu/24.04 stable opennebula

For Ubuntu 22.04, replace Ubuntu/24.04 with Ubuntu/22.04 in the repository URL before refreshing package metadata.

Refresh package metadata from the OpenNebula repository.

$ sudo apt update
Get:1 https://downloads.opennebula.io/repo/7.2/Ubuntu/24.04 stable Release [2554 B]
Get:2 https://downloads.opennebula.io/repo/7.2/Ubuntu/24.04 stable/opennebula amd64 Packages [5430 B]
Reading package lists... Done

Install the KVM node package.

$ sudo apt install --assume-yes opennebula-node-kvm
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following NEW packages will be installed:
  libvirt-daemon-system opennebula-node-kvm qemu-system-x86
##### snipped #####
Setting up libvirt-daemon-system (10.0.0-2ubuntu8.14) ...
Setting up opennebula-node-kvm (7.2.0-1) ...

The package installs the OpenNebula node integration, libvirt components, QEMU packages for the host architecture, and the oneadmin user membership needed for libvirt and KVM access.

Restart libvirtd so it loads the packaged OpenNebula configuration.
```
$ sudo systemctl restart libvirtd
```
Related: How to manage OpenNebula services with systemctl in Linux
Confirm that libvirtd is active.
```
$ sudo systemctl is-active libvirtd
active
```
If the unit is not active, inspect sudo journalctl -u libvirtd before registering the host.

Confirm that the node package and libvirt service package are installed.

$ dpkg-query -W opennebula-node-kvm libvirt-daemon-system
libvirt-daemon-system	10.0.0-2ubuntu8.14
opennebula-node-kvm	7.2.0-1

Check the oneadmin group membership on the node.

$ id oneadmin
uid=9869(oneadmin) gid=9869(oneadmin) groups=9869(oneadmin),108(kvm),110(libvirt)

Open a front-end terminal as oneadmin.
```
$ sudo -iu oneadmin
```
Add the front-end and node host keys to oneadmin known hosts.
```
$ ssh-keyscan frontend01.example.net node01.example.net >> /var/lib/one/.ssh/known_hosts
```
Regenerate and redistribute this file when a front-end or node host key changes. Controlled host-key management avoids silent trust of a rebuilt or replaced server.
Copy the oneadmin public key from the front-end to the KVM node.
```
$ ssh-copy-id -i /var/lib/one/.ssh/id_rsa.pub node01.example.net
Number of key(s) added: 1
```
Do not copy /var/lib/one/.ssh/id_rsa to the node unless the OpenNebula SSH authentication agent is intentionally disabled. The default agent forwards the private key for node-to-node and node-to-front-end operations.

Copy the known-hosts file to the KVM node.

$ scp -p /var/lib/one/.ssh/known_hosts node01.example.net:/var/lib/one/.ssh/

Confirm passwordless SSH from the front-end to the node.
```
$ ssh node01.example.net hostname -f
node01.example.net
```
Confirm SSH from the node back to the front-end.
```
$ ssh node01.example.net ssh frontend01.example.net hostname -f
frontend01.example.net
```
OpenNebula migration and image-transfer operations need SSH paths from the front-end to hosts, between hosts, and from hosts back to the front-end.
Verify the bridge that VM networks will reference.
```
$ ip link show type bridge
4: br0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 state UP mode DEFAULT group default qlen 1000
```
The bridge name can be different, but every host that belongs to the same virtual-network design should expose the matching bridge name.
Related: How to create an OpenNebula virtual network
Check the storage path used by local datastores or shared mounts.
```
$ df -h /var/lib/one
Filesystem      Size  Used Avail Use% Mounted on
/dev/vdb1       200G  8.1G  192G   5% /var/lib/one
```
For NFS, Ceph, LVM, or other shared datastore layouts, verify the storage driver and mount design before scheduling VMs on the node.
Related: How to create an OpenNebula datastore
Register the node from the front-end.
```
$ onehost create node01.example.net -i kvm -v kvm
ID: 1
```
Keep host registration details in the dedicated host workflow when adding several nodes or placing the host into a non-default cluster.
Related: How to add a host to OpenNebula
Confirm that the host reaches the ON state.
```
$ onehost list
  ID NAME                 CLUSTER   RVM      ALLOCATED_CPU      ALLOCATED_MEM STAT
   1 node01.example.net   default     0       0 / 1600 (0%)     0K / 125.8G (0%) on
```
If the host remains in INIT, wait for the next monitor cycle. If it changes to ERR, inspect /var/log/one/oned.log on the front-end and recheck passwordless SSH.