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:

# 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
The private key (key.pem) is created with mode 0600; agents also tighten permissions on existing keys at startup

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:

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:

[Service]
ExecStart=/usr/local/bin/socktop_agent --enableSSL --port 8443

Reload and restart:

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:

# Copy certificate from agent host
scp user@agent-host:~/.config/socktop_agent/tls/cert.pem ~/socktop-agent-cert.pem

Connect with certificate pinning:

# 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

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 per host.

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:

# 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

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):

{
  "profiles": {
    "local": {
      "url": "ws://127.0.0.1:3000/ws"
    },
    "rpi-master": {
      "url": "wss://rpi-master:8443/ws",
      "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/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.

Keyboard shortcuts