Convert the appliance disk out of the OVA, define a libvirt domain with BIOS firmware and the right sizing, and reach the dashboard.

Run a CID222 appliance on a plain QEMU/KVM host managed by libvirt. libvirt has no OVA importer, so you extract the disk from the .ova, convert it, and define a domain around it.

Warning

This procedure is written from the libvirt and QEMU documentation. It has not been reproduced end to end in our lab. What is verified is the part that matters most: every shipped appliance disk is boot-tested under QEMU on virtio, SATA AHCI, LSI SCSI and VMware pvscsi controllers before the image is released, and all four must reach userspace.

What do I need?

Licence: Any
Role: admin_user

Prerequisites

You have the appliance .ova file and the .sha256 file supplied next to it.
The host runs libvirt with KVM, and you can define domains — either as root or as a member of the libvirt group.
The host has at least 32 GB of RAM, 8 CPU cores and 100 GB free where the disk image will live.
The libvirt network or bridge you will attach the appliance to serves DHCP. The default NAT network does.
You have read Requirements and sizing and Network prerequisites.

Convert the disk and define the domain

Verify the download

Check the .ova against the .sha256 file supplied with it.

sha256sum -c cid222-appliance-v<version>.ova.sha256

The command prints OK. A mismatch means a corrupted download — fetch it again rather than converting it.

Extract the disk

Unpack the archive.

mkdir -p /var/tmp/cid-ova && tar -xf cid222-appliance-v<version>.ova -C /var/tmp/cid-ova
ls /var/tmp/cid-ova

The directory holds one .ovf descriptor, one .mf manifest and one .vmdk disk.

Convert the disk

Convert the stream-optimised disk into a format libvirt runs well.

qemu-img convert -p -O qcow2 /var/tmp/cid-ova/*.vmdk /var/lib/libvirt/images/cid222-appliance.qcow2

The command prints its progress to 100 per cent. qemu-img info on the result reports the qcow2 format and the virtual size.

Define and start the domain

Create the domain around the converted disk, sized for your package.

virt-install \
  --name cid222-appliance \
  --memory 65536 --vcpus 16 \
  --boot bios \
  --disk path=/var/lib/libvirt/images/cid222-appliance.qcow2,bus=virtio,format=qcow2 \
  --network network=default,model=virtio \
  --osinfo ubuntu24.04 \
  --graphics none --console pty,target_type=serial \
  --import

The domain is defined and started, and the command attaches to its serial console. --boot bios is not optional: the appliance image is built and verified for BIOS firmware and does not boot under UEFI.

Watch the first boot

Leave the console attached until the guest reaches a login prompt.

First boot takes a few minutes while the services and the database initialise. Detach from the console with Ctrl+].

Find the appliance's address

Ask libvirt for the guest's address.

virsh domifaddr cid222-appliance

The command lists one interface with an IPv4 address. An empty result means the guest has not finished booting, or the network served no DHCP.

Open the dashboard

Browse to http://<appliance-ip>/.

The appliance redirects to the first-boot setup wizard, because it has no administrator yet.

Verify

virsh dominfo cid222-appliance reports the memory and virtual CPU count you set, and the domain state as running.
virsh dumpxml cid222-appliance contains no loader element referencing an EFI firmware image.
http://<appliance-ip>/ loads and lands on the setup wizard rather than a login form.
From a machine that can reach the guest, curl -sS -o /dev/null -w '%{http_code}\n' http://<appliance-ip>/ returns 200.

If it fails

The guest hangs before the login prompt, or drops to a firmware shell → the domain was defined with UEFI firmware. Redefine it with --boot bios.
The guest panics with a message about being unable to mount the root filesystem → the disk was attached on a bus the guest has no driver for. Use bus=virtio or bus=sata, both of which the image is boot-tested on.
virsh domifaddr stays empty after the guest reaches a login prompt → the network served no DHCP. Attach the domain to the default NAT network, or install from the ISO using its manual-network boot entry — see Install from the ISO.
The page will not load and the console shows containers still starting → give it a few more minutes; a brief 502 during first boot is expected.

Note

Running a secure web gateway as a second virtual machine on the same libvirt host defeats source-address controls on the appliance's inspection listener: the host's own network address translation rewrites every guest's source address to the container bridge, so all peers arrive as one address. Give a gateway a physical network, or accept that the allowlist cannot distinguish peers in that lab.

Next steps

First boot and the setup wizard — create the administrator and choose the deployment mode.
Licensing and activation — swap the built-in trial for your package.
Naming, DNS and TLS — give the appliance names and a trusted certificate before you connect clients.

Install on KVM and libvirt