====== 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 [[wiki:keros_custo:sw_updates|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 [[wiki:keros_custo:upgrade#configuration_management_sysupgrade|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          |  @red:Not supported     |  @red:Not supported             | @red:Not supported |
^  KerOS v4.1        |  armv7ahf-neon\\ klk_wifc\\ klkgw  |  armv7ahf-neon\\ klk_lbps\\ klkgw  |  armv7ahf-neon\\ klkgw  |  @red:Not supported             | @red:Not supported |
^  KerOS v4.2        |   :::                              |  :::                               |  :::                    |  armv7ahf-neon\\ klkgw          | @red:Not supported |
^  KerOS v5.x        |   :::                              |  :::                               |  :::                    |  :::                            | armv7ahf-neon\\ klkgw |

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

==== 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:__

<file bash 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
</file>


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 [[wiki:resources:resources#keros_firmware_and_toolchain|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.

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

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.

<code>
# control.tar.gz
. 
├── control
├── postinst
├── preinst
└── postrm

</code>


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''.

<code>
# data.tar.gz
.
└── user
    └── test-packet1_1.0
        └── test_file1-1.0
</code>

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

===== Package removal =====

A package removal mechanism is available. Using this mechanism is strongly recommended to avoid problems during backup restore. See Backup restore [[wiki:systeme_mana:features| 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 [[wiki:resources:resources#tools|the resources page]].\\
This tool requires installing ''build-essential'' on your host:
<code bash>
sudo apt-get install build-essential
</code>

The generation of the removal package is done using the following command.
<code bash>
./gen_remove_ipk ipk_name
</code>
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)

<code bash>
opkg list-installed
keros - 3.1.3
test - 1.0.0
</code>

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

<note important>
It is recommend to use the **remove-backup** ipk. \\
To get the list of backuped packages use the following command: 
<code bash>
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
</code>
</note>

==== "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:
<code bash>
2017.02.16-17:02:41 -- Remove package with backup from test-remove-backup.ipk: OK
</code>

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.

<note>These IPK are special packages for the system:
  * They are not installed in packages list
  * They are not installed in backup
</note>

===== 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 [[wiki:resources:resources#tools|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 |



<note tip>The KerOS version can be found on the product using these commands:
<code bash>
opkg info keros | grep Version
Version: 4.0.2-0-g0d9f3135
</code></note>

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. 

<code bash>
tar -xzf generate_hotfix_package.tar.gz
cd my_package_hotfix/
./opkg-build -o root -g root my_package_hotfix/
</code>

Hotfix package can be deployed on a product using the standard [[wiki:keros_custo:sw_updates|software update]] mechanism.