Table of Contents

Upgrade from KerOS version 3.x to 4.0 with custom liveburner

KerOS v4.0 introduces some important modifications (new kernel, rootfsRW, hotfixing) requiring an upgrade with a liveburner when coming from KerOS v3.x firmware. This page will provide a way to do this upgrade with conservation of some elements like the configuration and reinstall some additional packages.

Introduction

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

To solve this, this procedure will provide:

This procedure is not applicable to the 4.1 version of KerOS liveburner. More information about the supported migration scenarii is available here

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

Upgrade procedure

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 to mount a safezone and copy the files to backup on it.
  4. Upgrade of the KerOS system including the eMMC flash and installation of the KerOS package.
  5. Execution of the preapps and/or postapps scripts to access to the safezone and restore/merge saved files.
  6. Execution of the preapps script (if present) to access to the safezone and restore/merge saved files
  7. Installation of the additional packages
  8. Execution of the postapps script (if present)
  9. Save packages in backup
  10. Execution of the prereboot script (if present)
  11. Restart on the new KerOS system.

Requirements

Limits

Some limits are present in this upgrade mechanism:

Migrations supported

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

Usage

Generate a custom liveburner (from a Linux machine)

Default process

First, uncompress the update_liveburner package:

#tar -xvzf update_liveburner_package-v4.1.0.tar.gz
update_liveburner.sh
extract_custom_elements.sh
show_ipk_infos.sh
functions
dumpimage
mkimage
sample_scripts/
sample_scripts/postapps
sample_scripts/preapps
sample_scripts/preinst
sample_scripts/prereboot
spftocpfconf.klk-lpbs
spftocpfconf.klk-wifc
spftocpfconf.klkgw

The package is ready to be used with some integrated migrations.

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

#./update_liveburner.sh liveburner_4.0.X_klk-lpbs-signed.ipk sample_scripts/preapps sample_scripts/postapps sample_scripts/preinst sample_scripts/prereboot
Liveburner custom-liveburner_4.0.X_klk-lpbs-signed.ipk created

Additional packages can be installed simply by adding them as arguments.

./update_liveburner.sh liveburner_4.0.2_klk-lpbs-signed.ipk sample_scripts/preapps sample_scripts/postapps sample_scripts/preinst sample_scripts/prereboot my_package.ipk

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_4.0.2_klk-lpbs-signed.ipk sample_scripts/preapps sample_scripts/postapps sample_scripts/preinst sample_scripts/prereboot

Advanced process with customization (experienced user)

Default upgrade will only keep the network configuration but it is possible to customize it using the preinst, preapps, postapps or prereboot scripts. Please note that some variables/mountpoints are provided:

Variable Role Example
ROOTFSRW_PATH Root path adapted to the firmware version. For KerOS < 4.0 it will be /user/rootfs_rw/ and for >= 4.0 version it will be / 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}/

In case of custom upgrade, please note that the management of the content of the safezone needs to be done using the scripts preinst, 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.

Save

Saving files must be done using the preinst script. It will be executed before installing the new firmware. As an example, the preinst script provided will backup the network configuration files in the safezone.
To add some files, append them at the end of the script like shown in the commented example line.

File to download - preinst.sh

In the case of 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 about 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

To restore, 2 ways are possible:

The first way is the more simple way. It consist of adapting the preapps/postapps scripts (like for preinst). Kerlink recommends this method.

File to download - preapps.sh

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.

The second way to restore files is to add pre/post scripts in the applications packages themselves, The drawback of this method is that application packages will be saved in backup. So the risk is to restore the files in safezone during a restoration of the product!

Install a custom liveburner

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

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

For example:

# ./show_ipk_infos.sh custom-liveburner_4.0.2_klk-lpbs-signed.ipk
== Package content ==
 
/tmp/updateliveburner/ipk/
├── control
│   ├── control
│   ├── postinst
│   └── preinst
├── data
│   └── tmp
│       └── linux.itb
└── debian-binary
 
3 directories, 5 files
 
== Package CONTROL ==
 
Package: liveburner
Version: 4.0.2-0-g0d9f3135
Depends: keros (>= 2.0.0)
Architecture: klk_lpbs
Maintainer: Kerlink <support@kerlink.fr>
Priority: required
Section: keros
Source: http://www.kerlink.fr
Description: Kerlink OS
   Kerlink OS tunned for klk_lpbs target
   Sign information: SRK0=0xDBCE282B
   Files added:
      lorad_1.0.0-1_klk_lpbs.ipk
      lorafwd_1.0.1-1_armv7ahf-neon.ipk
      netsnmphotfix_1.0.0_klk_lpbs.ipk
      lorasnmp_v3.1_klk_lpbs.ipk
      bscc_v3.1_klk_lpbs.ipk
      preinst
      postapps
      prereboot
      preapps
 
