KVM deployment guide

Production steps for running the Pixop Prime appliance as a KVM guest. The guest is Amazon Linux 2023 with the same stack as AWS; the KVM host is commonly Ubuntu 24.04 LTS. Pixop supplies a QCOW2 and a host installer archive—you do not build the appliance.

Short path: KVM quickstart. Acceptance: KVM commissioning sheet.

AWS Marketplace and KVM appliance builds ship on independent schedules. Confirm capabilities with pixop-version on the guest and your delivery metadata—not by assuming parity with a Marketplace AMI.

Delivery package

Verify artifacts (before install)

Run each check from the directory that contains the file being verified. Filenames below are illustrative; use the names from your delivery.

Installer archive (example pixop-kvm-installer.tar.gz):

cd /path/to/delivery
sha256sum -c pixop-kvm-installer.tar.gz.sha256

QCOW2 image (example pixop-prime-kvm.qcow2):

cd /path/to/delivery
sha256sum -c pixop-prime-kvm.qcow2.sha256

If either command reports FAILED or No such file, stop and contact whoever supplied the artifacts. Do not install from a failed verification.

Extract the installer archive on the host so scripts/pixop-install exists at the extract root:

mkdir -p /path/to/extracted-installer
tar -xf /path/to/delivery/pixop-kvm-installer.tar.gz -C /path/to/extracted-installer
test -x /path/to/extracted-installer/scripts/pixop-install

All host commands below assume you are in the extract root:

cd /path/to/extracted-installer
sudo ./scripts/pixop-install <command> [options]

Guest commands run over SSH as ec2-user without extra sudo around /opt/pixop/bin tools.

Host prerequisites

You need hardware virtualization (vmx or svm), a discrete NVIDIA GPU for passthrough, IOMMU enabled in firmware and kernel, RAM and vCPUs for the guest, and—for production—an existing Linux bridge (for example br0) with LAN addressing planned. The installer does not create bridges, enable IOMMU, or modify GRUB/firmware.

Host packages (Ubuntu 24.04)

On Ubuntu 24.04, doctor expects these six apt packages (exact names):

qemu-system-x86, qemu-utils, libvirt-daemon-system, libvirt-clients, ovmf, xorriso

Install them with your standard change process, or add --install-packages to install only on Ubuntu 24.04 when doctor reports missing packages and you approve apt changes. The flag is meant for Ubuntu; on other distributions the installer still invokes apt-get when packages are missing and the flag is set—do not rely on it outside Ubuntu 24.04. If you use --install-packages, apt may run before you confirm the domain name at the install prompt. install --dry-run makes no host modifications (no apt, no libvirt changes).

doctor is read-only: PASS, WARN, FAIL. Treat any FAIL as a blocker.

Disk space for the managed image

install uses qemu-img convert to create a managed QCOW2 at /var/lib/pixop-kvm/images/<domain>.qcow2. The source file passed to --image is never modified or deleted. The converted file is not guaranteed to match the downloaded QCOW2 byte size—plan headroom for conversion, guest growth, and any snapshots you create outside this tool.

Before install, check both the root filesystem (used for an initial space gate) and the filesystem that will hold managed state:

df -h /
df -h /var/lib

The installer’s pre-install check compares free space on / to the source QCOW2 file size plus a small margin. That check is not sufficient proof that /var/lib/pixop-kvm has room for the converted image and later growth—treat your own df review as mandatory.

1. Verify the host

cd /path/to/extracted-installer
sudo ./scripts/pixop-install doctor

Resolve every FAIL before install.

2. Install with bridged networking (production)

Attach virtio-net to an existing bridge. SSH, HTTP :8080, and SRT UDP 5000 / 5001 use the guest LAN address.

Dry run (flags must match the real install except --dry-run):

