Wirnet™ i-series

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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.

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

===== 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 [[wiki:resources|resources page]].
  * The ''update_liveburner_package-4.0-g8c53719.tar.gz'' tool available [[wiki:resources#other_tools|here]].
  * The following packages: <code bash>sudo apt-get install device-tree-compiler cpio binutils</code>

===== 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:
<code bash>
#tar -xvzf update_liveburner_package-4.0-g8c53719.tar.gz
update_liveburner.sh
dumpimage
mkimage
fitimage.its
preinst
preapps
</code>

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:
<code bash>
#./update_liveburner.sh liveburner_4.0.X_klk-lpbs-signed.ipk preinst preapps
Liveburner custom-liveburner_4.0.X_klk-lpbs-signed.ipk created
</code>

<note tip>
Additional packages can be installed simply by adding them as arguments.
<code bash>
./update_liveburner.sh liveburner_4.0.2_klk-lpbs-signed.ipk preinst preapps my_packet.ipk
</code>
</note>

=== 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 |
<code bash preinst.sh>
#!/bin/sh
# Description: Script to be executed before a liveburner upgrade.
# It will mount a safezone to backup the configuration files BEFORE
# the installation of the new firmware.


EMMC_DEVICE="NOT_SUPPORTED"
SAFEZONE_MOUNTPOINT="/tmp/safezeone"
KEROS_CONFIGS_ARCHIVE="keros_config.tar.gz"
ROOTFSRW_PATH="/"

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}"
			# Update RootFS RW path for system without overlayFS
			[ ${i} -eq 3 ] && ROOTFSRW_PATH="/user/rootfs_rw/"
			break
		fi
	done

	if [ "${EMMC_DEVICE}" == "NOT_SUPPORTED" ]; then
		fatal_error "Emmc device not found. Kernel version: ${KERNEL_VERSION}. Please fix."
	fi
}

create_safezone()
{
	echo "Creating safezone"
	echo 0 > /sys/block/${EMMC_DEVICE}boot0/force_ro
	mkfs.ext2 -F /dev/${EMMC_DEVICE}boot0 || fatal_error "Error during safezone format"
	mkdir -p ${SAFEZONE_MOUNTPOINT}
	mount /dev/${EMMC_DEVICE}boot0 ${SAFEZONE_MOUNTPOINT} || fatal_error "Error during safezone mount"
	echo "Safezone created and ready to use"
}

backup_keros_configurations()
{
	echo "Backuping KerOS configurations in safezone..."
	tar -cvzf ${SAFEZONE_MOUNTPOINT}/${KEROS_CONFIGS_ARCHIVE} -C ${ROOTFSRW_PATH} etc/network
	echo "Backup finished"
}

detect_emmc
create_safezone
backup_keros_configurations

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

# Example:
# cp ${ROOTFSRW_PATH}/etc/hosts ${SAFEZONE_MOUNTPOINT}/
</code>
++++

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

</code>
++++

<note tip>''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>

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 [[wiki:sw_updates|here]]. 

==== Expected traces of upgrade ====

Please find here the important part of a liveburner upgrade with save/restoration of ''network'' files:
++++ traces.log |
<code>
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
</code>
++++
Wirnet™ i-series

User Tools

Site Tools

Page Tools
