bitcoin-knots, fulcrum, datum-gateway: add and use the socket_proxy role

Three near-identical hosts: edge plays become one role plus three short
calls. 183 lines removed, 34 added, plus a 111-line role.

Verified before touching any playbook: all six live units on vipy reproduced
byte-identically. Then --limit edge --check per playbook - bitcoin-knots and
fulcrum changed=0; datum-gateway changed=2, both attributable to the already
known caddy_site comment line and the Reload caddy handler it triggers.
The 6 units and 14 Caddy files on the hosts are byte-identical afterwards.

PLAN_4 claimed these three plays had "no behavioural drift at all". That was
wrong - it came from a diff truncated by head -60. The live bitcoin-p2p-proxy
units carry four settings this playbook never wrote:

  .socket   Documentation=, FreeBind=true
  .service  Documentation=, TimeoutStopSec=5,
            StandardOutput=journal, StandardError=journal

FreeBind is the one that matters: it lets the socket bind to an address that
is not up yet, so without it the socket can fail to start on boot. Running
the bitcoin-knots playbook would have stripped it. Same class of hazard as
headscale. The role expresses all four; bitcoin-p2p is the only caller that
passes any.

Also: UFW treats the rule comment as part of the rule. datum-stratum's live
comment is "DATUM Gateway Stratum public access" but the role's derived
default produced "DATUM Stratum public access", which rewrote the rule.
Caught in the dry-run; datum now passes the comment explicitly.

Two deliberate differences from the original, both documented in the README:
ignore_errors: yes on the upstream check became failed_when: false, and the
handler restarts the .socket, which drops connections open through it - it
fires only when a unit file actually changes.

The inert Uptime Kuma TCP monitor blocks stay in the playbooks rather than
being pulled into a new role (12/12/18 guarded tasks).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

ansible/roles/socket_proxy/README.md

@@ -0,0 +1,62 @@
+# `socket_proxy`
+
+Exposes a service running on a private Tailscale host through a public TCP port
+on an edge machine, using `systemd-socket-proxyd`. Writes a `.socket` and a
+`.service` unit, enables the socket, opens the UFW port, and checks the upstream
+is reachable.
+
+## Usage
+
+```yaml
+- ansible.builtin.include_role:
+    name: socket_proxy
+  vars:
+    socket_proxy_name: fulcrum-ssl          # -> fulcrum-ssl-proxy.{socket,service}
+    socket_proxy_description: "Fulcrum SSL" # -> "Fulcrum SSL Proxy Socket"
+    socket_proxy_listen_port: "{{ fulcrum_ssl_port }}"
+    socket_proxy_upstream_host: "{{ fulcrum_tailscale_hostname }}"
+```
+
+`socket_proxy_upstream_port` defaults to `socket_proxy_listen_port`, which is
+what all three current callers want.
+
+## Optional unit settings
+
+These exist because the **live** `bitcoin-p2p-proxy` units on vipy carried
+settings the playbook never wrote. Somebody added them by hand, so running
+`deploy_bitcoin_knots_playbook.yml` would have silently removed them:
+
+| Variable | Emits | Why it matters |
+|---|---|---|
+| `socket_proxy_free_bind` | `FreeBind=true` in `[Socket]` | Lets the socket bind to an address that is not up yet. Without it the socket can fail to start on boot. |
+| `socket_proxy_documentation` | `Documentation=` in both units | Cosmetic. |
+| `socket_proxy_timeout_stop_sec` | `TimeoutStopSec=` | Bounds how long a stop can hang. |
+| `socket_proxy_log_to_journal` | `StandardOutput=journal` + `StandardError=journal` | Cosmetic on modern systemd, which defaults to the journal anyway. |
+
+Only `bitcoin-p2p` passes any of them.
+
+## `socket_proxy_ufw_comment`
+
+Defaults to `"<description> public access"`, which reproduces the live rule
+comment for bitcoin-p2p and fulcrum-ssl. **datum-stratum must pass it
+explicitly** — its live comment is `DATUM Gateway Stratum public access` while
+the derived default would be `DATUM Stratum public access`, and UFW treats the
+comment as part of the rule, so the mismatch rewrites the rule on every run.
+
+## The upstream check never fails the play
+
+`wait_for` on the upstream carries `failed_when: false`. The proxy is correctly
+configured whether or not the backend happens to be up, and this is the one task
+that depends on another machine. The original plays used `ignore_errors: yes`,
+which prints a red "ignoring" line; `failed_when: false` is the quieter
+equivalent.
+
+## Restarts
+
+The handler restarts the `.socket`, not the `.service` — that is what picks up a
+changed unit; the service is started by the socket on the next connection.
+
+**Restarting a socket drops connections that are currently open through it.**
+For bitcoin-p2p that means peers reconnect; for datum-stratum it means a mining
+client has to reconnect and may lose in-flight shares. The handler only fires
+when a unit file actually changes.

