Differences

This shows you the differences between two versions of the page.

--- wiki:upgrade_keros3_to_4 [2018/09/20 14:44]
ghi [Upgrade procedure]
+++ — (current)
@@ Line 1: / Line 1: @@
-====== Upgrade from KerOS 3.x to 4 with custom liveburner ======
-KerOS 4.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 flush 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 flushing 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 raw.</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 flush 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 =====
-  * 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>
-<note important>Procedure hereunder is dedicated to Linux operating systems.</note>
-===== 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 ====
-=== 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.
-++++ preinst |
-<code>
-#!/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.
-++++ preapps |
-<code>
-#!/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.
-.07.23-15:05:11 -- Update from custom-liveburner_4.0-beta1-72-g1461500-dirty_klk-lpbs-unsigned.ipk: OK
-.07.23-15:05:11 -- Update Status : updated 1, failed 0 , partial 0 result : OK
-.
-.
-.
-Starting Burner
--> Clean All EMMC including ProvenCore Data
-+0 records in
-+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
-mId 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 ...
-+0 records in
-+0 records out
-+1 records in
-+1 records out
-+1 records in
-+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)
-+1 records in
-+1 records out
--> flashing Secondary boot binaries
-+0 records in
-+0 records out
-+1 records in
-+1 records out
-+1 records in
-+1 records out
--> flashing Stock Linux
-+1 records in
-+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
-x00000005
-Reboot is needed
-</code>
-++++

Wirnet™ i-series

User Tools

Site Tools

Differences

Page Tools