Skip to content

Agent upgrade


We recommend using different ways of upgrading the qbee-agent based on which version you are running in your fleet. There might be different versions running, and this document describes how you can safely upgrade to the latest version regardless of the version you are running.

Versions before 2024.05

Versions before 2024.05 does not support doing direct package updates through direct use of package manager commands, neither in File Distribution or Software Management. Instead it is required to use a custom made upgrade script distributed together with the upgrade package using File Distribution. This script will do sanity checking, and if this passes it will start the upgrade process in the background.

The script is available here.

An example File Distribution configuration is available here

  1. Upload the packages with the relevant package architectures to a file stricture in the qbee file manager (eg. /qbee-agent-upgrade)

  2. Upload the script to the same location in the File Manager

  3. Define a File Distribution configuration similar to the example file distribution with the following elements

    • Pre-condition for checking current version and architecture
    • File set containing the upgrade script and the relevant package for the architecture
    • Run command that calls the upgrade script with the package as input

Upon successful upgrade there will be a log entry for the device in the UI


Disable other configuration

When doing the upgrade it is recommended to disable all other configuration items, especially any Package Management or Software Management configurations.

Versions including and after 2024.05

Versions including and before 2024.05 are able to upgrade using the Software Management feature in qbee configuration.

  1. Upload the packages with the relevant package architectures to a file stricture in the qbee file manager (eg. /qbee-agent-upgrade)

  2. Define a Software Management configuration by simply pointing to the packages in the File Manager

The following is an example of upgrading versions 2024.14 to version 2024.19.

  "enabled": true,
  "extend": false,
  "version": "v1",
  "items": [
      "package": "/qbee-agent-upgrade/qbee-agent_2024.19_$(sys.pkg_arch).deb",
      "pre_condition": "dpkg -s qbee-agent | awk '/^Version:/{print $NF}' | grep -q 2024.14"

Note that this example uses the $(sys.pkg_arch) parameter which is locally resolved at the device. Read more about locally resolved parameters here

Update outgoing firewall rules?

From version 2024.09 qbee introduced a new remote access feature. This uses a different backend with different IP addresses. Before upgrading to any version after 2024.09 you should make sure that you have the necessary firewall openings to the following host

You can test this from one of your devices using the following command (NB: remember to set proxy environment variables if necessary)

wget -q -O /dev/null --server-response --content-on-error=off --no-check-certificate

The command should produce a HTTP/1.1 200 OK.

Note on changes

Console access

Due to the aforementioned migration from openvpn based remote access, there are some changes in user experience of the remote console UI. Besides some minor styling changes, there's also no required username/password anymore to log on to the system.


Versions before 2024.09 used openvpn to provide remote access capabilities, and when using Firewall configuration there would be an implicit rule added to allow traffic over the qbee0 interface.

Docker containers

Docker containers defined in version 1.2.1 of qbee-agent where initiated in a different way than in versions >=2023.26. As the state information is based on how the containers are started, qbee-agent might restart containers after upgrade from versions 1.2.1 to versions including and after 2023.26.


Upgrading qbee-agent involves replacing the qbee-agent in full and restarting the agent. It should be tested in a non-production environment before rolling out to the complete fleet. Please reach out to should you have questions or issues with the upgrade procedure.