A Rust implementation of the Reticulum Network Stack.
Ferret provides an rnsd daemon and is a native Rust library for building applications on Reticulum. It ships the same CLI utilities as the Python reference implementation — rnsd, rnstatus, rnpath, rnid, etc. — plus some additional utilities like rnmon, rnnamed, rnlog, rnlink, and rnbench.
Ferret is functional and interoperable with the Python reference stack. It has been tested with:
- NomadNet — TUI launches, announces propagate, network peers discovered
- Python RNS clients — shared instance connection, RPC queries, announce forwarding
- Live Reticulum network — TCP transport interfaces (RMAP, RNS Faultline, etc.)
- Interfaces: TCP client/server, UDP, Auto, Serial, Backbone
- Shared instance server (local TCP on port 37428)
- Instance control port
- Announce validation, path table management, rate limiting
- Packet forwarding between network interfaces and local clients
- State persistence (path table, known destinations, transport identity)
- HDLC and KISS codec framing
- Leveled logging
- CLI utilities:
rnsd,rnstatus
- Live network testing of link-based utilities (
rncp,rnx,rnlink,rnbench) - Full transport-layer integration for
rnprobe(packet receipt callbacks)
- Interfaces: I2P, Pipe, KISS, RNode, Weave, QUIC (experimental)
- LXStamper-compatible proof-of-work stamps (not yet validated against live peers exchanging discovery announces)
- IFAC (Interface Access Code) authentication
- CLI utilities:
rnpath,rnid,rnprobe,rncp,rnx,rnlog,rnlink,rnbench,rnmon,rnnamed,rnodeconf - Name service library with proof-of-work stamp cost, record validation, persistent store (no limits implemented yet)
# Build all binaries
cargo build --release
# Run the daemon (uses ~/.reticulum/config, same as Python rnsd)
./target/release/rnsd
# Run with custom config directory
./target/release/rnsd -c /path/to/config
# Run with verbose logging
./target/release/rnsd -vv
# Run as a service (log to file)
./target/release/rnsd -s
# Check network status
./target/release/rnstatus
# Show all interfaces including hidden ones
./target/release/rnstatus -a
# Show path table
./target/release/rnpath -t
# Generate a new identity
./target/release/rnid -g ~/.reticulum/my_identity
# Encrypt a file
./target/release/rnid -i ~/.reticulum/my_identity -e secret.txt
# Sign a file
./target/release/rnid -i ~/.reticulum/my_identity -s document.txtFerret reads the Reticulum config from ~/.reticulum/config. If no config exists, it creates a default one.
- Stop any running Python
rnsdinstance - Start ferret:
./target/release/rnsd - Start NomadNet:
nomadnet
NomadNet will connect to ferret's shared instance automatically.
Ferret uses the standard Reticulum INI config format. Example:
[reticulum]
share_instance = yes
shared_instance_port = 37428
instance_control_port = 37429
enable_transport = no
[logging]
loglevel = 4
[interfaces]
[[Default Interface]]
type = AutoInterface
enabled = yes
[[TCP Transport]]
type = TCPClientInterface
enabled = yes
target_host = rmap.world
target_port = 4242| Level | Name | Shows |
|---|---|---|
| 0 | Critical | Fatal errors |
| 1 | Error | Recoverable errors |
| 2 | Warning | Interface failures, persist errors |
| 3 | Notice | Interface skipped, fallback to standalone |
| 4 | Info | Startup milestones, shutdown (default) |
| 5 | Verbose | Connections, announces validated, interfaces registered |
| 6 | Debug | Init steps, RPC commands, read loop lifecycle |
| 7 | Extreme | Per-packet routing, byte counts, frame decodes |
Ferret is a single-crate Rust project. The library modules are layered, and the CLI binaries live under src/bin/.
| Binary | Status | Description |
|---|---|---|
rnsd |
✅ | Reticulum daemon (shared instance server) |
rnstatus |
✅ | Network interface status display |
rnpath |
✅ | Path table management and queries |
rnid |
✅ | Identity management, encrypt/decrypt, sign/verify |
rnprobe |
✅ | Network probe (ping-like RTT measurement) |
rncp |
✅ | File transfer over Links |
rnx |
✅ | Remote command execution |
rnlog |
✅ | Live announce stream logger (ferret-original) |
rnlink |
✅ | Raw bidirectional Link pipe (ferret-original) |
rnbench |
✅ | Network throughput benchmark (ferret-original) |
rnmon |
✅ | TUI network monitor (ferret-original, requires tui feature) |
rnnamed |
✅ | Human-readable name service (ferret-original) |
rnodeconf |
✅ | RNode hardware configuration (requires serial feature) |
| Layer | Module | Purpose |
|---|---|---|
| 1 | crypto |
X25519, Ed25519, AES-CBC, SHA-256/512, HMAC, HKDF, Fernet tokens, LXStamper PoW |
| 2 | identity |
Keypair management, identity store, ratchet store, announce validation |
| 3 | destination |
Addressing, hashing, encryption, announce building |
| 3 | packet |
Wire-format packing/unpacking, receipts, proofs |
| 3 | transport |
Routing tables, inbound/outbound, announce processing, packet cache |
| 4 | link |
Link establishment, handshake, keepalive, encryption, requests |
| 4 | channel |
Reliable message delivery over links |
| 4 | buffer |
Stream I/O over channels |
| 5 | resource |
Large data transfer with segmentation and compression |
| 5 | discovery |
Interface announcer, auto-connect, blackhole management |
| 6 | interfaces |
TCP, UDP, Serial, KISS, RNode, I2P, Auto, Pipe, Backbone, Weave, Local |
| 7 | reticulum |
Main process, config parser, RPC server, background jobs, logging |
| 8 | rpc_client |
RPC client for shared-instance control port queries |
| 8 | util/format |
Output formatting (pretty hex, sizes, speeds, timestamps) |
| 8 | names |
Human-readable name service (record, store, resolver) |
Requires Rust 1.75+ (2021 edition).
# Default build (includes serial, backbone, QUIC support)
cargo build --release
# Minimal build (no serial/backbone/QUIC)
cargo build --release --no-default-features
# With specific features
cargo build --release --features "serial,backbone"| Feature | Default | Description |
|---|---|---|
serial |
yes | Serial port interfaces (KISS, RNode, Weave) and rnodeconf |
backbone |
yes | Backbone TCP mesh interface |
quic |
yes | QUIC transport (experimental) |
tui |
yes | TUI network monitor (rnmon) via ratatui |
plugins |
no | Dynamic library interface plugins |
# Run all tests
cargo test
# Run unit tests only
cargo test --lib
# Run CLI property tests
cargo test --test cli_props -- --test-threads=1
# Run integration tests
cargo test --test integration
# Run with single thread (avoids port conflicts for RPC tests)
cargo test -- --test-threads=1The test suite includes 280+ tests: unit tests, property-based tests (proptest), and end-to-end integration tests. The CLI property tests validate 15 correctness properties covering HMAC authentication, pickle wire format, encrypt/decrypt round-trips, sign/validate round-trips, and output formatting.
See LICENSE for details.
Ferret is built to be interoperable with Reticulum by Mark Qvist. The protocol specification and reference implementation are the authoritative source for wire-format compatibility.