Major version upgrade with a custom liveburner

Major version upgrade with a custom liveburner

Introduction

Major versions of KerOS introduce some important modifications (new kernel, hotfixing) requiring an upgrade with a liveburner when coming from the previous KerOS version. A liveburner package will by default flash the eMMC content and install only the KerOS package. So any packages, data, and configurations will be lost using such upgrade packages. This upgrade will be problematic for products already on the field that need to keep a device management link up and running before and after the upgrade.

This page provides:

A custom liveburner to upgrade the firmware from version 4.3.3 to version 5.5.4 preserving network, LoRa, and WMC configuration.
A tool to customize a liveburner to add some additional packages during the upgrade.

Please note that an upgrade is always risky and must be tested and validated before being deployed on the products on the field. We also recommend upgrading products in small batches and not all the products in a row.

Default custom liveburner for version 5.5.4

A custom liveburner has been generated to save usual configuration files:

Network configuration
LoRa configuration (CPF configuration)
BSCC configuration (for Wanesy Management Center customers)
Secrets and OpenVPN configuration (for Wanesy Management Center customers)

To upgrade your gateway from version 4.3.3 to version 5.5.4 with this configuration files preservation, use the custom liveburner file custom-liveburner_5.5.4_klkgw-signed.ipk available in the 5.5.4 release page. To upgrade your system, follow the software update process here.

This custom liveburner can be used to upgrade a gateway without WMC connection. In this case, OpenVPN and BSCC configurations are ignored. Network and LoRa configuration will be saved.

The gateway must be connected to internet.

This custom liveburner can be used only to upgrade a gateway with firmware version 4.3.3. If your gateway has a firmware version < 4.3.3, it is mandatory to upgrade your firmware to version 4.3.3 before to upgrade it to firmware version 5.x.

For gateways connected to the WMC (Wanesy Management Center): To reinstall the OpenVPN secrets after the 5.5.4 upgrade, the custom liveburner needs an internet connection to request the OpenVPN certificates to the Kerlink server.

Build your own 5.5.4 custom liveburner (experienced user)

click here

How does it work?

When using this customized liveburner, the following steps are done to achieve the upgrade:

Deploy and install the customized liveburner IPK on the product.
Product will restart on the liveburner upgrade tool.
Execution of the script preinst. It will mount a safezone to backup the configuration files BEFORE the installation of the new firmware.
Upgrade of the KerOS system including the eMMC flash and installation of the KerOS package.
Execution of the script postinst. It will mount a safezone to backup the configuration files AFTER the installation of the new firmware.
Execution of the preapps script.
Installation of the additional packages
Execution of the postapps script.
Save packages in backup.
Execution of the prereboot script.
Restart on the new KerOS system..

Requirements

A desktop Linux machine (native or virtual). ⇒ It will be used to build the liveburner package.
The KerOS liveburner 5.5.4 package available in the 5.5.4 release page.
The update_liveburner_package-v5.5.4.tar.gz tool available in the 5.5.4 release page.

The following packages:

sudo apt-get install device-tree-compiler cpio binutils tree

Limits

Some limits are present in this upgrade mechanism:

Safezone space: 2MiB.
Additional packages max size cumulated: 20MiB
The custom liveburner is intended to be used on gateways with a firmware 4.3.3 installed.

Generate a custom liveburner

Customization scripts

The tool integrates sample scripts in the sample_scripts directory that will provide some default migrations:

System configuration
LoRa configuration
Wanesy Management Center configuration (including Secrets and OpenVPN configuration)

These scripts can be customized to adapt the custom liveburner to the use case. Please note that some variables/mountpoints are provided:

Variable	Role	Example
`ROOTFSRW_PATH`	Root path adapted to the firmware version.	`cp ${ROOTFSRW_PATH}/etc/hosts ${SAFEZONE_MOUNTPOINT}/`
`SAFEZONE_MOUNTPOINT`	The mountpoint to use to access the safezone	`cp ${ROOTFSRW_PATH}/etc/hosts ${SAFEZONE_MOUNTPOINT}/`
`/user`	The mountpoint to use to access the RW USER partiton	`cp /user/myfile.txt ${SAFEZONE_MOUNTPOINT}/`

Please note that the management of the content of the safezone needs to be done using the scripts preinst, postinst, preapps, postapps, prereboot like detailed below. The recommended way is at least to clean the safezone content before starting to backup your files. The only files that must be kept in the safezone are keros_config.tar.gz, upgrade_logs.tar.gz and upgrade.log.

Uncompress the update liveburner package

