laantungir/fips
1
0
Fork 0
mirror of https://github.com/jmcorgan/fips.git synced 2026-10-05 11:08:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
0cc4153debad637525eb9b5fe626b5f8014e0910
fips/packaging/openwrt-ipk/README.md
T
Johnathan Corgan 9979826235 Prepare the v0.5.2 release notes, changelog and documentation corrections 
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.
2026-09-28 22:16:15 +00:00

249 lines
7.8 KiB
Markdown
Raw Blame History

# FIPS OpenWrt Package
This directory is an OpenWrt feed package that builds and installs FIPS on any
OpenWrt 22.03+ router via the standard `opkg` package system.
## Package contents
| Installed path | Purpose |
|---|---|
| `/usr/bin/fips` | Mesh daemon |
| `/usr/bin/fipsctl` | CLI control tool (`fipsctl show peers`, `fipsctl show links`, …) |
| `/usr/bin/fipstop` | Live TUI dashboard |
| `/usr/bin/fips-gateway` | Outbound LAN gateway service (not started by default) |
| `/usr/bin/fips-mesh-setup` | Opt-in helper — creates an open 802.11s mesh interface for router↔router backhaul |
| `/usr/bin/fips-ap-setup` | Opt-in helper — creates the open `!FIPS` access SSID for client devices |
| `/etc/init.d/fips` | procd service for the daemon (auto-start, crash respawn) |
| `/etc/init.d/fips-gateway` | procd service for the gateway (disabled by default) |
| `/etc/fips/fips.yaml` | Node configuration (edit before first start) |
| `/etc/fips/firewall.sh` | Firewall helper — accepts traffic on `fips0` |
| `/etc/sysctl.d/fips-bridge.conf` | `br_netfilter` settings for Ethernet transport |
| `/etc/sysctl.d/fips-gateway.conf` | `proxy_ndp` and IPv6 forwarding for the gateway |
| `/etc/hotplug.d/net/99-fips` | Applies firewall rules when `fips0` comes up |
| `/etc/uci-defaults/90-fips-setup` | First-boot kernel module, firewall and dnsmasq `.fips` forwarding setup |
| `/lib/upgrade/keep.d/fips` | Preserves `/etc/fips/` across `sysupgrade` |
## Requirements
### Build host
| Requirement | Notes |
|---|---|
| OpenWrt SDK 22.03+ | Older versions lack fw4 / nftables support |
| Rust host toolchain | Enable in `make menuconfig` → Advanced → Rust, or install rustup |
| Rust target for your router | Added automatically by the Makefile via `rustup target add` |
### Router
| Requirement | Notes |
|---|---|
| `kmod-tun` | Required for `fips0` TUN interface |
| `kmod-br-netfilter` | Required for Ethernet transport on bridge member ports |
Both kernel modules are listed as package dependencies (`DEPENDS`) and will be
installed automatically by `opkg`.
## Target architectures
The Makefile maps the OpenWrt `ARCH` variable to the correct Rust musl target:
| OpenWrt `ARCH` | Rust target |
|---|---|
| `aarch64` | `aarch64-unknown-linux-musl` |
| `x86_64` | `x86_64-unknown-linux-musl` |
| `mipsel` | `mipsel-unknown-linux-musl` |
| `mips` | `mips-unknown-linux-musl` |
| `arm` | `arm-unknown-linux-musleabihf` |
To add a missing architecture, add an `ifeq` block in `Makefile` mapping the
OpenWrt `ARCH` value to the Rust target triple.
## Building with the OpenWrt SDK
### 1. Obtain the SDK
Download the SDK for your router's target from
[downloads.openwrt.org](https://downloads.openwrt.org) and extract it.
### 2. Add this package
Copy or symlink this directory into the SDK's `package/` tree:
```bash
# From inside the SDK root:
ln -s /path/to/fips/packaging/openwrt-ipk package/fips
```
Or add the FIPS repository as a feed in `feeds.conf`:
```
src-git-full fips https://github.com/jmcorgan/fips.git
```
Then update and install feeds:
```bash
./scripts/feeds update fips
./scripts/feeds install -a -p fips
```
### 3. Build
```bash
make package/fips/compile V=s
```
The resulting `.ipk` is placed in `bin/packages/<arch>/`.
A package built from this `Makefile` carries none of the maintainer scripts in
`scripts/`. Those scripts enable and start `fips` on install and implement the
gateway-enablement and upgrade behavior described below, so that description
does not cover a package built this way. Released packages are built by
`build-ipk.sh` (and `../openwrt-apk/build-apk.sh`), which install those scripts.
### 4. Pin the source version
For reproducible production builds, replace `PKG_SOURCE_VERSION:=master` in
`Makefile` with a specific commit SHA and set `PKG_MIRROR_HASH` to the correct
hash (or keep `skip` for development):
```makefile
PKG_SOURCE_VERSION:=bf117dfabc123... # full 40-char SHA
PKG_MIRROR_HASH:=skip
```
## Installing on the router
```bash
scp bin/packages/<arch>/fips_0.1.0-1_<arch>.ipk root@192.168.1.1:/tmp/
ssh root@192.168.1.1 opkg install /tmp/fips_0.1.0-1_<arch>.ipk
```
## First-time configuration
Edit `/etc/fips/fips.yaml` on the router before starting the daemon:
```bash
ssh root@192.168.1.1
vi /etc/fips/fips.yaml
```
The default config enables:
- An ephemeral identity, generated on each start. Uncomment
`node.identity.persistent: true` to keep one; the key is then saved next to
the config, as `/etc/fips/fips.key`.
- TUN interface `fips0`
- DNS responder on `[::1]:5354`
- UDP transport on `[::]:2121`
- TCP transport on `0.0.0.0:8443`
- Ethernet transport, including the `wan`, `wwan` and `lan` entries
For Ethernet transport, edit the interface names in the `ethernet:` section to
match your router. **Always use physical port names
(`eth0`, `eth1`, or DSA port names like `wan`/`lan1`), never bridge names
(`br-lan`).** The shipped default WAN port is `eth0` (OpenWrt 24); on OpenWrt
25 (DSA) boards the WAN port is named `wan` — the `.apk` package ships that
default. Run `ip link show` to confirm the names on your board.
## Service management
```bash
/etc/init.d/fips start
/etc/init.d/fips stop
/etc/init.d/fips restart
/etc/init.d/fips enable # start at boot (already enabled by opkg postinstall)
/etc/init.d/fips disable
```
### Outbound LAN gateway (optional)
The `fips-gateway` service is installed but disabled by default. It
turns the router into an outbound gateway that bridges LAN clients
onto the FIPS mesh. Enable only after configuring a `gateway:`
section in `/etc/fips/fips.yaml`:
```bash
/etc/init.d/fips-gateway enable
/etc/init.d/fips-gateway start
```
See `docs/tutorials/deploy-fips-gateway.md` in the source tree for
the full walkthrough.
## Inspection and logs
```bash
# Node-level status overview
fipsctl show status
# Peer table
fipsctl show peers
# Transport links
fipsctl show links
# Active end-to-end sessions
fipsctl show sessions
# Live TUI dashboard
fipstop
# Daemon logs (OpenWrt syslog)
logread | grep fips
```
See [`docs/reference/cli-fipsctl.md`](../../docs/reference/cli-fipsctl.md)
for the full subcommand list.
## Upgrading
OpenWrt 25 and later have no opkg. Upgrade there with the `.apk` package,
using the same command that installs it:
```bash
apk add --allow-untrusted /tmp/fips_<new-version>_<arch>.apk
```
The `.apk` package's upgrade scripts stop `fips` and `fips-gateway`, start
`fips` again, and start `fips-gateway` only if it was enabled; see
[`../openwrt-apk/README.md`](../openwrt-apk/README.md).
On OpenWrt 24.10 and earlier, install the new `.ipk` with a plain
`opkg install`:
```bash
opkg install /tmp/fips_<new-version>_<arch>.ipk
```
opkg runs this as an upgrade. The installed package's `prerm` stops `fips` and
`fips-gateway` without disabling them, and the new package's `postinst` starts
`fips` and starts `fips-gateway` again if it was enabled.
An upgrade from 0.5.1 or earlier is the exception. The `prerm` in those
packages disables `fips-gateway` and records nothing about whether it was
enabled, so the new `postinst` enables it again. If you had the gateway
disabled, disable it again after that first upgrade:
```bash
/etc/init.d/fips-gateway stop
/etc/init.d/fips-gateway disable
```
If opkg refuses because the new file's version sorts lower than the installed
one, as it can between development builds, add `--force-downgrade`. opkg then
takes the same upgrade path.
Do not use `--force-reinstall`. opkg runs it as a removal followed by a fresh
install, so `fips-gateway` ends up disabled. To turn it back on:
```bash
/etc/init.d/fips-gateway enable
/etc/init.d/fips-gateway start
```
The config in `/etc/fips/fips.yaml` and the identity key `/etc/fips/fips.key`
(when persistent identity is on) are preserved by `opkg` (the yaml is installed
as a conffile; the key is not a package file). Both survive `sysupgrade` via
`/lib/upgrade/keep.d/fips`.
Reference in New Issue View Git Blame Copy Permalink