mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-05 19:18:25 +00:00
Johnathan Corgan
9979826235
Move the staged changelog entries under a 0.5.2 heading dated 2026-09-28 and leave an empty Unreleased section above it. The date is provisional: a comment beside the heading says so, and the two release-notes files carry the same date with the same marker, so the check at the version bump finds all three. Add the release notes and mirror them byte for byte to RELEASE-NOTES.md. Every link is absolute so the Release body resolves them, and each paragraph and list item is on one line, because the Release page shows every newline inside a paragraph as a line break; the file exempts itself from the line-length lint rule. The notes lead with who should upgrade and with the three defaults that changed: the gateway's DNS port, the Windows config directory, and an ephemeral node no longer writing its key file. They say what was measured and what was not, including the mixed-version interop run against v0.5.1 and v0.5.0, the Windows installer checks on Windows Server under Windows PowerShell 5.1 and PowerShell 7, and the checks still outstanding. They state that a link to a v0.5.0 or v0.5.1 node can still drop after a lost rekey reply until that node is upgraded, since the fix is on the answering side. The Windows upgrade notes say to stop the service before every run of the installer, and to move fips.yaml and fips.key from \etc\fips into C:\ProgramData\fips before upgrading a service that was set up by hand to read its config from \etc\fips, which otherwise comes up under a new identity with no warning. The README's status badge, release-notes link and status paragraph follow the release. Correct documentation that no longer matches the gateway, tree, Windows and packaging behavior: - The gateway design document, how-to, OpenWrt tutorial and the configuration reference describe the NAT rebuild as one transaction, the 1000-mapping ceiling and the new-name rate limit in place of the pool size as a hard cap, and which DNS queries allocate a mapping. - The spanning-tree documents describe the periodic re-broadcast and the resend of an unconfirmed announce, and the bloom filter update triggers include a parent switch and a child joining or leaving. - The fips, fipsctl and security references cover the restricted C:\ProgramData\fips on Windows, the ACL and key paths on macOS, FreeBSD and Windows, the legacy peer ACL fallback in \etc\fips, and the Debian fips.yaml's actual mode and conffile status. - The packaging guides no longer list MIPS as supported, the arm64 .deb leg is described as also purging the package, and the OpenWrt SDK-feed README says a package built from its Makefile carries none of the released packages' maintainer scripts. - The testing README gains a section for the OpenWrt maintainer-script suite and says the ACL allowlist suite runs by hand only, and the interop README lists the mesh-size check as its eighth phase. The upgrade notes were then corrected where following them as written would have left a node worse off: - Gateway DNS port: a fips.yaml that sets gateway.dns.listen keeps its port through the upgrade, and the v0.5.1 example config and deployment guide set it to [::1]:5353, so the resolver instruction depends on whether the config sets it. - OpenWrt: an operator who had the gateway disabled must stop it and then disable it after the first opkg upgrade. - FreeBSD: an upgrade step that restarts fips and fips_dns; the command comes from pkg's source and is listed as not measured. - Debian: the upgrade re-enables and starts fips-dns every time; `systemctl mask fips-dns` keeps it off. The .deb start bound is 90 seconds for fips-gateway. - Arch and the systemd tarball: what to restart or start after the upgrade, and that only a .deb upgrade reloads the firewall. - Ephemeral nodes: set persistent before upgrading to keep a key. - Windows: one ordered sequence in an elevated PowerShell, with the installer run under -ExecutionPolicy Bypass. - Building from source on glibc Linux also needs libdbus-1-dev and pkg-config. README, getting-started and the packaging README install the .deb with apt install ./ and point to the packaging README for per-format install commands. The notes record an OpenWrt 24 router test of the gateway DNS port, and that a gateway that fails to start leaves dnsmasq forwarding .fips to its port, with how to hand .fips back to the daemon. Drop the test-us03-next alias from the shipped hosts file and from the roster in the host-aliases how-to.
116 lines
4.8 KiB
Markdown
116 lines
4.8 KiB
Markdown
# 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/`](../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`](https://github.com/openwrt/openwrt/blob/main/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/`](../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…`):
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# from the repo root
|
|
./packaging/openwrt-apk/build-apk.sh --arch aarch64 # or x86_64; releases publish these two
|
|
```
|
|
|
|
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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|