Add mdBook documentation with Ghostty-style sidebar

docs/src/security/tls.md

@@ -0,0 +1,116 @@
+# TLS Configuration
+
+Secure your socktop agent connections with TLS/SSL encryption.
+### Enable TLS (Auto-Generated Certificate)
+
+The agent automatically generates a self-signed certificate on first run when you enable TLS:
+
+```bash
+# The agent will auto-generate cert and key on first TLS run
+socktop_agent --enableSSL --port 8443
+```
+
+The certificate is stored at:
+- **Linux (XDG)**: `$XDG_CONFIG_HOME/socktop_agent/tls/cert.pem` (defaults to `~/.config/socktop_agent/tls/`)
+- The agent prints the certificate location on first run
+
+**Example output:**
+```
+socktop_agent: generated self-signed TLS certificate at /home/user/.config/socktop_agent/tls/cert.pem
+```
+
+**Optional: Custom SANs (Subject Alternative Names)**
+
+To include additional IPs or hostnames in the auto-generated certificate:
+
+```bash
+SOCKTOP_AGENT_EXTRA_SANS="192.168.1.101,myhost.internal" socktop_agent --enableSSL --port 8443
+```
+
+This prevents `NotValidForName` errors when connecting via IPs not in the default SAN list.
+
+### Systemd Service with TLS
+
+Edit `/etc/systemd/system/socktop-agent.service`:
+
+```ini
+[Service]
+ExecStart=/usr/local/bin/socktop_agent --enableSSL --port 8443
+```
+
+Reload and restart:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart socktop-agent
+
+# Check logs for certificate location
+sudo journalctl -u socktop-agent -f
+```
+
+### Connect with Client
+
+Copy the auto-generated certificate from the agent to your client machine:
+
+```bash
+# Copy certificate from agent host
+scp user@agent-host:~/.config/socktop_agent/tls/cert.pem ~/socktop-agent-cert.pem
+```
+
+Connect with certificate pinning:
+
+```bash
+# Connect with TLS and pin the server certificate
+socktop --tls-ca ~/socktop-agent-cert.pem wss://hostname:8443/ws
+
+# Short form
+socktop -t ~/socktop-agent-cert.pem wss://hostname:8443/ws
+```
+
+**Note:** Providing `--tls-ca/-t` automatically upgrades `ws://` to `wss://` if you forget the protocol.
+
+
+### Example Profile with SSL 
+
+```bash
+socktop wss://server:3000
+```
+
+Profile:
+
+```json
+File: /home/jasonw/.config/socktop/profiles.json
+{
+  "profiles": {
+    "local": {
+      "url": "ws://127.0.0.1:3000/ws"
+    },
+    "rpi-master": {
+      "url": "wss://rpi-master:8443/ws",
+      "tls_ca": "/home/jasonw/.config/socktop/rpi-master.pem",
+      "metrics_interval_ms": 1000,
+      "processes_interval_ms": 5000
+    },
+    "rpi-worker-1": {
+      "url": "wss://192.168.1.102:8443/ws",
+      "tls_ca": "/home/jasonw/.config/socktop/rpi-worker-1.pem",
+      "metrics_interval_ms": 1000,
+      "processes_interval_ms": 5000
+    },
+    "rpi-worker-2": {
+      "url": "ws://192.168.1.103:8443/ws",
+      "tls_ca": "/home/jasonw/.config/socktop/rpi-worker-2.pem",
+      "metrics_interval_ms": 1000,
+      "processes_interval_ms": 5000
+    },
+    "rpi-worker-3": {
+      "url": "ws://192.168.1.104:8443/ws",
+      "tls_ca": "/home/jasonw/.config/socktop/rpi-worker-3.pem",
+      "metrics_interval_ms": 1000,
+      "processes_interval_ms": 5000
+    }
+  },
+  "version": 0
+}
+
+```

docs/src/security/token.md

@@ -0,0 +1,99 @@
+# Authentication Token
+
+This guide covers token-based authentication for securing socktop agent connections.
+
+- **Access Control** - Only authorized clients can connect
+- **Security** - Prevent unauthorized monitoring of your systems
+- **Auditability** - Track which tokens are in use
+- **Flexibility** - Revoke and rotate tokens as needed
+
+## Configuring Token Authentication
+
+### Agent Configuration
+
+#### APT Installation
+
+Edit `/etc/default/socktop-agent`:
+
+```bash
+sudo nano /etc/default/socktop-agent
+```
+
+Add your token:
+
+```bash
+# Authentication token
+TOKEN=7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8=
+```
+
+Restart the service:
+
+```bash
+sudo systemctl restart socktop-agent
+```
+
+#### Cargo Installation
+
+Start the agent with the token:
+
+```bash
+socktop_agent --token "7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
+```
+
+Or with systemd service:
+
+```bash
+sudo systemctl edit socktop-agent
+```
+
+Add environment variable:
+
+```ini
+[Service]
+Environment="TOKEN=7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
+```
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart socktop-agent
+```
+
+### Client Configuration
+
+#### Command Line
+
+```bash
+# Pass token via command line
+socktop ws://server:3000 -t "7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
+```
+
+#### Connection Profile
+
+Add token to profile (`~/.config/socktop/profiles.json`):
+
+```json
+{
+  "profiles": {
+    "secure-server": {
+      "url": "ws://server.example.com:3000/ws?token=7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
+    }
+  },
+  "version": 0
+}
+```
+
+Then connect:
+
+```bash
+socktop -P secure-server
+```
+
+#### Environment Variable
+
+```bash
+# Set token in environment
+export SOCKTOP_TOKEN="7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
+
+# Connect without specifying token
+socktop ws://server:3000
+```