Agent

Introduction to the qbee agent¶

The qbee agent is a highly optimized and lightweight piece of software that needs to be installed on each device to allow the platform to manage that device.

The qbee agent has been released as open source under the Apache License Version 2.0.

Find the source code here.

written in GO
lightweight and extremely robust
very few external dependencies for increased security
Consists of two parts, the configuration engine and the remote access
communicates with TCP over port 443 (https)
runs on basically any Linux and any hardware architecture
state based, pull based
open source

The following packages are pre-build. Please reach out if you need others.

Architecture	OS	Package:
ARM 32-bit	Debian based	armhf
ARM 64-bit	Debian based	arm64
Intel x86_64	Debian based	amd64
Intel i386	Debian based	i386
ARM 32-bit	RHEL based	armv7hl
ARM 64-bit	RHEL based	aarch64
Intel x86_64	RHEL based	x86_64
Intel i386	RHEL based	i686

Latest packages can be downloaded [here].(https://github.com/qbee-io/qbee-agent/releases/latest)

We also have a YOCTO meta layer available.

The qbee-agent is also available as OpenWRT package and in the Buildroot build system.

Support can help you with any questions.

The agent functionality¶

The agent usually runs as root. It has different commands that can be executed. In most cases you only need to run the bootstrap command which is described in bootstrapping.

However, the commands below allow to adjust where on the system the qbee directories are kept. This introduces flexibility for Yocto builds or if you use non-standard file systems

$ sudo qbee-agent -h
Usage: qbee-agent [global options] <command> [options] [<command> [options] ...]

Options:
  -c, --config-dir CONFIG_DIR  Configuration directory.                       [optional]  (default: /etc/qbee)      
  -s, --state-dir STATE_DIR    State directory.                               [optional]  (default: /var/lib/qbee)  
  -l, --log-level LOG_LEVEL    Logging level: DEBUG, INFO, WARNING or ERROR.  [optional]  (default: INFO)           


Commands:
  bootstrap - Bootstrap device.                          
  config    - Execute device configuration.              
  inventory - Send inventory data to the Device Hub API. 
  start     - Start the agent process.                   
  version   - Agent version.

Additional available parameters for bootstrapping¶

The parameters below give additional settings for the bootstrap process. They can be used if a proxy is part of the setup or if you want to disable remote access. Some customers also use this in a script to create a device name that incorporates a MAC address or similar.

$ sudo qbee-agent bootstrap -h
Usage: qbee-agent [global options] <command> [options] [<command> [options] ...]

Options:
  -k, --bootstrap-key BOOTSTRAP_KEY    Set the bootstrap key found in the user profile.  [required]  
      --disable-remote-access          Disable remote access.                            [optional]  
      --device-name DEVICE_NAME        Custom device name to use.                        [optional]  
  -t, --tpm-device TPM_DEVICE          TPM device to use (e.g. /dev/tpm0).               [optional]  
      --proxy-host PROXY_HOST          HTTP proxy host to use.                           [optional]  
      --proxy-port PROXY_PORT          HTTP proxy port to use.                           [optional]  
      --proxy-user PROXY_USER          HTTP proxy username.                              [optional]  
      --proxy-password PROXY_PASSWORD  HTTP proxy password.                              [optional]

For ideas how to deploy devices please visit the "deployment" menu. There it is also described how to use a proxy.

Additional available parameters for config¶

Here configuration can be loaded from a provided file. This can be used in offline scenarios or if updates need to be deployed from a USB stick.

$ sudo qbee-agent config -h
Usage: qbee-agent [global options] <command> [options] [<command> [options] ...]

Options:
  -f, --from-file FROM_FILE  Apply configuration from provided file.                                                 [optional]  
  -r, --report-to-console    Print configuration reports to console.                                                 [optional]  
  -d, --dry-run              Don't apply configuration. Just dump current configuration as JSON to standard output.  [optional]

Additional available parameters for start¶

This option allows to trigger the agent manually from the device.

$ sudo qbee-agent start -h
Usage: qbee-agent [global options] <command> [options] [<command> [options] ...]

Options:
  -1, --run-once  Run once.  [optional]

Agent functionality by version¶

Version	Description
2024.23	Podman, opkg (OpenWRT support)
2024.14	CPU temperature, RAUC non-streaming mode, rpm/yum support (RHEL-based systems)
2024.09	RAUC, remote run agent, new remote access replacing OpenVPN
2024.05	Additional $(sys) parameters described here: configuration parameters
2023.44	Parameters and secrets