Uncompress the update_liveburner package:

$ tar -xzvf update_liveburner_package-v5.5.4.tar.gz
update_liveburner.sh
extract_custom_elements.sh
show_ipk_infos.sh
functions
dumpimage
mkimage
sample_scripts/
sample_scripts/postinst
sample_scripts/postapps
sample_scripts/prereboot
sample_scripts/preinst
sample_scripts/preapps
files/
files/rootfs/
files/rootfs/etc/
files/rootfs/etc/rcU.d/
files/rootfs/etc/rcU.d/S99magic_link_renew_certificate.sh

Save files before upgrade

Saving files must be done using the preinst script. It will be executed before installing the new firmware.
To save some files, append them at the end of the script like shown in the commented example line of sample_scripts/preinst.

####################
# MAIN CUSTOMER PART
####################

# Example:
# cp ${ROOTFSRW_PATH}/etc/hosts ${SAFEZONE_MOUNTPOINT}/
# cp ${ROOTFSRW_PATH}/etc/my_appli ${SAFEZONE_MOUNTPOINT}/
# cp /user/testfile ${SAFEZONE_MOUNTPOINT}/

In the case a custom upgrade blocking problem happens during the execution of this script, it is possible to interrupt the upgrade. To do so, it is possible to use the function fatal_error in the custom part of the script like this:

cp ${ROOTFSRW_PATH}/etc/non_existant_file ${SAFEZONE_MOUNTPOINT}/ || fatal_error "Error detected! stop the upgrade!!"

In addition, customers must take care of the last command launched by the script. If it returns an error, the upgrade will also be aborted. This script is the last chance to stop an upgrade without consequences on the system. After this script, the upgrade is started and errors in other scripts will not stop the process.

Restore files after upgrade

To restore file, the method consist of adapting the preapps/postapps scripts (like for preinst).

####################
# MAIN CUSTOMER PART
####################

# Example:
# cp -fR ${SAFEZONE_MOUNTPOINT}/hosts /etc/
# cp -fR ${SAFEZONE_MOUNTPOINT}/my_appli /etc/
# cp -fR ${SAFEZONE_MOUNTPOINT}/testfile /user/

preapps script will be launched after the installation of the KerOS firmware but before installing any application package.
postapps script will be launched after the installation of all the application packages.</note>

Generate the custom liveburner

Then you can launch a generation of custom liveburner using the following command:

#./update_liveburner.sh liveburner_5.5.4_klkgw-signed.ipk sample_scripts/preapps sample_scripts/postapps sample_scripts/preinst sample_scripts/postinst sample_scripts/prereboot
Liveburner custom-liveburner_5.5.4_klkgw-signed.ipk created

It is possible to add some information in the description of the package by adding -m my_information. This information will be added in the CONTROL file of the package that you can read using the show_ipk_infos.sh tool.

./update_liveburner.sh -m my_information liveburner_5.5.4_klkgw-signed.ipk sample_scripts/preapps sample_scripts/postapps sample_scripts/preinst sample_scripts/postinst sample_scripts/prereboot

Generate the custom liveburner with additional packages/files

Additional packages (ex: my_package.ipk) can be installed simply by adding them as arguments when generating the custom liveburner:

./update_liveburner.sh liveburner_5.5.4_klkgw-signed.ipk sample_scripts/preapps sample_scripts/postapps sample_scripts/preinst sample_scripts/postinst sample_scripts/prereboot my_package.ipk

Additionnal files can be installed simply by adding them in the folder files/rootfs/ of the update liveburner package (example: creation of file S99magic_link_renew_certificate.sh for WMC certificate preservation). The files tree needs to be created in this folder.

Install a custom liveburner

To upgrade your system, follow the software update process. Information here.

Custom liveburner tools

Read custom liveburner information

It is possible to extract some information about the content of a previously generated custom liveburner using the tool show_ipk_infos.sh:

# ./show_ipk_infos.sh -h
Usage: ./show_ipk_infos.sh [-h] <custom_liveburner.ipk>
	-h: this usage
	custom_liveburner.ipk: custom liveburner to extract elements from

Extract content of a custom liveburner

Custom packages and scripts are integrated deeply in the liveburner. A tool is available to extract them easily:

# ./extract_custom_elements.sh -h
Usage: ./extract_custom_elements.sh [-h] <custom_liveburner.ipk>
	-h: this usage
	custom_liveburner.ipk: custom liveburner to extract elements from

Upgrade traces

Some traces are available after an upgrade with custom_liveburner in /user/.upgrade.log.

Table of Contents