pixop-install

Install and manage a Pixop Prime KVM appliance on a customer Linux host (qualified on Ubuntu 24.04). The guest is the same Amazon Linux 2023 appliance used on AWS, booted under libvirt with GPU passthrough—not a separate product install.

This is a host-side tool in the delivered installer archive (scripts/pixop-install). It is not on the appliance PATH, does not self-elevate like guest CLIs, and requires sudo. AWS Marketplace operators use the AMI directly and do not run pixop-install.

Extract the archive on the KVM host, then run commands from the extract root (directory that contains scripts/):

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

General syntax: sudo ./scripts/pixop-install COMMAND [OPTIONS]

Invocation

pixop-install --help
pixop-install --version

pixop-install doctor

pixop-install install --image PATH --gpu BDF|all [install options]
pixop-install uninstall [--purge] [options]
pixop-install start|stop|restart|status
pixop-install autostart enable|disable|status
pixop-install license set FILE | license status

Command reference

install options (selected)

license options

Updating an existing license overwrites in place—no VM, pixop-live, or container restart by design.

Delivery artifacts and disk

Before install, verify both the installer archive and QCOW2 with sha256sum -c against each delivered .sha256 file from the directory that holds the artifact (deployment guide).

install converts the source QCOW2 into a managed image under /var/lib/pixop-kvm/images/ (not a byte-for-byte copy). The --image source is never modified or deleted. Check df -h / and df -h /var/lib before install: you need capacity beyond the installer archive extract and beyond the source QCOW2 size for conversion and guest growth. The installer’s space gate on / uses source file bytes plus a margin—it does not replace your own capacity review.

Host packages (Ubuntu 24.04)

When doctor reports missing packages, these six names must be present (or installed via --install-packages on install after approval on Ubuntu 24.04):

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

doctor never installs packages. With --install-packages, apt-get may run before the interactive install confirmation when packages are missing—use the flag only on Ubuntu 24.04 after change approval. install --dry-run does not apt-install or change libvirt.

IOMMU, bridges, and firmware are provisioned outside the installer.

What changes / what never changes

Typical workflows

Qualify host:

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

Production plan (bridged)—dry run:

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

Production install (same flags, omit --dry-run):

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

Userspace SLIRP (local test only—not with --bridge):

sudo ./scripts/pixop-install install \
  --image /path/to/pixop-prime-kvm.qcow2 \
  --gpu all \
  --ssh-key ~/.ssh/id_ed25519.pub \
  --ssh-host-port 2222 \
  --expose-pixop

Start and check:

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

License from host (bridged):

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

Autostart after acceptance:

sudo ./scripts/pixop-install autostart enable

Remove (keep disk):

sudo ./scripts/pixop-install uninstall

Output interpretation

• doctor: any FAIL should block install.
• install prints GPU plan and asks to type domain name unless --yes.
• status shows State, Autostart, forwarded services, and suggested ssh command.
• license status reports hashes—not the JWT body.

Security

• Generated SSH private keys live under /var/lib/pixop-kvm/ssh/ mode 0600.
• --forward / --expose-pixop listen on 127.0.0.1 only in userspace mode.
• License files are pushed over SSH with batch mode and StrictHostKeyChecking=accept-new.

Common errors

Exit code 2 for unknown commands; doctor returns 1 when any check FAILs.

Guest CLI after install

Inside the VM, use appliance tools (pixopctl, tsduckctl, pixop-test-live, etc.). Capability follows the QCOW2 build—see pixop-version on the guest.

Related

• KVM quickstart
• KVM deployment guide
• pixop-license — guest-side license commands
• pixop-decode-jwt — raw JWT claim inspection (guest)
• Configuration