Skip to main content

MQTT Topic Reference

All communication between the SecureLink orchestrator and edge devices flows through MQTT. This page documents every topic, its direction, payload format, and which device types use it.

Broker​

SecureLink uses EMQX as the MQTT broker. After the initial bootstrap, all connections are authenticated using mutual TLS (mTLS) — both the broker and the connecting device present X.509 certificates signed by the same CA.

Naming Convention​

Topics follow a consistent naming convention:

PrefixDirectionMeaning
VSR/Southbound (API to Edge)Configuration and commands sent from the orchestrator to devices
VSRE/Northbound (Edge to API)Status, confirmations, and telemetry sent from devices to the orchestrator

The second segment is always the device's serial number, which uniquely identifies the device across all topics.

Complete Topic Table​

Southbound (API to Edge)​

TopicDevice TypesPurpose
VSR/{serial}/batchDedicated Edge, ConnectorFull batch configuration delivery
VSR/{serial}/batch/{tenantId}MTGEPer-tenant batch configuration delivery
VSR/{serial}/e2e-peeringDedicated Edge, ConnectorEdge-to-edge peering configuration (WireGuard or IPSec, supports dual tunnels)
edges/{guid}/commands/ssh-tunnel/{action}Dedicated Edge, MTGESSH tunnel management commands (start, stop, status)

Northbound (Edge to API)​

TopicDevice TypesPurpose
VSR/{serial}/informDedicated Edge, MTGEPeriodic status report (VPP interface statistics, WAN IP). Sent every 60 seconds.
VSR/{serial}/keepaliveMTGELightweight heartbeat. Sent every 30 seconds. Updates device last-seen time and transitions status to active.
VSRE/{serial}/config/confirmDedicated Edge, ConnectorBatch configuration confirmation (sequence number, config hash, success/failure, VPP mode).
VSRE/{serial}/config/confirm/{tenantId}MTGEPer-tenant batch configuration confirmation.
VSRE/{serial}/config/requestDedicated EdgeStartup configuration request. Sent when the agent boots and needs its current configuration. Uses exponential backoff on retry.
VSRE/{serial}/keepaliveConnectorConnector heartbeat. Sent every 30 seconds. Updates last-seen time and transitions status.
VSRE/{serial}/wireguard/statusDedicated Edge, Connectorwg0 (IoT) and connector WireGuard peer connection status — which peers are connected, last handshake times, bytes transferred.
VSRE/{serial}/wireguard-apps/statusDedicated Edgewg1 (Apps VPN) WireGuard peer connection status.
VSRE/{serial}/ipsec-apps/statusDedicated Edge, MTGEwg1 (Apps VPN) IKEv2 tunnel and SA status. Published every 45 seconds (20s offset).
VSRE/{serial}/suricata/alertsDedicated EdgeSuricata IDS/IPS alert data for security monitoring.
VSRE/{serial}/tenant-onboard/confirmMTGEConfirmation that a tenant's VRF and resources have been created on the gateway.
VSRE/{serial}/tenant-offboard/confirmMTGEConfirmation that a tenant's VRF and resources have been torn down.
edges/{guid}/responses/ssh-tunnel/{action}Dedicated Edge, MTGESSH tunnel management responses.
VSRE/{serial}/diag-{tool}/respDedicated EdgeDiagnostic tool responses (ping, traceroute, DNS lookup, etc.). Each tool has its own subtopic.
Topic Prefix Convention

Most topics use VSR/ (southbound) and VSRE/ (northbound), but some legacy topics like VSR/{serial}/inform and VSR/{serial}/keepalive use the VSR/ prefix in the northbound direction. The SSH tunnel topics use a GUID-based edges/{guid}/ prefix.

Example Payloads​

Batch Configuration (Southbound)​

A batch configuration message delivered to an edge:

{
  "rid": 1707753600000,
  "timestamp": 1707753600,
  "action": "batch",
  "params": {
    "operate": "sync",
    "seq_num": 42,
    "config_hash": "a1b2c3d4e5f6...",
    "commands": [
      {
        "index": 0,
        "topic": "interface",
        "body": {
          "interfaces": [
            { "name": "G0", "ip_address": "192.168.1.1/24", "enabled": true }
          ]
        }
      },
      {
        "index": 1,
        "topic": "wireguard",
        "body": {
          "interface_name": "wg0",
          "listen_port": 51820,
          "private_key": "...",
          "peers": [ ... ]
        }
      },
      {
        "index": 2,
        "topic": "static",
        "body": {
          "routes": [
            { "destination": "10.0.0.0/8", "next_hop": "192.168.1.254" }
          ]
        }
      }
    ]
  }
}

Key fields:

  • seq_num — Incrementing sequence number identifying this configuration version
  • config_hash — SHA-256 hash of the commands array, used for end-to-end verification
  • commands — Ordered list of handler configurations, applied in dependency order

Configuration Confirmation (Northbound)​

An edge confirming successful application of a batch:

{
  "serial": "EDGE-001",
  "seq_num": 42,
  "config_hash": "a1b2c3d4e5f6...",
  "status": "success",
  "applied_commands": 3,
  "failed_commands": 0,
  "vpp_mode": "DPDK",
  "timestamp": 1707753605
}

Key fields:

  • seq_num — Echoes back the sequence number that was applied
  • config_hash — Hash computed by the agent over what it actually applied (compared against the sent hash)
  • vpp_mode — Reports whether the edge is running DPDK or AF_PACKET mode
  • status — "success" or "failure"

Inform Message (Northbound)​

A periodic status report from an edge:

{
  "serial": "EDGE-001",
  "interfaces": [
    {
      "name": "GigabitEthernet0/0/0",
      "type": "dpdk",
      "ip_addresses": ["203.0.113.10/24"],
      "rx_packets": 1234567,
      "tx_packets": 987654,
      "link_up": true
    },
    {
      "name": "wg0",
      "type": "wireguard",
      "ip_addresses": ["10.100.0.1/24"],
      "rx_packets": 56789,
      "tx_packets": 43210,
      "link_up": true
    }
  ],
  "timestamp": 1707753660
}

The orchestrator extracts the WAN IP from the first interface matching the WAN type and updates the device record.

Debugging Tips​

Monitoring MQTT Traffic​

To observe messages flowing through the broker, you can subscribe to topics using the MQTT client tools:

warning

Monitoring production MQTT traffic requires broker credentials and should only be done during troubleshooting. The messages contain device configuration data.

Common patterns to monitor:

PatternWhat You'll See
VSR/+/batchAll batch configuration pushes to dedicated edges and connectors
VSR/+/informAll edge inform messages (useful for verifying an edge is reporting)
VSRE/+/config/confirmAll configuration confirmations (useful for verifying sync completion)
VSR/{specific-serial}/#All traffic for a specific device

EMQX Dashboard​

The EMQX broker provides a web dashboard showing connected clients, active subscriptions, message rates, and connection history. This is useful for verifying whether a specific edge device is currently connected to the broker.

Further Reading​