ansible/roles/socket_proxy/defaults/main.yml

@@ -0,0 +1,17 @@
+---
+# Required
+socket_proxy_name: ""              # "bitcoin-p2p" -> bitcoin-p2p-proxy.{socket,service}
+socket_proxy_description: ""       # "Bitcoin P2P" -> "Bitcoin P2P Proxy Socket"
+socket_proxy_listen_port: 0        # public port on the edge host
+socket_proxy_upstream_host: ""     # Tailscale hostname, e.g. "knots-box"
+
+# Optional
+socket_proxy_upstream_port: ""     # defaults to socket_proxy_listen_port
+socket_proxy_documentation: ""     # Documentation= in both units
+socket_proxy_free_bind: false      # FreeBind=true: bind before the address is up
+socket_proxy_timeout_stop_sec: ""  # TimeoutStopSec=
+socket_proxy_log_to_journal: false # StandardOutput/StandardError=journal
+
+# Firewall
+socket_proxy_ufw_proto: tcp
+socket_proxy_ufw_comment: ""       # defaults to "<description> public access"

ansible/roles/socket_proxy/handlers/main.yml

@@ -0,0 +1,8 @@
+---
+# Restarting the .socket is what picks up a changed unit; the .service is
+# started by the socket on the next connection.
+- name: Restart socket proxy
+  ansible.builtin.systemd:
+    name: "{{ socket_proxy_name }}-proxy.socket"
+    state: restarted
+    daemon_reload: yes

ansible/roles/socket_proxy/tasks/main.yml

@@ -0,0 +1,54 @@
+---
+- name: Assert socket_proxy parameters are sane
+  ansible.builtin.assert:
+    that:
+      - socket_proxy_name | length > 0
+      - socket_proxy_description | length > 0
+      - socket_proxy_listen_port | int > 0
+      - socket_proxy_upstream_host | length > 0
+    fail_msg: >-
+      socket_proxy: '{{ socket_proxy_name | default("<unnamed>") }}' needs a name,
+      a description, a listen port and an upstream host.
+    quiet: true
+
+- name: "Create the {{ socket_proxy_name }}-proxy socket unit"
+  ansible.builtin.template:
+    src: proxy.socket.j2
+    dest: "/etc/systemd/system/{{ socket_proxy_name }}-proxy.socket"
+    owner: root
+    group: root
+    mode: '0644'
+  notify: Restart socket proxy
+
+- name: "Create the {{ socket_proxy_name }}-proxy service unit"
+  ansible.builtin.template:
+    src: proxy.service.j2
+    dest: "/etc/systemd/system/{{ socket_proxy_name }}-proxy.service"
+    owner: root
+    group: root
+    mode: '0644'
+  notify: Restart socket proxy
+
+- name: "Enable and start the {{ socket_proxy_name }}-proxy socket"
+  ansible.builtin.systemd:
+    name: "{{ socket_proxy_name }}-proxy.socket"
+    enabled: yes
+    state: started
+    daemon_reload: yes
+
+- name: "Allow the {{ socket_proxy_name }} port through UFW"
+  community.general.ufw:
+    rule: allow
+    port: "{{ socket_proxy_listen_port | string }}"
+    proto: "{{ socket_proxy_ufw_proto }}"
+    comment: "{{ socket_proxy_ufw_comment | default(socket_proxy_description ~ ' public access', true) }}"
+
+# Reachability of the upstream over Tailscale. Deliberately non-fatal: the proxy
+# is still correctly configured if the backend happens to be down, and this is
+# the one check that depends on another machine being up.
+- name: "Verify {{ socket_proxy_upstream_host }} is reachable over Tailscale"
+  ansible.builtin.wait_for:
+    host: "{{ socket_proxy_upstream_host }}"
+    port: "{{ socket_proxy_upstream_port | default(socket_proxy_listen_port, true) }}"
+    timeout: 10
+  failed_when: false

