Skip to content

docs(deployment): add daemon TLS-in-front deployment recipe (#2052)#3518

Merged
oferchen merged 1 commit into
masterfrom
docs/daemon-tls-deployment-2052
May 1, 2026
Merged

docs(deployment): add daemon TLS-in-front deployment recipe (#2052)#3518
oferchen merged 1 commit into
masterfrom
docs/daemon-tls-deployment-2052

Conversation

@oferchen
Copy link
Copy Markdown
Owner

@oferchen oferchen commented May 1, 2026

Summary

Closes tracker #2052. SECURITY.md referenced "TLS-in-front" deployment as the recommended way to expose oc-rsync --daemon over an untrusted network but did not provide a runnable recipe. This PR adds docs/deployment/daemon-tls.md with concrete, copy-pasteable configurations and cross-links it from SECURITY.md and README.md so operators land on the recipe directly.

Files changed

  • NEW docs/deployment/daemon-tls.md - the recipe itself.
  • SECURITY.md - inline link added under the existing "Daemon TLS" hardening note.
  • README.md - inline link added to the "Daemon TLS" bullet under "Known Limitations / Architectural Trade-offs".

No code changes; docs only.

Recipe contents

The new doc covers:

  1. Loopback bind of the daemon (address = 127.0.0.1, port = 873) with a minimal oc-rsyncd.conf plus secrets file permissions, auth users, hosts allow / hosts deny, and refuse options examples that mirror upstream rsyncd.conf(5) syntax.
  2. stunnel server-side config terminating TLS on 0.0.0.0:874 and forwarding to 127.0.0.1:873. Modeled directly on upstream's target/interop/upstream-src/rsync-3.4.1/stunnel-rsyncd.conf. Includes a matching client-side stunnel block.
  3. ssh -L recipe for ad-hoc operator access, with an ~/.ssh/config block (ExitOnForwardFailure yes, ServerAliveInterval) and a systemd user unit for persistent forwards.
  4. HAProxy TCP-mode config (mode tcp, bind ... ssl crt ..., server 127.0.0.1:873 check), modern TLS defaults (Mozilla intermediate 2024), optional PROXY-protocol v2 with a pointer to the daemon's proxy_protocol.rs v1/v2 handler.
  5. systemd unit excerpts:
    • drop-in for the shipped oc-rsyncd.service reinforcing the loopback bind and tightening syscall filters,
    • full stunnel-oc-rsyncd.service unit,
    • drop-in for the distro-shipped haproxy.service,
    • user-mode oc-rsyncd-tunnel.service for the SSH-forward case.
  6. Firewall guidance: nftables and iptables rules that allow tcp/874 from authorised CIDRs and unconditionally drop tcp/873 on non-loopback interfaces; Docker/Podman bridge isolation patterns (--internal networks, host networking + firewall).
  7. Verification checklist with ss, openssl s_client, and nc -zv probes.

Verification

  • Default daemon port 873 confirmed via crates/daemon/src/daemon.rs (DEFAULT_PORT) and crates/daemon/src/rsyncd_config/sections.rs.
  • stunnel directives (accept, connect, cert, key, verify, CAfile, sslVersionMin) cross-checked against the upstream stunnel-rsyncd.conf example and stunnel(8).
  • rsyncd.conf(5) directives (address, port, auth users, secrets file, hosts allow, hosts deny, use chroot, refuse options) verified against target/interop/upstream-src/rsync-3.4.1/rsyncd.conf.5.md.
  • host.example used consistently for the public hostname; 198.51.100.0/24 and 2001:db8::/32 (RFC 5737 / RFC 3849) used for documentation CIDRs.
  • All hyphens, no em-dashes (per project style).

Test plan

  • CI: fmt+clippy passes.
  • CI: nextest stable passes (no code touched, regression-only check).
  • CI: Windows stable, macOS stable, Linux musl stable build.
  • CI: interop validation passes.
  • Manual: relative links from SECURITY.md and README.md to docs/deployment/daemon-tls.md resolve on github.com.

SECURITY.md referenced TLS-in-front deployment but did not provide a
runnable recipe. Add `docs/deployment/daemon-tls.md` with concrete
configurations for the three supported terminators (stunnel, `ssh -L`,
HAProxy TCP mode), hardened systemd unit excerpts for each scenario,
and nftables/iptables/container-bridge rules that deny external access
to the daemon's loopback-bound 873/tcp port.

Cross-link from the SECURITY.md "Daemon TLS" hardening note and from
the README "Known Limitations / Architectural Trade-offs" section so
operators land on the recipe directly.
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label May 1, 2026
@oferchen oferchen merged commit 31ddf3d into master May 1, 2026
12 checks passed
@oferchen oferchen deleted the docs/daemon-tls-deployment-2052 branch May 1, 2026 21:07
oferchen added a commit that referenced this pull request May 5, 2026
…3518)

SECURITY.md referenced TLS-in-front deployment but did not provide a
runnable recipe. Add `docs/deployment/daemon-tls.md` with concrete
configurations for the three supported terminators (stunnel, `ssh -L`,
HAProxy TCP mode), hardened systemd unit excerpts for each scenario,
and nftables/iptables/container-bridge rules that deny external access
to the daemon's loopback-bound 873/tcp port.

Cross-link from the SECURITY.md "Daemon TLS" hardening note and from
the README "Known Limitations / Architectural Trade-offs" section so
operators land on the recipe directly.
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