This is an old revision of the document!

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

KerOS v4.x introduces some important modifications (new Kernel, rootfsRW, hotfixing) requiring an upgrade with a liveburner. 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 package, data and configurations will be lost using such upgrade package.
This upgrade will be problematic for products already on the field that needs to keep a Device Management link UP and RUNNING before and after the upgrade.

To solve this, this procedure will provide:

A way to backup some files (i.e. configurations) before flashing the eMMC and restore them at the end of the upgrade.
A tool to customize a liveburner in order to add some additional packages during the upgrade.

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:

Deploy and install the customized liveburner IPK on the product.
Product will restart on the liveburner upgrade tool.
Execution of the script preinst to mount a safezone and copy the files to backup on it.
Upgrade of the KerOS system including the eMMC flash and installation of the KerOS package.
Execution of the preapps and/or postapps scripts to access to the safezone and restore/merge saved files.
Installation of the additional packages and save in backup.
Restart on the new KerOS system.

Requirements

A desktop Linux machine (native or virtual).
An original KerOS liveburner 4.x package available in the resources page.
The update_liveburner_package-4.0-g8c53719.tar.gz tool available here.

The following packages:

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

Limits

Some limits are present in this upgrade mechanism:

Safezone space: 2MiB.
Additional packages max size cumulated: 20MiB.
Secure Storage is lost for products without Secure Boot activated.

Usage

Generate a custom liveburner (from a Linux machine)

Default process

First, uncompress the update_liveburner package:

#tar -xvzf update_liveburner_package-4.0-g8c53719.tar.gz
update_liveburner.sh
dumpimage
mkimage
fitimage.its
preinst
preapps

The package is ready to be used but will only backup/restore the network configuration files.

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

#./update_liveburner.sh liveburner_4.0.X_klk-lpbs-signed.ipk preinst preapps
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 preinst preapps my_packet.ipk

Advanced process with customization (experienced user)

Default upgrade will only keep the network configuration but it is possible to customize it using the preinst and preapps 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 and preapps like detailed below.

The recommended way is at least to clean the safezone content before starting to backup your files. The only file that must be kept in the safezone is keros_config.tar.gz.

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 case of customer blocking problem 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 customer 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:

Restore using the preapps/postapps scripts.
Use scripts in application packages.

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

#!/bin/sh
# Description: Script to be executed during a liveburner upgrade
# but before installing application packages.
# It will mount the safezone and restore the files.
 
EMMC_DEVICE="NOT_SUPPORTED"
SAFEZONE_MOUNTPOINT="/tmp/safezeone"
KEROS_CONFIGS_ARCHIVE="keros_config.tar.gz"
 
fatal_error()
{
	echo "$1"
	exit 1
}
 
detect_emmc()
{
	for i in $(seq 0 9); do
		if [ -b "/dev/mmcblk${i}" ]; then
			EMMC_DEVICE="mmcblk${i}"
			break
		fi
	done
 
	if [ "${EMMC_DEVICE}" == "NOT_SUPPORTED" ]; then
		fatal_error "Emmc device not found. Kernel version: ${KERNEL_VERSION}. Please fix."
	fi
}
 
mount_safezone()
{
	echo "Mounting safezone"
	echo 0 > /sys/block/${EMMC_DEVICE}boot0/force_ro
	mkdir -p ${SAFEZONE_MOUNTPOINT}
	mount /dev/${EMMC_DEVICE}boot0 ${SAFEZONE_MOUNTPOINT}
	echo "Safezone ready to use"
}
 
restore_keros_configurations()
{
	echo "Restoring KerOS configurations from safezone..."
	if [ -f ${SAFEZONE_MOUNTPOINT}/${KEROS_CONFIGS_ARCHIVE} ]
	then
		tar -xvzf ${SAFEZONE_MOUNTPOINT}/${KEROS_CONFIGS_ARCHIVE} -C /
		echo "Restoration finished"
	else
		echo "No restoration files in safezone. Nothing done."
	fi
}
 
adjust_keros_configurations()
{
	echo "Adjusting KerOS configurations..."
 
	# Allow Connman to be configured by webui/restAPI
	for cnf_file in /etc/network/connman/lan.config /etc/network/connman/wlan.config
	do
		[ -f "${cnf_file}" ] && mv "${cnf_file}" "${cnf_file}.keros3"
	done
	echo "LAN and WLAN configuration files removed"
 
	for service_dir in $(find /etc/network/connman/ -type d \( -name ethernet_* -o -name wifi_* \))
	do
		local settings_file="${service_dir}/settings"
		if [ -f "${settings_file}" ]
		then
			echo "Adjust configuration in ${settings_file}"
			sed -i '/^Config\.file.*/d' "${settings_file}"
			sed -i '/^Config\.ident.*/d' "${settings_file}"
			sed -i 's/^IPv4\.method\=fixed.*/IPv4\.method\=manual/g' "${settings_file}"
		fi
	done
 
	echo "Adjustements finished"
}
 
