laantungir/fips
1
0
Fork 0
mirror of https://github.com/jmcorgan/fips.git synced 2026-07-30 19:46:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add Debian/Ubuntu .deb packaging and update README

Browse Source 
Debian packaging via cargo-deb:
- Add [package.metadata.deb] to Cargo.toml with assets, dependencies,
  and conffiles declarations
- Maintainer scripts: postinst (create fips group, enable services,
  restart on upgrade), prerm (stop/disable on remove, stop-only on
  upgrade), postrm (purge config, keys, group)
- Systemd units (fips.service, fips-dns.service) with /usr/bin/ paths
  for .deb installs
- tmpfiles.d entry for /run/fips/ runtime directory
- build-deb.sh wrapper script for building packages

README rewrite:
- Replace run-from-source Quick Start with Building section
- Add Installation options: Debian .deb (cargo-deb) and generic Linux
  (systemd tarball)
- Add full Configuration reference with default fips.yaml
- Add Usage sections: DNS resolution, monitoring (fipsctl + fipstop),
  service management, and testing
- Update project structure and features list
This commit is contained in:
Johnathan Corgan
2026-03-08 02:56:33 +00:00
parent c086ee3edf
commit 231ef7c82d
10 changed files with 359 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+141 -83
View File
@@ -21,10 +21,19 @@ identities, discover each other, and route traffic without any central
authority or global topology knowledge.
FIPS uses Nostr keypairs (secp256k1/schnorr) as native node identities,
making every Nostr user a potential network participant. Nodes address each
other by npub, and the same cryptographic identity used in the Nostr ecosystem
serves as both the routing address and the basis for end-to-end encrypted
sessions across the mesh.
allowing users to generate their own persistent or ephemeral node addresses.
Nodes address each other by npub, and the same cryptographic identity serves
as both the routing address and the basis for end-to-end encrypted sessions
across the mesh.
FIPS allows existing TCP/IP based network software to use the FIPS mesh
network by generating a local IP address from the node npub and tunnelling
IP packets to other endpoints transparently knowing only their npub. Native
FIPS-aware applications do not need this IP tunneling or emulation capability.
All traffic over the FIPS mesh is encrypted and authenticated both
hop-to-hop between peers and independently end-to-end between FIPS
endpoints.
## Features
@@ -42,129 +51,177 @@ sessions across the mesh.
measurement
- **ECN congestion signaling** — hop-by-hop CE flag relay with RFC 3168 IPv6
marking, transport kernel drop detection
- **Operator visibility** — `fipsctl` control socket interface for runtime
inspection of peers, links, sessions, tree state, and metrics
- **Operator visibility** — `fipsctl` CLI and `fipstop` TUI dashboard for
runtime inspection of peers, links, sessions, tree state, and metrics
- **Zero configuration** — sensible defaults; a node can start with no config
file, though peer addresses are needed to join a network
## Quick Start
## Building
### Requirements
- Rust 1.85+ (edition 2024)
- Linux (TUN interface requires `CAP_NET_ADMIN` or root)
### Build
```
```bash
git clone https://github.com/fips-network/fips.git
cd fips
cargo build --release
```
### Run
Requires Rust 1.85+ (edition 2024) and Linux with TUN support.
```
# Start with default search paths (see below):
sudo ./target/release/fips
## Installation
# With an explicit configuration file:
sudo ./target/release/fips -c fips.yaml
After building, choose one of the following methods to install.
### Debian / Ubuntu (.deb)
Requires [cargo-deb](https://crates.io/crates/cargo-deb):
```bash
cargo install cargo-deb
cargo deb
sudo dpkg -i target/debian/fips_*.deb
```
Without `-c`, the node searches for `fips.yaml` in these locations
(highest priority first, values from later files override earlier ones):
This installs the daemon, CLI tools, systemd units, and a default
configuration. Edit `/etc/fips/fips.yaml` before starting:
1. `./fips.yaml` (current directory)
2. `~/.config/fips/fips.yaml` (user config)
3. `/etc/fips/fips.yaml` (system)
```bash
sudo nano /etc/fips/fips.yaml
sudo systemctl start fips
```
If no config file is found, the node starts with defaults (ephemeral
identity, default ports, no peers).
The service is enabled at boot automatically. To use `fipsctl` and
`fipstop` without sudo, add your user to the `fips` group:
A minimal two-node setup (each node points at the other):
```bash
sudo usermod -aG fips $USER # log out and back in to take effect
```
Remove with `sudo dpkg -r fips` (preserves config) or
`sudo dpkg -P fips` (removes everything including identity keys).
### Generic Linux (systemd tarball)
```bash
./packaging/systemd/build-tarball.sh
tar xzf deploy/fips-*-linux-*.tar.gz
cd fips-*-linux-*/
sudo ./install.sh
```
See [packaging/systemd/README.install.md](packaging/systemd/README.install.md)
for the full installation and configuration guide.
## Configuration
The default configuration file is installed at `/etc/fips/fips.yaml`:
```yaml
# node-a.yaml # node-b.yaml
node: # node:
identity: # identity:
nsec: "nsec1aaa..." # nsec: "nsec1bbb..."
transports: # transports:
udp: # udp:
bind_addr: "0.0.0.0:2121" # bind_addr: "0.0.0.0:2121"
peers: # peers:
- npub: "npub1bbb..." # - npub: "npub1aaa..."
addresses: # addresses:
- transport: udp # - transport: udp
addr: "10.0.0.2:2121" # addr: "10.0.0.1:2121"
# FIPS Node Configuration
node:
identity:
# By default, a new ephemeral keypair is generated on each start.
# Uncomment persistent to keep the same identity across restarts;
# on first start a keypair is saved to fips.key/fips.pub next to
# this config file (mode 0600/0644).
# persistent: true
#
# Or set an explicit key (overrides persistent):
# nsec: "nsec1..."
tun:
enabled: true
name: fips0
mtu: 1280
dns:
enabled: true
bind_addr: "127.0.0.1"
port: 5354
transports:
udp:
bind_addr: "0.0.0.0:2121"
tcp:
# Accepts inbound connections. No static outbound peers.
bind_addr: "0.0.0.0:8443"
# Ethernet transport — uncomment and set your interface name.
# ethernet:
# interface: "eth0"
# discovery: true
# announce: true
# auto_connect: true
# accept_connections: true
peers: []
# Static peers for bootstrapping (UDP or TCP):
# - npub: "npub1..."
# alias: "gateway"
# addresses:
# - transport: udp
# addr: "217.77.8.91:2121" # public FIPS testing node
# connect_policy: auto_connect
```
The `nsec` field accepts bech32 (`nsec1...`) or hex-encoded secret keys.
Omit `nsec` for an ephemeral identity that changes each restart, or set
`node.identity.persistent: true` to auto-generate and reuse a stable
identity via key file (see
[fips-configuration.md](docs/design/fips-configuration.md#identity-nodeidentity)).
See [docs/design/fips-configuration.md](docs/design/fips-configuration.md)
for the full reference.
See [docs/design/fips-configuration.md](docs/design/fips-configuration.md) for
the full configuration reference.
## Usage
### Test Connectivity
### DNS Resolution
FIPS includes a built-in DNS resolver (enabled by default, port 5354)
that maps `.fips` names to fd00::/8 IPv6 addresses derived from each
node's public key. Configure your system to send `.fips` queries to it.
FIPS includes a DNS resolver (enabled by default, port 5354) that maps
`.fips` names to fd00::/8 IPv6 addresses. With systemd-resolved:
With systemd-resolved:
```
```bash
sudo resolvectl dns fips0 127.0.0.1:5354
sudo resolvectl domain fips0 ~fips
```
Or manually in `/etc/resolv.conf` (routes all DNS through FIPS for
`.fips` names only if your resolver supports conditional forwarding;
otherwise this sets it as a general nameserver):
Then reach any FIPS node by npub with standard IPv6 tools:
```
nameserver 127.0.0.1
options port:5354
```
Once DNS is configured, ping a peer by npub:
```
```bash
ping6 npub1bbb....fips
ssh npub1bbb....fips
```
Any IPv6-capable application can reach FIPS nodes this way — `ping6`,
`ssh`, `curl`, etc.
### Monitoring
### Inspect
Use `fipsctl` to query a running node:
While a node is running, use `fipsctl` to inspect its state:
```
```bash
fipsctl show status # Node status overview
fipsctl show peers # Authenticated peers
fipsctl show links # Active links
fipsctl show tree # Spanning tree state
fipsctl show sessions # End-to-end sessions
fipsctl show bloom # Bloom filter state
fipsctl show mmp # MMP metrics summary
fipsctl show cache # Coordinate cache stats
fipsctl show connections # Pending handshake connections
fipsctl show transports # Transport instances
fipsctl show routing # Routing table summary
```
`fipsctl` communicates with the node via a Unix domain control socket
(enabled by default). All queries are read-only. Use `-s <path>` to
override the socket path.
`fipstop` provides an interactive TUI dashboard with live-updating
views of node status, peers, links, sessions, tree state, transports,
and routing:
### Multi-node Testing
```bash
fipstop # connect to local daemon
fipstop -r 1 # 1-second refresh interval
```
See [testing/](testing/) for Docker-based integration test harnesses including
static topology tests and stochastic chaos simulation.
### Service Management
```bash
sudo systemctl start fips
sudo systemctl stop fips
sudo systemctl restart fips
sudo journalctl -u fips -f
```
### Testing
See [testing/](testing/) for Docker-based integration test harnesses
including static topology tests and stochastic chaos simulation.
## Documentation
@@ -175,7 +232,8 @@ a layered protocol specification. Start with
## Project Structure
```
src/ Rust source (library + fips/fipsctl binaries)
src/ Rust source (library + fips/fipsctl/fipstop binaries)
packaging/ Debian, systemd tarball, and shared packaging files
docs/design/ Protocol design specifications
testing/ Docker-based integration test harnesses
```