wiki:package_management
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
wiki:package_management [2018/12/27 14:44] hch [removal packages generation] |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== 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: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: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'' or the preferred target product arch: ''klk_lbps'' and ''klk_wifc''. | ||
| - | |||
| - | ==== 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 can be unstable because the original file will not be restored automatically so the file is simply removed when the package will be removed. | ||
| - | |||
| - | ===== Building your own package ===== | ||
| - | |||
| - | A ''.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: [[resources_ibts:resources#toolchain| Wirnet iBTS toolchain]] or [[resources_ifemto:resources#toolchain| Wirnet iFemtoCell toolchain]]. | ||
| - | |||
| - | This section gives a practical example about how to generate a ''.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 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. | ||
| - | |||
| - | <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 packet, 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: | ||
| - | - 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 | ||
| - | |||
| - | |||
| - | <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) 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 | ||
| - | </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: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''. You can download it from wiki page: [[wiki:common_resources#tools|Common resources]].\\ | ||
| - | 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. | ||
| - | |||
| - | <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:/.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 | ||
| - | </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 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. | ||
| - | |||
| - | ==== Create a hotfix package ==== | ||
| - | |||
| - | To generate a hotfix package, you can use the ''generate_hotfix_package.tar'' example provided in the resources pages: [[resources_ibts:resources#other_tools|Wirnet iBTS resources]] & [[resources_ifemto:resources#other_tools|Wirnet iFemtoCell resources]]. | ||
| - | |||
| - | Important fields in ''my_package_hotfix/CONTROL/control'' must be present. | ||
| - | ^ Field ^ Role ^ Possible values ^ | ||
| - | | Architecture | Compatible target: iBTS, iFemtocell | **iBTS**: klk_lpbs, **iFemtocell**: klk_wifc | | ||
| - | | 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 this 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 iBTS and iFemtoCell. | ||
| - | |||
| - | <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:sw_updates|software update]] mechanism. | ||
wiki/package_management.1545918264.txt.gz · Last modified: 2019/01/17 10:01 (external edit)
