mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-10 08:37:02 +00:00
Johnathan Corgan
7daca6bcf1
Bring the packaging README into agreement with what the ipk actually installs and the CLI surface fipsctl exposes today: - Package contents table now lists /usr/bin/fips-gateway, /etc/init.d/fips-gateway, and /etc/sysctl.d/fips-gateway.conf alongside the daemon. These have been part of the install block but were missing from the README. - fipsctl examples updated to the current command form (fipsctl show peers / show links / show sessions in place of the removed shorthands), with a pointer to the canonical CLI reference. - Service management section gains a short subsection covering the optional gateway service, including the enable/start incantation and a link to the deploy-fips-gateway tutorial.
199 lines
5.6 KiB
Markdown
199 lines
5.6 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`), never bridge names (`br-lan`).** 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`.
|