SSH Access

SecureLink provides secure SSH access to edge devices through a reverse tunnel architecture. Edges establish an outbound SSH tunnel to a cloud bastion host, and administrators connect through the bastion using short-lived user certificates.

How It Works

Admin (laptop)          Bastion (cloud)           Edge (site)
    │                       │                        │
    │  SSH via ProxyJump    │   Reverse tunnel       │
    ├──────────────────────►├◄───────────────────────┤
    │  (user certificate)   │   (tunnel key)         │
    │                       │   Port 11249           │

1. The edge opens a persistent reverse SSH tunnel to the bastion on port 22
2. The bastion forwards connections from the tunnel port (e.g., 11249) to the edge's SSH daemon
3. Administrators connect through the bastion using ProxyJump with a short-lived user certificate

No inbound firewall rules are needed on the edge. The edge initiates all connections outbound.

Setting Up SSH Access

SSH access is configured on the Edge Detail > SSH Access tab. The setup follows three steps:

Step 1: Generate Tunnel Key

Click Generate Tunnel Key to create an Ed25519 keypair for the reverse tunnel:

• The public key is registered on the bastion's authorized keys (fetched dynamically from the API)
• The private key is pushed to the edge via MQTT
• A tunnel port is allocated (unique per edge, range 10000-19999)

After key generation, the edge automatically establishes the reverse tunnel.

Step 2: Verify Tunnel Connection

The Reverse Tunnel status indicator shows:

Status	Meaning
Active (green)	Tunnel is connected and port is listening on bastion
Not Active (red)	Tunnel is down — check edge connectivity

The tunnel status is determined from VictoriaMetrics metrics pushed by the edge agent every 15 seconds. If the status shows inactive, use the tunnel control buttons:

• Start Tunnel — Sends MQTT command to start the tunnel process
• Restart Tunnel — Restarts an active tunnel (e.g., after key rotation)
• Stop Tunnel — Stops the tunnel process
• Health Check — Tests tunnel connectivity

Step 3: Generate User Certificate

Once the tunnel is active, click Generate User Certificate to create a short-lived SSH certificate:

1. A modal prompts for your SSH public key (e.g., ~/.ssh/id_ed25519.pub)
2. The API signs it with the tenant's SSH CA, creating a 24-hour certificate
3. Download the certificate file

The certificate grants access as edge or root user on the edge.

Connecting to the Edge

After downloading the certificate, open a terminal in your Downloads folder and paste the command shown in the UI:

ssh -o IdentitiesOnly=yes \
    -o IdentityFile=~/.ssh/id_ed25519 \
    -o CertificateFile=user-cert-<guid>.pub \
    -o StrictHostKeyChecking=no \
    -o ProxyCommand="ssh -o IdentitiesOnly=yes \
        -o IdentityFile=~/.ssh/id_ed25519 \
        -o CertificateFile=user-cert-<guid>.pub \
        -o StrictHostKeyChecking=no \
        -W localhost:<tunnel-port> root@ssh-bastion.vsm.netlinkz.dev" \
    edge@localhost

The UI provides this command with a copy button — no manual assembly needed.

One-Click Connection

The SSH Access tab shows a ready-to-paste command with all parameters filled in. Just download the cert, cd to Downloads, and paste.

Tunnel Reinitialize

If the edge has lost its tunnel keys (e.g., after a factory reset or disk wipe), use the Reinitialize Tunnel button. This:

1. Generates a new tunnel key pair (or re-pushes the existing one)
2. Sends the key to the edge via MQTT
3. The edge restarts the tunnel with the new credentials

Tunnel Metrics

The SSH Access tab displays live metrics from the edge:

Metric	Description
Connected	Whether the tunnel is currently active
Uptime	How long the tunnel has been connected
Reconnections	Number of times the tunnel has reconnected
Key Age	Days since the tunnel key was generated

These metrics are collected by the edge agent and pushed to VictoriaMetrics every 15 seconds.

Security Model

• Tunnel key: Ed25519 keypair generated per-edge. Private key stored on edge at /var/lib/edge-agent/ssh/tunnel_key.
• User certificates: Signed by the tenant's SSH CA. Valid for 24 hours. Principals: edge, root.
• Host certificates: Edge sshd presents a CA-signed host certificate. The bastion's TrustedUserCAKeys accepts user certs signed by any tenant CA.
• No passwords: All authentication is certificate-based. Password auth is disabled on both the bastion and edge.

SSH Is for Troubleshooting Only

SSH access is provided for diagnostics and troubleshooting. All routine edge configuration — interfaces, WireGuard, routing, NAT, ACLs — should be managed through the SecureLink UI. Changes made via the UI are tracked, versioned, and synchronized reliably.

Do Not Modify VPP Configuration via SSH

Never modify VPP configuration directly via SSH. The orchestrator manages VPP through its batch sync process and will override any manual changes on the next configuration sync.

What You Can Do via SSH

• View logs: docker logs agent-mqtt-cli, docker logs vpp-agent
• Check VPP status: docker exec vpp-agent vppctl show interface
• Network diagnostics: ping, traceroute, dig from the edge's perspective
• Verify connectivity: Confirm the edge can reach the MQTT broker, orchestrator, and DNS
• Check tunnel status: docker logs agent-mqtt-cli 2>&1 | grep tunnel