docs: 1.60 update — fix fabricated content, add kill/platform/known-issues docs
- Rewrite configuration.md from the real CLI/env surface (the page documented ~10 agent flags, /etc/default/socktop-agent, and env vars that don't exist) - Fix token docs: SOCKTOP_TOKEN env + URL query param; client -t is --tls-ca, not a token flag - Rewrite agent-integration.md: requests are plain text (get_metrics, ...), not JSON; correct proto schema, real GPU/metrics fields, 1.60 additive fields (sampled_at_ms, timestamp_us, journal notice) - Fix connector.md: real ConnectorConfig builder API, error variants, examples list; bump to 1.60 - Document the 1.60 process kill feature (usage/general + keyboard-mouse) - TLS: document exact-match pinning semantics, cert rotation, key perms, upgrade-clients-first note; genericize profile example - Agent service: journal access setup (systemd-journal group), packaged- service cert path, drop fake positional-port form, fix broken fences - New pages: Platform Notes (Windows/macOS/RISC-V/Pi kernel tip, ARMv7 --no-default-features) and Known Issues - Fedora build prereqs: libdrm-devel + libdrm-amdgpu (closes socktop#35) - Freshen intro (1.60, new demo apng, correct crates.io names, GitHub Releases link), quick-start, upgrading (order notes, stale-binary tip), zellij (remove invalid pane_template example) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
jasonwitty
+31
-20
@@ -1,6 +1,16 @@
|
||||
# TLS Configuration
|
||||
|
||||
Secure your socktop agent connections with TLS/SSL encryption.
|
||||
|
||||
## How Verification Works
|
||||
|
||||
The client supports two modes:
|
||||
|
||||
- **Certificate pinning (default).** The certificate the agent presents must be **byte-identical** to one of the certificates in the PEM file you pass with `--tls-ca/-t`. Nothing else is accepted — not other certificates chained to the same CA, not renewed certificates. The pinned PEM may contain multiple certificates (useful during rotation: ship old + new together). Expiry is irrelevant for pinned connections. This mode is designed for the agent's self-signed certificates on home networks.
|
||||
- **Hostname verification (`--verify-hostname`).** Standard WebPKI validation against the certificate as a root, including hostname/SAN checking.
|
||||
|
||||
> **Upgrade note:** client versions before 1.60 did **not** enforce pinning — with `--verify-hostname` off, any server certificate was silently accepted. If you use TLS, make sure your clients are 1.60 or newer.
|
||||
|
||||
### Enable TLS (Auto-Generated Certificate)
|
||||
|
||||
The agent automatically generates a self-signed certificate on first run when you enable TLS:
|
||||
@@ -13,6 +23,7 @@ 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
|
||||
- The private key (`key.pem`) is created with mode `0600`; agents also tighten permissions on existing keys at startup
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
@@ -67,19 +78,30 @@ socktop --tls-ca ~/socktop-agent-cert.pem wss://hostname:8443/ws
|
||||
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.
|
||||
**Notes:**
|
||||
|
||||
- Providing `--tls-ca/-t` automatically upgrades `ws://` to `wss://` if you forget the protocol.
|
||||
- Copy only `cert.pem` to clients — **never** the private key (`key.pem`); it stays on the agent.
|
||||
- You can monitor multiple agents by passing a different `--tls-ca` per invocation, or better, saving one [profile](../usage/connection-profiles.md) per host.
|
||||
|
||||
### Example Profile with SSL
|
||||
### Certificate Expiry and Rotation
|
||||
|
||||
The auto-generated certificate is valid for ~397 days. Pinned clients don't check expiry, but `--verify-hostname` clients do, and the agent won't regenerate an expired certificate on its own. To rotate:
|
||||
|
||||
```bash
|
||||
socktop wss://server:3000
|
||||
# On the agent host (adjust path if XDG_CONFIG_HOME is set, or
|
||||
# /var/lib/socktop/.config/socktop_agent/tls/ for the packaged service)
|
||||
rm ~/.config/socktop_agent/tls/cert.pem ~/.config/socktop_agent/tls/key.pem
|
||||
sudo systemctl restart socktop-agent # if running under systemd
|
||||
```
|
||||
|
||||
Profile:
|
||||
The agent generates a fresh pair on the next TLS start. Distribute the new `cert.pem` to clients. For a seamless rollover, append the new cert to the clients' pinned PEM first (both are accepted), then remove the old one after the agent switches.
|
||||
|
||||
### Example Profiles with TLS
|
||||
|
||||
Profiles store the pinned certificate path alongside the URL (`~/.config/socktop/profiles.json`):
|
||||
|
||||
```json
|
||||
File: /home/jasonw/.config/socktop/profiles.json
|
||||
{
|
||||
"profiles": {
|
||||
"local": {
|
||||
@@ -87,30 +109,19 @@ File: /home/jasonw/.config/socktop/profiles.json
|
||||
},
|
||||
"rpi-master": {
|
||||
"url": "wss://rpi-master:8443/ws",
|
||||
"tls_ca": "/home/jasonw/.config/socktop/rpi-master.pem",
|
||||
"tls_ca": "/home/user/.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",
|
||||
"tls_ca": "/home/user/.config/socktop/rpi-worker-1.pem",
|
||||
"metrics_interval_ms": 1000,
|
||||
"processes_interval_ms": 5000
|
||||
}
|
||||
},
|
||||
"version": 0
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Then connect with `socktop -P rpi-master`. See [Connection Profiles](../usage/connection-profiles.md).
|
||||
|
||||
+32
-48
@@ -1,56 +1,31 @@
|
||||
# Authentication Token
|
||||
|
||||
This guide covers token-based authentication for securing socktop agent connections.
|
||||
The agent can require a shared token from connecting clients. Without the correct token, the WebSocket connection is rejected.
|
||||
|
||||
- **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
|
||||
- **Access control** - only clients that know the token can connect
|
||||
- **Defense in depth** - combine with [TLS](./tls.md) so the token isn't sent in cleartext over untrusted networks
|
||||
|
||||
## Configuring Token Authentication
|
||||
## Agent: Setting the Token
|
||||
|
||||
### Agent Configuration
|
||||
The token is configured with the `SOCKTOP_TOKEN` environment variable. (There is no `--token` command-line flag.)
|
||||
|
||||
#### APT Installation
|
||||
|
||||
Edit `/etc/default/socktop-agent`:
|
||||
### Running Manually
|
||||
|
||||
```bash
|
||||
sudo nano /etc/default/socktop-agent
|
||||
SOCKTOP_TOKEN=changeme socktop_agent --port 3000
|
||||
```
|
||||
|
||||
Add your token:
|
||||
### Running as a systemd Service
|
||||
|
||||
```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:
|
||||
Add the environment variable with a drop-in (works for both APT and manual installs):
|
||||
|
||||
```bash
|
||||
sudo systemctl edit socktop-agent
|
||||
```
|
||||
|
||||
Add environment variable:
|
||||
|
||||
```ini
|
||||
[Service]
|
||||
Environment="TOKEN=7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
|
||||
Environment=SOCKTOP_TOKEN=changeme
|
||||
```
|
||||
|
||||
```bash
|
||||
@@ -58,24 +33,30 @@ sudo systemctl daemon-reload
|
||||
sudo systemctl restart socktop-agent
|
||||
```
|
||||
|
||||
### Client Configuration
|
||||
Alternatively, uncomment the `# Environment=SOCKTOP_TOKEN=changeme` line that ships in the packaged unit file.
|
||||
|
||||
#### Command Line
|
||||
## Client: Sending the Token
|
||||
|
||||
The client passes the token as a `token` query parameter in the WebSocket URL. Quote the URL so your shell doesn't interpret the `?`:
|
||||
|
||||
```bash
|
||||
# Pass token via command line
|
||||
socktop ws://server:3000 -t "7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
|
||||
socktop "ws://server:3000/ws?token=changeme"
|
||||
|
||||
# With TLS
|
||||
socktop --tls-ca /path/to/cert.pem "wss://server:8443/ws?token=changeme"
|
||||
```
|
||||
|
||||
#### Connection Profile
|
||||
**Warning:** the client's `-t` flag is short for `--tls-ca` (a certificate path), not for the token.
|
||||
|
||||
Add token to profile (`~/.config/socktop/profiles.json`):
|
||||
### In a Connection Profile
|
||||
|
||||
Store the token as part of the profile URL (`~/.config/socktop/profiles.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": {
|
||||
"secure-server": {
|
||||
"url": "ws://server.example.com:3000/ws?token=7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
|
||||
"url": "ws://server.example.com:3000/ws?token=changeme"
|
||||
}
|
||||
},
|
||||
"version": 0
|
||||
@@ -88,12 +69,15 @@ Then connect:
|
||||
socktop -P secure-server
|
||||
```
|
||||
|
||||
#### Environment Variable
|
||||
**Note:** the profiles file then contains the token in plaintext — keep its permissions restrictive.
|
||||
|
||||
## Generating a Strong Token
|
||||
|
||||
```bash
|
||||
# Set token in environment
|
||||
export SOCKTOP_TOKEN="7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
|
||||
|
||||
# Connect without specifying token
|
||||
socktop ws://server:3000
|
||||
openssl rand -base64 32
|
||||
```
|
||||
|
||||
## Recommendations
|
||||
|
||||
- On untrusted networks, always combine the token with [TLS](./tls.md); over plain `ws://` the token is visible to anyone who can capture traffic.
|
||||
- Rotate the token by updating `SOCKTOP_TOKEN` on the agent, restarting the service, and updating client profiles.
|
||||
|
||||
Reference in New Issue
Block a user