Feb 2026 · Updated Oct 2026 · 12 min read · CAMRELAY · Build log

CamRelay: Tunnelling a Vendor P2P Camera Path into a Local TCP/RTSP Endpoint

A build log read from the camrelay repository: a Rust daemon that carries a camera's own RTSP session through a reverse-engineered P2P channel for cameras I own, how recording and rclone archiving hang off it, and where reconnect, stop and error handling are still unfinished.

✎ hoan02/camrelay · #Camrelay #Rust #Tokio #P2P #RTSP #Frigate #FFmpeg #rclone #Systems

At a glance

3

Cargo workspace members

Root daemon (6,528 lines in src/), camrelay-contract (164), camrelay-storage (958)

20

Unit tests, none against a camera

Across 8 files; CI runs fmt, check, test and clippy -D warnings

5 s / 8 s

Heartbeat vs read timeout

Every channel is bounded at 128 messages; no reconnect loop exists after the tunnel starts

0 of 3

Device rows validated

docs/device-validation-matrix.md lists IMOU, Dahua and KBVision, all Unclaimed

Problem Context

Camera ecosystems that are reachable only through a vendor P2P cloud do not fit NVR software that expects a local RTSP URL. For cameras I own, I wanted a small daemon that hides the P2P session and hands local tools an ordinary TCP endpoint.

Architecture & Design

camrelay is a Tokio and Axum daemon. For each camera it runs a provider handshake over UDP, opens a PTCP session, and exposes one local TCP port; each local client becomes a multiplexed realm that carries the camera's own RTSP bytes. A loopback RTSP auth proxy lets FFmpeg record MP4 segments and produce HLS without camera credentials on a command line, and rclone uploads closed segments. A reconcile loop restarts recorders and schedules uploads; the tunnel itself has no reconnect logic yet.

Key Technical Decisions

  1. 1Tunnel bytes instead of re-serving RTSP: the daemon never parses media. Consequence: low complexity and any RTSP client works, but there is no frame-level view, no shared upstream stream, and UDP RTP is likely unusable.
  2. 2One UDP session, one local port and one tunnel task per camera, with clients multiplexed as realms. Consequence: cameras fail independently, but one stalled client can block every realm on that camera through the single reader loop.
  3. 3Bounded channels (128) and fixed small buffers everywhere. Consequence: memory use cannot grow from a slow consumer, at the price of backpressure that propagates upstream.
  4. 4A loopback RTSP auth proxy for FFmpeg. Consequence: camera passwords stay out of command lines and process lists, at the cost of about 420 lines of hand-written RTSP/Digest handling that only two tests cover.
  5. 5Recording and archive as optional layers driven by a periodic reconcile loop, with FFmpeg doing `-c copy` segmenting. Consequence: relay availability does not depend on storage or rclone, and recorder restarts come for free, but failed uploads wait for a manual action.
  6. 6Opt-in SQLite with encrypted secrets beside legacy JSON files. Consequence: a rollback path and idempotent import, but two sources of truth and a master key that must be backed up separately.

Why a bridge: the camera speaks P2P, the NVR speaks RTSP

Frigate, Home Assistant and FFmpeg all want the same thing: an rtsp:// URL on the local network. Some Dahua-family cameras and recorders that I own are reachable remotely only through the vendor's P2P path: a cloud signaling server brokers a UDP session between the app and the device, and nothing is exposed as a plain RTSP port. camrelay is my attempt to speak that path from a small Rust daemon, so that a local consumer sees a normal TCP endpoint.

This is interoperability work for cameras I own and administer. The README says the same: use only credentials and P2P access for devices you are authorized to administer. I will describe the protocol only as far as the repository's own README and docs do, and the article contains no credentials, serials or provider account details.

What I read for this note: the README.md, the architecture, media-gateway and device-validation docs, every Rust source file in src/, the two workspace crates, Dockerfile, deploy/compose/, the CI workflow and dh-p2p.lua. I did not run it against a camera for this article. Where I say "as I read it", it is the code, not a test run. The clone is shallow (one commit visible), so I say nothing about how the design evolved or why unless a doc says so.

One correction to how I used to describe the project, since it shapes everything below: camrelay is not an RTSP server. It does not parse the camera's media or re-serve frames. It opens a local TCP listener per camera and carries the bytes of the camera's own RTSP server through the P2P session. RTSP awareness exists in exactly one place, a loopback auth proxy, covered in section four.

Architecture: one daemon, two small crates, a lot in the root

The Cargo workspace has three members: the root camrelay binary and two library crates. The async runtime is Tokio (locked at 1.52.3 in Cargo.lock, features = ["full"]), the HTTP layer is Axum 0.7.9, outbound HTTP is reqwest 0.12 with rustls, and the SQLite layer is sqlx 0.8.