cd /path/to/extracted-installer
sudo ./scripts/pixop-install install \
  --dry-run \
  --image /path/to/pixop-prime-kvm.qcow2 \
  --gpu all \
  --vcpus 8 \
  --memory 16G \
  --bridge br0 \
  --ssh-key ~/.ssh/id_ed25519.pub \
  --license /path/to/license.jwt

Confirm printed domain name, bridge, and GPU BDFs. The installer asks you to type the domain name before host changes; use --yes only after reviewing a dry run.

Install:

sudo ./scripts/pixop-install install \
  --image /path/to/pixop-prime-kvm.qcow2 \
  --gpu all \
  --vcpus 8 \
  --memory 16G \
  --bridge br0 \
  --ssh-key ~/.ssh/id_ed25519.pub \
  --license /path/to/license.jwt

Add --install-packages when doctor reported missing Ubuntu packages and your change window approves apt installs.

--gpu all selects every discrete NVIDIA GPU that passes VFIO checks (audio functions included). Use --gpu 0000:bb:dd.f for one GPU.

Defaults: domain pixop-prime, userspace SLIRP only if --bridge is omitted, autostart disabled, VM not started after install.

Passthrough impact: While the VM runs, selected GPUs use vfio-pci and are unavailable on the host.

SRT gateway layout

The appliance listens on UDP 5000 (ingest) and UDP 5001 (egress). Encoders and players use caller mode. Failover between gateways is outside the VM. Allow TCP 22 and TCP 8080 only on trusted networks. See Network and transport.

Userspace SLIRP (non-production)

For host-local testing only: omit --bridge, use --ssh-host-port and optionally --expose-pixop (127.0.0.1 forwards only). Never combine SLIRP forwards with --bridge. Details: KVM quickstart.

3. Start, license, and confirm GPUs

sudo ./scripts/pixop-install start
sudo ./scripts/pixop-install status

GUEST_IP="203.0.113.10"
ssh -i ~/.ssh/id_ed25519 "ec2-user@${GUEST_IP}"

License from the host:

sudo ./scripts/pixop-install license status \
  --identity ~/.ssh/id_ed25519 \
  --guest-host "${GUEST_IP}"

sudo ./scripts/pixop-install license set /path/to/license.jwt \
  --identity ~/.ssh/id_ed25519 \
  --guest-host "${GUEST_IP}"

On the guest:

pixop-version
nvidia-smi
pixop-preflight

4. First live SRT acceptance

Run continuous live ingest and egress for at least two minutes before production sign-off. Use Connect your first SRT stream and the KVM commissioning sheet. Accept processed output with a downstream decoder or media analyzer—not only SRT caller connectivity.

Output geometry, codec, frame rate, HDR/SDR signaling, and bitrate follow the installed guest build (pixop-version) and your configuration.

5. Autostart and lifecycle

Enable autostart only after acceptance passes:

sudo ./scripts/pixop-install autostart enable

autostart enable does not start a stopped VM. Optional planned host reboot validates boot persistence.

sudo ./scripts/pixop-install stop
sudo ./scripts/pixop-install restart

uninstall keeps the managed disk. uninstall --purge irreversibly deletes managed state under /var/lib/pixop-kvm. The customer source QCOW2 is never deleted.

Upgrade and change control

• New QCOW2 generation: new install or migration planned with support—no in-place guest OS upgrade.
• Container digest: pixop-image-update when Pixop publishes a reference for your line.
• Host installer: use the archive from your delivery; re-run doctor after host OS upgrades.

Document checksum verification, license renewal, bridge/IP, and failover tests.

Security

• Production SRT and the API belong on trusted networks by design.
• SLIRP forwards bind 127.0.0.1 only—not for WAN exposure.
• Keep license JWTs and SRT passphrases out of tickets.
• Operator SSH private keys are not copied into /var/lib/pixop-kvm by the installer.

Related guides

• KVM troubleshooting guide
• KVM commissioning sheet
• pixop-install
• CLI reference
• GPU requirements (FAQ)
• Monitoring and troubleshooting