Packages management

Packages management

The KerOS Distribution supports OPKG packages (embedded version compatible with dpkg packages).

OPKG packages are used to install customer applications and firmware upgrades (the firmware is installed with an OPKG package). OPKG packages use the .ipk extension. It is strongly recommended to use OPKG packages to deploy binaries/applications since the backup mechanism relies on it. Please follow update procedure to install an IPK.

A package can either be installed using the network or using a USB key.

Software packages

Despite some specific packages like keros for the firmware and removal packages, software packages should respect some recommendations:

Data including configuration should be installed in /user partition.
Files deployed in rootfs should be saved during upgrade by adding a sysupgrade dedicated file.

Compatibility from previous versions

The firmware version KerOS 4.0 introduced some important modifications in the system that have some consequences on the packages compatibility:

/user/rootfs_rw path is no longer valid. RootFS files needs to be modified directly: /etc/hosts instead of /user/rootfs_rw/etc/hosts
cortexa9hf-neon-mx6sx architecture is not longer valid and must be replaced by armv7ahf-neon

Starting from version 4.1, KerOS firmwares are usable on all Wirnet™ i-series gateways. Product arch is klkgw for all gateways.

Accepted Architectures

To sum up the accepted package's architectures on the gateways, you can consult the following table:

Firmware Version	Wirnet™ iFemtoCell	Wirnet™ iBTS	Wirnet™ iStation	Wirnet™ iFemtocell-Evolution	Wirnet™ iZeptoCell
Firmware Version	Gateway
KerOS v4.0	armv7ahf-neon klk_wifc	armv7ahf-neon klk_lbps	Not supported	Not supported	Not supported
KerOS v4.1	armv7ahf-neon klk_wifc klkgw	armv7ahf-neon klk_lbps klkgw	armv7ahf-neon klkgw	Not supported	Not supported
KerOS v4.2				armv7ahf-neon klkgw	Not supported
KerOS v5.x				armv7ahf-neon klkgw	armv7ahf-neon klkgw

Please note that the klkgw architecture is accepted on every product since KerOS v4.1! So package maintainer MUST integrates a detection of the product (if necessary) in order to adapt its behavior

RootFS files Warning

If the package contains RootFS files and overrides system files (i.e. /etc/syslog.conf), the package maintainer must manage the removal of the package differently. The package must have a postrm that will restore or merge the original KerOS file.

Example:

postrm

#!/bin/sh
 
KEROS_RO_SQFS="/keros/keros.sqfs"
KEROS_RO_MP="/.rootfs.ro"
 
fatal_error()
{
	echo "$1"
	exit 1
}
 
# Mount KerOS original Rootfs
mount_keros_rootfs()
{
	mount -t squashfs -o ro ${KEROS_RO_SQFS} ${KEROS_RO_MP} || fatal_error "Error when mounting KerOS RO rootfs"
}
 
# Umount KerOS original Rootfs
umount_keros_rootfs()
{
	umount ${KEROS_RO_MP}
	sync
}
 
mount_keros_rootfs
 
##########
# Revert KerOS original files here
# ex: cp -f ${KEROS_RO_MP}/etc/syslog.conf /etc/syslog.conf
##########
echo "Reverting file /etc/syslog.conf..."
cp -f ${KEROS_RO_MP}/etc/syslog.conf /etc/syslog.conf
echo "Done"
 
umount_keros_rootfs

If this operation is not done, the system could become unstable if the package is removed because the original file will not be automatically restored. Instead, the file will simply be removed.

Building your own package

An .ipk package contains two sets of files: a set of files to install on the system when the package is installed, and a set of files that provide additional metadata about the package or which are executed when the package is installed or removed. This second set of files is called control information files. Additionally, OPKG automatically generates a file named debian-binary. The debian-binary file contains the version of the Debian file format.

IPK packages are not directly built on the gateway. They are built on a computer with a Linux OS. If the files to be installed are binaries, they first need to be cross-compiled using appropriate toolchain. Toolchain corresponding to your firmware can be found here.

This section gives a practical example about how to generate an .ipk package. To build a custom package, it is advised to use this example as a reference and then modify it.

This packet, named test-packet-1_1.0_klk_lpbs, installs two files in the folder /user/test-packet1_1.0. One is installed by OPKG, the second is generated by a script.

Below are the contents of the package.

#test-packet-1_1.0_klk_lpbs
.
├── control.tar.gz
├── data.tar.gz
└── debian-binary