MemberLinesWhat it owns
src/ (root binary)6,528P2P handshake (dh.rs, 695), PTCP framing (ptcp.rs, 389), tunnel lifecycle (tunnel.rs, 210), byte pumps (process.rs, 175), RTSP auth proxy (rtsp_proxy.rs, 419), FFmpeg live and recording (live.rs, recordings.rs), Axum API and auth (web.rs, 3,093)
crates/camrelay-contract164Serde DTOs for /api/v1: roles, error envelope, camera, recording and audit summaries
crates/camrelay-storage958SQLite, three migrations, Argon2id user hashes, ChaCha20-Poly1305 for stored secrets, sessions, audit log, idempotent import of the legacy JSON files

The split is worth being honest about. docs/architecture.md describes a target layout with camrelay-core, camrelay-api and camrelay-media crates. Those crates do not exist yet. Today the P2P code, the HTTP API and the FFmpeg supervision all live in the root crate, and web.rs alone is almost half of it. The two extracted crates are the parts that had a clean seam: the wire types and the persistence layer.

Around the daemon sit a React console (apps/web, Vite), a Flutter client (apps/mobile) and a shared design-token package. I will not cover them; they only use the versioned /api/v1 and, per the architecture doc, never see camera credentials.

Two supervisors tick inside the process. Tunnels are started once, at boot for cameras with auto_start, or from the API. A separate loop in main.rs wakes every archive_poll_seconds (default 15, floor 5) and calls RecordingManager::reconcile, which is the only periodic self-healing in the codebase. Section five comes back to that.

The P2P tunnel: handshake, PTCP, realms

Per camera, run_tunnel does four things in order: bind a local TCP listener on local_port, bind a UDP socket, run p2p_handshake, then start three tasks (writer, reader, heartbeat) and loop on accept.

Handshake. At the level the README documents it: HTTP-like request/response text over UDP to a provider endpoint configured in brands.json, authenticated with platform credentials that are separate from the camera's own RTSP login, followed by a device-side step that establishes the PTCP channel. Each step has a timeout (5 s for the device handshake, 8 s per signaling read), and the error text suggests that "relay mode may be required" if the direct path fails. p2p_handshake has a relay_mode parameter, but tunnel.rs passes false and there is no per-camera setting, which the README's limitations list also admits. A provider probe endpoint in the API checks only that the platform credential is accepted; the README is explicit that this does not prove a camera works.

PTCP. The README calls it a proprietary protocol reconstructed through reverse engineering, with no official documentation in the repo, and credits two upstream projects for the foundations. In ptcp.rs a packet is a fixed 24-byte header (magic, two byte counters, a packet id, local and remote message ids) plus one of seven body kinds: sync, command, payload, bind, status, heartbeat, empty. Payloads carry a 32-bit realm and a length, and parsing rejects truncated headers, wrong lengths and non-zero padding with an Err instead of a panic. There is a test for exactly that. dh-p2p.lua is a Wireshark dissector for the signaling and PTCP traffic, shipped for investigation; the README labels it optional, and the Dockerfile copies it into the image.

Realms are how several clients share one camera. Each accepted local TCP client gets a random 32-bit realm. The tunnel sends a Bind for that realm to the remote RTSP port, waits for the device's CONN status, and only then starts the two pump tasks. Data from the client becomes Payload(realm, bytes); data from the device is routed by realm to that client's channel.

// src/tunnel.rs (trimmed)
let (tx, rx) = mpsc::channel::<Vec<u8>>(128);
let (conn_tx, conn_rx) = oneshot::channel::<bool>();
let realm_id = rand::random::<u32>();
channels2.lock().unwrap().insert(realm_id, tx);
conn_channels2.lock().unwrap().insert(realm_id, conn_tx);

dh_tx.send(PTCPEvent::Connect(realm_id)).await?;
conn_rx.await?;                       // wait for the device's CONN

let (r, w) = client.into_split();
tokio::spawn(process_reader(r, realm_id, dh_tx_clone));
tokio::spawn(process_writer(w, rx));

Buffering and backpressure. Every channel is bounded at 128 messages, the client read buffer is 4096 bytes, and a PTCP datagram is read into a 4096-byte buffer. Nothing is unbounded, which matches the "no unbounded queues" rule in the architecture doc. The consequence is head-of-line blocking: dh_reader does tx.send(data).await into the per-realm channel inside the single loop that reads the UDP socket. If one local client stops reading, that channel fills and the loop stalls for every realm on that camera. I would call that fine for one NVR per camera and wrong for many viewers.

I also looked for retransmission and reordering. The session tracks sent and received byte counters and acknowledges incoming packets with an empty one, but I did not find a resend queue or a reorder buffer. I do not know whether the device side makes that unnecessary on a clean network; I have not tested a lossy one.

