Configuration Management

Config Manager keeps a history of your configuration. Take a snapshot before and after a change, compare any snapshot with what is running now, and restore an earlier snapshot when a change goes wrong. Every restore can itself be undone. Connect a Git repository to keep an off-node copy, or download a backup file.

Reach for Config Manager before a large change, after commissioning a site, when you want to know what changed since last week, or when you need to move a configuration to a replacement node.

What is backed up

ControlBird separates your configuration from the configuration that the platform and your installed extensions provide. Config Manager versions only yours:

• Included: everything you created or changed, such as devices, mappers, alarms, users, roles, schematics, faceplates, dashboards, programs, historian tables, and your own entity types and fields. Changes you make to the settings of built-in or extension-provided items are included too, and they are kept when the platform or the extension is upgraded.
• Installed extensions: each snapshot records which extensions were installed and at which versions, so a restore can install them again.
• Not included: the platform's own structure and the items an extension installs. These come back with the platform version and the extension versions, so there is nothing to back up. Live values, statuses, alarm states, and sign-in sessions are not configuration and are never included.
• Passwords and other secrets are stored encrypted for the nodes of your cluster, and for your recovery key if you create one, never in readable form.
• AI chat history is not backed up, so a restore does not bring it back. Backups taken before this change may still hold chat history in the repository's already-pushed history. Deleting it is your choice.
• Compiled programs are backed up, so a restored node runs its programs at once, without reaching the compiler.
• The automatic backup setting is not part of a backup, so restoring never switches your backups off.

Built-in and extension-provided items cannot be deleted, renamed, or moved, but you can change their settings. This keeps every upgrade able to update them safely.

The Config Manager app

Open Config Manager from the ControlBird menu. It has three tabs and a status bar that shows whether an operation is running.

Snapshots and history

• Snapshot records the current configuration with a message. If nothing changed since the last snapshot, no new entry is added.
• Snapshots are also taken automatically, every hour by default. In Automatic backup on the Remote tab, choose Every hour, Every day, or Off. Automatic snapshots start once first-time setup is complete. An automatic run that finds no change adds no snapshot. Automatic entries appear in History as Automatic snapshot, made by system.
• The status bar shows Last checked, the last time the configuration was checked for changes, and Last backup, described under Remote repository.
• History is a single timeline, newest first. The latest snapshot is marked HEAD.
• After each snapshot, a short report lists what was captured, anything that was left out on purpose, with counts, and whether the snapshot was pushed to the remote.

Comparing

Changes vs live compares a snapshot with the running configuration. Each item is marked added, modified, or removed, with a before and after value for every changed field. Secret values are never shown.

Restoring

1. Dry run. Choosing Restore first plans the restore without changing anything, and shows how many items would be created, moved, renamed, deleted, or updated.
2. Confirm. Nothing changes until you confirm.
3. Undo point. If the running configuration differs from the latest snapshot, it is snapshotted first as Before restore to .... When the restore finishes, the dialog offers to restore that snapshot, which undoes the restore.
4. Extensions. Extensions the snapshot used are installed at the versions it used, and the items that depend on them are restored after that.

Items keep their identity across a restore, so dashboards, alarms, and programs that refer to them keep working. While a restore runs, snapshots and other operations are refused until it finishes. If the node restarts during a restore, the restore continues when it comes back. The recovery key is not kept, so a restore that continues this way skips the secrets only the key can read and lists them; once it finishes, restore the same snapshot again with the key to bring them back.

A restore asks for your decision in three cases:

• The snapshot was taken on a different cluster. Choose Restore anyway to continue. Secrets encrypted for that cluster's nodes cannot be read here unless the snapshot was taken with a recovery key.
• This node cannot read the snapshot's secrets, but a recovery key can. Enter the recovery key and choose Use recovery key, or choose Restore without them and enter those passwords and tokens again afterwards. A key that does not match is refused before anything changes, so you can check it for typos and try again.
• An extension version the snapshot needs is not available. Choose Skip missing extensions to restore everything else.

Connect GitHub

To back up to GitHub without handling tokens, first install the ControlBird Backup app on your GitHub account and allow it to see the repositories you want to use. Then choose Connect GitHub during first-time setup or on the Remote tab. ControlBird shows a short code; open GitHub, enter the code, and approve the sign-in.

Pick one of your repositories, or create a new private one, and ControlBird connects to it. The node keeps only a deploy key for that one repository. It does not keep your GitHub sign-in. Use Refresh after you change which repositories the app can see.

Remote repository

A remote is the off-node copy of your history. Enter the repository URL and credentials on the Remote tab; the password or token is stored as a secret and masked everywhere.

• Push sends your snapshots to the remote. You rarely need it, because every snapshot, manual or automatic, is pushed straight away. A failed push never fails the snapshot; the report says whether it was pushed. Pressing Push after you fix the cause of a failed backup clears the alarm.
• Pull brings in snapshots from the remote. It only moves forward: if your local history and the remote have diverged, Pull stops and tells you so. Pushes also only move forward and never overwrite the remote.
• Reset to remote replaces your local history with the remote's. The local snapshots it discards are kept aside, and the running configuration is not changed until you restore a snapshot.

