KVM license and Pulse activation

KVM appliances use a customer-supplied license JWT at /etc/pixop-live/license.jwt instead of AWS Marketplace activation. Pulse Basic Auth for telemetry is provisioned separately into /etc/pixop-live/pulse.env. This guide covers install-time licensing, Pulse enrollment, credential apply, and renewal. Command details: pixop-kvm-pulse.

What you need

The QCOW2 image sets PIXOP_MARKETPLACE_MODE=off so first boot does not call AWS License Manager. Product entitlement is enforced when you activate against Pulse with pixop.allowed_deployments: ["kvm"].

Install with license (recommended)

From the extracted installer archive on the KVM host:

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

Then start the VM. On first boot, guest initialization runs pixop-kvm-pulse activate when license.jwt is present and Marketplace did not already provision Pulse.

If Pulse is unreachable at boot, init continues (deferred activation) and enables pixop-kvm-pulse-retry.timer: first run about 3 minutes after boot, then roughly every 10 minutes with up to 90 seconds randomized delay.

License after install (no automatic Pulse)

pixop-install license set only places or updates the JWT on the guest. It does not call Pulse. After a late install or renewal, run Pulse activation explicitly.

From the host (bridged production—VM running, SSH key matches install):

cd /path/to/extracted-installer
GUEST_IP="203.0.113.10"
sudo ./scripts/pixop-install license activate \
  --identity ~/.ssh/id_ed25519 \
  --guest-host "${GUEST_IP}"

This SSHs to the guest and runs sudo pixop-kvm-pulse activate --json. It prints non-secret fields such as deploymentId and restartRequired; it never prints JWT or Pulse passwords.

Inside the guest:

pixop-kvm-pulse activate
pixop-kvm-pulse status --json

Use license status on the host to confirm the JWT file hash—not KVM Pulse credential state (pixop-license is Marketplace-centric and does not replace pixop-kvm-pulse status).

Applying credentials to a running encoder

pixop-live reads pulse.env only when the container is created. After activation, check:

pixop-kvm-pulse status --json

When restartRequired is true, apply credentials during a maintenance window with Pixop-only restart (keeps TSDuck ingest up):

pixopctl restart

Do not use pixop-stack restart for credential apply—that disturbs TSDuck ingest. pixop-kvm-pulse and pixop-install license activate never restart pixop-live for you.

Encoder license_connectivity caveat

If the encoder parameter license_connectivity is required, the running pixop-live process must have valid Pulse credentials at container start. Deferred KVM activation (boot without Pulse, retry timer) does not bypass that runtime check—video may run under best_effort until credentials exist and you restart pixop-live when status says they are pending.

Expiration and renewal

1. Install the renewed JWT on the host: pixop-install license set … (overwrites in place; no VM restart when a license was already present).
2. Run pixop-install license activate or guest pixop-kvm-pulse activate / repair so Pulse re-authorizes and refreshes pulse.env.
3. If status reports restartRequired, run pixopctl restart in a planned window.

Local state.json may still list a deploymentId until the next Pulse call; server-side revocation or license replacement is revealed by the next activate / repair request, which may fail—contact Pixop support with pixop-kvm-pulse show-identity output (public key + appliance id only). JWT expiry on disk can be inspected with pixop-license decode; pixop-kvm-pulse status does not validate server revocation or JWT expiry.

Replacement and rebind

Hardware replacement or a lost appliance private key requires Pixop support rebind—provide pixop-kvm-pulse show-identity (never share appliance-key). Back up /var/lib/pixop-kvm-pulse/ with the VM before migration or clone; disk clones copy enrollment identity.

Security

• Do not paste license JWTs, pixop-license token output, or pulse.env contents into tickets.
• Pulse credentials are mode 0600 root:root; identity directory is 0700.
• Customers use only the public KVM activate API over HTTPS—not admin revoke or encryption configuration endpoints.

Related

• KVM quickstart
• KVM troubleshooting — license file vs Pulse issues
• pixop-install
• pixop-kvm-pulse