detect_emmc
mount_safezone
restore_keros_configurations
adjust_keros_configurations
 
####################
# MAIN CUSTOMER PART
####################
 
# Example:
# cp -fR ${SAFEZONE_MOUNTPOINT}/*  /etc/

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.

Expected traces of upgrade

Please find here the important part of a liveburner upgrade with save/restoration of network files:

traces.log

Application package custom-liveburner_4.0-beta1-72-g1461500-dirty_klk-lpbs-unsigned.ipk found
Creating safezone
mke2fs 1.43.5 (04-Aug-2017)
Discarding device blocks: done                            
Creating filesystem with 2048 1k blocks and 256 inodes

Allocating group tables: done                            
Writing inode tables: done                            
Writing superblocks and filesystem accounting information: done

[    6.929758] EXT4-fs (mmcblk0boot0): mounted filesystem without journal. Opts: (null)
Safezone created and ready to use
Backuping KerOS configurations in safezone...
etc/network/
etc/network/connman/
etc/network/connman/lan.config.example
etc/network/connman/main.conf
etc/network/connman/settings
etc/network/connman/wlan.config.example
etc/network/connman/wlan.config
etc/network/connman/lan.config
etc/network/connman/ethernet_7076ff017771_cable/
etc/network/connman/ethernet_7076ff017771_cable/settings
etc/network/connman/ethernet_7076ff017771_cable/data
etc/network/fixnetwork.conf
etc/network/if-down.d/
etc/network/if-post-down.d/
etc/network/if-pre-up.d/
etc/network/if-pre-up.d/nfsroot
etc/network/if-up.d/
etc/network/if-up.d/ntpdate-sync
etc/network/ifplugd/
etc/network/ifplugd/local.action
etc/network/ifplugd/local.conf
etc/network/interfaces
etc/network/netctl.cfg
etc/network/networkmonitoring.conf
etc/network/ofono/
etc/network/ofono/provisioning
etc/network/udhcpd.conf
Backup finished
Installing liveburner (4.0-beta1-72-g1461500) on root.
Configuring liveburner.
2018.07.23-15:05:11 -- Update from custom-liveburner_4.0-beta1-72-g1461500-dirty_klk-lpbs-unsigned.ipk: OK
2018.07.23-15:05:11 -- Update Status : updated 1, failed 0 , partial 0 result : OK
.
.
.
Starting Burner

-> Clean All EMMC including ProvenCore Data
64+0 records in
64+0 records out

-> Create partitions
Checking that no-one is using this disk right now ... OK

Disk /dev/mmcblk0: 7.3 GiB, 7818182656 bytes, 15269888 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes

>>> Created a new DOS disklabel with disk identifier 0xc68711b9.
/dev/mmcblk0p1: Created a new partition 1 of type 'Linux' and of size 512 MiB.
/dev/mmcblk0p2: Created a new partition 2 of type 'Linux' and of size 512 MiB.
Partition #2 contains a ext4 signature.
/dev/mmcblk0p3: Created a new partition 3 of type 'Linux' and of size 6.3 GiB.
Partition #3 contains a ext4 signature.
/dev/mmcblk0p4: Done.

New situation:
Disklabel type: dos
Disk identifier: 0xc68711b9

Device         Boot   Start      End  Sectors  Size Id Type
/dev/mmcblk0p1         2048  1050623  1048576  512M 83 Linux
/dev/mmcblk0p2      1050624  2099199  1048576  512M 83 Linux
[   11.129860]  mmcblk0: p1 p2 p3887 13170688  6.3G 83 Linux


The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.
[   11.155498]  mmcblk0: p1 p2 p3
Checking that no-one is using this disk right now ... OK

Disk /dev/mmcblk0: 7.3 GiB, 7818182656 bytes, 15269888 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0xc68711b9

Old situation:

Device         Boot   Start      End  Sectors  Size    11.197039]  mmcblk0: p1 p2 p3
1mId Type
/dev/mmcblk0p1         2048  1050623  1048576  512M 83 Linux
/dev/mmcblk0p2      1050624  2099199  1048576  512M 83 Linux
/dev/mmcblk0p3      2099200 15269887 13170688  6.3G 83 Linux

/dev/mmcblk0p1: 
New situation:
Disklabel type: dos
Disk identifier: 0xc68711b9