You can connect the remote during first-time setup or at any later time. Connecting or changing the remote, with Connect GitHub, the URL form, or setup, pushes the node's history within about a minute. The connection settings stay with the node and are not part of a backup, so restoring a backup never changes where a node pushes to.

Last backup is the time the remote last confirmed that it holds your latest snapshot. When a backup fails, a banner shows the reason: the credentials or deploy key were refused, the repository was not found, the push timed out (use Push), or the remote holds history this node does not have. In the last case, choose Pull, Reset to remote, or connect another repository.

Config Backup alarm

If backups keep failing for 15 minutes, a Config Backup alarm of Medium severity is raised. After a failure, the node retries once after 10 minutes. The alarm clears on the next successful push.

Backup files

On the Backup tab, choose a snapshot and Download bundle to save it as a file. Import bundle adds a downloaded file to the history as a new snapshot; the running configuration changes only when you restore it. Secrets in a backup file stay encrypted for the cluster that created it, and for its recovery key if one is set.

Recovery key

Passwords, tokens and other secrets in a backup are encrypted for the nodes of the cluster that took it, so only those nodes can read them. A recovery key is a second way in: every snapshot taken while a recovery key is set also encrypts each secret for that key, so the secrets can be brought back on a replacement node.

• Create one on the Backup tab with Create recovery key, or during first-time setup after you connect a repository. ControlBird shows a 32-character key and its key ID once. Copy, download or print it, store it somewhere other than the node, confirm that you have, and choose Save. Config Manager then takes a snapshot named "Recovery key set". If you use a remote repository, push so the remote holds that snapshot too.
• The key is never shown again. ControlBird keeps only the part that encrypts, never the part that decrypts. A lost recovery key cannot be recovered.
• Replace or Remove the key on the same tab. Snapshots taken before the change stay encrypted for the old key, so keep the old key for as long as you keep those backups.
• Restoring with the key. When a restore meets secrets this node cannot read, it asks for the key, as described in Restore. A node with no recovery key of its own that restores secrets with one keeps that key as its recovery key, so its next snapshots are encrypted for it too.
• Creating, replacing and removing the key, and restoring with it, requires the Config Backup permission.

Moving to a new node

1. Install ControlBird on the new node and open the setup wizard.
2. Choose how the owner signs in. When the wizard asks how you want to start, choose Restore from a git backup or Restore from a backup file.
3. For a git backup, connect the repository and pick a backup; the latest is selected for you. For a backup file, choose the file you downloaded.
4. If the backup's secrets were encrypted for the old node, the wizard asks for the recovery key. Type the key you stored when you created it and choose Use recovery key. Without a recovery key, choose Restore without them; passwords, tokens and other secrets then need to be entered again.
5. Review what the restore will do, then choose Restore. The wizard shows progress and then lists what was restored, including how many secrets the recovery key brought back, and every secret that still needs to be entered again.
6. Keep signing in with the account you just set up. The backup's sign-in for your account is not restored over it. The new node keeps the recovery key you used, so its own backups can be moved the same way.

Once the new node pushes to the same repository, the old node can no longer push and raises the Config Backup alarm. Disconnect the old node from the repository or retire it.

First-time setup

A new self-hosted node has no account with a password. The first time you open its web interface, the setup wizard asks you to choose how the node's owner signs in (a password, OpenID Connect, or LDAP). It then asks how you want to start. Start fresh asks for a time zone and, optionally, a Git repository to back up your configuration; an empty repository receives your first snapshot, and a repository that already holds a backup is left untouched. Your configuration is saved to the chosen repository now, and every hour when it changes. Choose another disconnects the repository it leaves behind. The restore choices bring over an existing backup instead, as described in Moving to a new node. Whoever completes the wizard first becomes the owner, so finish it before exposing the node to other networks. Cloud nodes are already owned by the account that created them.

Troubleshooting & Limitations

• "Config Manager unavailable": the service that keeps the history is not running. Check its status in Logs & Diagnostics. In a cluster it runs on one node.
• Snapshot button disabled: a restore is in progress. Wait for it to finish.
• Pull reports diverged history: push or save what you need, then use Reset to remote.
• Config Backup alarm or a backup failed banner: read the reason. If the credentials or deploy key were refused, reconnect the repository or GitHub. If the repository was not found, check its address and that the key has access. If the push timed out, press Push. Pressing Push after fixing the cause clears the alarm.
• The remote holds history this node does not have: another node or an earlier install pushed to the same repository. Choose Pull to bring it in, Reset to remote to replace this node's history with it, or connect another repository. Backups never overwrite the remote.
• Delete, rename, or move refused: the item is provided by the platform or by an installed extension. Change its settings instead, or uninstall the extension.
• Live values are not restored: only configuration is versioned. Statuses, readings, and alarm states come from the running system.
• Access: the app requires the Config Manager permission, which the Engineer role and above have. Downloading or importing a bundle, creating or removing the recovery key, and restoring with it, also requires the Config Backup permission, which only the Owner and Administrator roles have.
• "This key doesn't match recovery key ...": the snapshot was taken with a different recovery key, or the key was mistyped. Check each group of four characters. If you replaced the key since, the snapshot needs the key it was taken with; the key ID tells you which one that is.