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:

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

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

Note: Providing --tls-ca/-t automatically upgrades ws:// to wss:// if you forget the protocol.

Example Profile with SSL

socktop wss://server:3000

Profile:

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
}