pixop-net

Read-only Linux networking diagnostics for multipath SRT on the Pixop LIVE appliance (Amazon Linux 2023 guest). The tool inspects host interfaces, routing tables, reverse-path filtering, and—when you pass a relay args template—parses bonded SRT legs from TSDuck relay configuration. It does not change interfaces, routes, firewall rules, or TSDuck state.

Version note: pixop-net and multipath relay diagnostics appear only on relay-capable recipes. Confirm the binary exists (command -v pixop-net) before relying on these workflows.

Usage

pixop-net multipath inspect [--json] [--relay-args PATH] [--role ingest|egress]
                            [--iface NAME[:IP]] ...

pixop-net multipath verify  [--json] [--relay-args PATH] [--role ingest|egress]
                            [--iface NAME[:IP]] ...
                            [--peer INDEX:PEER_IP] ...

Option	Applies to	Description
`--json`	`inspect`, `verify`	Machine-readable report on stdout
`--relay-args PATH`	both	Relay `.ingest.args` or `.egress.args` template (for example `/etc/pixop-live/tsduck/main.ingest.args`)
`--role ingest\|egress`	both	Which transport direction to read from the args file (default: `ingest`)
`--iface NAME[:IP]`	both	Focus on a specific interface and optional IPv4 (repeatable). `NAME=IP` is also accepted
`--peer INDEX:PEER_IP`	`verify` only	Remote peer IP for per-leg route verification (repeatable)

There are no multipath apply, prepare, rollback, status, or live routing mutation subcommands—only inspect and verify.

What changes / what never changes

Changes	Never changes
Nothing (read-only)	Network config, `ip rule`, `rp_filter`, relay args, systemd units

Preconditions and scope

Environment	Notes
AWS Marketplace / EC2	Run on the appliance guest (AL2023). Uses host `ip` data and optional relay args under `/etc/pixop-live/tsduck/`.
KVM	Same guest OS inside the VM after `pixop-install start`; not run on the Ubuntu host.
Multipath relay	Meaningful `members` and bind checks require `--relay-args` pointing at a relay backend template. For native SRT use tsduckctl `check` / `credentials` plus `.env` config; when `tsduck-transport-info` is installed, `tsduckctl transport` adds introspection of either native or relay effective backend.

Privilege: Normally run without sudo. If --relay-args points at a file your user cannot read (typical for relay templates owned by root), the wrapper re-executes itself via sudo for that invocation only. Set PIXOP_NET_NOSUDO=1 to disable auto-elevation (you must then run with sufficient permissions yourself).

Typical workflows

Baseline host snapshot (no relay file):

pixop-net multipath inspect

Lists IPv4 addresses per interface, main and policy routing tables, rp_filter values, and warnings when strict reverse-path filtering may break multipath return paths.

Parse ingest legs from the main relay template:

pixop-net multipath inspect \
  --relay-args /etc/pixop-live/tsduck/main.ingest.args \
  --role ingest

Verify listener bind IPs exist on the host:

pixop-net multipath verify \
  --relay-args /etc/pixop-live/tsduck/main.ingest.args \
  --role ingest

Without --peer, verify still checks that configured listener addresses are present on local interfaces. Peer-specific ip route get checks are unverified until you supply --peer.

Verify return routing for a bonded caller leg (example peer on leg 0):

pixop-net multipath verify \
  --relay-args /etc/pixop-live/tsduck/main.ingest.args \
  --role ingest \
  --peer 0:203.0.113.50

Repeat --peer for each leg index that should be checked. If exactly one --peer is given and a member has srcip, that peer may be applied to that member.

JSON for automation:

pixop-net multipath verify --json \
  --relay-args /etc/pixop-live/tsduck/main.ingest.args \
  --role ingest | jq .

Output interpretation

Human output ends with a Result line on verify:

Result	Meaning
`OK`	No errors in the report; routing checks passed or were not required
`OK (interface inspection only; no peer routes verified)`	No `--relay-args` or no peer-specific verification performed
`OK (address checks passed; N route check(s) unverified)`	Bind/address checks passed; some legs lacked peer context
`NOT OK`	Errors present (missing bind IP, failed route check, bad `--iface`, and similar)

inspect prints WARNING: / ERROR: lines but does not print a final Result line. Exit code 1 if errors is non-empty; 0 otherwise.

verify exit code 0 when ok is true; 1 when not. Parse failures and I/O errors print pixop-net: … on stderr and exit 2.

JSON reports include interfaces, members (from relay args when supplied), route_checks with status of verified, unverified, or failed, peer_routing_status, and warnings (for example strict rp_filter on interfaces used for multipath).

Security and logs

Read-only; does not print SRT passphrases (parsing is done in shared transport libraries that mask secrets).
Safe to attach JSON output to support cases after review; it still contains listener IPs, ports, and interface names.
Do not treat a green verify as proof that an external encoder can connect—only that local addressing and optional route lookups match expectations.

Common errors

Symptom	Likely cause
`pixop-net: …` exit 2	Bad args file path, unreadable file without sudo, or invalid relay template
`interface eth1 not found`	Wrong `--iface` name on this instance type
`listener bind IP X is not configured on this host`	Relay template binds to an address not assigned locally (common misconfiguration on multi-NIC hosts)
`CHECK failed: …`	Kernel routing does not send traffic to the peer via the expected device for a `srcip` leg
Command not found	Native-only or older recipe without this binary

tsduck-transport-info — relay/native transport introspection and UDP bind status
tsduckctl — start/stop instances and operator connection sheet
pixop-flow — UDP bitrate at pipeline tap points
Connect your first SRT stream