SecureLink Installer CLI

The SecureLink Installer (securelink-installer) is a universal provisioning tool that configures all SecureLink device types — dedicated edges, MTGEs, and connectors — using a one-time deployment token.

Overview

The installer handles the complete device lifecycle:

• Checks system prerequisites and installs Docker if needed
• Claims a one-time deployment token from the orchestrator
• Receives the full device bundle (identity, certificates, infrastructure endpoints, registry credentials)
• Configures VPP (DPDK or AF_PACKET), mTLS MQTT, SSH access, Docker Compose, and systemd services
• Pulls Docker images from the private registry
• Supports in-place upgrades and factory reset

Requirements

• Ubuntu 22.04 or later (x86_64)
• Root access (sudo)
• Network access to the SecureLink orchestrator
• Internet access (for Docker installation and image pull)

Docker Not Required

The installer will automatically install Docker if it's not already present. No manual Docker setup is needed.

Commands

install — Provision a New Device

Provisions a brand-new device using a one-time deployment token.

sudo ./securelink-installer install \
  --token NLZ-XXXX-XXXX-XXXX \
  --url https://edge-api.vsm.netlinkz.dev

Flag	Required	Description
--token	Yes	Deployment token (format: NLZ-XXXX-XXXX-XXXX)
--url	Yes	Orchestrator API URL (HTTPS recommended)
--insecure	No	Skip TLS certificate verification
--ca-cert	No	Path to custom CA certificate
--data-dir	No	Override data directory (default: /var/lib/edge or /var/lib/connector)
--force	No	Skip confirmation prompts (for automated deployments)

What Install Does

The installer performs 15 steps in order:

Step	Action	Details
1	Preflight checks	Validates architecture (x86_64), kernel (5.4+), memory (4GB+), disk (10GB+). Auto-installs missing tools (curl, ip, ethtool, lspci). For DPDK mode, checks IOMMU is enabled.
2	Install Docker	Checks if Docker is installed. If not, downloads and runs the official Docker install script from get.docker.com, enables the service, and adds the current user to the docker group.
3	Claim token	Calls the orchestrator's provision API (POST /api/v2/provision/device), validates the token, and receives the complete device bundle.
4	Display summary	Shows device type, name, GUID, serial number, VPP mode, and tenant for confirmation.
5	Save identity	Writes identity.json to the data directory (root-owned, 0600).
6	Save discovery config	Writes discovery.json (enables future upgrades without re-provisioning).
7	Save certificates	Writes mTLS CA cert, device cert, and private key. If the MQTT broker uses a separate CA, it is appended to the trust store automatically. (Edges and MTGEs only)
8	Configure SSH access	Generates Ed25519 host key, requests host certificate from the CA, configures sshd with TrustedUserCAKeys for admin access, and writes tunnel configuration for the agent's built-in tunnel manager. (Edges and MTGEs only)
9	Configure dataplane	For DPDK mode: sets up hugepages (2 GB), loads VFIO kernel module, detects and binds NICs to vfio-pci (management interface automatically excluded). For AF_PACKET: skipped.
10	Generate VPP config	Creates vpp.conf and govpp.conf for the appropriate dataplane mode.
11	Pull Docker images	If registry credentials are provided in the bundle, logs in to the private registry, pulls agent-mqtt-cli and suricata images, and re-tags for local use. Falls back to pre-loaded images if registry is unavailable.
12	Create directories	Sets up /opt/netlinkz/config/, log directories, state directories, and a minimal Bird configuration stub.
13	Generate Docker Compose	Creates edge-compose.yml or connector-compose.yml with all required services and mTLS MQTT configuration.
14	Generate Alloy config	Creates alloy-edge.alloy for log collection via Grafana Alloy. (Edges and MTGEs only)
15	Create systemd service	Writes edge-agent.service or connector-agent.service, enables, and starts all services.

Preflight and Docker install run before the token is claimed