ansible/roles/socket_proxy/templates/proxy.service.j2

@@ -0,0 +1,18 @@
+[Unit]
+Description={{ socket_proxy_description }} Proxy to {{ socket_proxy_upstream_host }}
+{% if socket_proxy_documentation %}
+Documentation={{ socket_proxy_documentation }}
+{% endif %}
+Requires={{ socket_proxy_name }}-proxy.socket
+After=network.target
+
+[Service]
+Type=notify
+ExecStart=/lib/systemd/systemd-socket-proxyd {{ socket_proxy_upstream_host }}:{{ socket_proxy_upstream_port | default(socket_proxy_listen_port, true) }}
+{% if socket_proxy_timeout_stop_sec %}
+TimeoutStopSec={{ socket_proxy_timeout_stop_sec }}
+{% endif %}
+{% if socket_proxy_log_to_journal %}
+StandardOutput=journal
+StandardError=journal
+{% endif %}

ansible/roles/socket_proxy/templates/proxy.socket.j2

@@ -0,0 +1,14 @@
+[Unit]
+Description={{ socket_proxy_description }} Proxy Socket
+{% if socket_proxy_documentation %}
+Documentation={{ socket_proxy_documentation }}
+{% endif %}
+
+[Socket]
+ListenStream={{ socket_proxy_listen_port }}
+{% if socket_proxy_free_bind %}
+FreeBind=true
+{% endif %}
+
+[Install]
+WantedBy=sockets.target

ansible/services/bitcoin-knots/deploy_bitcoin_knots_playbook.yml

@@ -753,62 +753,21 @@
     uptime_kuma_api_url: "https://{{ subdomains.uptime_kuma }}.{{ root_domain }}"
 
   tasks:
