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, never in readable form.

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.
• History is a single timeline, newest first. The latest snapshot is marked HEAD.
• After each snapshot, a short report lists what was captured and anything that was left out on purpose, with counts.

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.

A restore asks for your decision in two 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, so enter those passwords and tokens again afterwards.
• An extension version the snapshot needs is not available. Choose Skip missing extensions to restore everything else.

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

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.

Moving to a new node

1. Install ControlBird on the new node and complete the setup wizard.
2. Connect the same remote and Pull, or import a backup file.
3. Restore the snapshot you want. Confirm the different-cluster prompt when it appears.
4. Enter again any passwords and tokens that were encrypted for the old cluster.

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), then a time zone and, optionally, a Git remote for configuration history. 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.
• 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 also requires the Config Backup permission, which only the Owner and Administrator roles have.