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

```
