Skip to main content
Version: Next

Software Management

thin-edge.io software management is implemented by two operations which give the ability to manage software packages of different types on the same device.

  • software_list is used to fetch a pertinent subset of the software packages installed on a device.
  • software_update let the user install, update and remove software packages on a device.

software_list MQTT API​

The software_list operation API follows the generic thin-edge.io rules for operations:

  • The te/<device-topic-id>/cmd/software_list topic is used to publish the type of software packages that can be managed on the device with the given topic identifier.
  • Each te/<device-topic-id>/cmd/software_list/+ topic is dedicated to a software list command instance,
  • The workflow is generic with "init", "executing", "successful" and "failed" statuses.

Operation registration​

The registration message of the software_list operation on a device:

  • must provide a types list of the types of software package that can be installed on this device (e.g. ["apt", "docker"])
  • can provide a description of the operation and of each supported package type.
tedge mqtt pub -r 'te/device/child001///cmd/software_list' '{
  "description": "List software packages installed on the device",
  "types": [
    "apt",
    "docker"
  ]
}'

init state​

A software_list command has nothing to provide beyond a status field. This empty message stands for a request of the list of software currently installed.

tedge mqtt pub -r 'te/device/child001///cmd/software_list/c8y-2023-09-25T14:34:00' '{
  "status": "init"
}'

executing state​

Just before starting the command execution, the agent marks the command as executing by publishing a retained message that repeats the former command except that:

  • the status is set to executing

successful state​

The payload for a successful software_list command has two fields:

  • the status is set to successful
  • a currentSoftwareList field is added with the new list of packages installed on the device
    • These packages are grouped by software package type: 
      {
         "currentSoftwareList": [
           {
             "type": "apt",
             "modules": [ "..." ]
           },
           {
             "type": "docker",
             "modules": [ "..." ]
           }
        ]
      }
    • Each installed package is given:
      • the package "name",
      • the installed "version".

As an example, here is a (simplified) status message for a successful software_list command on a child device:

tedge mqtt pub -r 'te/device/child001///cmd/software_list/c8y-2023-09-25T14:34:00' '{
    "status": "successful",
    "currentSoftwareList": [
        {
            "type": "debian",
            "modules": [
                {
                    "name": "nodered",
                    "version": "1.0.0",
                },
                {
                    "name": "collectd",
                    "version": "5.12"
                }
            ]
        },
        {
            "type": "docker",
            "modules": [
                {
                    "name": "nginx",
                    "version": "1.21.0",
                },
            ]
        }
    ]
}'

failed state​

The payload for a failed software_list is made of two fields:

  • the status is set to failed
  • a reason text field is added with the root cause of the failure
tedge mqtt pub -r 'te/device/child001///cmd/software_list/c8y-2023-09-25T14:34:00' '{
    "status": "failed",  
    "reason": "Permission denied",
}'

software_update MQTT API​

The software_update operation API follows the generic thin-edge.io rules for operations:

  • The te/<device-topic-id>/cmd/software_update topic is used to publish the type of software packages that can be managed on the device with the given topic identifier.
  • Each te/<device-topic-id>/cmd/software_update/+ topic is dedicated to a software update command instance, and is used to publish the subsequent states of the command execution.
  • The workflow is generic with "init", "executing", "successful" and "failed" statuses.

Operation registration​

The registration message of the software_update operation on a device:

  • must provide a types list of the types of software package that can be installed on this device (e.g. ["apt", "docker"])
  • can provide a description of the operation and of each supported package type.
tedge mqtt pub -r 'te/device/child001///cmd/software_update' '{
  "description": "Install, update and remove software packages",
  "types": [
    "apt",
    "docker"
  ]
}'
info

The software types are currently not sent to the cloud (e.g. Cumulocity IoT), however this is planned in a future release.

init state​

A software_update command is defined by an "updateList" array giving the packages to install, update or remove.

  • The "updateList" field is a list of software update actions.
    • These actions are grouped by software package type: 
      {"updateList": [
         {
             "type": "apt",
             "modules": [ "..." ]
         },
         {
             "type": "docker",
             "modules": [ "..." ]
         }
      ]}
    • Each action is either to "install" or "remove" a software package.
      • "action": "install" is to be understood as a goal: "this package must be installed with this version" whatever the actual action to reach this goal, being a fresh install, an upgrade or a downgrade.
      • "action": "remove" is also to be understood as a goal: "that package must not be installed".
    • An action provides:
      • the package "name" (as known by the package packager),
      • optionally a "version" (using the same conventions as the package manager),
      • optionally an "url" from where to download the package.

As an example, here is a message requesting a software_update on a child device:

