Clarify sensor proxy HTTPS workflow in docs
This commit is contained in:
rcourtman
parent
a278b52b5e
commit
b77330b1be
3 changed files with 26 additions and 31 deletions
36
SECURITY.md
36
SECURITY.md
|
|
@ -38,34 +38,14 @@ environment where `PULSE_DOCKER=true`/`/.dockerenv` is detected.
|
|||
|
||||
#### Migration Path (Production)
|
||||
|
||||
1. **Deploy `pulse-sensor-proxy` on each Proxmox host**
|
||||
1. **Install the sensor proxy on the Proxmox host that runs Pulse**
|
||||
```bash
|
||||
curl -o /usr/local/bin/pulse-sensor-proxy \
|
||||
https://github.com/rcourtman/pulse/releases/latest/download/pulse-sensor-proxy
|
||||
chmod +x /usr/local/bin/pulse-sensor-proxy
|
||||
curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/scripts/install-sensor-proxy.sh | \
|
||||
bash -s -- --ctid <pulse-lxc-id> --pulse-server https://pulse.example.com:7655
|
||||
```
|
||||
2. **Create a systemd unit** (`/etc/systemd/system/pulse-sensor-proxy.service`)
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Pulse Temperature Sensor Proxy
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=root
|
||||
ExecStart=/usr/local/bin/pulse-sensor-proxy
|
||||
Restart=on-failure
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
3. **Enable and start the service**
|
||||
```bash
|
||||
systemctl daemon-reload
|
||||
systemctl enable --now pulse-sensor-proxy
|
||||
```
|
||||
4. **Restart the Pulse container** so it binds to the proxy socket. The
|
||||
container will automatically fall back to socket-based temperature polling.
|
||||
- For Docker or standalone hosts where Pulse cannot mount the socket (or when collecting temps from *other* nodes), run the installer with `--standalone --http-mode` so each host exposes its own HTTPS endpoint on port 8443.
|
||||
2. **Let the installer manage the hardened systemd unit** – it creates the dedicated `pulse-sensor-proxy` user, installs TLS material, and restarts the service safely.
|
||||
3. **Restart the Pulse container** so it binds to `/run/pulse-sensor-proxy` (for local temps) and registers the HTTPS proxy (for remote temps). The backend automatically prefers the HTTPS proxy, then the socket, and never stores SSH keys in the container.
|
||||
|
||||
#### Removing Old SSH Keys
|
||||
|
||||
|
|
@ -85,9 +65,9 @@ docker exec pulse rm -rf /home/pulse/.ssh/id_ed25519*
|
|||
┌─────────────────────────────────────┐
|
||||
│ Proxmox Host │
|
||||
│ ┌───────────────────────────────┐ │
|
||||
│ │ pulse-sensor-proxy (root) │ │
|
||||
│ │ pulse-sensor-proxy (svc user)│ │
|
||||
│ │ · Runs sensors -j │ │
|
||||
│ │ · Exposes Unix socket only │ │
|
||||
│ │ · Exposes Unix socket + TLS │ │
|
||||
│ └───────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ │ /run/pulse-sensor-proxy.sock
|
||||
|
|
|
|||
|
|
@ -425,6 +425,10 @@ The sensor proxy reads `/etc/pulse-sensor-proxy/config.yaml` (or the path suppli
|
|||
| `allow_idmapped_root` | bool | `true` | Governs acceptance of ID-mapped root callers. |
|
||||
| `allowed_idmap_users` | list(string) | `["root"]` | Restricts which ID-mapped usernames are accepted. |
|
||||
| `metrics_address` | string | `default` (maps to `127.0.0.1:9127`) | Set to `"disabled"` to turn metrics off. |
|
||||
| `http_enabled` | bool | `false` | Enables the HTTPS listener (`pulse-sensor-proxy --http-mode`). Required for remote nodes. |
|
||||
| `http_listen_addr` | string | `:8443` | Bind address for the HTTPS server. Use `0.0.0.0:8443` to listen on all interfaces. |
|
||||
| `http_tls_cert` / `http_tls_key` | string | empty | Absolute paths to the TLS certificate and private key used by the HTTPS listener. |
|
||||
| `http_auth_token` | string | empty | Bearer token the Pulse server must present in the `Authorization` header. Generate 32+ random bytes. |
|
||||
| `max_ssh_output_bytes` | int | `1048576` (1 MiB) | Maximum stdout size accepted from remote sensors before aborting. |
|
||||
| `require_proxmox_hostkeys` | bool | `false` | When `true`, refuse new nodes unless their host keys come from the Proxmox cluster store (no ssh-keyscan fallback). |
|
||||
| `rate_limit.per_peer_interval_ms` | int | `1000` | Milliseconds between allowed RPCs per UID. Set `>=100` in production. |
|
||||
|
|
@ -437,6 +441,16 @@ rate_limit:
|
|||
per_peer_burst: 10 # allow 10-node sweep
|
||||
```
|
||||
|
||||
All HTTP settings can also be supplied via environment variables for ephemeral deployments:
|
||||
|
||||
| Environment variable | Mirrors config key |
|
||||
| --- | --- |
|
||||
| `PULSE_SENSOR_PROXY_HTTP_ENABLED` | `http_enabled` |
|
||||
| `PULSE_SENSOR_PROXY_HTTP_ADDR` | `http_listen_addr` |
|
||||
| `PULSE_SENSOR_PROXY_HTTP_TLS_CERT` | `http_tls_cert` |
|
||||
| `PULSE_SENSOR_PROXY_HTTP_TLS_KEY` | `http_tls_key` |
|
||||
| `PULSE_SENSOR_PROXY_HTTP_AUTH_TOKEN` | `http_auth_token` |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Automatic Updates
|
||||
|
|
|
|||
|
|
@ -301,7 +301,7 @@ When you need to provision the proxy yourself (for example via your own automati
|
|||
- **Proxmox LXC:** append `lxc.mount.entry: /run/pulse-sensor-proxy run/pulse-sensor-proxy none bind,create=dir 0 0` to `/etc/pve/lxc/<CTID>.conf` and restart the container.
|
||||
- **Docker:** bind mount `/run/pulse-sensor-proxy` into the container (`- /run/pulse-sensor-proxy:/run/pulse-sensor-proxy:ro`).
|
||||
|
||||
After the container restarts, the backend will automatically use the proxy. To refresh SSH keys on cluster nodes (e.g., after adding a new node), SSH to your Proxmox host and re-run the setup script: `curl -fsSL https://get.pulsenode.com/install-proxy.sh | bash -s -- --ctid <your-container-id>`
|
||||
After the container restarts, the backend will automatically use the proxy. To refresh SSH keys on cluster nodes (e.g., after adding a new node), SSH to your Proxmox host and re-run the setup script: `curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/scripts/install-sensor-proxy.sh | bash -s -- --ctid <your-container-id>`
|
||||
|
||||
### Post-install Verification
|
||||
|
||||
|
|
@ -1080,7 +1080,8 @@ cp id_ed25519.pub id_ed25519.pub.backup
|
|||
ssh-keygen -t ed25519 -f id_ed25519 -N "" -C "pulse-sensor-proxy-rotated"
|
||||
|
||||
# 3. Re-run setup to push keys to cluster
|
||||
curl -fsSL https://get.pulsenode.com/install-proxy.sh | bash -s -- --ctid <your-container-id>
|
||||
curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/scripts/install-sensor-proxy.sh | \
|
||||
bash -s -- --ctid <your-container-id>
|
||||
|
||||
# 4. Verify temperature data still works in Pulse UI
|
||||
```
|
||||
|
|
@ -1278,7 +1279,7 @@ test -S /run/pulse-sensor-proxy/pulse-sensor-proxy.sock && echo "Socket OK" || e
|
|||
**New Cluster Node Not Showing Temperatures:**
|
||||
1. Ensure lm-sensors installed: `ssh root@new-node "sensors -j"`
|
||||
2. Proxy auto-discovers on next poll (may take up to 1 minute)
|
||||
3. Re-run the setup script to configure SSH keys on the new node: `curl -fsSL https://get.pulsenode.com/install-proxy.sh | bash -s -- --ctid <CTID>`
|
||||
3. Re-run the setup script to configure SSH keys on the new node: `curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/scripts/install-sensor-proxy.sh | bash -s -- --ctid <CTID>`
|
||||
|
||||
**Permission Denied Errors:**
|
||||
1. Verify socket permissions: `ls -l /run/pulse-sensor-proxy/pulse-sensor-proxy.sock`
|
||||
|
|
|
|||
Loading…
Reference in a new issue