Harden configurable RTSP transport (follow-up to #351)

- MQTT verify: accept rtsp_transport in the verify payload and fall back
  to the configured transport, like the RTSP url already does, so unsaved
  transport choices can be verified from Kerberos Hub.
- RTSPS + forced UDP: fail fast with a clear error when the camera does
  not offer SRTP, instead of every SETUP failing with "unable to setup
  secure UDP" (which Connect only logs). "auto" already picks TCP here.
- Backchannel: always use TCP. gortsplib's auto fallback only triggers
  when no packets are received, which never happens on a send-only
  backchannel, and talk-back over UDP is not validated on hardware.
- UDP read buffer: request 4 MiB, capped at net.core.rmem_max, because
  gortsplib fails the SETUP when it cannot get the exact size requested.
- Logging: route gortsplib's transport-switch messages through the
  structured logger and log the negotiated transport per stream.
- README: document the transport options and their caveats.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Cédric Verstraeten
2026-11-21 20:25:48 +00:00
co-authored by Claude Opus 5.5
parent 1e16a8e27c
commit f6575652bc
5 changed files with 204 additions and 3 deletions
+16
View File
@@ -354,6 +354,22 @@ For a private CA, mount a PEM trust bundle containing every CA certificate neede
See [RTSPS and TLS certificates](README-RTSPS-TLS.md) for the complete Bosch UI, private-CA, deployment, validation, and troubleshooting procedure.
### RTSP transport (TCP, UDP or auto)
`AGENT_CAPTURE_IPCAMERA_RTSP_TRANSPORT` (or the transport dropdown in Settings) selects how RTP media is received from the camera:
- `tcp` (default): media is interleaved on the RTSP TCP connection. Most reliable, works through any NAT or firewall.
- `udp`: media is sent over separate UDP ports. Lower latency, but lost packets are not resent.
- `auto`: UDP first, falling back to TCP when the camera refuses UDP or no UDP packets arrive within 3 seconds.
Notes:
- With `rtsps://` URLs, `udp` only works when the camera offers SRTP. Otherwise the connection fails with a message pointing to `tcp` or `auto`. `auto` uses TCP for such cameras on its own.
- The audio backchannel (talk-back) always uses TCP.
- For UDP the Agent requests a 4 MiB socket receive buffer, capped at the host's `net.core.rmem_max` (often about 208 KiB). For high-bitrate main streams, raise the limit on the host, for example `sysctl -w net.core.rmem_max=4194304`. Lost packets are logged as `rtp_packets_lost`.
- UDP needs the camera's RTP packets to reach the Agent. Docker bridge networking normally works; if a firewall or Kubernetes network policy drops them, use `auto` or `tcp`.
- The transport the Agent ended up with is logged as `rtsp_transport` (and `rtsp_transport_switch` when `auto` falls back to TCP).
| Name | Description | Default Value |
| --------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------ |
| `LOG_LEVEL` | Level for logging, could be "info", "warning", "debug", "error" or "fatal". | "info" |
+111 -2
View File
@@ -32,6 +32,7 @@ import (
"github.com/bluenviron/gortsplib/v5/pkg/format/rtplpcm"
"github.com/bluenviron/gortsplib/v5/pkg/format/rtpmpeg4audio"
"github.com/bluenviron/gortsplib/v5/pkg/format/rtpsimpleaudio"
"github.com/bluenviron/gortsplib/v5/pkg/headers"
"github.com/bluenviron/mediacommon/pkg/bits"
"github.com/bluenviron/mediacommon/pkg/codecs/h264"
"github.com/bluenviron/mediacommon/pkg/codecs/h265"
@@ -77,6 +78,77 @@ func rtspProtocol(transport string) *gortsplib.Protocol {
return &protocol
}
// backChannelProtocol is the transport used for the audio backchannel. It is
// always TCP: gortsplib's "auto" fallback only switches to TCP when no packets
// are received over UDP, which never happens on a send-only backchannel, and
// talk-back over UDP has not been validated on camera hardware.
func backChannelProtocol() *gortsplib.Protocol {
protocol := gortsplib.ProtocolTCP
return &protocol
}
// errSecureUDPUnavailable is returned when UDP is forced on an RTSPS camera
// that does not offer SRTP, so the media could not be sent encrypted over UDP.
var errSecureUDPUnavailable = errors.New(
"the RTSPS camera does not offer SRTP, so RTP over UDP cannot be encrypted; " +
"set the RTSP transport to \"tcp\" or \"auto\"")
// checkSecureUDP rejects forced UDP on an RTSPS stream whose video media is not
// SRTP (RTP/SAVP). gortsplib would otherwise fail every SETUP with "unable to
// setup secure UDP", which Connect only logs. "auto" is not affected because
// gortsplib picks TCP on its own for such streams.
func checkSecureUDP(scheme string, protocol *gortsplib.Protocol, medias []*description.Media) error {
if protocol == nil || *protocol != gortsplib.ProtocolUDP || !strings.EqualFold(scheme, "rtsps") {
return nil
}
for _, medi := range medias {
if medi.Type == description.MediaTypeVideo && medi.Profile != headers.TransportProfileSAVP {
return errSecureUDPUnavailable
}
}
return nil
}
// udpReadBufferTarget is the UDP socket read buffer requested for RTP over
// UDP. The OS default (around 208 KiB on Linux) drops packets on
// high-bitrate main streams.
const udpReadBufferTarget = 4 * 1024 * 1024
// rmemMaxPath holds the largest receive buffer an unprivileged socket may use.
const rmemMaxPath = "/proc/sys/net/core/rmem_max"
// udpReadBufferSize returns the UDP read buffer to request: the target,
// capped at the OS limit rmemMax. gortsplib fails the SETUP when it cannot get
// the exact size it asked for, so the size must never exceed the limit. It
// returns 0 (OS default) for TCP, or when the limit is unknown or not above the
// default.
func udpReadBufferSize(protocol *gortsplib.Protocol, rmemMax int) int {
if protocol != nil && *protocol == gortsplib.ProtocolTCP {
return 0
}
if rmemMax <= 0 {
return 0
}
if rmemMax < udpReadBufferTarget {
return rmemMax
}
return udpReadBufferTarget
}
// readRmemMax reads the OS receive buffer limit, or 0 when it is unavailable
// (non-Linux systems or a restricted /proc).
func readRmemMax() int {
data, err := os.ReadFile(rmemMaxPath)
if err != nil {
return 0
}
value, err := strconv.Atoi(strings.TrimSpace(string(data)))
if err != nil {
return 0
}
return value
}
func rtspsTLSConfig() (*tls.Config, error) {
if os.Getenv(rtspsInsecureEnv) == "true" {
return &tls.Config{InsecureSkipVerify: true}, nil // #nosec G402 -- explicit opt-in for cameras with self-signed certificates
@@ -576,10 +648,21 @@ func (g *Golibrtsp) Connect(ctx context.Context, ctxOtel context.Context) (err e
}
g.health = newStreamHealth()
protocol := rtspProtocol(g.Transport)
g.Client = gortsplib.Client{
RequestBackChannels: false,
Protocol: rtspProtocol(g.Transport),
Protocol: protocol,
UDPReadBufferSize: udpReadBufferSize(protocol, readRmemMax()),
TLSConfig: tlsConfig,
// In "auto" mode gortsplib may move from UDP to TCP; report it through
// the structured logger instead of gortsplib's plain stdout logging.
OnTransportSwitch: func(err error) {
log.WithFields(log.Fields{
"component": "capture",
"event": "rtsp_transport_switch",
"stream": g.streamLabel,
}).Warn("RTSP transport switched: " + err.Error())
},
// Route gortsplib's packet-loss / decode-error reporting through our
// structured logger with stream context (replaces its plain stdout
// logging). These hooks are what let us tell whether the camera is
@@ -613,6 +696,10 @@ func (g *Golibrtsp) Connect(ctx context.Context, ctxOtel context.Context) (err e
return sanitizeRTSPError(err, g.Url)
}
if err = checkSecureUDP(u.Scheme, protocol, desc.Medias); err != nil {
return err
}
// Initialize the mutex and FPS calculation.
g.VideoDecoderMutex = &sync.Mutex{}
g.initFPSCalculation()
@@ -850,6 +937,27 @@ func (g *Golibrtsp) Connect(ctx context.Context, ctxOtel context.Context) (err e
return
}
// logNegotiatedTransport logs the transport that SETUP agreed on, which can
// differ from the configured one in "auto" mode. A later UDP to TCP switch
// (no packets received in time) is reported by OnTransportSwitch.
func (g *Golibrtsp) logNegotiatedTransport() {
transport := g.Client.Transport()
if transport == nil || transport.Session == nil {
return
}
configured := strings.ToLower(strings.TrimSpace(g.Transport))
if configured == "" {
configured = RTSPTransportTCP
}
log.WithFields(log.Fields{
"component": "capture",
"event": "rtsp_transport",
"stream": g.streamLabel,
"configured": configured,
"negotiated": transport.Session.Protocol.String(),
}).Info("RTSP transport negotiated")
}
func (g *Golibrtsp) ConnectBackChannel(ctx context.Context, ctxRunAgent context.Context) (err error) {
_, span := tracer.Start(ctxRunAgent, "ConnectBackChannel")
@@ -862,7 +970,7 @@ func (g *Golibrtsp) ConnectBackChannel(ctx context.Context, ctxRunAgent context.
g.Client = gortsplib.Client{
RequestBackChannels: true,
Protocol: rtspProtocol(g.Transport),
Protocol: backChannelProtocol(),
TLSConfig: tlsConfig,
}
// parse URL
@@ -982,6 +1090,7 @@ func (g *Golibrtsp) Start(ctx context.Context, streamType string, queue *packets
if g.health == nil {
g.health = newStreamHealth()
}
g.logNegotiatedTransport()
// called when a MULAW audio RTP packet arrives
if g.AudioG711Media != nil && g.AudioG711Forma != nil {
+67
View File
@@ -13,6 +13,8 @@ import (
"testing"
"github.com/bluenviron/gortsplib/v5"
"github.com/bluenviron/gortsplib/v5/pkg/description"
"github.com/bluenviron/gortsplib/v5/pkg/headers"
"github.com/bluenviron/mediacommon/pkg/codecs/h264"
)
@@ -280,3 +282,68 @@ func TestRTSPProtocol(t *testing.T) {
})
}
}
func TestBackChannelProtocolIsTCP(t *testing.T) {
if got := backChannelProtocol(); got == nil || *got != gortsplib.ProtocolTCP {
t.Fatalf("backChannelProtocol() = %v, want tcp", got)
}
}
func TestCheckSecureUDP(t *testing.T) {
tcp := gortsplib.ProtocolTCP
udp := gortsplib.ProtocolUDP
plainVideo := []*description.Media{
{Type: description.MediaTypeVideo, Profile: headers.TransportProfileAVP},
}
srtpVideo := []*description.Media{
{Type: description.MediaTypeVideo, Profile: headers.TransportProfileSAVP},
}
tests := []struct {
name string
scheme string
protocol *gortsplib.Protocol
medias []*description.Media
wantErr bool
}{
{name: "rtsps udp plain video", scheme: "rtsps", protocol: &udp, medias: plainVideo, wantErr: true},
{name: "rtsps udp srtp video", scheme: "rtsps", protocol: &udp, medias: srtpVideo},
{name: "rtsps tcp", scheme: "rtsps", protocol: &tcp, medias: plainVideo},
{name: "rtsps auto", scheme: "rtsps", protocol: nil, medias: plainVideo},
{name: "rtsp udp", scheme: "rtsp", protocol: &udp, medias: plainVideo},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
err := checkSecureUDP(test.scheme, test.protocol, test.medias)
if test.wantErr && !errors.Is(err, errSecureUDPUnavailable) {
t.Fatalf("checkSecureUDP() = %v, want errSecureUDPUnavailable", err)
}
if !test.wantErr && err != nil {
t.Fatalf("checkSecureUDP() = %v, want nil", err)
}
})
}
}
func TestUDPReadBufferSize(t *testing.T) {
tcp := gortsplib.ProtocolTCP
udp := gortsplib.ProtocolUDP
tests := []struct {
name string
protocol *gortsplib.Protocol
rmemMax int
want int
}{
{name: "tcp keeps os default", protocol: &tcp, rmemMax: 8 << 20, want: 0},
{name: "unknown limit keeps os default", protocol: &udp, rmemMax: 0, want: 0},
{name: "default linux limit", protocol: &udp, rmemMax: 212992, want: 212992},
{name: "raised limit capped at target", protocol: &udp, rmemMax: 16 << 20, want: udpReadBufferTarget},
{name: "auto uses target", protocol: nil, rmemMax: 16 << 20, want: udpReadBufferTarget},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
if got := udpReadBufferSize(test.protocol, test.rmemMax); got != test.want {
t.Fatalf("udpReadBufferSize() = %d, want %d", got, test.want)
}
})
}
}
+3
View File
@@ -256,6 +256,9 @@ type VerifyStreamPayload struct {
Timestamp int64 `json:"timestamp"` // timestamp of the verify request.
Stream string `json:"stream"` // "main" or "sub".
RTSP string `json:"rtsp"` // optional RTSP url to verify; falls back to the configured one.
// RTSPTransport is the optional transport to verify with ("tcp", "udp" or
// "auto"); falls back to the configured one.
RTSPTransport string `json:"rtsp_transport,omitempty"`
}
// We received a update config request, we'll update the current config and send a confirmation back.
+7 -1
View File
@@ -845,6 +845,12 @@ func HandleVerifyStream(mqttClient mqtt.Client, hubKey string, payload models.Pa
}
}
// Same for the transport, so an unsaved transport choice can be verified.
rtspTransport := verifyPayload.RTSPTransport
if rtspTransport == "" {
rtspTransport = configuration.Config.Capture.IPCamera.RTSPTransport
}
success := false
errMsg := ""
width := 0
@@ -862,7 +868,7 @@ func HandleVerifyStream(mqttClient mqtt.Client, hubKey string, payload models.Pa
rtspClient := &capture.Golibrtsp{
Url: rtspUrl,
Transport: configuration.Config.Capture.IPCamera.RTSPTransport,
Transport: rtspTransport,
}
errConnect := rtspClient.Connect(ctx, ctx)
if errConnect != nil {