How does it work?

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

1. Deploy and install the customized liveburner IPK on the product.
2. Product will restart on the liveburner upgrade tool.
3. Execution of the script preinst. It will mount a safezone to backup the configuration files BEFORE the installation of the new firmware.
4. Upgrade of the KerOS system including the eMMC flash and installation of the KerOS package.
5. Execution of the script postinst. It will mount a safezone to backup the configuration files AFTER the installation of the new firmware.
6. Execution of the preapps script.
7. Installation of the additional packages
8. Execution of the postapps script.
9. Save packages in backup.
10. Execution of the prereboot script.
11. 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:

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

./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.