Syncing Configuration
SecureLink uses a staged configuration model. Changes you make in the UI are not applied to the edge immediately. Instead, they are collected and pushed to the edge as a single batch when you trigger a sync. This ensures configuration changes are applied atomically and can be verified.
How Config Sync Works
- Edit: You make changes to the edge configuration in the UI (interfaces, WireGuard, routes, NAT, ACLs, etc.)
- Stage: Changes are saved to the orchestrator database and the edge is marked as having pending changes
- Sync: You click Sync Now (or an automatic sync is triggered), and the orchestrator builds a complete batch configuration
- Deliver: The batch configuration is published to the edge over MQTT
- Apply: The edge agent receives the configuration and applies it to VPP and associated services
- Confirm: The edge sends a confirmation message back to the orchestrator with a configuration hash
Dirty Indicator
When an edge has pending configuration changes, a yellow dot appears next to its config status throughout the UI. This "dirty" indicator is visible on:
- The edge row in the Edges list table
- The edge detail page header
- The Sync button itself
The indicator clears once the configuration is successfully synced and confirmed by the edge.
Sync States
| State | Color | Description |
|---|---|---|
| Synced | Green | The edge has confirmed it is running the current configuration. No pending changes. |
| Pending | Yellow | Configuration changes have been made in the UI but have not been pushed to the edge. |
| Applying | Blue | The configuration has been sent to the edge and is currently being applied. |
| Failed | Red | The edge was unable to apply the configuration or did not confirm within the expected time. |
Manual Sync
To manually sync configuration to an edge:
- Navigate to the edge's detail page
- If changes are pending, the Sync Now button will be active
- Click Sync Now
- The button changes to Syncing... while the operation is in progress
- Once the edge confirms, the status changes to Synced
Automatic Sync
Some configuration changes trigger an automatic sync without requiring you to click the Sync button. This typically occurs for changes that are considered safe to apply immediately and do not require manual review.
Config Confirmation and Hash Verification
After the edge applies a configuration, it sends a confirmation message back to the orchestrator. This confirmation includes a cryptographic hash of the applied configuration.
The orchestrator compares the hash in the edge's confirmation message against the hash of the configuration it sent. If the hashes match, the orchestrator marks the configuration as Synced. If the hashes do not match, the configuration is marked as Failed, indicating the edge did not apply the intended configuration.
This hash verification ensures that the exact configuration you defined in the UI is what is running on the edge, providing end-to-end configuration integrity.
Troubleshooting a Failed Sync
If a configuration sync fails, follow these steps:
- Check edge connectivity: Verify the edge is online and reporting heartbeats. An offline edge cannot receive configuration updates.
- Review the configuration: Look for invalid values such as overlapping IP ranges, duplicate port numbers, or conflicting ACL rules.
- Check edge logs: Use the SSH access or Monitoring tab to review the edge agent's logs for specific error messages about why the configuration was rejected.
- Retry the sync: After correcting any issues, click Sync Now again to reattempt the configuration push.
If the problem persists, the edge may need to be investigated via SSH. See SSH Access for instructions.
Under the Hood
This section provides additional technical detail about how config sync works internally. You do not need this information for day-to-day operations, but it can be helpful for advanced troubleshooting.
When you click Sync Now, the orchestrator builds a batch message containing:
- Sequence number — An incrementing counter that identifies this configuration version. The edge echoes it back in its confirmation so the orchestrator knows which version was applied.
- Config hash — A SHA-256 hash of the entire configuration. The edge computes its own hash after applying and sends it back. If the hashes match, the orchestrator knows the exact configuration it intended is what is running on the device.
- Commands — An ordered list of handler-specific configurations (interfaces, tunnels, routing, NAT, ACLs, services, monitoring). Commands are applied in eight dependency-ordered phases — for example, interfaces are configured before tunnels, and tunnels before routing — to prevent errors caused by missing dependencies.
If an edge reboots or loses its MQTT connection, it may end up running an older configuration version. When the edge reconnects and reports its current sequence number, the orchestrator detects that it is behind the latest version. After a brief stabilization delay (to allow VPP to fully start), the orchestrator automatically re-pushes the latest configuration. No manual intervention is required — the system is self-healing.
Additionally, when an edge agent first starts up, it proactively requests its configuration from the orchestrator rather than waiting passively. If the orchestrator is temporarily unreachable, the agent retries with increasing delays until it succeeds.
For the complete technical specification of the config sync pipeline — including all seven steps, the dirty flag lifecycle, phase dependency diagrams, and device-specific differences — see Config Sync Pipeline in the Admin Guide.