mirror of
https://github.com/kerberos-io/agent.git
synced 2026-11-21 22:50:39 +00:00
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:
co-authored by
Claude Opus 5.5
parent
1e16a8e27c
commit
f6575652bc
@@ -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" |
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 {
|
||||
|
||||
Reference in New Issue
Block a user