If prerequisites fail (e.g., IOMMU not enabled for DPDK), the token is not consumed. You can fix the issue, reboot if needed, and re-run the installer with the same token.

DPDK Auto-Detection

When the orchestrator indicates DPDK mode, the installer interactively sets up the dataplane:

1. IOMMU check — Verifies intel_iommu=on or amd_iommu=on in kernel command line. If missing, prints GRUB configuration instructions and exits (token is not consumed).
2. Hugepages — Allocates 1024 x 2 MB hugepages (2 GB total), persisted via sysctl.
3. VFIO module — Loads vfio-pci kernel module and persists for reboot.
4. PCI detection — Scans PCI bus for Ethernet controllers via lspci.
5. Management interface protection — Automatically detects the interface carrying the default route (SSH/management) and excludes it from DPDK binding.
6. NIC binding — Unbinds selected NICs from kernel drivers and binds to vfio-pci.
7. Restore service — Creates a systemd service that re-applies DPDK bindings on reboot.

MQTT Configuration

The installer configures the edge agent for mTLS MQTT:

• Protocol: ssl:// with TLS 1.2/1.3
• Server validation: Uses MQTT_TLS_SERVER_NAME for SNI verification against the broker's certificate
• Client authentication: Edge certificate and private key (from the provision bundle)
• Trust store: Contains both the tenant CA and the MQTT broker CA

Non-Interactive Mode

For automated deployments, use --force to skip all confirmation prompts:

sudo ./securelink-installer install \
  --token NLZ-XXXX-XXXX-XXXX \
  --url https://edge-api.vsm.netlinkz.dev \
  --force

---

upgrade — Update an Existing Device

Regenerates configuration files without re-provisioning. Identity, certificates, and SSH access are preserved.

sudo ./securelink-installer upgrade --force

Flag	Required	Description
--data-dir	No	Override data directory (auto-detected)
--images-dir	No	Directory containing Docker image tarballs to load
--force	No	Skip confirmation prompts

What Upgrade Does

1. Load discovery config — Reads discovery.json from the data directory
2. Load Docker images — Scans images directory for .tar.gz / .tar files and loads via docker load
3. Stop services — Stops Docker Compose and systemd service, removes orphaned containers
4. Regenerate Docker Compose — Recreates compose file from discovery config using latest templates
5. Regenerate Alloy config — Updates logging configuration
6. Regenerate VPP config — Updates VPP startup configuration
7. Validate SSH certificate — Checks host certificate validity and refreshes if expiring (< 30 days)
8. Migrate tunnel config — If upgrading from v2.0, migrates SSH tunnel from legacy systemd service to agent-managed tunnel
9. Start services — Restarts the systemd service

Typical Upgrade Workflow

# Using build-lab.sh (builds + deploys in one step)
./scripts/build-lab.sh .250

# Or manually:
scp securelink-installer agent-mqtt-cli-production.tar.gz edge@192.168.0.250:/tmp/
ssh edge@192.168.0.250 "sudo /tmp/securelink-installer upgrade --images-dir /tmp/ --force"

note

Upgrade requires discovery.json to exist. Devices provisioned before this feature was introduced must be re-installed with a new token.

---

status — Check Device State

Displays provisioning state and service health.

securelink-installer status

Section	Shows
Identity	Device type, name, GUID, serial number, tenant
Discovery	Install timestamp, last upgrade, orchestrator URL, MQTT broker, Loki URL
Certificates	CA cert, device cert, private key (present or missing)
DPDK	PCI address-to-interface bindings (if applicable)
Configuration	Paths to compose, Alloy, VPP config files (present or missing)
Services	Systemd service status (active / inactive)
Containers	Running Docker containers

---

factory-reset — Return to Factory State

Removes all provisioned data. The device must be re-provisioned with a new token.

sudo ./securelink-installer factory-reset

Irreversible