In this example, the control.tar.gz archive contains three files.

A file named control that contains meta-data about the package.
A script named preinst that is executed before package installation. It displays a message.
A script named postinst that is executed after package installation. It displays a message and generates a comment line in the file /etc/syslog.conf.
A script named postrm that is executed after package deinstallation. It displays a message.

As best it can, opkg maintains backward compatibility with ipkg and conforms to a subset of Debian's policy manual regarding control files.

# control.tar.gz
. 
├── control
├── postinst
├── preinst
└── postrm

The archive data.tar.gz contains the set of files to install. In this example, test_file1-1.0 file is in the folder test-packet1_1.0 which is in the folder user. Thus, during the installation test_file1-1.0 file will be copied under /user/test-packet1_1.0.

# data.tar.gz
.
└── user
    └── test-packet1_1.0
        └── test_file1-1.0

To generate a package, the tools opkg-build require a directory tree containing all the files to copy, all scripts and the meta-data file. The following script generates the directory tree as well as the files populating it. Then it creates the packet itself. To do so, 6 steps are required:

Downloading opkg-build if not already done.
Generating a control file containing meta-data in the CONTROL folder.
Generating a dummy file to be installed in /user/test-packet1_1.0.
Generating a script file that will display a message during the installation in the CONTROL folder.
Generating in the CONTROL folder a script file that will display a message during the installation and generate a file in /user/test-packet1_1.0.
Building the packet using opkg-build.

generate_ipk.sh

generate_ipk.sh

#!/bin/sh
 
WORKDIR=`dirname $0`
 
OPKGB_WEB="https://git.yoctoproject.org/cgit/cgit.cgi/opkg-utils/plain/opkg-build"
OPKG_PKG_NAME="test-packet1"
VERSION="2.0"
OPKG_PKG_DIR="${WORKDIR}/package"
DEST_DIR="${OPKG_PKG_DIR}/user/${OPKG_PKG_NAME}_${VERSION}"
#ARCH defines wether the packet will be used on IBTS (klk_lpbs), iFemtoCell (klk_wifc)
# or all the Kerlink Wirnet(TM) products with KerOS FW >=v4.1 (klkgw)
ARCH="klkgw"
 
PATH=${PATH}:${WORKDIR}
 
# 1 - Download opkg-build if necessary
command -v opkg-build > /dev/null 2>&1
if [ $? -ne 0 ]
then
	echo "Opkg-build is necessary, downloading it from ${OPKGB_WEB}"
	wget ${OPKGB_WEB}
	chmod 755 opkg-build
fi
 
# 2 - Generate meta-data for opkg
rm -rf ${OPKG_PKG_DIR}
mkdir -p ${OPKG_PKG_DIR}/CONTROL
cat > ${OPKG_PKG_DIR}/CONTROL/control << EOF
Package: ${OPKG_PKG_NAME}
Version: ${VERSION:=0.0}
Architecture: ${ARCH}
Maintainer: Kerlink <support@kerlink.fr>
Priority: optional
Section: test
Source: Kerlink's Wirnet(TM) i-series wiki
Description: Install two files in userland
EOF
 
# 3 - Copy or create the file(s) to be installed
mkdir -p ${DEST_DIR}
 
cat > ${DEST_DIR}/test_file1-${VERSION} << EOF
I am a test file. I should be removed if my package is uninstalled.
EOF
 
# In most cases, the user doesn't need this script to generate the files to be installed 
# He just needs to copy pre-existing files from another directory
# The previous "cat" command can be replaced by a "cp" command
# cp /custom/path/to/file_to_install ${DEST_DIR}/ 
 
# 4 - Generate or copy a preinst script
cat > ${OPKG_PKG_DIR}/CONTROL/preinst << EOF 
	echo "I am a script file executed before the installation of ${OPKG_PKG_NAME}-${VERSION}"
EOF
 
# In most cases, the user doesn't need this script to generate the "preinst" file
# He just needs to copy a pre-existing file from another directory
# The previous "cat" command can be replaced by a "cp" command
# cp /custom/path/to/preinst ${OPKG_PKG_DIR}/CONTROL/
 
chmod 755 ${OPKG_PKG_DIR}/CONTROL/preinst
 
# 5 - Generate or copy a postinst script
cat > ${OPKG_PKG_DIR}/CONTROL/postinst << EOF1
echo "I am a script file executed after the copy of the files in ${OPKG_PKG_NAME}-${VERSION}"
echo "# I am the test line from the test IPK package" >> /etc/syslog.conf 
EOF1
 
