Johnathan Corgan
9462d5d125
apk-tools v3 runs only the incoming package's pre-upgrade and post-upgrade scripts on an upgrade, and the .apk registered neither. An upgrade replaced the binaries and init scripts on disk but left procd running the old fips and fips-gateway processes until a reboot or a manual restart. The .apk now registers pre-upgrade and post-upgrade as thin wrappers around the same prerm and postinst bodies the .ipk ships. One header line gives each body the opkg upgrade contract it already handles: pre-upgrade rewrites apk's "<new> <old>" arguments to "upgrade <new>", so prerm stops both services without disabling them and leaves its marker, and post-upgrade exports PKG_UPGRADE=1, as OpenWrt's own package-pack.mk does, so postinst starts fips and starts the gateway only if it was enabled. Registering post-upgrade alone would not have been enough: procd ignores a start of a running instance whose command line is unchanged, so the services have to be stopped first. testing/openwrt/package-test.sh runs the real build-apk.sh on the host against a stub apk and checks the registered phases, the #! lines, that the install and removal scripts are the shipped bodies, and, by executing each wrapper's header with apk's argv and environment, that the upgrade pair hands the bodies the right arguments. The ash harness runs it first and then runs the captured scripts in three new apk scenarios, and the packaging workflow's apk structural check now requires all four scripts in the adbdump. An upgrade onto a package built this way was run on OpenWrt 25.12.2 with its apk-tools 3.0.5: apk ran both pre-upgrade and post-upgrade, and both came from the incoming package. The adbdump key format the workflow check matches, each script as a "<phase>:" key under scripts:, was read from the apk-tools v3.0.5 source (src/serialize_yaml.c), the tag the packaging workflow builds from source. It matches the dump that source-built 3.0.5 printed for this change in the packaging workflow, where all four scripts appeared under scripts: and passed the check on both architectures. OpenWrt's own apk-tools 3.0.5 is built without mkpkg, and on a router adbdump cannot read the installed database and info has no --scripts, so which scripts an installed package registered cannot be read back on a device. The check covers the built package only.
4.8 KiB
FIPS OpenWrt Package (apk)
Builds a FIPS .apk for OpenWrt 25+, where apk-tools is the mandatory
package manager. apk is also available opt-in on 24.10 (where opkg remains
the default). For OpenWrt 24.x and earlier, the .ipk package in
../openwrt-ipk/ still works.
Like the .ipk build, this is SDK-free: it cross-compiles with
cargo-zigbuild and assembles the package directly — no OpenWrt SDK image. The
.ipk format is a plain tar.gz we can hand-roll, but the .apk (apk-tools v3
ADB) container is not, so we drive the official apk mkpkg applet — the same
tool OpenWrt's own include/package-pack.mk
calls. The only extra requirement over the .ipk build is the apk binary.
Layout
| File | Purpose |
|---|---|
build-apk.sh |
Cross-compile + assemble the .apk via apk mkpkg |
apk-version.sh |
Map a release tag / commit height to an apk-tools-valid version |
apk-version.test.sh |
Case-table test for apk-version.sh (sh apk-version.test.sh) |
The installed-filesystem payload (init scripts, fips.yaml, sysctl drop-ins,
hotplug, uci-defaults, …) is shared with the .ipk package — there is one
canonical copy in ../openwrt-ipk/files/. build-apk.sh
stages from there, so the two packages ship the same files apart from one
staged rewrite: build-apk.sh changes ethernet.wan.interface in the staged
fips.yaml from eth0 to wan, the OpenWrt 25 DSA port name. Keep the
staging block in build-apk.sh in sync with ../openwrt-ipk/build-ipk.sh.
Versioning
apk-tools enforces a strict version grammar
(<digit>(.<digit>)*(_<suffix><digit>*)*(-r<N>)). apk-version.sh builds a
valid version from structured inputs rather than rewriting an already-flattened
string:
| Input | apk version |
|---|---|
tag v1.2.3 |
1.2.3-r0 |
tag v1.2.3-rc1 |
1.2.3_rc1-r0 |
dev 1234 (commit height) |
0.0.0_git1234-r0 |
The human-readable version (v1.2.3, master.123.abcdef0) is still used for the
artifact filename; only the metadata embedded in the package is normalized.
Building
Prerequisites
| Requirement | Notes |
|---|---|
cargo install cargo-zigbuild + zig |
Rust musl cross-compilation (as for .ipk) |
apk-tools v3 apk binary |
Provides apk mkpkg; not packaged for most distros — build from source |
fakeroot |
Optional; makes packaged files root-owned on an unprivileged build host |
apk-tools is not in Debian/Ubuntu repos, so build the pinned release from source.
Pin the same commit the targeted OpenWrt release ships (see
package/system/apk/Makefile upstream) so the .apk is readable by the device's
apk. CI builds 3.0.5 (b5a31c0d…):
sudo apt-get install -y build-essential meson ninja-build pkg-config \
zlib1g-dev libssl-dev libzstd-dev liblzma-dev lua5.4-dev scdoc
git clone https://gitlab.alpinelinux.org/alpine/apk-tools.git
cd apk-tools && git checkout b5a31c0d865342ad80be10d68f1bb3d3ad9b0866
meson setup build && ninja -C build src/apk
export APK_BIN="$PWD/build/src/apk"
Build the package
# from the repo root
./packaging/openwrt-apk/build-apk.sh --arch aarch64 # or x86_64, mipsel, mips, arm
Output: dist/fips_<version>_<openwrt-arch>.apk. Override the version with
PKG_VERSION (filename) and APK_VERSION (embedded metadata); otherwise both are
derived from git.
Installing on the router
Packages are unsigned (the same posture as our .ipk), so install with
--allow-untrusted:
scp -O dist/fips_<version>_<arch>.apk root@192.168.1.1:/tmp/
ssh root@192.168.1.1 apk add --allow-untrusted /tmp/fips_<version>_<arch>.apk
On OpenWrt 25.x, installing from a signed repository requires the publisher's
key; a single --allow-untrusted package install does not. If we ever publish an
apk feed, add ECDSA (prime256v1) signing via apk mkpkg --sign and distribute the
public key to /etc/apk/keys/.
Upgrading
Upgrade with the same command, pointed at the new package:
ssh root@192.168.1.1 apk add --allow-untrusted /tmp/fips_<new-version>_<arch>.apk
The new package's upgrade scripts stop fips and fips-gateway before the
files are replaced, then start fips again and start fips-gateway only if it
was enabled, so the upgrade keeps the gateway's enabled state. apk runs
the incoming package's upgrade scripts, not the installed one's, so this holds
from the first upgrade onto a package that carries them, whatever version is
installed.
/etc/fips/fips.yaml is marked as a config file (via
/lib/apk/packages/fips.conffiles), so apk preserves local edits across upgrades,
and /lib/upgrade/keep.d/fips preserves /etc/fips/ across sysupgrade — the
same guarantees as the .ipk package.