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:

• Claims a one-time deployment token from the orchestrator
• Receives the full device bundle (identity, certificates, infrastructure endpoints)
• Configures VPP (DPDK or AF_PACKET), Docker Compose, SSH tunnels, and systemd services
• Supports in-place upgrades and factory reset

Requirements

• Ubuntu 22.04 or later
• Docker installed and running
• Root access (sudo)
• Network access to the SecureLink orchestrator

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-XXXX \
  --url http://192.168.0.200:3001

Flag	Required	Description
--token	Yes	Deployment token (format: NLZ-XXXX-XXXX-XXXX-XXXX)
--url	Yes	Orchestrator URL
--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 13 steps in order:

1. Claim token — Calls the orchestrator's provision API, validates the token, and receives the complete device bundle (identity, certificates, infrastructure endpoints, device config)
2. Display summary — Shows device type, name, GUID, serial number, and tenant for confirmation
3. Save identity — Writes identity.json to the data directory (root-owned, 0600)
4. Save discovery config — Writes discovery.json (enables future upgrades without re-provisioning)
5. Save certificates — Writes mTLS CA cert, device cert, and private key (edges and MTGEs only)
6. Configure SSH tunnel — Generates Ed25519 host key, requests host certificate from the CA, creates reverse tunnel systemd service
7. Configure dataplane — For DPDK mode: sets up hugepages (2 GB), loads VFIO kernel module, binds NICs to vfio-pci. For AF_PACKET: skipped
8. Generate VPP config — Creates vpp.conf and govpp.conf for the appropriate dataplane mode
9. Create directories — Sets up /opt/netlinkz/config/, log directories, state directories
10. Generate Docker Compose — Creates edge-compose.yml or connector-compose.yml with all required services
11. Generate Promtail config — Creates logging configuration for Loki integration (edges and MTGEs only)
12. Create systemd service — Writes edge-agent.service or connector-agent.service
13. Start services — Runs systemctl daemon-reload, enable, and start

DPDK Auto-Detection

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

1. Scans PCI bus for Ethernet controllers via lspci
2. Displays detected NICs with vendor, current driver, and interface name
3. Prompts to bind all devices to VFIO (skipped with --force)
4. Unbinds NICs from their current driver and binds to vfio-pci
5. Creates a restore service that re-applies DPDK bindings on reboot
6. Allocates 1024 x 2 MB hugepages (2 GB total) and persists via sysctl

Non-Interactive Mode

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

sudo ./securelink-installer install \
  --token NLZ-XXXX-XXXX-XXXX-XXXX \
  --url http://192.168.0.200:3001 \
  --force

---

upgrade — Update an Existing Device

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

sudo ./securelink-installer upgrade

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
5. Regenerate Promtail config — Updates logging configuration
6. Regenerate VPP config — Updates VPP startup configuration
7. Start services — Restarts the systemd service

Typical Upgrade Workflow

# Copy new images and installer to the device
scp securelink-installer edge-images/*.tar.gz edge@192.168.0.250:/tmp/

# Run upgrade with new images
sudo ./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. Does not require root.

securelink-installer status

Flag	Required	Description
--data-dir	No	Override data directory (auto-detected)

Output Sections

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, promtail, 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

Flag	Required	Description
--force, -f	No	Skip confirmation prompt
--data-dir	No	Override data directory

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 when registering a new device. Each token:

• Follows the format NLZ-XXXX-XXXX-XXXX-XXXX
• Uses an unambiguous character set (excludes I, O, 0, 1 to avoid confusion)
• Is single-use — once claimed, the token cannot be reused
• Must be used before it expires

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	None
SSH Tunnel	Yes	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)
promtail	Log aggregation to Loki
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)

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

DPDK binding fails

• Verify VT-d / IOMMU is enabled in BIOS
• Check that NICs support SR-IOV or VFIO
• Run lspci -v to confirm Ethernet controllers are detected

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 | tail -20
• Verify certificates are valid: openssl x509 -in /var/lib/edge/certs/edge.crt -noout -dates
• Check the orchestrator URL is reachable from the device