mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-22 07:48:26 +00:00
89352d3218
BLE transport implementation using L2CAP Connection-Oriented Channels (SeqPacket mode) via the bluer crate, behind cfg(feature = "ble"). Core transport: - BleTransport<I> generic over BleIo trait (BluerIo prod, MockBleIo test) - Connection pool with priority eviction (static > discovered, max 7) - Connect-on-send via connect_inline() matching TCP behavior - Per-connection receive loops with pool cleanup on disconnect Discovery and probing: - Combined scan_probe_loop using select! over scanner events and a BinaryHeap delay queue with per-entry random jitter (0-5s) to prevent herd effects when multiple nodes see the same beacon simultaneously - Pre-handshake pubkey exchange ([0x00][pubkey:32]) for IK identity - Cross-probe tie-breaker: smaller NodeAddr's outbound wins (same convention as FMP/FSP rekey dual-initiation) - Probed peers reported to DiscoveryBuffer; pool fills through normal node-layer auto-connect -> send_async -> connect_inline path Beacon management: - Periodic advertising: 1s burst every 30s (configurable via beacon_interval_secs / beacon_duration_secs) - FIPS service UUID for scan filtering Configuration (all fields optional with defaults): - adapter, psm, mtu, max_connections, connect_timeout_ms - advertise, scan, auto_connect, accept_connections - beacon_interval_secs (30), beacon_duration_secs (1) Hardware validated with two BLE nodes: - 2048-byte MTU, ~60-160ms RTT, zero-config auto-connect - BLE spike tool at testing/ble/ for standalone adapter validation 42 unit tests + 4 node-level integration tests, all CI-compatible via MockBleIo (no hardware required). tokio test-util added for time-dependent scan/probe tests.
183 lines
3.9 KiB
Markdown
183 lines
3.9 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. Bluetooth Transport
|
|
|
|
If using BLE for local mesh discovery, the FIPS binary must be built with
|
|
the `ble` feature (enabled by default). BlueZ must be installed and running:
|
|
|
|
```bash
|
|
sudo apt install bluez
|
|
sudo systemctl enable --now bluetooth
|
|
```
|
|
|
|
Add your service user to the `bluetooth` group, or run with
|
|
`CAP_NET_ADMIN` + `CAP_NET_RAW` capabilities.
|
|
|
|
Configure BLE in the transports section:
|
|
|
|
```yaml
|
|
transports:
|
|
ble:
|
|
adapter: "hci0"
|
|
advertise: true
|
|
scan: true
|
|
auto_connect: true
|
|
accept_connections: true
|
|
```
|
|
|
|
### 4. 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" # IP or hostname (e.g., "peer.example.com:2121")
|
|
connect_policy: auto_connect
|
|
```
|
|
|
|
### 5. 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
|
|
```
|