Skip to content

docs(daemon): add TLS-in-front deployment recipes (#2052)#3500

Merged
oferchen merged 2 commits into
masterfrom
docs/daemon-tls-in-front-2052
May 1, 2026
Merged

docs(daemon): add TLS-in-front deployment recipes (#2052)#3500
oferchen merged 2 commits into
masterfrom
docs/daemon-tls-in-front-2052

Conversation

@oferchen
Copy link
Copy Markdown
Owner

@oferchen oferchen commented May 1, 2026

Summary

Adds docs/daemon/tls-in-front.md, a new operator-facing page covering
how to put TLS in front of an oc-rsyncd daemon. oc-rsync's daemon
mode is plaintext rsync over TCP (wire-equivalent to upstream); this
page documents the three pragmatic ways to wrap that wire in TLS
without protocol changes.

What landed

  • Threat model - what TLS-in-front does (wire confidentiality and
    integrity, server identity, optional mTLS) and what it does not
    replace (auth users, secrets file, hosts allow, filter rules,
    chroot).
  • stunnel recipe - sample stunnel.conf listening on TCP/874 with
    cert / key, forwarding to 127.0.0.1:8730, plus a matching
    oc-rsyncd.conf snippet bound via address = 127.0.0.1 and
    port = 8730.
  • SSH-tunnel recipe - ssh -N -L 8730:localhost:8730 host plus
    oc-rsync rsync://localhost:8730/module/. Explicitly distinguishes
    this from rsync-over-ssh transport (-e ssh), which spawns a remote
    --server and bypasses the daemon entirely.
  • Reverse proxy recipe - HAProxy listen block in mode tcp with
    bind ... ssl crt, plus an nginx stream {} block. Calls out that
    HTTP-mode proxies will corrupt the rsync wire protocol.
  • Client side - oc-rsync has no native TLS client; the page covers
    local stunnel, --connect-program with openssl s_client (%H/%P
    placeholders), and SSH-tunnel shapes.
  • Operational notes - cert hygiene (DNS-SAN required), mTLS
    directives per terminator, address binding, the --port flag, and
    why HTTP health checks must be avoided.
  • Cross-references - links to docs/daemon/filter-precedence.md
    and docs/DAEMON_PROCESS_MODEL.md, and to upstream's
    stunnel-rsyncd.conf.

Factual claims were verified against
crates/daemon/src/daemon/sections/config_parsing/global_directives.rs
(directive names address / port),
crates/daemon/src/daemon/sections/config_parsing/module_directives.rs
(auth users, secrets file, hosts allow),
crates/cli/src/frontend/command_builder/sections/build_base_command/network.rs
(--port, --connect-program with %H/%P), and upstream
rsync-3.4.1/stunnel-rsyncd.conf / daemon-parm.txt.

Closes the documentation request in #2052.

Test plan

  • CI: docs-only change, no code touched outside docs/. Expect
    fmt/clippy/nextest/Windows/macOS/Linux-musl all green by virtue
    of being a no-op for the build graph.
  • Manual: render docs/daemon/tls-in-front.md and verify the
    relative links to filter-precedence.md and
    ../DAEMON_PROCESS_MODEL.md resolve.

oferchen added 2 commits May 1, 2026 11:13
Document how to put TLS in front of oc-rsyncd using stunnel, an SSH
local-forward, or a TCP-mode reverse proxy (HAProxy/nginx). Covers
threat model, matching `oc-rsyncd.conf` snippets, client-side options
including `--connect-program` and `--port`, mTLS, and DNS-SAN cert
hygiene. Cross-links the daemon filter-precedence page.
@oferchen oferchen merged commit 399e8dd into master May 1, 2026
10 checks passed
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label May 1, 2026
@oferchen oferchen deleted the docs/daemon-tls-in-front-2052 branch May 1, 2026 21:09
oferchen added a commit that referenced this pull request May 5, 2026
Document how to put TLS in front of oc-rsyncd using stunnel, an SSH
local-forward, or a TCP-mode reverse proxy (HAProxy/nginx). Covers
threat model, matching `oc-rsyncd.conf` snippets, client-side options
including `--connect-program` and `--port`, mTLS, and DNS-SAN cert
hygiene. Cross-links the daemon filter-precedence page.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant