User Tools

Site Tools


Sidebar

Kerlink Wiki Home Page

Home

Setups

General information

Wirnet™ iBTS information

Wirnet™ iFemtoCell information

Wirnet™ iFemtoCell-evolution information

Wirnet™ iStation information

System management

Network management

LoRa Features

KerOS customization

Support and resources



www.kerlink.com

wiki:keros_custo:package_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 Gateway
Wirnet™ iFemtoCell Wirnet™ iBTS Wirnet™ iStation Wirnet™ iFemtocell-Evolution Wirnet™ iZeptoCell
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

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:

  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

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.

wiki/keros_custo/package_management.txt · Last modified: 2022/10/24 16:49 by ehe