Skip to content

Troubleshooting

Host system checks

KVM availability

Virtual machines require KVM support. Verify that the host CPU supports virtualisation and that KVM is accessible:

kvm-ok

If the command is not available, install it (cpu-checker on Ubuntu). Alternatively, check directly:

ls -la /dev/kvm

If /dev/kvm does not exist, enable virtualisation in the BIOS/UEFI of the host machine or check with the server provider.

Disk space

Each VM creates a QCOW2 disk image (default 20 GB). Check available space on the Onteon installation directory and the VM store:

df -h /var/lib/onteon

The store grows with every VM instance and snapshot. Use delete-disk to reclaim space from instances that are no longer needed.

QEMU installation

The microservice requires qemu-system-x86_64 and qemu-img. Verify they are installed:

which qemu-system-x86_64
which qemu-img

If either is missing, install the qemu-kvm package (Ubuntu) or the equivalent for your distribution.

Cluster checks

OCC and ONM services

Confirm that both cluster components are running:

systemctl status onteon-control-center.service
systemctl status onteon-node-manager.service

If a service is not running, consult the logs:

journalctl --unit onteon-control-center.service --no-pager --lines 50
journalctl --unit onteon-node-manager.service --no-pager --lines 50

CLI connectivity

Test that the CLI can reach the cluster:

onteon-cli occ get node-managers

If the command fails or returns an empty list:

  • verify that environment variables (OCLI_OCC_ADDRESSES, OCLI_OCC_PORT, etc.) are set correctly or unset to use defaults,
  • check the active configuration with onteon-cli config get,
  • confirm that the auth tokens match the initial values from the installation step.

Application list

List registered applications to confirm the VM templates are loaded:

onteon-cli onm get apps

Expected output includes entries for qemu-ubuntu, qemu-centos, qemu-gentoo and qemu (generic). If any are missing, re-run the installer.

VM instance checks

Instance state

List all instances and their states:

onteon-cli onm get instances

States:

  • CREATED --- instance exists but is not running (or was stopped),
  • STARTED --- instance is running.

Common issues

Port fallback

SPICE and port-forwarding ports are auto-allocated starting from 15900 and 12200 respectively. If a port cannot be opened, the microservice increments the port number until it finds a free one.

Ports that are used by the VM instance will be also logged to the /var/lib/onteon/onteon-node-manager/log/app/APP-NAME/APP-VERSION/APP-ID/INSTANCE-ID/start.log log file.

VM does not boot from ISO

The qemu (generic) microservice waits for an ISO to appear before booting. If no ISO is found, the VM will wait indefinitely.

  • confirm that download-image was run before starting the instance,
  • verify the download URL is reachable from the host.

SPICE connection refused

  • ensure the VM is running (STARTED state),
  • confirm the SPICE port is correct (see Port fallback),
  • verify that no firewall is blocking the port,
  • on the client machine, install virt-viewer (provides remote-viewer).

SSH connection refused

  • ensure the VM is running (STARTED state),
  • use the correct forwarded port --- default is 12200 but it may auto-increment,
  • check that the VM's SSH service is running (log in via SPICE first),
  • verify the port map with write-conf --vm-net-port-map.

Snapshot or delete-disk fails

These commands require exclusive access to the disk image. Stop the instance before running snapshot-disk or delete-disk. For live snapshots, the instance must be in the STARTED state.

Getting help

If the issue persists, collect the following information before contacting support:

  • output of onteon-cli config get,
  • output of onteon-cli occ get graph,
  • output of onteon-cli onm get instances,
  • relevant log files from /var/lib/onteon/onteon-node-manager/log/app/APP-NAME/APP-VERSION/APP-ID/INSTANCE-ID/start.log.