mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-09 08:14:42 +00:00
ArjenandJohnathan Corgan
22a5b3e5c6
The shared fips.yaml ships ethernet.wan.interface: "eth0", the default WAN port on OpenWrt 24 and earlier. OpenWrt 25 (DSA) boards, which the .apk package targets, name the WAN port "wan" instead. Rewrite the staged copy at build time so the as-installed config binds the Ethernet transport to the right port out of the box, without maintaining a second copy of the config file. The .ipk package keeps "eth0". Update the openwrt README to document eth0 (24) vs wan (25/DSA) and add a CHANGELOG entry.
202 lines
5.9 KiB
Markdown
202 lines
5.9 KiB
Markdown
# 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.
|
|
|
|
For ad-hoc deployment without the build system, see
|
|
[`deploy/native/`](../../deploy/native/README.md) instead.
|
|
|
|
## 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) |
|
|
| `/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/dnsmasq.d/fips.conf` | Forwards `.fips` DNS queries to the daemon |
|
|
| `/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 and firewall 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 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>/`.
|
|
|
|
### 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:
|
|
- Persistent identity (key generated on first start, saved to `/etc/fips/fips.key`)
|
|
- TUN interface `fips0`
|
|
- DNS responder on `127.0.0.1:5354`
|
|
- UDP transport on `0.0.0.0:2121`
|
|
|
|
For Ethernet transport, uncomment the `ethernet:` section and set the correct
|
|
physical interface names for 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. See
|
|
[`deploy/native/README.md`](../../deploy/native/README.md) for details.
|
|
|
|
## 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
|
|
|
|
Install the new `.ipk` over the existing one:
|
|
|
|
```bash
|
|
opkg install --force-reinstall fips_<new-version>_<arch>.ipk
|
|
```
|
|
|
|
The config in `/etc/fips/fips.yaml` and the identity key `/etc/fips/fips.key`
|
|
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`.
|