mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-05 19:18:25 +00:00
Johnathan Corgan
ce19d5bd23
On Windows the config directory, the key directory and the peer ACL defaults disagreed. SYSTEM_CONFIG_DIR and the ACL defaults resolved to /etc/fips on the current drive, the search path never probed the directory the service installer writes to, and fipsctl keygen wrote to the per-user %APPDATA%\fips. A service started before a reboot found none of the installed files and ran on defaults, and a peers.deny placed beside the hosts file in C:\ProgramData\fips was never read, so the ACL failed open. Windows now uses C:\ProgramData\fips for all of them, the directory the hosts file and the service installer already use, and the search path probes it before the per-user config. A key left in %APPDATA%\fips is still picked up when the new directory has none, by the daemon and by fipsctl address, with a note to move it. The daemon warns when it ran on a config found only in %APPDATA%\fips, which the service never reads. fipsctl keygen points at a key left in %APPDATA%\fips, and --install-service names the file the service reads. A peers.allow or peers.deny left at the old /etc/fips location would otherwise be dropped on upgrade, and a dropped deny list fails open. For one release the daemon keeps reading each file from /etc/fips, resolved against the current drive exactly as before, when it is not at the new location, and warns naming both paths and asking for it to be moved. When both exist the new file is read and the warning says the old one is ignored. The choice is made per file and re-checked on every ACL reload, so moving, adding or removing a file takes effect without a restart, including a copy that keeps the old file's modification time. The fallback is meant to be removed in a later release. Linux, macOS and FreeBSD paths are unchanged. The Windows ZIP's README told users to put fips.yaml beside fips.exe or in %APPDATA%\fips, neither of which the service reads, and the reference docs gave %APPDATA%\fips as fipsctl keygen's default. The README now says the service reads C:\ProgramData\fips\fips.yaml and keeps the key, hosts and peer ACL files beside it, and describes the per-user files a foreground run also reads. The reference docs list C:\ProgramData\fips as the Windows system config directory and keygen default.
99 lines
4.3 KiB
Markdown
99 lines
4.3 KiB
Markdown
# `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 reads (or
|
|
writes, on first start) the identity files:
|
|
|
|
| File | Mode | Purpose |
|
|
| ---- | ---- | ------- |
|
|
| `fips.key` | `0600` | Bech32 nsec for the persistent identity (Unix only; Windows inherits parent ACLs). |
|
|
| `fips.pub` | `0644` | Bech32 npub corresponding to `fips.key`. |
|
|
|
|
When `node.identity.persistent` is `false` (the default), a fresh
|
|
keypair is written to these files on every start.
|
|
|
|
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.
|