laantungir/fips
1
0
Fork 0
mirror of https://github.com/jmcorgan/fips.git synced 2026-10-05 19:18:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
efe77410a1636dba576231cd912ff685ca33990b
fips/docs/reference/cli-fips.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

114 lines
5.2 KiB
Markdown
Raw Blame History

# `fips`
The FIPS mesh network daemon.
## Synopsis
```text
fips [-c FILE]
```
On Windows the same binary additionally accepts `--install-service`,
`--uninstall-service`, and (used internally by the service control
manager) `--service`.
## Description
`fips` is the FIPS daemon. It loads a YAML configuration, resolves an
identity, brings up the TUN adapter, listens on configured transports,
authenticates peers, maintains the spanning tree, and forwards mesh
traffic. There is one daemon per node.
The daemon stays in the foreground, logging to stderr, until it
receives `SIGINT` or `SIGTERM`. On Windows, the service variant is
controlled through the standard service control manager.
## Options
| Flag | Argument | Description |
| ---- | -------- | ----------- |
| `-c`, `--config` | `FILE` | Use `FILE` as the configuration. Skips the default search paths. |
| `-V` | — | Print the short version, `<version> (rev <git-hash>)`. The `rev` part is omitted when the build could not read a git revision, as in a package built from a git worktree. |
| `--version` | — | Print the long version: short version plus build target triple. |
| `-h`, `--help` | — | Print usage and exit. |
| `--install-service` | — | (Windows only) Install `fips` as a Windows service. Requires Administrator. |
| `--uninstall-service` | — | (Windows only) Uninstall the Windows service. Requires Administrator. |
| `--service` | — | (Windows only, internal) Run as a Windows service. Invoked by the service control manager — not for direct use. |
There are no other CLI flags; all daemon behaviour is governed by the
YAML configuration. See [configuration.md](configuration.md).
## Exit Codes
| Code | Meaning |
| ---- | ------- |
| `0` | Clean shutdown after `SIGINT` / `SIGTERM`. |
| `1` | Failed to load configuration, resolve identity, construct the node, or start the node. The reason is printed to stderr before exit. |
## Environment
| Variable | Description |
| -------- | ----------- |
| `RUST_LOG` | Tracing filter directive. Overrides `node.log_level` from the config. Examples: `info`, `debug`, `fips=trace,fips::node::handlers::mmp=debug`. |
| `XDG_RUNTIME_DIR` | Used to derive the default control-socket path when `/run/fips` does not exist. See [control-socket.md](control-socket.md). |
| `FIPS_CONFIG` | (Windows service mode only) Path to the configuration file when the daemon runs under the service control manager. |
The daemon also clamps the `nostr_relay_pool`, `nostr_sdk`, and `nostr`
log targets to `info` whenever the effective log level is below
`trace`, so that `RUST_LOG=debug` does not flood the journal with raw
relay frames. To see those frames, set the level to `trace`.
## Files
`fips` looks for `fips.yaml` in the following locations, lowest to
highest priority. All present files are merged in priority order; the
highest-priority value wins.
| Priority | Path | Purpose |
| -------- | ---- | ------- |
| 1 | `/usr/local/etc/fips/fips.yaml` (macOS, FreeBSD), `C:\ProgramData\fips\fips.yaml` (Windows), `/etc/fips/fips.yaml` (other Unix) | System-wide defaults |
| 2 | `~/.config/fips/fips.yaml` (`%APPDATA%\fips\fips.yaml` on Windows) | User preferences |
| 3 | `~/.fips.yaml` | Legacy user config |
| 4 | `./fips.yaml` | Deployment-specific overrides |
On macOS and FreeBSD both system directories are probed: `/etc/fips`
first, then `/usr/local/etc/fips`, so the packaged file wins over a
leftover `/etc/fips` copy from an earlier install. Windows likewise
probes `\etc\fips` on the current drive, then `C:\ProgramData\fips`.
Adjacent to the highest-priority config file the daemon keeps the
identity files:
| File | Mode | Purpose |
| ---- | ---- | ------- |
| `fips.key` | `0600` | Bech32 nsec for the persistent identity, written only in persistent mode (Unix; on Windows the file takes its directory's ACL, which `install-service.ps1` restricts to SYSTEM and Administrators). |
| `fips.pub` | `0644` | Bech32 npub of the running identity, written on every start. In persistent mode it corresponds to `fips.key`. |
When `node.identity.persistent` is `false` (the default), a fresh
keypair is generated on every start and only `fips.pub` is written.
A `fips.key` found there is moved aside to `fips.key.unused` and a
warning is logged.
On Windows the service writes its log to `C:\ProgramData\fips\fips.log`,
rolled at 10 MiB with four old files kept; a foreground run logs to the
console.
On Windows, `install-service.ps1` restricts `C:\ProgramData\fips` to
SYSTEM and Administrators. Reading or editing files there,
`fipsctl keygen`, `fipsctl address` with no argument, and a foreground
run that relies on `C:\ProgramData\fips\fips.yaml` need an elevated
prompt; unelevated, a foreground run may skip that file without saying
so or fail with an access error. Run the installer before `fipsctl keygen`,
and again after moving files into the directory, since a moved file
keeps its old permissions.
The control socket path is derived per
[control-socket.md](control-socket.md).
## See also
- [`fipsctl`](cli-fipsctl.md) — control-socket client.
- [`fipstop`](cli-fipstop.md) — live-status TUI.
- [configuration.md](configuration.md) — YAML reference.
- [control-socket.md](control-socket.md) — control-socket protocol.
Reference in New Issue View Git Blame Copy Permalink