Firmware-independent Object Upgrade PM Plugin

General

The goal of this feature is to enable firmware-independent updates/upgrades of certain individual firmware components. There are two benefits when only updating or upgrading individual firmware components:

Firmware-independent updates no longer require flashing a new firmware image to the nodes.
Less frequent upgrade of the entire firmware image is required.

OpenSync 2.2 provides a generic mechanism for upgrading the selected OpenSync components as opposed to upgrading the entire firmware.

Using this approach when performing upgrades simplifies the development of new apps, reduces the time when responding to the customers' issues, and helps with improving the product.

Example: In the case of using a third party Walleye service, this feature enables signature upgrades without the need to upgrade the entire firmware.

These are the update steps (based on the Walleye service example):

Right before the update, a node is informed by the controller that a new signature bundle is available.
The node downloads the signature via a secure and encrypted connection.
In the opposite direction, the node informs the controller about its version, Walleye plugin, and signature version.
Signature update is done. Node reboot is no longer necessary after the signature update.

A signature update has minimum impact on the gateway node operation and does not disturb its functioning. Therefore, the update can be performed at any time of the day. It does not have to be limited to non-busy hours only, but can be configured according to the customer's preferences.

Updates can be executed in several phases. The firmware can also report about the status of the update to the controller. The support team can monitor the signature bundle health from the dashboard and receives alerts in case of any issues.

Implementation

These are the changes introduced with OpenSync 2.2:

An object management module is added to the Platform Manager.
A description of the object to be managed is added to the OVSDB table.
Persistent storage API stores the object on the node.
An OVSDB FSM state table is created to provide a version of each plugin and its dependencies.

Northbound API

New tables Object_Store_Config and Object_Store_State have been introduced with OpenSync 2.2. The Object_Store_Config table enables controller-to-device communication when upgrading only specific firmware modules. The Object_Store_State table displays the active upgrade parameters for specific firmware modules.

Object_Store_Config

Name	Type	Comment

Name	Type	Comment
dl_url	string [512]	Download URL: Set by the controller when a new object is available Cleared by a device when download is done (even if download failed)
dl_timeout	integer	Download timeout: Set by the controller for a download timeout Cleared by a device when download is done (even if download has failed)
name	string	Name of an object: Set by the controller when a new download is triggered Set by a device at booting (from the already installed objects)
version	string	Version of an object: Set by the controller when a new download is triggered Set by a device at booting (from the already installed objects)

Object_Store_State

Name	Type	Comment

Name	Type	Comment
name	string	Name of an object: Set by a device
version	string	Version of an object: Set by a device
fw_integrated	bool	An object is preintegrated in the FW image: True if an object is preintegrated in the image – the object is installed by default. False if an object is installed from the controller (Object_Store_Config table). Preintegrated objects can not be removed.
status	enum	Status of an object: always set only by a device string enum: "install-failed" "install-done" "download-started" "download-failed" "download-done" "load-failed" "active" "error" "obsolete"

$ ovsh s Object_Store_State
-------------------------------------------------
_uuid         | 712b~541d      | 296f~6934      |
_version      | 61c0~1c3e      | a267~ac07      |
fw_integrated | false          | true           |
module        | fsm            | fsm            |
name          | app_signatures | app_signatures |
status        | 0              | 0              |
version       | 1.4            | 1.3            |
-------------------------------------------------

OMS_Config

OMS_Config is the table that the receiving modules are monitoring for the object updates. This table lists the available versions for a given object name. In case of multiple versions for the same object name, it is up to the receiving module to decide which one to use.

Name	Type	Description
object_name	string	Name of the object to be upgraded
version	string	Version of the object (set by the controller)
other_config	string

Object Status Reporting

Reporting of object status uses the protobuf format. The State field of the OMS_State table is used for this purpose.

Southbound API

bool osp_objm_install(char *path, char *name, char *version);

Installs an object. The path variable is the path destination where the downloaded tarball is located. The name and the version are the identifiers by which an object is loaded.

bool osp_objm_remove(char *name, char *version);

Removes an object from the storage.

bool osp_objm_path(char *buf, size_t buffsz, char *name, char *version);

Gets the path location where in the filesystem the base of an object is. From that location the process can load any files that were in that object.

OSP dl API Definitions

bool osp_dl_download(char *url, char *dst_path, int timeout, osp_dl_cb dl_cb);

Downloads the API with the URL of what should be downloaded, local dst_path of the location where to download and timout.
Download should be implemented as a non-blocking (async) call. When a download is complete, a dl_cb callback should be called.

OSP Implementation

bool osp_dl_download(char *url, char *dst_path, int timeout, osp_dl_cb dl_cb);

Using libcurl
Using pthread to enable a non-blocking (async) implementation

bool osp_objm_install(char *path, char *name, char *module, char *version);

Use the current root filesystem. A folder /usr/opensync/storage where all of the objects are saved. Every object has its own sub-folder that is generated by <name>-<version>. In this way, getting the path of an installed object (with osp_objm_path) is simple.

bool osp_objm_remove(char *name, char *module, char *version);

removes the folder storage_path/<name>/<version>

bool osp_objm_path(char *buf, size_t buffsz, char *name, char *version);

returns the storage_path/<name>/<version>

Example: OVS table mentioned above with the two Walleye signature versions would generate a folder structure.

/usr
|-- opensync
    |-- storage
        |-- app_signatures
			|-- 1.1
			|-- 1.2

The function call:

osp_objm_path(&buf, buf_size, "app_signatures", "1.1") will return /usr/opensync/storage/app_signatures/1.1

Requirements

Regardless of the implementation, the selected upgrade/update approach needs to address the following:

The controller provides the URL of the object to download.
The controller provides the storage type for the object.
The object manager knows where to store the object locally.
The object manager knows how to validate the object integrity.

The required information for the object manager can be shared between OVSDB and metadata provided within the object.

Points 1 and 2 above have to be provided through OVSDB.

Points 3 and 4 can be provided within the package when it contains files to be written in the file system.