Factory reset permanently removes identity, certificates, SSH keys, configuration files, and DPDK bindings. The device cannot reconnect to the orchestrator without a new deployment token.

---

Deployment Token

Tokens are generated in the SecureLink management UI (Admin > System Settings > Deployment Tokens) or via the API. Each token:

• Follows the format NLZ-XXXX-XXXX-XXXX (12-character body, 3 segments)
• Uses an unambiguous character set (excludes I, O, 0, 1)
• Is single-use — once claimed, the token cannot be reused
• Must be used before it expires (configurable, default 7 days)
• Can be linked to a specific device (pre-registered) or unlinked (any device can claim it)

Device Type Differences

Feature	Dedicated Edge	MTGE	Connector
VPP	DPDK or AF_PACKET	DPDK or AF_PACKET	None
Certificates	mTLS (CA + device cert + key)	mTLS	mTLS
SSH Tunnel	Yes (reverse tunnel to bastion)	Yes	No
DPDK Support	Optional	Optional	No
Suricata	Yes	Yes	No
Data Directory	/var/lib/edge	/var/lib/edge	/var/lib/connector
Compose File	edge-compose.yml	edge-compose.yml (EDGE_MODE=mtge)	connector-compose.yml

Services Started

Edge / MTGE

Container	Purpose
vpp-agent	VPP data plane (DPDK or AF_PACKET)
agent-mqtt-cli	Edge control agent (config sync, status publishing, SSH tunnel)
alloy	Log collection to Loki (Grafana Alloy)
dnsmasq	DNS / DHCP relay
bird	BGP routing daemon
suricata	IDS/IPS engine
strongswan	IPSec / IKEv2 daemon

Connector

Container	Purpose
connector-agent	Lightweight agent (WireGuard, iptables, routing)
bird	BGP routing daemon
strongswan	IPSec / IKEv2 daemon

Verification

After installation, verify the device is operational:

# Check installer status
securelink-installer status

# Check systemd service
systemctl status edge-agent

# Check running containers
docker ps

# Check agent MQTT connection
docker logs agent-mqtt-cli 2>&1 | tail -20

# Check VPP interfaces (edges/MTGEs only)
docker exec vpp-agent vppctl show interface

The device should appear in the SecureLink management UI within 60 seconds (the first inform interval).

Troubleshooting

Token claim fails

• Verify the token hasn't already been used (tokens are single-use)
• Check network connectivity to the orchestrator URL
• Ensure the token hasn't expired

Docker installation fails

• Verify internet connectivity: curl -fsSL https://get.docker.com
• If behind a proxy, configure Docker proxy settings manually
• Try installing Docker manually: curl -fsSL https://get.docker.com | sh

IOMMU not enabled (DPDK)

The installer will print GRUB configuration instructions:

1. Edit /etc/default/grub
2. Add intel_iommu=on iommu=pt to GRUB_CMDLINE_LINUX
3. Run sudo update-grub
4. Reboot
5. Re-run the installer with the same token

DPDK binding fails

• Verify VT-d / IOMMU is enabled in BIOS
• Check that NICs support VFIO: ls /sys/kernel/iommu_groups/
• Run lspci -v to confirm Ethernet controllers are detected

MQTT connection fails

• Check the agent logs: docker logs agent-mqtt-cli 2>&1 | grep -i mqtt
• Verify the MQTT broker is reachable: openssl s_client -connect mqtt.vsm.netlinkz.dev:8883
• Check certificates: openssl x509 -in /var/lib/edge/certs/edge.crt -noout -dates

Services won't start

• Check Docker is running: systemctl status docker
• Check service logs: journalctl -u edge-agent -f
• Verify Docker images are loaded: docker images

Device not appearing in UI

• Check MQTT connectivity: docker logs agent-mqtt-cli 2>&1 | grep -i connect
• Verify the MQTT URL uses ssl:// (not tcp://): check edge-compose.yml
• Check the orchestrator URL is reachable from the device