pixop-preflight

Host diagnostic for the Pixop LIVE appliance. Walks OS, NVIDIA, Docker, digest-pinned images, configuration layout, groups, transport listeners, systemd wiring, healthcheck defaults, and optional Pulse/license posture. Prints PASS / WARN / FAIL lines and a summary count.

Availability: Verify this tool on your appliance with command -v pixop-preflight and pixop-version. Installed path when present: /opt/pixop/bin/pixop-preflight.

Purpose and scope

Use before commissioning, after host changes, or when support asks for a baseline. Preflight does not change appliance configuration, pull images, start or restart units, or run GPU inference tests. It does not invoke pixop-timing-probe. External AWS Security Group, NACL, and firewall rules are mentioned for operators but do not add WARN or FAIL.

Ephemeral probes (short-lived): to prove UID 1001 can write under /var/lib/pixop-live/parameters, the script briefly creates .pixop-uid1001-write-probe in that directory and removes it. When pixop-live is running, it may write container env names to a mktemp file under /tmp to check Pulse variable presence without printing values — that file is removed before exit. These probes are not configuration changes and do not survive the run.

Usage

pixop-preflight

No flags in the shipped script. If you are not root, the tool re-execs via sudo (absolute path) so checks can read protected paths and prove UID 1001 access.

Exit codes:

Code	Meaning
`0`	No `FAIL` lines (warnings allowed)
`1`	One or more `FAIL`

The shipped script has no flags; it exits 0 or 1 only.

What it checks (section map)

Section	Examples
Host	Amazon Linux 2023
NVIDIA	`nvidia-smi`, open kernel module, Dual MIT/GPL license
Docker	service active, `nvidia` runtime registered
Images	`LIVE_IMAGE` / `TSDUCK_IMAGE` digest-pinned and present locally; TSDuck fork plugins
Configuration	Required files under `/etc/pixop-live`, log paths, `logrotate`, sysctl `rmem_max`/`wmem_max`
Groups	`ec2-user` in `pixop` and `docker`; no legacy `ducker` group
License / Pulse	`license.jwt` readability for UID 1001; `pulse.env` permissions when present
Transport	SRT listeners on resolved ingest/egress ports (native or relay via `tsduck-transport-info`); multicast tap
Systemd	Unit files, instance-init marker vs `pixop-live` enablement, `pixop-healthcheck.timer`, `PIXOP_HEALTHCHECK_RESTART=1`
Journald	Persistent journal directory and drop-in
Runtime	`pixop-live-run` caps/mounts; optional running-container checks

After /var/lib/pixop-live/instance-init.complete exists, empty SRT passphrases are FAIL; before init, empty passphrases are WARN.

Operator workflows

Standard health pass (with stack checks):

pixop-preflight
pixop-stack status

Before opening a support case:

pixop-preflight | tee /tmp/preflight-$(date -u +%Y%m%d).txt

Redact any accidental paste of environment exports; preflight does not print passphrases or Pulse passwords.

Relay or custom transport debugging: If relay inspection fails, read the FAIL line for tsduck-transport-info — fix instance env or helper installation before retrying.

Interpreting common results

Outcome	Typical cause
`license.jwt absent` WARN	KVM pre-license or AWS instance before entitlement
Empty SRT passphrase WARN	First-boot `pixop-instance-init` not finished
UDP 5000/5001 not bound FAIL (after init)	Ingress/egress down or wrong transport mode
`pixop-healthcheck.timer` FAIL	Timer not enabled, not active, or `PIXOP_HEALTHCHECK_RESTART` is not `1` in `/etc/pixop-live/healthcheck.env`
NVIDIA driver not 610 branch WARN	Non-qualified driver (may still run)

Summary line format: Preflight complete: N PASS, M WARN, K FAIL.

Privacy and security

Passphrase checks report set/not set only.
Pulse check reports configured without values.
Running-container Pulse env names may be noted; values are not printed.

Limitations

Does not measure end-to-end SRT from the internet (only local ss and unit state).
Does not validate stream PIDs, latency, or enhanced output quality — use tsduckctl, pixop-flow, and pixop-timing-probe.
GPU workload test is intentionally skipped (pixop-test-live is separate).

Monitoring and troubleshooting
pixop-support-bundle — embeds a preflight capture
Connect your first SRT stream
Network and transport