The local side: how Frigate, FFmpeg and the recorder consume it

A consumer connects to 127.0.0.1:<local_port> (the host that runs the daemon) and speaks RTSP to the camera as if the camera were local. The README's test command uses TCP transport: ffplay -rtsp_transport tcp "rtsp://127.0.0.1:8551/cam/realmonitor?channel=1&subtype=0". Because the listener is a TCP socket, I would expect RTP over UDP not to work through it; I have not tried. For Frigate the README says to use the same URL as an input. There is no Frigate-specific test or config in the repo, and the README lists a native Frigate integration under "not yet promised". Home Assistant is not mentioned anywhere in the repo's README or docs, so I will not claim more than "any RTSP client".

Credentials stay out of URLs. The raw tunnel just forwards the camera's authentication challenge to the client. For the paths the daemon starts itself (HLS preview and recording) there is rtsp_proxy.rs: a loopback listener on an ephemeral port that sits between FFmpeg and the tunnel. It reads RTSP messages (including $-prefixed interleaved frames), answers the camera's 401 with Basic or Digest authorization built from the stored camera login, and after a successful PLAY switches to copy_bidirectional. The point, per the README, is that camera secrets never appear on an FFmpeg command line. Two tests cover Basic and Digest header construction.

Recording. recordings.rs spawns FFmpeg once per running camera:

// src/recordings.rs: start_recorder (args trimmed)
Command::new(&self.config.ffmpeg_path).args([
    "-hide_banner", "-loglevel", "warning",
    "-rtsp_transport", "tcp", "-i", &url,   // loopback proxy URL
    "-map", "0", "-c", "copy",
    "-f", "segment", "-segment_time", &segment_seconds,
    "-reset_timestamps", "1", "-strftime", "1", &output,
]).spawn()

-c copy means no transcoding: the stream is remuxed into MP4 segments named by timestamp, segment_seconds defaulting to 300 with a floor of 30. A segment is indexed into recordings.json (or SQLite) only once it is non-empty and its mtime is at least 8 seconds old, so an open file is skipped. There is no hardware acceleration: every FFmpeg invocation I found copies the video stream (the HLS path re-encodes audio to AAC).

Archive. Closed segments are SHA-256'd and uploaded with rclone copyto --retries 3 --low-level-retries 10 --retries-sleep 5s. With archive_verify on, it downloads the object again and compares hashes. rclone remotes are configured outside the repo; the Compose file mounts the rclone config read-only. Live HLS is separate: 2-second segments, a 6-entry playlist, delete_segments, served behind a camera-scoped ticket.

Failure modes: what the code does when things break

This is the section where reading the code matters most, because the README's limitations list already says "error handling and reconnect behavior still need hardening for unattended NVR use" and "guaranteed reconnection after every network or device failure" is under not-yet-promised. Here is what I can add by following the paths.

EventWhat I read in the code
No packet from the device for 8 sptcp_read times out, returns Err, dh_reader logs P2P reader stopped and exits
One malformed datagramParse returns Err (no panic); dh_reader treats any Err the same way and exits
UDP send failsdh_writer logs and exits
Reader or writer has exitedTunnel status stays Running; the TCP listener keeps accepting; nothing restarts the session
Handshake fails at startStatus becomes Error(message); no retry
FFmpeg recorder exitsNext reconcile tick reaps it and starts a new one, if the tunnel status is still Running
rclone failsSegment marked failed with stderr; only status == "local" rows are scheduled, so a failed one waits for the manual Archive action
Disk fullNot handled; FFmpeg's own error is the only signal. local_retention_days defaults to 0, meaning nothing is deleted

The heartbeat is a task that sends a heartbeat event every 5 seconds, which is shorter than the 8-second read timeout, so a healthy idle session should not trip it.

// src/tunnel.rs
tokio::spawn(async move {
    loop {
        tokio::time::sleep(Duration::from_secs(5)).await;
        if hb_tx.send(PTCPEvent::Heartbeat).await.is_err() { break; }
    }
});

The part that worries me is the fourth row. When the reader task dies, the status the API reports and the status reconcile uses are both still Running. Recorder restarts then keep launching FFmpeg against a listener that accepts connections but whose accept loop waits for a CONN that cannot arrive (conn_rx.await has no timeout). From the outside this looks like a camera that hangs, not one that is down.

Two smaller things I noticed. TunnelManager::stop aborts the supervisor task, but run_tunnel runs in a nested tokio::spawn; as I read Tokio's semantics, dropping that handle detaches the inner task instead of cancelling it, so the listener and sub-tasks may outlive a stop. And I found no place where a realm's sender is removed from the channel map when a client disconnects. Neither is tested; both are things to verify with a real run before I trust them.

