mirror of https://github.com/jmcorgan/fips.git synced 2026-10-05 19:18:25 +00:00

Files

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

6.0 KiB

Raw Blame History

Use Shortnames Instead of Long Npubs

A FIPS node's canonical address is <npub>.fips. The npub is 63 characters of bech32 — fine for the daemon, awkward to type or fit in a docs example. The local DNS resolver consults a host map before falling back to direct-npub resolution, so short names like test-us01.fips work as substitutes wherever <npub>.fips would.

This guide covers the two ways to populate that map and when to use which.

When to use which

Two independent mechanisms feed the same DNS responder:

Mechanism	Source	Scope	Reload
Hosts file	`/etc/fips/hosts`	Node-local, intended for shared rosters	Auto on mtime change
Peer alias	`alias:` field on a `peers:` entry	Node-local, scoped to configured peers	Daemon restart

Pick the hosts file when:

The shortname refers to a peer your operator-team agrees to call by that name across machines (the public test mesh ships this way).
You want the destination's name to resolve in DNS or appear in fipsctl show peers display even though it isn't in your peers: block — e.g., a mesh node you reach transitively through your direct peers. The hosts-file entry is for name resolution and display only; it does not stand in for the npub a peer-config entry requires.

Pick the peer alias when:

The shortname is just a label you use locally for a peer that's already in your peers: block.
You want the alias to live with the rest of the peer config (one place to look) rather than in a separate file.

The two coexist. If both reference the same shortname, /etc/fips/hosts wins — the file is treated as the authoritative shared roster.

What ships in the default `/etc/fips/hosts`

The installer drops /etc/fips/hosts populated with the public test mesh roster:

test-us01      npub1qmc3cvfz0yu2hx96nq3gp55zdan2qclealn7xshgr448d3nh6lks7zel98
test-us02      npub10yffd020a4ag8zcy75f9pruq3rnghvvhd5hphl9s62zgp35s560qrksp9u
test-us03      npub136yqae6na688fs75g95ppps3lxe07fvxefj77938zf47uhm6074sxw8ctm
test-us04      npub1gd7ye2qp2lphhzx75fynnjzaxx4dqanddecet0wtt5ss5ek8h9ps62wdkf
test-de01      npub1260n42s06vzc7796w0fh3ny7zcpw6tlk4gq3940gmfrzl5c9pv2s3657q8
test-es01      npub17lpmzulpc98d8ff727k6e98atxn3phzupzsqqwe54ytduym747ws4tw5zm
test-uk01      npub1u0z26dc4qeneu5rvwvmpfhtwh3522ed6rlgxr9jarrfnjrc6ew4qxjysrs

These resolve out of the box — ping6 test-us01.fips works even before you've added any peer to your config, as long as the destination is reachable through your mesh links.

If you don't intend to interact with the public test mesh, the entries are safe to comment out or delete. They are plain hosts-file lines, not protocol participants — removing them only changes name resolution on your machine.

Add an entry to `/etc/fips/hosts`

Append a line to /etc/fips/hosts:

my-laptop     npub1abc...xyz

Format rules:

One hostname and one npub per line, separated by whitespace.
Hostnames are lowercase letters, digits, and hyphens; max 63 characters.
Comments start with # and continue to end of line; blank lines are ignored.
On duplicate hostnames, the last entry wins.

The daemon picks up the change on the next DNS query — no restart required (the file's mtime is checked on each query). Verify:

dig my-laptop.fips AAAA +short

Expect one fd97:... AAAA record.

/etc/fips/hosts is shipped as a dpkg conffile (and the AUR equivalent), so package upgrades preserve your edits. The file is 0644 root:root — readable by anyone, writable by root.

Add a peer alias

In /etc/fips/fips.yaml, set the alias: field on the peer entry:

peers:
  - npub: "npub1abc...xyz"
    alias: "my-laptop"
    addresses:
      - transport: udp
        addr: "192.0.2.10:2121"
    connect_policy: auto_connect

Restart the daemon for the alias to take effect:

sudo systemctl restart fips
dig my-laptop.fips AAAA +short

The alias also shows up in fipsctl show peers display_name column, so log entries and CLI output reference the peer by shortname instead of truncated npub.

Resolution order

When the DNS responder receives a query for <name>.fips:

Hosts file lookup. If <name> matches an entry in /etc/fips/hosts, the daemon returns the AAAA record derived from that entry's npub.
Peer alias lookup. If <name> matches the alias field on a configured peer, return that peer's AAAA.
Direct npub resolution. If <name> is itself a valid bech32 npub (the canonical 63-char npub1... form), the daemon returns the AAAA derived from that npub directly.
NXDOMAIN. If none of the above match, the query returns no answer.

The order means the hosts file overrides peer aliases on conflict. That's deliberate: the file represents operator-shared naming, the peer alias is a node-local label.

Cross-references and ACLs

Aliases interact with the peer ACL — if you maintain peers.allow or peers.deny lists keyed on hostnames rather than npubs, those names go through the same hosts-file resolution. See ../reference/security.md for the ACL format and the alias-resolution semantics.

fipsctl connect and fipsctl disconnect accept a shortname where they expect an npub. Resolution for these commands goes through /etc/fips/hosts only — peer-config alias: entries are not loaded by fipsctl, so a shortname that exists only as a peer alias must still be referenced by full npub on the CLI. See ../reference/cli-fipsctl.md.

6.0 KiB Raw Blame History