-    - name: Create Bitcoin P2P proxy socket unit
-      copy:
-        dest: /etc/systemd/system/bitcoin-p2p-proxy.socket
-        content: |
-          [Unit]
-          Description=Bitcoin P2P Proxy Socket
-
-          [Socket]
-          ListenStream={{ bitcoin_p2p_port }}
-
-          [Install]
-          WantedBy=sockets.target
-        owner: root
-        group: root
-        mode: '0644'
-      notify: Restart bitcoin-p2p-proxy socket
-
-    - name: Create Bitcoin P2P proxy service unit
-      copy:
-        dest: /etc/systemd/system/bitcoin-p2p-proxy.service
-        content: |
-          [Unit]
-          Description=Bitcoin P2P Proxy to {{ bitcoin_tailscale_hostname }}
-          Requires=bitcoin-p2p-proxy.socket
-          After=network.target
-
-          [Service]
-          Type=notify
-          ExecStart=/lib/systemd/systemd-socket-proxyd {{ bitcoin_tailscale_hostname }}:{{ bitcoin_p2p_port }}
-        owner: root
-        group: root
-        mode: '0644'
-
-    - name: Reload systemd daemon
-      systemd:
-        daemon_reload: yes
-
-    - name: Enable and start Bitcoin P2P proxy socket
-      systemd:
-        name: bitcoin-p2p-proxy.socket
-        enabled: yes
-        state: started
-
-    - name: Allow Bitcoin P2P port through UFW
-      ufw:
-        rule: allow
-        port: "{{ bitcoin_p2p_port | string }}"
-        proto: tcp
-        comment: "Bitcoin P2P public access"
-
-    - name: Verify connectivity to knots-box via Tailscale
-      wait_for:
-        host: "{{ bitcoin_tailscale_hostname }}"
-        port: "{{ bitcoin_p2p_port }}"
-        timeout: 10
-      ignore_errors: yes
+    - name: Expose Bitcoin P2P through a socket proxy
+      ansible.builtin.include_role:
+        name: socket_proxy
+      vars:
+        socket_proxy_name: bitcoin-p2p
+        socket_proxy_description: "Bitcoin P2P"
+        socket_proxy_listen_port: "{{ bitcoin_p2p_port }}"
+        socket_proxy_upstream_host: "{{ bitcoin_tailscale_hostname }}"
+        # These four were added by hand on vipy and were NOT in this playbook;
+        # writing the unit without them would have dropped FreeBind, which lets
+        # the socket bind before the address is up.
+        socket_proxy_documentation: "https://github.com/bitcoin/bitcoin"
+        socket_proxy_free_bind: true
+        socket_proxy_timeout_stop_sec: 5
+        socket_proxy_log_to_journal: true
 
     - name: Display public endpoint
       when: uptime_kuma_enabled | default(false)
@@ -931,8 +890,3 @@
         - /tmp/setup_bitcoin_p2p_tcp_monitor.py
         - /tmp/ansible_bitcoin_p2p_config.yml
 
-  handlers:
-    - name: Restart bitcoin-p2p-proxy socket
-      systemd:
-        name: bitcoin-p2p-proxy.socket
-        state: restarted

ansible/services/datum-gateway/deploy_datum_gateway_playbook.yml

@@ -663,62 +663,17 @@
     uptime_kuma_api_url: "https://{{ subdomains.uptime_kuma }}.{{ root_domain }}"
 
   tasks:
-    - name: Create Stratum proxy socket unit
-      copy:
-        dest: /etc/systemd/system/datum-stratum-proxy.socket
-        content: |
-          [Unit]
-          Description=DATUM Stratum Proxy Socket
-
-          [Socket]
-          ListenStream={{ datum_gateway_stratum_port }}
-
-          [Install]
-          WantedBy=sockets.target
-        owner: root
-        group: root
-        mode: "0644"
-      notify: Restart datum-stratum-proxy socket
-
-    - name: Create Stratum proxy service unit
-      copy:
-        dest: /etc/systemd/system/datum-stratum-proxy.service
-        content: |
-          [Unit]
-          Description=DATUM Stratum Proxy to {{ datum_tailscale_hostname }}
-          Requires=datum-stratum-proxy.socket
-          After=network.target
-
-          [Service]
-          Type=notify
-          ExecStart=/lib/systemd/systemd-socket-proxyd {{ datum_tailscale_hostname }}:{{ datum_gateway_stratum_port }}
-        owner: root
-        group: root
-        mode: "0644"
-
-    - name: Reload systemd daemon
-      systemd:
-        daemon_reload: yes
-
-    - name: Enable and start Stratum proxy socket
-      systemd:
-        name: datum-stratum-proxy.socket
-        enabled: yes
-        state: started
-
-    - name: Allow Stratum port through UFW
-      ufw:
-        rule: allow
-        port: "{{ datum_gateway_stratum_port | string }}"
-        proto: tcp
-        comment: "DATUM Gateway Stratum public access"
-
-    - name: Verify connectivity to knots-box Stratum via Tailscale
-      wait_for:
-        host: "{{ datum_tailscale_hostname }}"
-        port: "{{ datum_gateway_stratum_port }}"
-        timeout: 10
-      ignore_errors: yes
+    - name: Expose the DATUM Stratum port through a socket proxy
+      ansible.builtin.include_role:
+        name: socket_proxy
+      vars:
+        socket_proxy_name: datum-stratum
+        socket_proxy_description: "DATUM Stratum"
+        socket_proxy_listen_port: "{{ datum_gateway_stratum_port }}"
+        socket_proxy_upstream_host: "{{ datum_tailscale_hostname }}"
+        # Matches the UFW comment already on vipy; the derived default would
+        # have said "DATUM Stratum" and rewritten the rule.
+        socket_proxy_ufw_comment: "DATUM Gateway Stratum public access"
 
     - name: Display public Stratum endpoint
       when: uptime_kuma_enabled | default(false)
