Step 19: Configuration Management
Snapshot your configuration, see what changed, and restore an earlier version with one undoable step.
Full reference
For complete details and limitations, see the Configuration Management reference.
The Config Manager
Everything you have built so far (devices, alarms, dashboards, users, programs) is your configuration. The Config Manager app keeps a history of it: you take snapshots, compare them with the running system, and restore an earlier one if a change goes wrong.
The platform's own structure and the items your extensions install are not part of this history. They come back with the platform and extension versions, so a snapshot holds only what is yours, including any settings you changed on built-in items.
Opening the Config Manager
Click the ControlBird logo in the taskbar and select Config Manager. The app has three tabs:
- History: take snapshots, browse them, compare, and restore
- Remote: connect a Git repository for an off-node copy
- Backup: download or import a backup file
The status bar at the bottom shows whether the Config Manager is idle or busy, and the progress of a long operation.
Take a Snapshot
The list shows every snapshot, newest first. The latest one is marked HEAD.
Describe the state you are saving, for example Before adding Building 2.
It lists what was captured and anything intentionally left out. If nothing changed since the last snapshot, no new entry is added.
See What Changed
Make some changes in the other apps, then click Changes vs live on a snapshot. The list compares that snapshot with the running system:
Password and token values never appear in the list. When you are happy with the result, take another snapshot with a message that says what changed.
Restore a Snapshot
A dry run plans the restore and shows how many items would be created, moved, renamed, deleted, or updated. Nothing has changed yet.
If the running configuration differs from the latest snapshot, it is saved first as Before restore to ..., so you can always come back.
When the restore finishes, the dialog offers to restore that saved snapshot, which undoes the restore.
Your items keep their identity
Restored items keep their identity, so dashboards, alarms, and programs that point at them keep working. Extensions the snapshot used are installed again at the same versions.
Keep an Off-Node Copy
On the Remote tab, enter a Git repository URL, then click Save. For an HTTPS URL, also enter a username and token. For an SSH URL, click Generate key, copy the public key, and add it to the repository as a deploy key with write access. The node keeps the private key, and no one can read it back. From then on:
- Push sends your snapshots to the repository.
- Pull brings in snapshots pushed from elsewhere.
- Reset to remote replaces local history with the repository's when the two have diverged. The running configuration does not change until you restore.
The first SSH connection to a host trusts the host key it presents, for every node of the cluster. Trusted hosts lists each key with its SHA256 fingerprint, so you can compare it with the one your Git host publishes. If a host later presents a different key, pulls and pushes to it are refused. When the host really did change its key, click Remove next to the old one, and the next connection trusts the new key.
Prefer a file? On the Backup tab, pick a snapshot and click Download bundle. Import bundle adds a downloaded file to the history, ready to restore.
Best Practices
Bracket every significant change so you can compare it and roll it back.
Say what changed and why: Raised tank alarm limits for summer
Check the counts before confirming a restore, especially deletes.
A remote copy protects your history if the node itself is lost.
Troubleshooting
"Config Manager unavailable"
- Check the service: look at its status and log in Logs & Diagnostics
- Verify permissions: you need the Config Manager permission (Engineer role and above); downloading or importing a bundle also needs the Config Backup permission (Owner and Administrator only)
- Click Retry once the service is running
The Snapshot button is disabled
A restore is in progress. The banner at the top shows which snapshot is being restored; snapshots are available again when it finishes.
A restore asks me to confirm a different cluster
The snapshot came from another installation. Choose Restore anyway to continue, then enter again any passwords and tokens, since those were encrypted for the other installation.
I can't delete or rename an item
Items provided by the platform or by an installed extension cannot be deleted, renamed, or moved. You can still change their settings, and those changes are kept in your snapshots and across upgrades.