pixopctl

Operator wrapper for pixop-live.service only. It runs systemctl / journalctl with Pixop-specific semantics for restart and recover, and exposes a quick health probe against the local metrics HTTP endpoint.

Version note: On the appliance, run pixop-version and pixopctl (no args) to confirm commands exist. Guest operators do not type sudo; the script re-executes via its absolute path.

Usage

pixopctl {start|stop|restart|recover|status|enable|disable|logs|health}
pixopctl -h|--help

Command	Mutates runtime?	Action
`start`	Yes	`systemctl start pixop-live.service`
`stop`	Yes	`systemctl stop pixop-live.service`
`restart`	Yes	Pixop-only `systemctl restart` — primary SRT ingest stays up
`recover`	Yes	Ordered pipeline recovery (see below)
`status`	No	`systemctl --no-pager status pixop-live.service`
`enable` / `disable`	Boot policy	`systemctl enable` / `disable` on `pixop-live.service` only
`logs`	No	`journalctl -u pixop-live` (see Logs)
`health`	No	HTTP GET `http://127.0.0.1:${PIXOP_METRICS_PORT:-8080}/v1/metrics` (first lines only)

Refused command	Exit	Message
`pull`, `rollback`	2	Directs you to pixop-image-update

Unknown commands and invalid help usage exit 2. restart / recover return 1 if pixop-live.service is not active after restart, or if ingress recovery steps fail.

Service relationships

Component	Managed by pixopctl?	Typical companion
`pixop-live.service`	Yes	pixop-stack for full pipeline
`tsduck-in@main`, `tsduck-out@*`	No	tsduckctl
Container images	No	pixop-image-update
Automated wedged-pipeline recovery	No (invokes pixopctl)	`pixop-healthcheck` timer → `recover` when configured

Stopping only Pixop with pixopctl stop leaves TSDuck ingress/egress running; that is usually wrong for maintenance. Use pixop-stack stop for a full pipeline stop.

Restart vs recover

Both commands leave egress (tsduck-out@*) running. Only recover touches primary ingress.

Step	`restart`	`recover`
Stop `tsduck-in@main`	No	Yes (`tsduckctl stop main --type in`, errors ignored)
Restart `pixop-live.service`	Yes	Yes
Start `tsduck-in@main`	No	Yes + `tsduckctl check main --type in`
Wait for UDP SRT ingest bind	No	Implicit in `tsduckctl start` / `check`

recover is the conservative path used by pixop-healthcheck when automatic restart is enabled. Use it when Pixop is wedged but you want ingress torn down and brought back cleanly.

Stream outage during recover

Recover stops primary ingress before restarting Pixop. Active SRT senders see a disconnect until ingress restarts and re-binds (default UDP 5000). Egress on 5001 may keep running, but downstream may see stale or interrupted output while Pixop restarts. Plan recover during a maintenance window or accept a brief ingest gap.

Primary ingress instance name defaults to main (PIXOP_STACK_PRIMARY_IN override for tests only).

Health vs pixop-flow

Tool	What it measures	Restarts?
`pixopctl health`	Prometheus-style text from `/v1/metrics`	No
pixop-flow	UDP payload Mbps at five pipeline stages via `tcpdump`	No
`pixop-healthcheck`	JSON metrics + policy; may call `recover`	Only when policy says so

health does not prove end-to-end SRT connectivity or correct video PID; it only shows that the metrics HTTP server responds. For bitrate and backbone utilization, use pixop-flow.

Output configuration

Video output (resolution, chroma, bit depth, color signalling, bitrate, and other NVEnc settings) is controlled by /etc/pixop-live/nvencc.args, not by pixopctl itself.

# edit nvencc.args, then:
pixopctl restart

Use restart (not recover) after nvencc.args changes so ingest SRT stays connected.

Logs

Source	Command / path
Service lifecycle (systemd)	`pixopctl logs` or `journalctl -u pixop-live`
Application diagnostics	`/var/log/pixop-live/live.log` (TERMINAL-format stderr via systemd)

pixopctl logs defaults to journalctl -n 200 -f. Pass extra journalctl arguments after --, for example:

pixopctl logs -- -n 500 --since "1 hour ago"

Task-oriented examples

Goal	Command
Confirm Pixop unit state	`pixopctl status`
Bounce Pixop after config edit	`pixopctl restart`
Healthcheck-style recovery	`pixopctl recover`
Quick metrics sanity check	`pixopctl health`
Persist start on boot	`pixopctl enable` (does not start now)
Stop entire pipeline	`pixop-stack stop` (not pixopctl)

Not supported

pull / rollback — container updates use digest-pinned pixop-image-update.
TSDuck instances — use tsduckctl.
Host OS, NVIDIA driver, systemd unit changes — require a new tested AMI or QCOW2 appliance image.

LIVE_IMAGE_PREV in live.env may exist as an audit trail after image apply; pixopctl does not read it.

Troubleshooting

Symptom	Check
`recover` fails on ingress	`tsduckctl status main --type in`; `tsduckctl logs main`
`health` fails / empty	`pixopctl status`; port `PIXOP_METRICS_PORT` (default 8080)
Restart succeeds but bad video	`nvencc.args`, license, ingress PID — not pixopctl scope