Skip to content

Configuration management


The core feature of qbee is its ability to manage large numbers of devices using smart grouping and configuration profiles. It provides a simple and consistent interface to define configurations such as firewall rules, remote OTA software update management and settings across different device types. The state-based configuration engine is highly flexible, basically being able to tackle any device automation task through the powerful remote scripting engine available within the file distribution configuration. Just try it on your specific device, a Raspberry Pi, any Linux VM or Docker container. Then you can configure your firewall, SSH keys, users, or even manage complex package installations or docker setups with ease. See a short introduction here:

Configuration Management with is a pull-based configuration management tool, ensuring your devices always converge to the defined state or display an error message. The local qbee agent regularly queries the centralized server for new configuration information. If there is none available, it checks if the device complies with the current state and goes back to sleep. However, if new configuration information is available, the agent downloads it and converges towards the new configuration. This approach offers several benefits, such as allowing the agent to operate and maintain configuration even if the network is down. Additionally, any devices added later to a group, such as spare parts or replacements, will always receive the latest configuration, including the latest SSH keys and user definitions. Here are some practical implications:

  • configuration is only becoming valid if you commit it

  • configuration management works pull based and by converging to the defined state

  • it will take at least until the next connect interval of the agent until it receives the configuration

  • the qbee agent will report success or an error if it cannot reach its state

  • the qbee agent maintains its defined state. If a managed password or firewall setting is change manually on the device qbee will revert it in the next run (and send a log message about this). This is also true for files that are played out.

  • in very few cases the agent cannot converge to its defined state due to conflicting setup. Then an error message is displayed (for example a file is played out that does not have correct access rights, or a process should be started that does not exist)

  • This allows to update a large number of devices in a very short time. It takes 5 minutes (or one agent interval) to update one device. It also takes just 5 minutes to update thousands of devices.

Define configuration settings

In the configure menu the top selector defines for which device or group of devices configuration is applied. "All devices" will enable this for the main branch of the tree. All subsequent groups and devices (that don't explicitly override it), will inherit this configuration. You can do multiple configuration changes at once, but it is recommended to always do one after the other.

Configuration inheritance

For each level you are on, you see which configurations are defined for that branch of the tree. In case configuration has changed you will see a yellow circle to indicate changes that are not committed yet.

Configuration inheritance - settings

To define a new configuration on a selected level, select it and press the "Enable" button. Then the selected level (and all its group below in the branch of the tree) will inherit the new configuration. Modifying a configuration will cause a "Save settings" button to be activated. Updated configurations need to be saved before navigating away and committed before becoming active.

Breaking inheritance

Commit your configuration changes to become active

Any changes you make to configurations are noted by a small yellow circle in the according configuration topic on the left hand side. In addition, you see that the "Commit changes" button turns red.

Configuration commit - Users

First when this is pressed and the change is committed it will become active. Before committing it is also possible to revert back and reset all changes. Pressing the "Commit changes" button will invoke a new window that allows you to define the commit message that will be shown in the audit section.


Pressing save here will allow the configuration change to get active on the server and then the changes can be picked up by the relevant devices. In the logs section all reported changes are accessible.

You need to SAVE and COMMIT

Make sure you save configuration AND commit it. Otherwise, nothing will happen (except that you will see the orange circle indicating saved changes that are not committed yet).

Changes will be applied after the next agent run and can be tracked

Configuration can only be active after having been committed and picked up by a device after the next qbee agent run. This can take 5 minutes or even longer if you select a longer agent run interval in settings. You can see all executed changes in the logs or in the audit tab.

Disabling a configuration

If a parent group defines a configuration we want to exclude for a subgroup or a device, we can define a new configuration on that level with "Enabled" flag disabled.

Disable device configuration

An additional confirmation prompt is then display while saving the change to ensure that configurations are not disabled by accident.

!qbee-configuration-delete-2{: .center width=1000 height=317 loading=lazy alt="Disabled configuration warning"

When this change is saved and committed, devices under that level will no longer receive this configuration.

Extending a configuration

When we want to extend the parent configuration on a subgroup or a device level, we can define a new configuration on the child level with the "Extend" flag enabled. This will append the configuration from the current level to the parent's configuration.

For example: Let's add admin user through Users configuration on All devices group and then add admin-A user on the group_A level.

Extend device configuration

This will result in devices under group_A to have both admin and admin-A users created.

Preview result configuration

When we disabled the "Extend" flag though:

Disable extent only - admin-A is present

It will result in devices under group_A to have only admin-A user created.

Preview result configuration with extend disabled

Extendable configurations

Not all configurations can be extended, therefore not all configurations will have the "Extend" toggle available. In those cases, the configuration defined on a subgroup or a device will always override the parent's configuration.

Importing and exporting configuration

It is possible to import and export configurations. Either to keep track of those or to migrate settings between different branches of the tree. Please click in "JSON" in the configuration form. This shows the current configuration as a JSON file and here it is possible to import and export settings. You can also edit the JSON directly, but only correct JSON content is considered. If you want to overwrite then you can "clear area" and copy in the new JSON (for example the file that you have previously exported). Pressing the "Import settings" button will then turn it active.

Import and export configuration as JSON

Deleting a configuration

Once configuration is no longer needed, it can be deleted by clicking on the "Delete configuration" button on the bottom of the form. Deleted configuration won't be inherited and none of the devices will receive it.

Some considerations around state based configuration management

Some considerations around the state based concept

The qbee agent checks with each run if new configuration is available. If so the new configuration information is downloaded. Then the agent works on converging to the defined state issuing log messages if this was successful or not. This has some implications:

  • Devices joining later will still receive all current configuration information

    This is very useful if devices are kept as spares or might not be online all the time

  • qbee monitors and keeps its state

    If a password is defined as configuration in qbee and this is changed on the device qbee will change it back any time it runs. Also, if a file is played out and monitored by qbee on the target system and it is changed there it will be changed back.

  • bad configuration can make qbee work against you

    This is not a bad thing but it needs to be understood. If a file on a device is used to store device information and written by a process on the target device it should not be monitored directly. Then it should be transferred to the device as config_original.json and then copied with an after command to config.json. If this is written by the device qbee will not correct it as long as the config_original.json is not updated within the qbee file manager.