From f2362086efef4aa1f089d6bd16f3cf92f69a4a71 Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Tue, 24 Mar 2026 20:37:42 -0700 Subject: [PATCH 1/3] Deploy Tor Snowflake proxy on ringtail MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add snowflake-proxy as a native systemd service on ringtail to help censored users reach the Tor network. This is a bridge proxy, not an exit node — traffic exits through Tor exit nodes elsewhere. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../deploy-snowflake-proxy.feature.md | 1 + docs/reference/infrastructure/ringtail.md | 9 +++ docs/reference/services/snowflake-proxy.md | 74 +++++++++++++++++++ nixos/ringtail/configuration.nix | 26 +++++++ service-versions.yaml | 7 ++ 5 files changed, 117 insertions(+) create mode 100644 docs/changelog.d/deploy-snowflake-proxy.feature.md create mode 100644 docs/reference/services/snowflake-proxy.md diff --git a/docs/changelog.d/deploy-snowflake-proxy.feature.md b/docs/changelog.d/deploy-snowflake-proxy.feature.md new file mode 100644 index 0000000..e34af2b --- /dev/null +++ b/docs/changelog.d/deploy-snowflake-proxy.feature.md @@ -0,0 +1 @@ +Add Tor Snowflake proxy on ringtail as a systemd service to support anti-censorship efforts. diff --git a/docs/reference/infrastructure/ringtail.md b/docs/reference/infrastructure/ringtail.md index 95d6ee2..d5bbd91 100644 --- a/docs/reference/infrastructure/ringtail.md +++ b/docs/reference/infrastructure/ringtail.md @@ -86,6 +86,15 @@ argocd cluster add default --name k3s-ringtail ## Systemd Services +### Snowflake Proxy + +A Tor [[snowflake-proxy]] that helps censored users reach the Tor network. Runs as a simple systemd service using the `snowflake` nixpkgs package. The proxy is not a Tor exit node — it only bridges encrypted WebRTC connections to Tor relays. + +| Property | Value | +|----------|-------| +| **Service unit** | `snowflake-proxy.service` | +| **Metrics** | `localhost:9999/metrics` (Prometheus) | + ### Forgejo Actions Runner A native Forgejo Actions runner (`ringtail-nix-builder`) runs as a systemd service via the NixOS `services.gitea-actions-runner` module. It builds containers using `nix-build` and pushes them to Zot via `skopeo`. diff --git a/docs/reference/services/snowflake-proxy.md b/docs/reference/services/snowflake-proxy.md new file mode 100644 index 0000000..2322c5f --- /dev/null +++ b/docs/reference/services/snowflake-proxy.md @@ -0,0 +1,74 @@ +--- +title: Snowflake Proxy +modified: 2026-03-24 +tags: + - service + - privacy + - anti-censorship +--- + +# Snowflake Proxy + +Tor Snowflake proxy that helps censored users reach the Tor network. Runs as a native systemd service on [[ringtail]]. + +## Quick Reference + +| Property | Value | +|----------|-------| +| **Host** | ringtail | +| **Type** | NixOS systemd service | +| **Package** | `pkgs.snowflake` (nixpkgs) | +| **Binary** | `proxy` | +| **Upstream** | https://snowflake.torproject.org/ | +| **Source** | https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake | +| **Metrics** | `localhost:9999/metrics` (Prometheus) | + +## Architecture + +Snowflake is a pluggable transport for Tor that uses WebRTC to provide short-lived proxies. The proxy: + +1. Polls the Tor broker for censored clients needing a bridge +2. Establishes a WebRTC connection with the client +3. Forwards the encrypted traffic to a Tor bridge (relay) + +**This proxy is NOT a Tor exit node.** Traffic exits through Tor exit nodes operated by others. The proxy operator cannot see traffic content (double-encrypted: WebRTC DTLS + Tor onion routing) and destination servers never see the proxy's IP. + +``` +Censored user ──[WebRTC/DTLS]──▶ THIS PROXY ──[encrypted]──▶ Tor bridge ──▶ Tor network ──▶ Exit node +``` + +## Configuration + +The service runs with default settings — no special configuration needed. Key defaults: + +| Setting | Value | +|---------|-------| +| **Broker** | `https://snowflake-broker.torproject.net/` | +| **Relay** | `wss://snowflake.torproject.net/` | +| **STUN** | Google + BlackBerry STUN servers | +| **Capacity** | Unlimited concurrent clients | +| **Summary interval** | 1 hour | +| **Metrics port** | 9999 (Prometheus format) | + +## Resource Usage + +Based on community reports, a Snowflake proxy typically uses: + +- **Bandwidth:** ~5-10 GB/day (varies with client demand) +- **Memory:** Under 100 MB +- **CPU:** Negligible + +## Legal Considerations + +Running a Snowflake proxy carries very low legal risk in the US: + +- Traffic does not exit from the proxy's IP (exit nodes are elsewhere) +- Content is not visible to the proxy operator (end-to-end encrypted) +- No known legal cases against Snowflake proxy operators worldwide +- EFF and Tor Project both classify this as minimal-risk activity +- US intermediary protections (Section 230, ECPA) apply + +## Related + +- [[ringtail]] - Host machine +- [[architecture]] - Overall system design diff --git a/nixos/ringtail/configuration.nix b/nixos/ringtail/configuration.nix index db682f6..c4b8919 100644 --- a/nixos/ringtail/configuration.nix +++ b/nixos/ringtail/configuration.nix @@ -492,6 +492,32 @@ in unqualified-search-registries = ["registry.ops.eblu.me", "docker.io", "ghcr.io", "quay.io"] ''; + # Tor Snowflake proxy (anti-censorship bridge, not an exit node) + systemd.services.snowflake-proxy = { + description = "Tor Snowflake Proxy"; + after = [ "network-online.target" ]; + wants = [ "network-online.target" ]; + wantedBy = [ "multi-user.target" ]; + serviceConfig = { + ExecStart = "${pkgs.snowflake}/bin/proxy -metrics"; + DynamicUser = true; + Restart = "always"; + RestartSec = 10; + # Hardening + NoNewPrivileges = true; + ProtectSystem = "strict"; + ProtectHome = true; + PrivateTmp = true; + ProtectKernelTunables = true; + ProtectKernelModules = true; + ProtectControlGroups = true; + RestrictNamespaces = true; + RestrictRealtime = true; + MemoryDenyWriteExecute = true; + MemoryMax = "512M"; + }; + }; + # Forgejo Actions runner (nix container builder) services.gitea-actions-runner = { package = pkgs.forgejo-runner; diff --git a/service-versions.yaml b/service-versions.yaml index 321efe8..26c1d08 100644 --- a/service-versions.yaml +++ b/service-versions.yaml @@ -257,6 +257,13 @@ services: upstream-source: https://code.forgejo.org/forgejo/runner/releases notes: Forgejo runner on ringtail via nixpkgs; version tracks flake.lock + - name: snowflake-proxy + type: nixos + last-reviewed: 2026-03-24 + current-version: "2.11.0" + upstream-source: https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake/-/releases + notes: Tor Snowflake proxy on ringtail; anti-censorship bridge, not an exit node + - name: mealie type: argocd last-reviewed: 2026-03-16 -- 2.50.1 (Apple Git-155) From 508f7a957d4bd195735eda5309055c86a228eb1e Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Tue, 24 Mar 2026 20:44:56 -0700 Subject: [PATCH 2/3] Add Grafana dashboard and Prometheus scraping for snowflake proxy Bind metrics to 0.0.0.0 so Alloy can scrape from k8s, add HOST_IP downward API env var to alloy-ringtail DaemonSet, and add a dashboard with connection rate, traffic rate, country breakdown, and process memory. Co-Authored-By: Claude Opus 4.6 (1M context) --- argocd/manifests/alloy-ringtail/config.alloy | 10 + .../manifests/alloy-ringtail/daemonset.yaml | 4 + .../dashboards/configmap-snowflake-proxy.yaml | 323 ++++++++++++++++++ .../grafana-config/kustomization.yaml | 1 + nixos/ringtail/configuration.nix | 2 +- 5 files changed, 339 insertions(+), 1 deletion(-) create mode 100644 argocd/manifests/grafana-config/dashboards/configmap-snowflake-proxy.yaml diff --git a/argocd/manifests/alloy-ringtail/config.alloy b/argocd/manifests/alloy-ringtail/config.alloy index c63b478..e92ab0f 100644 --- a/argocd/manifests/alloy-ringtail/config.alloy +++ b/argocd/manifests/alloy-ringtail/config.alloy @@ -27,6 +27,16 @@ prometheus.relabel "instance" { } } +// ============== SNOWFLAKE PROXY METRICS ============== + +// Scrape Tor Snowflake proxy metrics from host (systemd service on port 9999) +prometheus.scrape "snowflake_proxy" { + targets = [{"__address__" = coalesce(sys.env("HOST_IP"), "localhost") + ":9999", "job" = "snowflake_proxy"}] + metrics_path = "/internal/metrics" + scrape_interval = "30s" + forward_to = [prometheus.relabel.instance.receiver] +} + // ============== KUBE-STATE-METRICS SCRAPE ============== prometheus.scrape "kube_state_metrics" { diff --git a/argocd/manifests/alloy-ringtail/daemonset.yaml b/argocd/manifests/alloy-ringtail/daemonset.yaml index fffd66e..cdd264d 100644 --- a/argocd/manifests/alloy-ringtail/daemonset.yaml +++ b/argocd/manifests/alloy-ringtail/daemonset.yaml @@ -33,6 +33,10 @@ spec: valueFrom: fieldRef: fieldPath: spec.nodeName + - name: HOST_IP + valueFrom: + fieldRef: + fieldPath: status.hostIP resources: requests: cpu: 50m diff --git a/argocd/manifests/grafana-config/dashboards/configmap-snowflake-proxy.yaml b/argocd/manifests/grafana-config/dashboards/configmap-snowflake-proxy.yaml new file mode 100644 index 0000000..089cae3 --- /dev/null +++ b/argocd/manifests/grafana-config/dashboards/configmap-snowflake-proxy.yaml @@ -0,0 +1,323 @@ +apiVersion: v1 +kind: ConfigMap +metadata: + name: grafana-dashboard-snowflake-proxy + namespace: monitoring + labels: + grafana_dashboard: "1" +data: + snowflake-proxy.json: | + { + "annotations": { "list": [] }, + "editable": true, + "fiscalYearStartMonth": 0, + "graphTooltip": 1, + "id": null, + "links": [], + "panels": [ + { + "datasource": { "type": "prometheus", "uid": "prometheus" }, + "fieldConfig": { + "defaults": { + "color": { "mode": "thresholds" }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { "color": "green", "value": null } + ] + } + }, + "overrides": [] + }, + "gridPos": { "h": 4, "w": 6, "x": 0, "y": 0 }, + "id": 1, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "textMode": "auto", + "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false } + }, + "title": "Total Connections", + "type": "stat", + "targets": [ + { + "expr": "sum(tor_snowflake_proxy_connections_total)", + "legendFormat": "connections", + "refId": "A" + } + ] + }, + { + "datasource": { "type": "prometheus", "uid": "prometheus" }, + "fieldConfig": { + "defaults": { + "color": { "mode": "thresholds" }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { "color": "green", "value": null } + ] + }, + "unit": "bytes" + }, + "overrides": [] + }, + "gridPos": { "h": 4, "w": 6, "x": 6, "y": 0 }, + "id": 2, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "textMode": "auto", + "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false } + }, + "title": "Total Traffic (Inbound)", + "type": "stat", + "targets": [ + { + "expr": "tor_snowflake_proxy_traffic_inbound_bytes_total", + "legendFormat": "inbound", + "refId": "A" + } + ] + }, + { + "datasource": { "type": "prometheus", "uid": "prometheus" }, + "fieldConfig": { + "defaults": { + "color": { "mode": "thresholds" }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { "color": "blue", "value": null } + ] + }, + "unit": "bytes" + }, + "overrides": [] + }, + "gridPos": { "h": 4, "w": 6, "x": 12, "y": 0 }, + "id": 3, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "textMode": "auto", + "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false } + }, + "title": "Total Traffic (Outbound)", + "type": "stat", + "targets": [ + { + "expr": "tor_snowflake_proxy_traffic_outbound_bytes_total", + "legendFormat": "outbound", + "refId": "A" + } + ] + }, + { + "datasource": { "type": "prometheus", "uid": "prometheus" }, + "fieldConfig": { + "defaults": { + "color": { "mode": "thresholds" }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { "color": "orange", "value": null } + ] + } + }, + "overrides": [] + }, + "gridPos": { "h": 4, "w": 6, "x": 18, "y": 0 }, + "id": 4, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "textMode": "auto", + "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false } + }, + "title": "Connection Timeouts", + "type": "stat", + "targets": [ + { + "expr": "tor_snowflake_proxy_connection_timeouts_total", + "legendFormat": "timeouts", + "refId": "A" + } + ] + }, + { + "datasource": { "type": "prometheus", "uid": "prometheus" }, + "fieldConfig": { + "defaults": { + "color": { "mode": "palette-classic" }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisLabel": "", + "drawStyle": "line", + "fillOpacity": 20, + "lineWidth": 2, + "pointSize": 5, + "showPoints": "never", + "spanNulls": false, + "stacking": { "group": "A", "mode": "none" } + }, + "unit": "cps" + }, + "overrides": [] + }, + "gridPos": { "h": 8, "w": 12, "x": 0, "y": 4 }, + "id": 5, + "options": { + "legend": { "calcs": ["mean", "max"], "displayMode": "table", "placement": "bottom" }, + "tooltip": { "mode": "multi", "sort": "desc" } + }, + "title": "Connection Rate", + "type": "timeseries", + "targets": [ + { + "expr": "rate(tor_snowflake_proxy_connections_total[5m])", + "legendFormat": "{{ country }}", + "refId": "A" + } + ] + }, + { + "datasource": { "type": "prometheus", "uid": "prometheus" }, + "fieldConfig": { + "defaults": { + "color": { "mode": "palette-classic" }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisLabel": "", + "drawStyle": "line", + "fillOpacity": 20, + "lineWidth": 2, + "pointSize": 5, + "showPoints": "never", + "spanNulls": false, + "stacking": { "group": "A", "mode": "none" } + }, + "unit": "Bps" + }, + "overrides": [] + }, + "gridPos": { "h": 8, "w": 12, "x": 12, "y": 4 }, + "id": 6, + "options": { + "legend": { "calcs": ["mean", "max"], "displayMode": "table", "placement": "bottom" }, + "tooltip": { "mode": "multi", "sort": "desc" } + }, + "title": "Traffic Rate", + "type": "timeseries", + "targets": [ + { + "expr": "rate(tor_snowflake_proxy_traffic_inbound_bytes_total[5m])", + "legendFormat": "inbound", + "refId": "A" + }, + { + "expr": "rate(tor_snowflake_proxy_traffic_outbound_bytes_total[5m])", + "legendFormat": "outbound", + "refId": "B" + } + ] + }, + { + "datasource": { "type": "prometheus", "uid": "prometheus" }, + "fieldConfig": { + "defaults": { + "color": { "mode": "palette-classic" }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisLabel": "", + "drawStyle": "bars", + "fillOpacity": 80, + "lineWidth": 1, + "pointSize": 5, + "showPoints": "never", + "spanNulls": false, + "stacking": { "group": "A", "mode": "normal" } + } + }, + "overrides": [] + }, + "gridPos": { "h": 8, "w": 12, "x": 0, "y": 12 }, + "id": 7, + "options": { + "legend": { "calcs": ["sum"], "displayMode": "table", "placement": "right", "sortBy": "Total", "sortDesc": true }, + "tooltip": { "mode": "multi", "sort": "desc" } + }, + "title": "Connections by Country", + "type": "timeseries", + "targets": [ + { + "expr": "increase(tor_snowflake_proxy_connections_total[1h])", + "legendFormat": "{{ country }}", + "refId": "A" + } + ] + }, + { + "datasource": { "type": "prometheus", "uid": "prometheus" }, + "fieldConfig": { + "defaults": { + "color": { "mode": "palette-classic" }, + "custom": { + "axisBorderShow": false, + "axisCenteredZero": false, + "axisLabel": "", + "drawStyle": "line", + "fillOpacity": 10, + "lineWidth": 2, + "pointSize": 5, + "showPoints": "never", + "spanNulls": false, + "stacking": { "group": "A", "mode": "none" } + }, + "unit": "bytes" + }, + "overrides": [] + }, + "gridPos": { "h": 8, "w": 12, "x": 12, "y": 12 }, + "id": 8, + "options": { + "legend": { "calcs": ["lastNotNull"], "displayMode": "table", "placement": "bottom" }, + "tooltip": { "mode": "multi", "sort": "desc" } + }, + "title": "Process Memory", + "type": "timeseries", + "targets": [ + { + "expr": "process_resident_memory_bytes{job=\"snowflake_proxy\"}", + "legendFormat": "RSS", + "refId": "A" + }, + { + "expr": "process_virtual_memory_bytes{job=\"snowflake_proxy\"}", + "legendFormat": "Virtual", + "refId": "B" + } + ] + } + ], + "schemaVersion": 39, + "tags": ["snowflake", "tor", "anti-censorship"], + "templating": { "list": [] }, + "time": { "from": "now-24h", "to": "now" }, + "timepicker": {}, + "timezone": "browser", + "title": "Snowflake Proxy", + "uid": "snowflake-proxy", + "version": 1 + } diff --git a/argocd/manifests/grafana-config/kustomization.yaml b/argocd/manifests/grafana-config/kustomization.yaml index 6412e8b..a6e8000 100644 --- a/argocd/manifests/grafana-config/kustomization.yaml +++ b/argocd/manifests/grafana-config/kustomization.yaml @@ -27,6 +27,7 @@ resources: - dashboards/configmap-forgejo.yaml - dashboards/configmap-tempo.yaml - dashboards/configmap-alerts.yaml + - dashboards/configmap-snowflake-proxy.yaml # TeslaMate dashboards are fetched by the init-teslamate-dashboards init # container in the Grafana deployment, sourced from mirrors/teslamate on forge. # See argocd/manifests/grafana/deployment.yaml for the version pin. diff --git a/nixos/ringtail/configuration.nix b/nixos/ringtail/configuration.nix index c4b8919..6e18d0c 100644 --- a/nixos/ringtail/configuration.nix +++ b/nixos/ringtail/configuration.nix @@ -499,7 +499,7 @@ in wants = [ "network-online.target" ]; wantedBy = [ "multi-user.target" ]; serviceConfig = { - ExecStart = "${pkgs.snowflake}/bin/proxy -metrics"; + ExecStart = "${pkgs.snowflake}/bin/proxy -metrics -metrics-address 0.0.0.0"; DynamicUser = true; Restart = "always"; RestartSec = 10; -- 2.50.1 (Apple Git-155) From 86226c94db11dae54325f244e3f2bf7fa9d7b0f6 Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Tue, 24 Mar 2026 20:48:28 -0700 Subject: [PATCH 3/3] Add geoip databases for snowflake proxy country metrics MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit NixOS doesn't have /usr/share/tor/geoip — point the proxy at pkgs.tor.geoip derivation paths instead. Co-Authored-By: Claude Opus 4.6 (1M context) --- nixos/ringtail/configuration.nix | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/nixos/ringtail/configuration.nix b/nixos/ringtail/configuration.nix index 6e18d0c..7d948a2 100644 --- a/nixos/ringtail/configuration.nix +++ b/nixos/ringtail/configuration.nix @@ -499,7 +499,12 @@ in wants = [ "network-online.target" ]; wantedBy = [ "multi-user.target" ]; serviceConfig = { - ExecStart = "${pkgs.snowflake}/bin/proxy -metrics -metrics-address 0.0.0.0"; + ExecStart = toString [ + "${pkgs.snowflake}/bin/proxy" + "-metrics" "-metrics-address" "0.0.0.0" + "-geoipdb" "${pkgs.tor.geoip}/share/tor/geoip" + "-geoip6db" "${pkgs.tor.geoip}/share/tor/geoip6" + ]; DynamicUser = true; Restart = "always"; RestartSec = 10; -- 2.50.1 (Apple Git-155)