== Burner content ==
 
/tmp/updateliveburner/ipk/data/tmp/itb/initrd/burner/
├── bscc_v3.1_klk_lpbs.ipk
├── keros.ipk
├── lorad_1.0.0-1_klk_lpbs.ipk
├── lorafwd_1.0.1-1_armv7ahf-neon.ipk
├── lorasnmp_v3.1_klk_lpbs.ipk
├── netsnmphotfix_1.0.0_klk_lpbs.ipk
├── postapps
├── preapps
├── prereboot
└── spftocpfconf
 
0 directories, 10 files

Extract content of a custom liveburner

Custom packages and scripts are integrated deeply in the liveburner. A tool is present 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

For example:

# ./extract_custom_elements.sh custom-liveburner_4.0.2_klk-lpbs-signed.ipk
Extracting IPK file "custom-liveburner_4.0.2_klk-lpbs-signed.ipk" in workspace /tmp/updateliveburner...
IPK file "custom-liveburner_4.0.2_klk-lpbs-signed.ipk" extracted
Extracting Linux ITB "/tmp/updateliveburner/ipk/data/tmp/linux.itb" in workspace /tmp/updateliveburner/ipk/data/tmp...
Extracting Kernel...
Extracted:
 Image 0 (kernel@1)
  Description:  Kerlink Linux kernel
  Created:      Mon Apr  1 11:04:03 2019
  Type:         Kernel Image
  Compression:  uncompressed
  Data Size:    4668384 Bytes = 4558.97 kB = 4.45 MB
  Architecture: ARM
  OS:           Linux
  Load Address: 0x80800000
  Entry Point:  0x80800000
  Hash algo:    md5
  Hash value:   932a4133297a29fb9ebb0b65fd8bcd44
Kernel extracted
Extracting DTB...
Extracted:
 Image 1 (fdt@1)
  Description:  Kerlink board Flattened Device Tree blob
  Created:      Mon Apr  1 11:04:03 2019
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    32907 Bytes = 32.14 kB = 0.03 MB
  Architecture: ARM
  Hash algo:    md5
  Hash value:   ebc1494b4546fa4bb824965abcebac86
DTB extracted
Extracting INITRD...
Extracted:
 Image 2 (ramdisk@1)
  Description:  Ramdisk Image
  Created:      Mon Apr  1 11:04:03 2019
  Type:         RAMDisk Image
  Compression:  gzip compressed
  Data Size:    55649617 Bytes = 54345.33 kB = 53.07 MB
  Architecture: ARM
  OS:           Linux
  Load Address: 0x82000000
  Entry Point:  0x82000000
  Hash algo:    md5
  Hash value:   b051802e0f1797103a8ab41540edac29
INITRD extracted
Linux ITB extracted
Extracting INITRD "/tmp/updateliveburner/ipk/data/tmp/itb/initrd.cpio.gz" in workspace /tmp/updateliveburner/ipk/data/tmp/itb...
116753 blocs
INITRD extracted
 
== Extracting elements ==
 
File bscc_v3.1_klk_lpbs.ipk extracted
File keros.ipk extracted
File lorad_1.0.0-1_klk_lpbs.ipk extracted
File lorafwd_1.0.1-1_armv7ahf-neon.ipk extracted
File lorasnmp_v3.1_klk_lpbs.ipk extracted
File netsnmphotfix_1.0.0_klk_lpbs.ipk extracted
File postapps extracted
File preapps extracted
File prereboot extracted
File spftocpfconf extracted
File preinst extracted
 
All elements are extracted in custom-liveburner_4.0.2_klk-lpbs-signed directory 
 
== Extraction finished ==

Upgrade traces

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

.upgrade.log

These traces are kept between custom liveburner but are lost in these situations:

In addition, the update journal in /user/.update is reset when using a liveburner:

2019.04.01-09:06:37 -- Update from keros.ipk: OK
2019.04.01-09:06:55 -- Update from bscc_v3.1_klk_lpbs.ipk: OK
2019.04.01-09:06:56 -- Update from lorad_1.0.0-1_klk_lpbs.ipk: OK
2019.04.01-09:07:01 -- Update from lorafwd_1.0.1-1_armv7ahf-neon.ipk: OK
2019.04.01-09:07:02 -- Update from lorasnmp_v3.1_klk_lpbs.ipk: OK
2019.04.01-09:07:03 -- Update from netsnmphotfix_1.0.0_klk_lpbs.ipk: OK
2019.04.01-09:07:15 -- Update Status : updated 6, failed 0 , partial 0 result : OK