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.

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.

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 or the preferred target product arch: klk_lbps and klk_wifc.

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 can be unstable because the original file will not be restored automatically so the file is simply removed when the package will be removed.

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 Unix environment. If the files to be installed are binaries, they first need to be cross-compiled using the toolchain: Wirnet iBTS toolchain or Wirnet iFemtoCell toolchain.

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 will restore or merge the original KerOS file /etc/syslog.conf modify in this example.

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 requires a directory tree containing all files to copy, all scripts and 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:

1. Downloading opkg-build if not already done.
2. Generating a control file containing meta-data in the CONTROL folder.
3. Generating a dummy file to be installed in /user/test-packet1_1.0.
4. Generating a script file that will display a message during the installation in the CONTROL folder.
5. 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.
6. Building the packet using opkg-build.

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) or iFemtoCell (klk_wifc)
ARCH="klk_lpbs"
 
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 iFemtocell or IBTS 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
 
#!/bin/sh
 
fatal_error()
{
	echo "$1"
	exit 1
}
 
# Mount KerOS original Rootfs
mount_keros_rootfs()
{
	mount -t squashfs -o ro /keros/keros.sqfs /.rootfs.ro || fatal_error "Error when mounting KerOS RO rootfs"
}
 
# Umount KerOS original Rootfs
umount_keros_rootfs()
{
	umount /.rootfs.ro
	sync
}
 
mount_keros_rootfs
 
##########
# Revert KerOS original files here
##########
echo "Reverting file /etc/syslog.conf..."
cp -f /.rootfs.ro/etc/syslog.conf /etc/syslog.conf
echo "Done"
 
umount_keros_rootfs
 
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

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 are generated with the tool gen_remove_ipk. You can download it from wiki page: Common resources.
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.

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

root@klk-lpbs-0507DD:/.update/packages/backup # 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 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.

In order to provide a limited correction to the system, KerOS firmware >= 4.0 provides a hotfix management. It allows the installation of the temporary but quick correction on the system. This correction is generally integrated in next KerOS upgrade.

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

To generate a hotfix package, you can use the generate_hotfix_package.tar example provided in the wiki pages: Common resources.

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

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 iBTS and Wirnet iFemtoCell.

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.