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

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


===== 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 [[wiki:upgrade_keros5:firmware:release_5.5.4 | 5.5.4 release]] page. To upgrade your system, follow the software update process [[wiki:keros_custo:sw_updates|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.

<note important>The gateway must be connected to internet.</note>

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

<note important>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.</note>
===== 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 [[wiki:upgrade_keros5:firmware:release_5.5.4 | 5.5.4 release]] page.
  * The ''update_liveburner_package-v5.5.4.tar.gz'' tool available in the [[wiki:upgrade_keros5:firmware:release_5.5.4 | 5.5.4 release]] page.
  * The following packages: <code bash>sudo apt-get install device-tree-compiler cpio binutils tree</code>

==== 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:
<code bash>
$ 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
</code>


=== 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''.

<code>
####################
# MAIN CUSTOMER PART
####################

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

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:
<code bash>
cp ${ROOTFSRW_PATH}/etc/non_existant_file ${SAFEZONE_MOUNTPOINT}/ || fatal_error "Error detected! stop the upgrade!!"
</code>

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'').

<code>
####################
# MAIN CUSTOMER PART
####################

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

  * ''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:
<code bash>
#./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
</code>


<note tip>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.
<code bash>
./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
</code></note>


=== 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:
<code bash>
./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
</code>


  * 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 [[wiki:keros_custo:sw_updates|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'':
<code bash>
# ./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
</code>

===  Extract content of a custom liveburner ===

Custom packages and scripts are integrated deeply in the liveburner. A tool is available to extract them easily:
<code bash>
# ./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
</code>


=== Upgrade traces ===

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


++++