tsduck-transport-info

Advanced, read-only introspection of TSDuck transport configuration: relay *.args templates, per-instance env under /etc/pixop-live/tsduck/, and optional UDP socket bind status for SRT listeners. Intended for engineers diagnosing SRT bonding, listener addresses, and health-check classification—not for day-to-day operator commissioning (use tsduckctl credentials / transport / check first).

Version note: Present only on relay-capable appliances (command -v tsduck-transport-info). Absent on native-only SRT images. Interface and behavior may evolve; treat as diagnostic, not a stability contract.

Usage

tsduck-transport-info args PATH [--role ingest|egress] [--format json|shell]

tsduck-transport-info instance NAME [--env-dir DIR] [--format json|shell]

tsduck-transport-info bind-status NAME [--env-dir DIR]

Command	Arguments	Description
`args`	`PATH`	Parse a single relay args template file
`instance`	`NAME`	Resolve `NAME.env` + `NAME.{ingest\|egress}.args` (role from instance map)
`bind-status`	`NAME`	JSON only: compare configured SRT listener sockets to `ss` UDP rows

Flag	Default	Description
`--role ingest\|egress`	`ingest`	For `args` only: which `--input` / `--output` direction to treat as primary
`--format json\|shell`	`shell`	For `args` and `instance` (not `bind-status`)
`--env-dir DIR`	`/etc/pixop-live/tsduck`	Instance env and args directory

Known instance names match tsduckctl: main, egress-main, egress-aux1, egress-aux2. Unknown names exit with ERROR: unknown instance: … (code 2).

What changes / what never changes

Changes	Never changes
Nothing	Args templates, env files, running `tsduck@` units, SRT keys

Parsing uses shlex and urllib.parse only—no shell evaluation of operator strings.

Privacy and secrets

Literal placeholder @SRT_PASSPHRASE@ in templates stays literal in output.
Any real passphrase value in a URI or env is never emitted; JSON shows @SRT_PASSPHRASE@ when a passphrase is present.
pbkeylen and listener host/port/mode are shown. Do not paste full JSON into public tickets without redacting customer IPs if required by policy.
This tool does not print AWS tokens, Marketplace IDs, or Pulse JWTs.

Preconditions

Appliance guest (AL2023), relay or native backend as configured per instance.
bind-status is meaningful when health_check is srt-udp, srt-bonded-udp, or native-env and listeners are mode=listener with a concrete port. Other modes may report bind_check_applicable: false.

Workflows

Shell summary for main ingest relay file:

tsduck-transport-info instance main --format shell

Example keys (shell): backend, role, health_check, args_file, srt_bonded, group_type, srt_listener_N_*, srt_host, srt_port, srt_pbkeylen, warning_N.

JSON for scripting:

tsduck-transport-info instance egress-main --format json | jq .

Parse a standalone args file (egress role):

tsduck-transport-info args /etc/pixop-live/tsduck/egress-main.egress.args --role egress

Check whether listeners appear in the UDP socket table:

tsduck-transport-info bind-status main

Ad-hoc args path (for example a staged template):

tsduck-transport-info args /tmp/staging.ingest.args --role ingest --format json

Output interpretation

`shell` format

Line-oriented key=value pairs. Bonded groups set srt_bonded=1 and emit per-listener srt_listener_{index}_* fields. Warnings use warning_0, warning_1, …

`json` format (`args` / `instance`)

Structured TransportInfo: endpoints, srt_listeners, primary_srt_listener, health_check, bonded, group_type, warnings. Endpoint URIs in JSON omit the raw URI string; members carry masked passphrase when applicable.

`bind-status` JSON

Always pretty-printed JSON with sorted keys:

Field	Meaning
`health_check`	Classifier from parser (for example `srt-udp`, `srt-bonded-udp`, `native-env`)
`bind_check_applicable`	Whether UDP listener cross-check ran
`all_listening`	True only when applicable and every configured listener socket matches an `ss` row
`listeners[]`	`host`, `port`, `configured`, `listening`, `connection`, `state` per leg
`warnings`	Non-fatal parse or config notes

all_listening: false with listening: true on some legs may still be healthy if health check is not UDP-based for that backend—read bind_check_applicable first.

Diagnostics

Error	Cause
`ERROR: unknown instance`	Name not in instance map
`ERROR: invalid TRANSPORT_BACKEND`	Env file backend not `native` or `relay`
`ERROR: …` from `ValueError`	Missing env/args file, parse failure
Empty or misleading `bind-status`	Instance stopped, native caller-only egress, or non-listener SRT mode

Compare with:

tsduckctl status main
tsduckctl check main

pixop-net — multipath routing and rp_filter on the host
tsduckctl — operator lifecycle and credentials
pixop-probe-input — MPEG-TS analyze on the pre-Pixop tap
Monitoring and troubleshooting