Multipath and bonded SRT

Bonded SRT spreads one logical stream across multiple network paths (typically one NIC or listener per path). On Pixop Prime this is implemented only through the relay backend and srt-bond-relay inside the pinned TSDuck image. It is an advanced topic for relay-capable appliances—not native-only SRT templates.

Confirm before reading further:

pixop-version
command -v pixop-net          # must succeed on bonding-capable builds
command -v tsduck-transport-info
tsduckctl transport main      # only when the helper above is present

If TRANSPORT_BACKEND is native or helpers are missing, stop here and use single-path native SRT from Connect your first SRT stream.

When bonding is required (and when it is not)

Scenario	Typical approach
Single WAN link, one encoder, one appliance IP	Default one `srt://` listener on UDP 5000 — no bonding
Encoder presents two paths (dual NIC on appliance, distinct listener IPs)	Bonded group URI on one relay `--input` or `--output` line
Diverse uplinks with one active gateway at a time (failover by routing, not simultaneous paths)	Policy routing and a single SRT session may suffice — bonding is not mandatory
Redundant encoders as separate failover	Multiple `--input` lines = switch/failover, not bonding

Pixop does not implement automatic NIC bonding, hot failover, or routing configuration. You own Linux policy routes, default gateways per path, firewall rules, and encoder-side group membership.

Prerequisites

Relay backend on the affected instance (TRANSPORT_BACKEND=relay).
Addresses: Each bonded member binds a specific local IP (often per-NIC). 0.0.0.0 on all members is not a multipath design.
Routing: Return traffic for each path must leave via the interface that owns that path’s source address. Loose reverse-path filtering (rp_filter=2) is typical; strict rp_filter=1 triggers warnings in inspect output.
External gateway: Peers must reach each listener IP and port on UDP. AWS: security group rules per path CIDR. KVM bridged: LAN routing. No AWS API calls from pixop-net.
Encoder / receiver: Remote side must use a compatible SRT group with grouptype=broadcast on the member that completes the group (libsrt group semantics).

Read-only preflight does not configure any of the above — it only reports whether local preconditions look plausible.

Bonded URI syntax (one line only)

Use exactly one --input (ingest) or --output (egress) argument whose value is semicolon-separated srt:// members. Put grouptype=broadcast on the last member.

CONFIG example (documentation addresses only):

--input srt://203.0.113.1:5000?mode=listener&transtype=live&passphrase=@SRT_PASSPHRASE@&pbkeylen=16;srt://203.0.113.2:5000?mode=listener&transtype=live&passphrase=@SRT_PASSPHRASE@&pbkeylen=16&grouptype=broadcast

Rules enforced by tooling:

Rule	Detail
One bonding line	Multiple `--input` lines = independent failover, health check `srt-ambiguous` — not bonded
Same passphrase placeholder	`@SRT_PASSPHRASE@` from instance `.env`
Listener health	`tsduckctl` waits for every `(host, port)` UDP bind when health check is `srt-bonded-udp`
Caller legs	Use `srcip=` query parameters where needed; verify with `pixop-net` and `--peer`

Egress bonding uses one --output line with the same semicolon pattern on egress-main.egress.args (or aux templates if you enable those lanes).

RESTART the instance after template edits.

pixop-net (read-only)

Available only when the pixop-net binary exists (command -v pixop-net). Never changes routes, rp_filter, netplan, or relay files.

Command	Purpose
`pixop-net multipath inspect`	Interfaces, addresses, routes, rules, `rp_filter` warnings
`pixop-net multipath inspect --relay-args PATH --role ingest\|egress`	Above plus parsed bonded members
`pixop-net multipath verify --relay-args PATH --role ingest\|egress`	Listener IPs exist on host
`pixop-net multipath verify ... --peer INDEX:PEER_IP`	Per-leg `ip route get` toward peer

READ-ONLY examples (RFC 5737 placeholders):

pixop-net multipath inspect --json

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

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

Interpret JSON carefully:

Field	Meaning
`peer_routing_status: not_checked`	No `--peer` supplied — routing toward remote peers unverified
`ok` alone	Does not prove peer routing; read `peer_routing_status`
`prepare` / `apply` / `rollback`	Not implemented — reserved names only

Elevation: if relay args are root-only readable, pixop-net may re-exec via sudo for that invocation (PIXOP_NET_NOSUDO=1 to disable).

tsduckctl and bind semantics

After start or restart:

tsduckctl transport main
tsduckctl check main

Observation	Meaning
All listeners `bound`	UDP sockets listening on configured IPs/ports locally
`bound (SRT session unverified)`	Normal until SRT callers connect; does not prove peer routing or security-group reachability
Bonded group active	Requires encoder/receiver group configuration — not inferred from bind alone

tsduckctl start / restart with srt-bonded-udp blocks until all listeners bind (up to ~20 s of polling). Partial bind is a local failure — wrong listener IP, address not assigned to an interface, port already in use, or service crash. AWS security groups and NACLs affect remote handshake and traffic after bind; they do not cause bind() to fail on the appliance. Use pixop-net multipath verify for local IP assignment; test peer reachability separately.

Ingress stall recovery (--input-connected-stall-recovery-ms on default main.ingest.args) applies to SRT listener ingress only. It recovers some blackhole conditions without restarting the outer TSDuck unit. It must not fire on idle bonded members or benign single-path loss — watch journalctl -u tsduck-in@main for reset lines and correlate with path events.

Bound listeners vs redundant streams

Concept	What Pixop guarantees
UDP bind on each leg	Yes, when health check passes and networking is correct
SRT group media merge	Depends on libsrt group + encoder; appliance relay receives bonded input
Automatic path failover without routing	No
Hot swap NIC without template edit	No
Identical output on aux ports 5002/5003	Separate instances — not automatic clones of bonded main

Failure modes and limitations

Failure	Likely cause	Safe action
One leg never binds	Listener IP not on any NIC, port collision, or unit failed to start	`pixop-net multipath verify`; `journalctl -u tsduck-in@main`; fix template or local networking
Binds on all legs; encoder cannot connect one path	SG/NACL, routing, or asymmetric return path	Fix cloud/on-prem firewall and `ip route` / `rp_filter`; bind status alone cannot prove this
Binds OK, no media	Encoder not in matching group; wrong passphrase/pbkeylen	Verify peer config; `tsduckctl credentials`
Asymmetric routing	Strict `rp_filter` or missing policy route	Loosen `rp_filter` per platform guide; add `ip rule` (operator)
`srt-ambiguous` health	Multiple `--input` lines instead of one bonded URI	Fix template to single semicolon-separated line
Stall recovery storms	Misapplied recovery flag on non-SRT input	Remove `--input-connected-stall-recovery-ms` for UDP/RIST/RTMP

Policy routing examples for multi-homed Linux are maintained outside this appliance (see engineering MULTI_NIC_ROUTING_GUIDE in the srt-bond-relay project). Pixop ships diagnostics only.

Network and transport — port and topology reference
Transport configuration — relay edit workflow
Transport troubleshooting — symptom tables
pixop-net — CLI options
tsduck-transport-info — advanced JSON (bind-status; prefer tsduckctl check / tsduckctl transport)