@@ -845,8 +800,3 @@
         - /tmp/setup_datum_stratum_tcp_monitor.py
         - /tmp/ansible_datum_stratum_config.yml
 
-  handlers:
-    - name: Restart datum-stratum-proxy socket
-      systemd:
-        name: datum-stratum-proxy.socket
-        state: restarted

ansible/services/fulcrum/deploy_fulcrum_playbook.yml

@@ -552,62 +552,14 @@
     uptime_kuma_api_url: "https://{{ subdomains.uptime_kuma }}.{{ root_domain }}"
 
   tasks:
-    - name: Create Fulcrum SSL proxy socket unit
-      copy:
-        dest: /etc/systemd/system/fulcrum-ssl-proxy.socket
-        content: |
-          [Unit]
-          Description=Fulcrum SSL Proxy Socket
-
-          [Socket]
-          ListenStream={{ fulcrum_ssl_port }}
-
-          [Install]
-          WantedBy=sockets.target
-        owner: root
-        group: root
-        mode: '0644'
-      notify: Restart fulcrum-ssl-proxy socket
-
-    - name: Create Fulcrum SSL proxy service unit
-      copy:
-        dest: /etc/systemd/system/fulcrum-ssl-proxy.service
-        content: |
-          [Unit]
-          Description=Fulcrum SSL Proxy to {{ fulcrum_tailscale_hostname }}
-          Requires=fulcrum-ssl-proxy.socket
-          After=network.target
-
-          [Service]
-          Type=notify
-          ExecStart=/lib/systemd/systemd-socket-proxyd {{ fulcrum_tailscale_hostname }}:{{ fulcrum_ssl_port }}
-        owner: root
-        group: root
-        mode: '0644'
-
-    - name: Reload systemd daemon
-      systemd:
-        daemon_reload: yes
-
-    - name: Enable and start Fulcrum SSL proxy socket
-      systemd:
-        name: fulcrum-ssl-proxy.socket
-        enabled: yes
-        state: started
-
-    - name: Allow Fulcrum SSL port through UFW
-      ufw:
-        rule: allow
-        port: "{{ fulcrum_ssl_port | string }}"
-        proto: tcp
-        comment: "Fulcrum SSL public access"
-
-    - name: Verify connectivity to fulcrum-box via Tailscale
-      wait_for:
-        host: "{{ fulcrum_tailscale_hostname }}"
-        port: "{{ fulcrum_ssl_port }}"
-        timeout: 10
-      ignore_errors: yes
+    - name: Expose Fulcrum SSL through a socket proxy
+      ansible.builtin.include_role:
+        name: socket_proxy
+      vars:
+        socket_proxy_name: fulcrum-ssl
+        socket_proxy_description: "Fulcrum SSL"
+        socket_proxy_listen_port: "{{ fulcrum_ssl_port }}"
+        socket_proxy_upstream_host: "{{ fulcrum_tailscale_hostname }}"
 
     - name: Display public endpoint
       when: uptime_kuma_enabled | default(false)
@@ -730,9 +682,4 @@
         - /tmp/setup_fulcrum_ssl_tcp_monitor.py
         - /tmp/ansible_fulcrum_ssl_config.yml
 
-  handlers:
-    - name: Restart fulcrum-ssl-proxy socket
-      systemd:
-        name: fulcrum-ssl-proxy.socket
-        state: restarted