tedge mqtt pub -r 'te/device/child001///cmd/software_update/c8y-2023-09-25T14:53:00' '{
  "status": "init",
  "updateList": [
    {
      "type": "apt",
      "modules": [
        {
          "name": "nodered",
          "version": "1.0.0",
          "action": "install"
        },
        {
          "name": "collectd",
          "version": "5.12",
          "url": "https://collectd.org/download/collectd-tarballs/collectd-5.12.0.tar.bz2",
          "action": "install"
        }
      ]
    },
    {
      "type": "docker",
      "modules": [
        {
          "name": "nginx",
          "version": "1.21.0",
          "action": "install"
        },
        {
          "name": "mongodb",
          "version": "4.4.6",
          "action": "remove"
        }
      ]
    }
  ]
}'

executing state​

Just before starting the command execution, the agent marks the command as executing by publishing a retained message that repeats the former command except that:

  • the status is set to executing

successful state​

The payload for a successful software_update command repeats the same content as the former request except that:

  • the status is set to successful.

As an example, here is a status message for a successful software_update command on a child device:

tedge mqtt pub -r 'te/device/child001///cmd/software_update/c8y-2023-09-25T14:53:00' '{
  "status": "successful",
  "updateList": [
    {
      "type": "apt",
      "modules": [
        {
          "name": "nodered",
          "version": "1.0.0",
          "action": "install"
        },
        {
          "name": "collectd",
          "version": "5.12",
          "url": "https://collectd.org/download/collectd-tarballs/collectd-5.12.0.tar.bz2",
          "action": "install"
        }
      ]
    },
    {
      "type": "docker",
      "modules": [
        {
          "name": "nginx",
          "version": "1.21.0",
          "action": "install"
        },
        {
          "name": "mongodb",
          "version": "4.4.6",
          "action": "remove"
        }
      ]
    }
  ]
}'

failed state​

The payload for a failed software_update command repeats the same content as the former request except that:

  • the status is set to failed
  • a reason text field is added with the root cause of the failure
  • a failures array field might be added to list the errors for all the failing actions.
tedge mqtt pub -r 'te/device/child001///cmd/software_update/c8y-2023-09-25T14:53:00' '{
  "status": "failed",
  "reason": "Partial failure: Could not install collectd and nginx",
  "updateList": [
    {
      "type": "apt",
      "modules": [
        {
          "name": "nodered",
          "version": "1.0.0",
          "action": "install"
        },
        {
          "name": "collectd",
          "version": "5.12",
          "url": "https://collectd.org/download/collectd-tarballs/collectd-5.12.0.tar.bz2",
          "action": "install"
        }
      ]
    },
    {
      "type": "docker",
      "modules": [
        {
          "name": "nginx",
          "version": "1.21.0",
          "action": "install"
        },
        {
          "name": "mongodb",
          "version": "4.4.6",
          "action": "remove"
        }
      ]
    }
  ],
  "failures": [
    {
      "type": "apt",
      "modules": [
        {
          "name": "collectd",
          "version": "5.7",
          "action": "install",
          "reason": "Network timeout"
        }
      ]
    },
    {
      "type": "docker",
      "modules": [
        {
          "name": "mongodb",
          "version": "4.4.6",
          "action": "remove",
          "reason": "Other components dependent on it"
        }
      ]
    }
  ]
}'

tedge-agent implementation​

Software management plugins​

The tedge-agent service uses software management plugins to interact with the actual package managers.

For each type of software package supported on the device must be provided a specific software management plugin:

  • A plugin is an executable file implementing the software plugin API, to list, install and remove software packages of a specific type.
  • These plugins are looked up by tedge-agent in the plugin directory (/etc/tedge/sm-plugins if not specified otherwise).
  • tedge-agent uses the file name of a plugin executables as the software package type name.

Settings​

tedge-agent behavior on software_update commands can be configured with tedge config.

  • software.plugin.default sets the default software plugin to be used for software management on the device.
  • software.plugin.max_packages sets the maximum number of software packages reported for each type of software package.
  • software.plugin.exclude sets the filtering criterion that excludes software packages from the output list if they match the pattern.
  • software.plugin.include sets the filtering criterion that includes software packages in the output list if they match the pattern.
info

Include pattern takes precedence over exclude pattern, so when both are used at the same time, the software list will exclude packages according to the pattern but keep the exceptions covered by the include pattern.

Custom implementation​

thin-edge.io users can implement their own support for software management to address the specificities of their devices.

  • This can be done leveraging the tedge-agent and implementing a custom software plugin.
  • If for some reasons the tedge-agent cannot run on the target hardware, then a service must be implemented to support the software_list and software_update operation, as described below. In this case, the service is free to choose its own mechanisms to manage software packages and can even run on a device that is not the target hardware.