# In most cases, the user doesn't need this script to generate the "postinst" file
# He just needs to copy a pre-existing file from another directory
# The previous "cat" command can be replaced by a "cp" command
# cp /custom/path/to/postinst ${OPKG_PKG_DIR}/CONTROL/
 
chmod 755 ${OPKG_PKG_DIR}/CONTROL/postinst
 
# 6 - Generate or copy a postrm script
cat > ${OPKG_PKG_DIR}/CONTROL/postrm << EOF2
echo "I am a script file executed after the deinstallation of package ${OPKG_PKG_NAME}-${VERSION}"
EOF2
 
# In most cases, the user doesn't need this script to generate the "postrm" file
# He just needs to copy a pre-existing file from another directory
# The previous "cat" command can be replaced by a "cp" command
# cp /custom/path/to/postrm ${OPKG_PKG_DIR}/CONTROL/
 
chmod 755 ${OPKG_PKG_DIR}/CONTROL/postrm 
 
 
# 7 - Generate the package
rm -f *.ipk
opkg-build -o root -g root ${OPKG_PKG_DIR} > log
cat log
rm -f log

Package removal

A package removal mechanism is available. Using this mechanism is strongly recommended to avoid problems during backup restore. See Backup restore section for more information.

Package removal is done by installing (over network or USB) a removal package.

"removal packages" generation

Removal packages are generated with the tool gen_remove_ipk. It can be downloaded from the the resources page.
This tool requires installing build-essential on your host:

sudo apt-get install build-essential

The generation of the removal package is done using the following command.

./gen_remove_ipk ipk_name

Where ipk_name is the name of the package to be removed. The installed package names can be retrieved using the following command on the gateway. In the below example, the names are keros and test (the characters before the dash)

opkg list-installed
keros - 3.1.3
test - 1.0.0

gen_remove_ipk generates 2 IPK files:

<package name to remove>-remove.ipk: used to remove the package in the running configuration
<package name to remove>-remove-backup.ipk: used to remove the package in the running configuration and in the backup

It is recommend to use the remove-backup ipk.
To get the list of backuped packages use the following command:

root@klk-lpbs-0507DD: ll /.update/packages/backup/
drwxr-xr-x    2 root     root        4.0K Jun  5 15:29 .
drwxr-xr-x    4 root     root        4.0K Jun  5 15:00 ..
-rw-r--r--    1 root     root       38.6M Jun  5 12:53 keros.ipk

"Removal packages" use

Removal packages are installed on the target using standard update process (USB or network).

The status of the removal can be checked in /user/.update file:

2017.02.16-17:02:41 -- Remove package with backup from test-remove-backup.ipk: OK

Files that are not present in data.tar.gz archive of the original package will not be removed. For example, if the script postinst executed during the installation generates a file, it won’t be removed.

These IPK are special packages for the system:

They are not installed in packages list
They are not installed in backup

Hotfix packages

In order to provide a limited correction to the system, KerOS firmware >= 4.0 comes with a hotfix management. It allows the installation of the temporary but quick correction on the system. These corrections are generally integrated in next KerOS upgrade.

Hotfix packages have a strict dependency to the applicable KerOS version. Therefore, a hotfix package will not be kept when upgrading the system.

Create a hotfix package

To generate a hotfix package, the generate_hotfix_package.tar example provided in the resources page can be used.

Important fields in my_package_hotfix/CONTROL/control must be present.

Field	Role	Possible values
Architecture	Compatible target: iBTS, iFemtocell	Wirnet™ iBTS: klk_lpbs Wirnet™ iFemtoCell: klk_wifc All (KerOS >= 4.1.0): klkgw
Depends	Compatible KerOS version for the hotfix	4.0.2-0-g0d9f3135, 4.0.4-0-gad6a8c27
Tags	Indicates to the system that it is a hotfix package	hotfix

The KerOS version can be found on the product using these commands:

opkg info keros | grep Version
Version: 4.0.2-0-g0d9f3135

The package can be generated using opkg-build binary. Procedure hereunder is dedicated to Linux operating systems. There is no embedded compiler in Wirnet™ i-series gateways.

tar -xzf generate_hotfix_package.tar.gz
cd my_package_hotfix/
./opkg-build -o root -g root my_package_hotfix/

Hotfix package can be deployed on a product using the standard software update mechanism.

Table of Contents