Device         Boot   Start      End  Sectors  Size Id Type
/dev/mmcblk0p1       131072  1048575   917504  448M 83 Linux
/dev/mmcblk0p2      1050624  2099199  1048576  512M 83 Linux
/dev/mmcblk0p3      2099200 15269887 13170688  6.3G 83 Linux

The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.

-> Formatting p1: Keros ...
/dev/mmcblk0p1 contains a ext4 file system labelled 'Keros'
        last mounted on /keros on Mon Jul 23 15:04:58 2018

-> Formatting p2: Update ...
/dev/mmcblk0p2 contains a ext4 file system labelled 'Update'
        last mounted on /.update on Mon Jul 23 15:04:57 2018

-> Formatting p3: User ...
/dev/mmcblk0p3 contains a ext4 file system labelled 'User'
        last mounted on /user on Mon Jul 23 15:04:58 2018
[   14.413387] random: crng init done
[   22.525725] EXT4-fs (mmcblk0p2): mounted filesystem with ordered data mode. Opts: (null)
[   22.613598] EXT4-fs (mmcblk0p1): mounted filesystem with ordered data mode. Opts: (null)
umount: can't unmount none: No such file or directory
 -> Burning nominal firmware ...
---> Burning /burner/keros.ipk
mount: mounting /dev/mmcblk0p1 on /keros failed: Device or resource busy
[   23.810167] EXT4-fs (mmcblk0p1): re-mounted. Opts: (null)
-> Updating u-boot ...
94+0 records in
94+0 records out
455+1 records in
455+1 records out
4906+1 records in
4906+1 records out
Installing keros (4.0-beta1-72-g1461500) on root.
Configuring keros.
---> Save it as STOCK package
[   36.280173] EXT4-fs (mmcblk0p1): mounted filesystem with ordered data mode. Opts: (null)
umount: can't unmount none: No such file or directory
[   36.525435] EXT4-fs (mmcblk0p3): mounted filesystem with ordered data mode. Opts: (null)
OverlayFS available, mounting RootFS in RW
preapps script present, execute it...
Mounting safezone
[   37.117425] EXT4-fs (mmcblk0boot0): mounted filesystem without journal. Opts: (null)
Safezone ready to use
Restoring KerOS configurations from safezone...
etc/network/
etc/network/connman/
etc/network/connman/lan.config.example
etc/network/connman/main.conf
etc/network/connman/settings
etc/network/connman/wlan.config.example
etc/network/connman/wlan.config
etc/network/connman/lan.config
etc/network/connman/ethernet_7076ff017771_cable/
etc/network/connman/ethernet_7076ff017771_cable/settings
etc/network/connman/ethernet_7076ff017771_cable/data
etc/network/fixnetwork.conf
etc/network/if-down.d/
etc/network/if-post-down.d/
etc/network/if-pre-up.d/
etc/network/if-pre-up.d/nfsroot
etc/network/if-up.d/
etc/network/if-up.d/ntpdate-sync
etc/network/ifplugd/
etc/network/ifplugd/local.action
etc/network/ifplugd/local.conf
etc/network/interfaces
etc/network/netctl.cfg
etc/network/networkmonitoring.conf
etc/network/ofono/
etc/network/ofono/provisioning
etc/network/udhcpd.conf
Restoration finished
Done
 -> Installing additional packages ...
 -> Burning Stock Firmware ...

-> Set Redundant Boot (Secondary Image Table)
0+1 records in
0+1 records out

-> flashing Secondary boot binaries
94+0 records in
94+0 records out
455+1 records in
455+1 records out
4906+1 records in
4906+1 records out

-> flashing Stock Linux
16899+1 records in
16899+1 records out

-> Creating backup ...
umount: can't unmount /rootfs/tmp: Device or resource busy
MAC0 = 70:76:ff:01:77:71
MAC1 = 72:76:ff:01:77:71
Serial no = 0x2e060240
0x00000005
Reboot is needed

Wirnet™ i-series

Sidebar

Table of Contents

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

Introduction

Upgrade procedure

Requirements

Limits

Usage

Generate a custom liveburner (from a Linux machine)

Default process

Advanced process with customization (experienced user)

Save

Restore

Install a custom liveburner

Expected traces of upgrade

Wirnet™ i-series

User Tools

Site Tools

Sidebar

Table of Contents

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

Introduction

Upgrade procedure

Requirements

Limits

Usage

Generate a custom liveburner (from a Linux machine)

Default process

Advanced process with customization (experienced user)

Save

Restore

Install a custom liveburner

Expected traces of upgrade

Page Tools