mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-09 08:14:42 +00:00
Johnathan Corgan
b33d6531ce
The fips-dns.service unit had three issues: 1. Wants=systemd-resolved.service caused systemd to start systemd-resolved on systems that weren't using it, breaking existing DNS by rewriting /etc/resolv.conf to the stub resolver at 127.0.0.53. 2. The ExecStart busy-wait loop for fips0 had no timeout, hanging forever if fips.service failed to create the TUN device. 3. Installers unconditionally enabled fips-dns.service regardless of whether systemd-resolved was present. Fix by replacing Wants= with ConditionPathExists=/run/systemd/resolve (skips cleanly if resolved isn't running), adding Requires=fips.service (won't start without the daemon), bounding the fips0 wait loop to 30 seconds, and making the installers conditional on systemd-resolved being active.
158 lines
3.4 KiB
Markdown
158 lines
3.4 KiB
Markdown
# FIPS Installation Guide
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
tar xzf fips-*-linux-*.tar.gz
|
|
cd fips-*-linux-*/
|
|
sudo ./install.sh
|
|
```
|
|
|
|
## What Gets Installed
|
|
|
|
| File | Location |
|
|
|------|----------|
|
|
| fips (daemon) | /usr/local/bin/fips |
|
|
| fipsctl (CLI) | /usr/local/bin/fipsctl |
|
|
| fipstop (TUI) | /usr/local/bin/fipstop |
|
|
| Configuration | /etc/fips/fips.yaml |
|
|
| Identity key | /etc/fips/fips.key (auto-generated) |
|
|
| Public key | /etc/fips/fips.pub (auto-generated) |
|
|
| systemd unit | /etc/systemd/system/fips.service |
|
|
|
|
A system group `fips` is created for control socket access.
|
|
|
|
## Post-Install Configuration
|
|
|
|
Edit `/etc/fips/fips.yaml` before starting the service.
|
|
|
|
### 1. Identity
|
|
|
|
By default, the node generates a new ephemeral identity on each start
|
|
for privacy. If the node's npub will be published for others to use as a
|
|
static peer, enable a stable identity by uncommenting `persistent: true`
|
|
in the identity section:
|
|
|
|
```yaml
|
|
node:
|
|
identity:
|
|
persistent: true
|
|
```
|
|
|
|
On first start with persistence enabled, a keypair is auto-generated and saved:
|
|
|
|
- `/etc/fips/fips.key` (mode 0600) — secret key
|
|
- `/etc/fips/fips.pub` (mode 0644) — public key (npub)
|
|
|
|
The same identity is reused on subsequent starts. Alternatively, set
|
|
`node.identity.nsec` to use a specific key.
|
|
|
|
### 2. Ethernet Transport
|
|
|
|
If using Ethernet for local mesh discovery, uncomment the ethernet section
|
|
and set the interface name:
|
|
|
|
```yaml
|
|
transports:
|
|
ethernet:
|
|
interface: "eth0"
|
|
discovery: true
|
|
announce: true
|
|
auto_connect: true
|
|
accept_connections: true
|
|
```
|
|
|
|
### 3. Static Peers
|
|
|
|
For bootstrapping over UDP or TCP, add known peers:
|
|
|
|
```yaml
|
|
peers:
|
|
- npub: "npub1..."
|
|
alias: "gateway"
|
|
addresses:
|
|
- transport: udp
|
|
addr: "217.77.8.91:2121" # public FIPS testing node
|
|
connect_policy: auto_connect
|
|
```
|
|
|
|
### 4. DNS Resolver (optional, requires systemd-resolved)
|
|
|
|
FIPS includes a DNS responder for `.fips` domain names (port 5354).
|
|
On systems running `systemd-resolved`, the installer automatically enables
|
|
`fips-dns.service` to route `.fips` queries to the FIPS resolver.
|
|
|
|
If `systemd-resolved` is not running at install time, DNS integration is
|
|
skipped. To enable it later (after starting `systemd-resolved`):
|
|
|
|
```bash
|
|
sudo systemctl enable --now fips-dns.service
|
|
```
|
|
|
|
For manual configuration without `fips-dns.service`:
|
|
|
|
```bash
|
|
sudo resolvectl dns fips0 127.0.0.1:5354
|
|
sudo resolvectl domain fips0 ~fips
|
|
```
|
|
|
|
## Firewall Ports
|
|
|
|
| Port | Protocol | Purpose |
|
|
|------|----------|---------|
|
|
| 2121 | UDP | Peer-to-peer mesh traffic |
|
|
| 8443 | TCP | Inbound peer connections |
|
|
|
|
## Service Management
|
|
|
|
```bash
|
|
# Start / stop / restart
|
|
sudo systemctl start fips
|
|
sudo systemctl stop fips
|
|
sudo systemctl restart fips
|
|
|
|
# View logs
|
|
sudo journalctl -u fips -f
|
|
|
|
# Switch to debug logging
|
|
sudo systemctl set-environment RUST_LOG=debug
|
|
sudo systemctl restart fips
|
|
```
|
|
|
|
## Monitoring
|
|
|
|
```bash
|
|
# Quick status
|
|
fipsctl show status
|
|
|
|
# Interactive dashboard
|
|
fipstop
|
|
|
|
# Other queries
|
|
fipsctl show peers
|
|
fipsctl show links
|
|
fipsctl show sessions
|
|
fipsctl show routing
|
|
fipsctl show transports
|
|
```
|
|
|
|
## Non-Root Access to fipsctl/fipstop
|
|
|
|
Add your user to the `fips` group:
|
|
|
|
```bash
|
|
sudo usermod -aG fips $USER
|
|
```
|
|
|
|
Log out and back in for the group change to take effect.
|
|
|
|
## Uninstall
|
|
|
|
```bash
|
|
# Remove binaries and service, keep configuration
|
|
sudo ./uninstall.sh
|
|
|
|
# Remove everything including /etc/fips/ and the fips group
|
|
sudo ./uninstall.sh --purge
|
|
```
|