diff --git a/README.md b/README.md index 841b2d8..df67943 100644 --- a/README.md +++ b/README.md @@ -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" | diff --git a/machinery/src/capture/gortsplib.go b/machinery/src/capture/gortsplib.go index 608534a..be2e94e 100644 --- a/machinery/src/capture/gortsplib.go +++ b/machinery/src/capture/gortsplib.go @@ -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 { diff --git a/machinery/src/capture/gortsplib_test.go b/machinery/src/capture/gortsplib_test.go index 32460eb..a2bbb3f 100644 --- a/machinery/src/capture/gortsplib_test.go +++ b/machinery/src/capture/gortsplib_test.go @@ -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) + } + }) + } +} diff --git a/machinery/src/models/mqtt.go b/machinery/src/models/mqtt.go index 26530b4..cfa25e6 100644 --- a/machinery/src/models/mqtt.go +++ b/machinery/src/models/mqtt.go @@ -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. diff --git a/machinery/src/routers/mqtt/main.go b/machinery/src/routers/mqtt/main.go index a799195..8e48682 100644 --- a/machinery/src/routers/mqtt/main.go +++ b/machinery/src/routers/mqtt/main.go @@ -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 {