On partial frames: FFmpeg's segment muxer owns that problem, not camrelay. The only guard on the daemon side is the "non-empty and 8 seconds old" rule before indexing. I have not checked what an MP4 segment looks like after FFmpeg is killed mid-write.

Deployment and configuration

Config model. Four JSON files read from the working directory, all git-ignored, with sanitized *.example.json in the repo: config.json (web port and credentials, recording, live and archive options, 21 keys in the example), brands.json (provider endpoint plus platform credentials), cameras.json and tokens.json. A camera is nine fields:

// cameras.example.json (shape only)
{
  "id": "cam-example", "name": "Front door", "brand": "Dahua",
  "serial": "<device serial>", "username": "admin", "password": "<device RTSP password>",
  "port": 554, "local_port": 8551, "auto_start": false
}

local_port must be unique per camera; brand must match a name in brands.json. The SQLite mode (database_enabled) is opt-in and imports these files idempotently; with providers or cameras present it requires CAMRELAY_SECRET_KEY, a base64 32-byte key that encrypts stored secrets with ChaCha20-Poly1305. The compose README says to back that key up separately.

Container. A three-stage Dockerfile: Node 22 builds the React console, rust:1.86 builds a --locked release binary, and debian:bookworm-slim carries the result plus ffmpeg and rclone, running as a non-root camrelay user with /data as a volume. Compose adds restart: unless-stopped, a health check against /api/v1/health every 30 seconds, and mounts ./data and the rclone config. Port 8080 is the only published port. An optional override adds MediaMTX on a private Docker network for a WebRTC preview; the docs call it a foundation, not a verified path, and HLS is the one marked verified. The README warns against exposing the web server directly because there is no built-in TLS.

The tunnel listener binds 0.0.0.0:<local_port>, so on a bare-metal run the raw RTSP tunnel (and its camera login challenge) is reachable from the LAN. In Compose, only 8080 is published, which narrows that.

Observability and tests. Logging is println!/eprintln! (about 45 call sites, no tracing), and the PTCP layer prints a line for every packet it sends and reads. The structured pieces are an audit log in SQLite (written without request secrets, per a test) and a /api/v1 SSE system stream that publishes status every 5 seconds. There are 20 unit tests across eight files: PTCP and handshake parsing, RTSP auth headers, live gateway selection, recording checksum and retention, storage hashing, session rotation, import idempotency. CI runs fmt, check, test and clippy -D warnings, plus web typecheck/build, Flutter analyze/test/APK, and a Docker build without push. None of it touches a camera.

Rough edges, and what I would check next

I do not have measurements for this project. The repository contains no benchmark, no memory figure and no latency figure, so I make no claim about footprint or delay and the repo documents none, so I state none.

What I consider unfinished, in the order I would work on it:

  1. Session supervision. Detect a dead reader or writer, set the status to Error, close client sockets, and re-run the handshake with backoff. Add a timeout around conn_rx.await.
  2. Make stop actually stop. Abort or signal the inner task, and remove realm entries on disconnect.
  3. A real-device test row. The validation matrix has three Unclaimed rows. The README's own limitation, "no automated integration test against a real camera", stands; a fake PTCP peer in a test would cover reconnect without hardware.
  4. Failed uploads. Re-queue failed segments with a cap instead of waiting for a click, and handle low disk space explicitly.
  5. Logs and crates. Move per-packet println! behind tracing levels, and extract the core crate the architecture doc names so P2P code tests without Axum.

Not done and not claimed: universal Dahua compatibility, IMOU compatibility, automatic discovery, built-in TLS, a native Frigate integration, and a verified WebRTC path.

Separately, I noticed the repo's default login for a fresh start without a config file is admin / admin (the example config uses change-me). The README says to change it before exposing the service; I would rather the daemon refused to start with the default.

Verified repository evidence

  • systems · direct

    Built a Rust/Tokio TCP tunnel that reaches a camera over a vendor P2P path, fronted by a loopback RTSP authentication proxy; recording uses FFmpeg -c copy and archiving uses rclone. It is a tunnel, not an RTSP server, and no performance figures are claimed.

    ↳ Tokio TCP tunnel over the P2P session; recordings live in src/recordings.rs and the validated device path in docs/device-validation-matrix.md.

    hoan02/camrelay ↗

Key Engineering Takeaways

  • A bridge that tunnels bytes is small and honest, but it inherits every failure of the session underneath it.
  • Status must reflect the session, not the process: a task that exits quietly while the API says running is worse than a crash.
  • Compatibility claims belong in a per-device evidence table; the repo's own matrix is empty, so I claim none.
  • Documented and measured are different things: without a benchmark in the repo, I publish no performance number.