Mirror/Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2026-06-08 06:01:55 -07:00
Code Issues Packages Projects Releases Wiki Activity

Added markdown manual

Browse Source
This commit is contained in:
Mark Qvist
2026-05-06 19:25:28 +02:00
parent b8d6a14599
commit 49f56e7d0d
18 changed files with 11464 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Makefile
+2 -1
View File
@@ -27,6 +27,7 @@ clean:
purge_docs:
@echo Purging documentation build...
@-rm -rf ./docs/manual
@-rm -rf ./docs/markdown
@-rm -rf ./docs/*.pdf
@-rm -rf ./docs/*.epub
@@ -50,7 +51,7 @@ build_pure_wheel:
python3 setup.py bdist_wheel --pure
documentation:
make -C docs html
make -C docs html markdown
manual:
make -C docs latexpdf epub
docs/Makefile
+6
View File
@@ -35,3 +35,9 @@ help:
cp -r build/epub/ReticulumNetworkStack.epub ./Reticulum\ Manual.epub; \
echo "EPUB Manual Generated"; \
fi
@if [ $@ = "markdown" ]; then \
rm -rf markdown; \
cp -r build/markdown ./; \
echo "Markdown Manual Generated"; \
fi
docs/markdown/examples.md
+3368
View File
File diff suppressed because it is too large Load Diff
docs/markdown/forhumans.md
+1
View File
@@ -0,0 +1 @@
# An Explanation of Reticulum for Human Beings
docs/markdown/gettingstartedfast.md
+690
View File
@@ -0,0 +1,690 @@
# Getting Started Fast
The best way to get started with the Reticulum Network Stack depends on what
you want to do. This guide will outline sensible starting paths for different
scenarios.
## Standalone Reticulum Installation
If you simply want to install Reticulum and related utilities on a system,
the easiest way is via the `pip` package manager:
```shell
pip install rns
```
If you do not already have pip installed, you can install it using the package manager
of your system with a command like `sudo apt install python3-pip`,
`sudo pamac install python-pip` or similar.
You can also dowload the Reticulum release wheels from GitHub, or other release channels,
and install them offline using `pip`:
```shell
pip install ./rns-1.1.2-py3-none-any.whl
```
On platforms that limit user package installation via `pip`, you may need to manually
allow this using the `--break-system-packages` command line flag when installing. This
will not actually break any packages, unless you have installed Reticulum directly via
your operating system’s package manager.
```shell
pip install rns --break-system-packages
```
For more detailed installation instructions, please see the
[Platform-Specific Install Notes](#install-guides) section.
After installation is complete, it might be helpful to refer to the
[Using Reticulum on Your System](using.md#using-main) chapter.
### Resolving Dependency & Installation Issues
On some platforms, there may not be binary packages available for all dependencies, and
`pip` installation may fail with an error message. In these cases, the issue can usually
be resolved by installing the development essentials packages for your platform:
```shell
# Debian / Ubuntu / Derivatives
sudo apt install build-essential
# Arch / Manjaro / Derivatives
sudo pamac install base-devel
# Fedora
sudo dnf groupinstall "Development Tools" "Development Libraries"
```
With the base development packages installed, `pip` should be able to compile any missing
dependencies from source, and complete installation even on platforms that don’t have pre-
compiled packages available.
## Try Using a Reticulum-based Program
If you simply want to try using a program built with Reticulum, a [range of different
programs](software.md#software-main) exist that allow basic communication and a various other useful functions,
even over extremely low-bandwidth Reticulum networks.
## Using the Included Utilities
Reticulum comes with a range of included utilities that make it easier to
manage your network, check connectivity and make Reticulum available to other
programs on your system.
You can use `rnsd` to run Reticulum as a background or foreground service,
and the `rnstatus`, `rnpath` and `rnprobe` utilities to view and query
network status and connectivity.
To learn more about these utility programs, have a look at the
[Using Reticulum on Your System](using.md#using-main) chapter of this manual.
## Creating a Network With Reticulum
To create a network, you will need to specify one or more *interfaces* for
Reticulum to use. This is done in the Reticulum configuration file, which by
default is located at `~/.reticulum/config`. You can get an example
configuration file with all options via `rnsd --exampleconfig`.
When Reticulum is started for the first time, it will create a default
configuration file, with one active interface. This default interface uses
your existing Ethernet and WiFi networks (if any), and only allows you to
communicate with other Reticulum peers within your local broadcast domains.
To communicate further, you will have to add one or more interfaces. The default
configuration includes a number of examples, ranging from using TCP over the
internet, to LoRa and Packet Radio interfaces.
With Reticulum, you only need to configure what interfaces you want to communicate
over. There is no need to configure address spaces, subnets, routing tables,
or other things you might be used to from other network types.
Once Reticulum knows which interfaces it should use, it will automatically
discover topography and configure transport of data to any destinations it
knows about.
In situations where you already have an established WiFi or Ethernet network, and
many devices that want to utilise the same external Reticulum network paths (for example over
LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by
adding any external interfaces to the configuration of this system, and then enabling transport on it. Any
other device on your local WiFi will then be able to connect to this wider Reticulum
network just using the default ([AutoInterface](interfaces.md#interfaces-auto)) configuration.
Possibly, the examples in the config file are enough to get you started. If
you want more information, you can read the [Building Networks](networks.md#networks-main)
and [Interfaces](interfaces.md#interfaces-main) chapters of this manual, but most importantly,
start with reading the next section, [Bootstrapping Connectivity](#bootstrapping-connectivity),
as this provides the most essential understanding of how to ensure reliable
connectivity with a minimum of maintenance.
<a id="bootstrapping-connectivity"></a>
## Bootstrapping Connectivity
Reticulum is not a service you subscribe to, nor is it a single global network you “join”. It is a *networking stack*; a toolkit for building communications systems that align with your specific values, requirements, and operational environment. The way you choose to connect to other Reticulum peers is entirely your own choice.
One of the most powerful aspects of Reticulum is that it provides a multitude of tools to establish, maintain, and optimize connectivity. You can use these tools in isolation or combine them in complex configurations to achieve a vast array of goals.
Whether your aim is to create a completely private, air-gapped network for your family; to build a resilient community mesh that survives infrastructure collapse; to connect far and wide to as many nodes as possible; or simply to maintain a reliable, encrypted link to a specific organization you care about, Reticulum provides the mechanisms to make it happen.
There is no “right” or “wrong” way to build a Reticulum network, and you don’t need to be a network engineer just to get started. If the information flows in the way you intend, and your privacy and security requirements are met, your configuration is a success. Reticulum is designed to make the most challenging and difficult scenarios attainable, even when other networking technologies fail.
### Finding Your Way
When you first start using Reticulum, you need a way to obtain connectivity with the peers you want to communicate with - the process of *bootstrapping connectivity*.
#### IMPORTANT
A common mistake in modern networking is the reliance on a few centralized, hard-coded entrypoints. If every user simply connects to the same list of public IP addresses found on a website, the network becomes brittle, centralized, and ultimately fails to deliver on the promise of decentralization and resilience. You have a responsibility here.
Reticulum encourages the approach of *organic growth*. Instead of relying on permanent static connections to distant servers, you can use temporary bootstrap connections to continously *discover* more relevant or local infrastructure. Once discovered, your system can automatically form stronger, more direct links to these peers, and discard the temporary bootstrap links. This results in a web of connections that are geographically relevant, resilient and efficient.
It *is* possible to simply add a few public entrypoints to the `[interfaces]` section of your Reticulum configuration and be connected, but a better option is to enable [interface discovery](using.md#using-interface-discovery) and either manually select relevant, local interfaces, or enable discovered interface auto-connection.
A relevant option in this context is the [bootstrap only](interfaces.md#interfaces-options) interface option. This is an automated tool for better distributing connectivity. By enabling interface discovery and auto-connection, and marking an interface as `bootstrap_only`, you tell Reticulum to use that interface primarliy to find connectivity options, and then disconnect it once sufficient entrypoints have been discovered. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.
Good places to find interface definitions for bootstrapping connectivity are websites like
[directory.rns.recipes](https://directory.rns.recipes/) and [rmap.world](https://rmap.world/).
### Build Personal Infrastructure
You do not need a datacenter to be a meaningful part of the Reticulum ecosystem. In fact, the most important nodes in the network are often the smallest ones.
We strongly encourage everyone, even home users, to think in terms of building **personal infrastructure**. Don’t connect every phone, tablet, and computer in your house directly to a public internet gateway. Instead, repurpose an old computer, a Raspberry Pi, or a supported router to act as your own, personal **Transport Node**:
* Your local Transport Node sits in your home, connected to your WiFi and perhaps a radio interface (like an RNode).
* You configure this node with a `bootstrap_only` interface (perhaps a TCP tunnel to a wider network) and enable interface discovery.
* While you sleep, work, or cook, your node listens to the network. It discovers other local community members, validates their Network Identities, and automatically establishes direct links.
* Your personal devices now connect to your *local* node, which is integrated into a living, breathing local mesh. Your traffic flows through local paths provided by other real people in the community rather than bouncing off a distant server.
**Don’t wait for others to build the networks you want to see**. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes inevitable.
### Mixing Strategies
There is no requirement to commit to a single strategy. The most robust setups often mix static, dynamic, and discovered interfaces.
* **Static Interfaces:** You maintain a permanent interface to a trusted friend or organization using a static configuration.
* **Bootstrap Links:** You connect a `bootstrap_only` interface to a public gateway on the Internet to scan for new connectable peers or to regain connectivity if your other interfaces fail.
* **Local Wide-Area Connectivity:** You run a `RNodeInterface` on a shared frequency, giving you completely self-sovereign and private wide-area access to both your own network and other Reticulum peers globally, without any “service providers” being able to control or monitor how you interact with people.
By combining these methods, you create a system that is secure against single points of failure, adaptable to changing network conditions, and better integrated into your physical and social reality.
### Network Health & Responsibility
As you participate in the wider networks you discover and build, you will inevitably encounter peers that are misconfigured, malicious, or simply broken. To protect your resources and those of your local peers, you can utilize the [Blackhole Management](using.md#using-blackhole-management) system.
Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that *your* transport capacity is used for what *you* consider legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.
### Contributing to the Global Ret
If you have the means to host a stable node with a public IP address, consider becoming a [Public Entrypoint](#hosting-entrypoints). By [publishing your interface as discoverable](interfaces.md#interfaces-discoverable), you provide a potential connection point for others, helping the network grow and reach new areas.
For guidelines on how to properly configure a public entrypoint, refer to the [Hosting Public Entrypoints](#hosting-entrypoints) section.
## Connect to the Distributed Backbone
A global, distributed backbone of Reticulum Transport Nodes is being run by volunteers from around the world. This network constitutes a heterogenous collection of both public and private nodes that form an uncoordinated, voluntary inter-networking backbone that currently provides global transport and internetworking capabilities for Reticulum.
As a good starting point, you can find interface definitions for connecting your own networks to this backbone on websites such as [directory.rns.recipes](https://directory.rns.recipes/) and [rmap.world](https://rmap.world/).
<a id="hosting-entrypoints"></a>
## Hosting Public Entrypoints
If you want to help build a strong global interconnection backbone, you can host a public (or private) entry-point to a Reticulum network over the
Internet. This section offers some helpful pointers. Once you have set up your public entrypoint, it is a great idea to [make it discoverable over Reticulum](interfaces.md#interfaces-discoverable).
You will need a machine, physical or virtual with a public IP address, that can be reached by other devices on the Internet.
The most efficient and performant way to host a connectable entry-point supporting many
users is to use the `BackboneInterface`. This interface type is fully compatible with
the `TCPClientInterface` and `TCPServerInterface` types, but much faster and uses
less system resources, allowing your device to handle thousands of connections even on
small systems.
It is also important to set your connectable interface to `gateway` mode, since this
will greatly improve network convergence time and path resolution for anyone connecting
to your entry-point.
```ini
# This example demonstrates a backbone interface
# configured for acting as a gateway for users to
# connect to either a public or private network
[[Public Gateway]]
type = BackboneInterface
enabled = yes
mode = gateway
listen_on = 0.0.0.0
port = 4242
# On publicly available interfaces, it is
# essential to configure sensible announce
# rate targets.
announce_rate_target = 3600
announce_rate_penalty = 3600
announce_rate_grace = 6
```
If instead you want to make a private entry-point from the Internet, you can use the
[IFAC name and passphrase options](interfaces.md#interfaces-options) to secure your interface with a network name and passphrase.
```ini
# A private entry-point requiring a pre-shared
# network name and passphrase to connect to.
[[Private Gateway]]
type = BackboneInterface
enabled = yes
mode = gateway
listen_on = 0.0.0.0
port = 4242
network_name = private_ret
passphrase = 2owjajquafIanPecAc
```
If you are hosting an entry-point on an operating system that does not support
`BackboneInterface`, you can use `TCPServerInterface` instead, although it will
not be as performant.
## Connecting Reticulum Instances Over the Internet
Reticulum currently offers three interfaces suitable for connecting instances over the Internet: [Backbone](interfaces.md#interfaces-backbone), [TCP](interfaces.md#interfaces-tcps)
and [I2P](interfaces.md#interfaces-i2p). Each interface offers a different set of features, and Reticulum
users should carefully choose the interface which best suites their needs.
The `TCPServerInterface` allows users to host an instance accessible over TCP/IP. This
method is generally faster, lower latency, and more energy efficient than using `I2PInterface`,
however it also leaks more data about the server host.
The `BackboneInterface` is a very fast and efficient interface type available on POSIX operating
systems, designed to handle thousands of connections simultaneously with low memory, processing
and I/O overhead. It is fully compatible with the TCP-based interface types.
TCP connections reveal the IP address of both your instance and the server to anyone who can
inspect the connection. Someone could use this information to determine your location or identity. Adversaries
inspecting your packets may be able to record packet metadata like time of transmission and packet size.
Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use
packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it.
Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address,
which most Internet connections don’t offer anymore.
The `I2PInterface` routes messages through the [Invisible Internet Protocol
(I2P)](https://geti2p.net/en/). To use this interface, users must also run an I2P daemon in
parallel to `rnsd`. For always-on I2P nodes it is recommended to use [i2pd](https://i2pd.website/).
By default, I2P will encrypt and mix all traffic sent over the Internet, and
hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node
will also relay other I2P user’s encrypted packets, which will use extra
bandwidth and compute power, but also makes timing attacks and other forms of
deep-packet-inspection much more difficult.
I2P also allows users to host globally available Reticulum instances from non-public IP’s and behind firewalls and NAT.
In general it is recommended to use an I2P node if you want to host a publicly accessible
instance, while preserving anonymity. If you care more about performance, and a slightly
easier setup, use TCP.
## Adding Radio Interfaces
Once you have Reticulum installed and working, you can add radio interfaces with
any compatible hardware you have available. Reticulum supports a wide range of radio
hardware, and if you already have any available, it is very likely that it will
work with Reticulum. For information on how to configure this, see the
[Interfaces](interfaces.md#interfaces-main) section of this manual.
If you do not already have transceiver hardware available, you can easily and
cheaply build an [RNode](hardware.md#rnode-main), which is a general-purpose long-range
digital radio transceiver, that integrates easily with Reticulum.
To build one yourself requires installing a custom firmware on a supported LoRa
development board with an auto-install script or web-based flasher.
Please see the [Communications Hardware](hardware.md#hardware-main) chapter for a guide.
If you prefer purchasing a ready-made unit, you can refer to the
list of suppliers.
Other radio-based hardware interfaces are being developed and made available by
the broader Reticulum community. You can find more information on such topics
over Reticulum-based information sharing systems.
If you have communications hardware that is not already supported by any of the
[existing interface types](interfaces.md#interfaces-main), it is easy to write (and potentially
publish) a [custom interface module](interfaces.md#interfaces-custom) that makes it compatible with Reticulum.
## Creating and Using Custom Interfaces
While Reticulum includes a flexible and broad range of built-in interfaces, these
will not cover every conceivable type of communications hardware that Reticulum
can potentially use to communicate.
It is therefore possible to easily write your own interface modules, that can be
loaded at run-time and used on-par with any of the built-in interface types.
For more information on this subject, and code examples to build on, please see
the [Configuring Interfaces](interfaces.md#interfaces-main) chapter.
## Develop a Program with Reticulum
If you want to develop programs that use Reticulum, the easiest way to get
started is to install the latest release of Reticulum via pip:
```default
pip install rns
```
The above command will install Reticulum and dependencies, and you will be
ready to import and use RNS in your own programs. The next step will most
likely be to look at some [Example Programs](examples.md#examples-main).
The entire Reticulum API is documented in the [API Reference](reference.md#api-main)
chapter of this manual. Before diving in, it’s probably a good idea to read
this manual in full, but at least start with the [Understanding Reticulum](understanding.md#understanding-main) chapter.
<a id="install-guides"></a>
## Platform-Specific Install Notes
Some platforms require a slightly different installation procedure, or have
various quirks that are worth being aware of. These are listed here.
### Android
Reticulum can be used on Android in different ways. The easiest way to get
started is using an app like [Sideband](https://unsigned.io/sideband).
For more control and features, you can use Reticulum and related programs via
the [Termux app](https://termux.com/), at the time of writing available on
[F-droid](https://f-droid.org).
Termux is a terminal emulator and Linux environment for Android based devices,
which includes the ability to use many different programs and libraries,
including Reticulum.
To use Reticulum within the Termux environment, you will need to install
`python` and the `python-cryptography` library using `pkg`, the package-manager
build into Termux. After that, you can use `pip` to install Reticulum.
From within Termux, execute the following:
```shell
# First, make sure indexes and packages are up to date.
pkg update
pkg upgrade
# Then install python and the cryptography library.
pkg install python python-cryptography
# Make sure pip is up to date, and install the wheel module.
pip install wheel pip --upgrade
# Install Reticulum
pip install rns
```
If for some reason the `python-cryptography` package is not available for
your platform via the Termux package manager, you can attempt to build it
locally on your device using the following command:
```shell
# First, make sure indexes and packages are up to date.
pkg update
pkg upgrade
# Then install dependencies for the cryptography library.
pkg install python build-essential openssl libffi rust
# Make sure pip is up to date, and install the wheel module.
pip install wheel pip --upgrade
# To allow the installer to build the cryptography module,
# we need to let it know what platform we are compiling for:
export CARGO_BUILD_TARGET="aarch64-linux-android"
# Start the install process for the cryptography module.
# Depending on your device, this can take several minutes,
# since the module must be compiled locally on your device.
pip install cryptography
# If the above installation succeeds, you can now install
# Reticulum and any related software
pip install rns
```
It is also possible to include Reticulum in apps compiled and distributed as
Android APKs. A detailed tutorial and example source code will be included
here at a later point. Until then you can use the [Sideband source code](https://github.com/markqvist/sideband) as an example and starting point.
### ARM64
On some architectures, including ARM64, not all dependencies have precompiled
binaries. On such systems, you may need to install `python3-dev` (or similar) before
installing Reticulum or programs that depend on Reticulum.
```shell
# Install Python and development packages
sudo apt update
sudo apt install python3 python3-pip python3-dev
# Install Reticulum
python3 -m pip install rns
```
With these packages installed, `pip` will be able to build any missing dependencies
on your system locally.
### Debian Bookworm
On versions of Debian released after April 2023, it is no longer possible by default
to use `pip` to install packages onto your system. Unfortunately, you will need to
use the replacement `pipx` command instead, which places installed packages in an
isolated environment. This should not negatively affect Reticulum, but will not work
for including and using Reticulum in your own scripts and programs.
```shell
# Install pipx
sudo apt install pipx
# Make installed programs available on the command line
pipx ensurepath
# Install Reticulum
pipx install rns
```
Alternatively, you can restore normal behaviour to `pip` by creating or editing
the configuration file located at `~/.config/pip/pip.conf`, and adding the
following section:
```ini
[global]
break-system-packages = true
```
For a one-shot installation of Reticulum, without globally enabling the `break-system-packages`
option, you can use the following command:
```shell
pip install rns --break-system-packages
```
#### NOTE
The `--break-system-packages` directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing `pip` packages user- and system-wide. While this *could* in rare
cases lead to version conflicts, it does not generally pose any problems, especially
not in the case of installing Reticulum.
### MacOS
To install Reticulum on macOS, you will need to have Python and the `pip` package
manager installed.
Systems running macOS can vary quite widely in whether or not Python is pre-installed,
and if it is, which version is installed, and whether the `pip` package manager is
also installed and set up. If in doubt, you can [download and install](https://www.python.org/downloads/)
Python manually.
When Python and `pip` is available on your system, simply open a terminal window
and use one of the following commands:
```shell
# Install Reticulum and utilities with pip:
pip3 install rns
# On some versions, you may need to use the
# flag --break-system-packages to install:
pip3 install rns --break-system-packages
```
#### NOTE
The `--break-system-packages` directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing `pip` packages user- and system-wide. While this *could* in rare
cases lead to version conflicts, it does not generally pose any problems, especially
not in the case of installing Reticulum.
Additionally, some version combinations of macOS and Python require you to
manually add your installed `pip` packages directory to your PATH environment
variable, before you can use installed commands in your terminal. Usually, adding
the following line to your shell init script (for example `~/.zshrc`) will be enough:
```shell
export PATH=$PATH:~/Library/Python/3.9/bin
```
Adjust Python version and shell init script location according to your system.
### OpenWRT
On OpenWRT systems with sufficient storage and memory, you can install
Reticulum and related utilities using the opkg package manager and pip.
#### NOTE
At the time of releasing this manual, work is underway to create pre-built
Reticulum packages for OpenWRT, with full configuration, service
and `uci` integration. Please see the [feed-reticulum](https://github.com/gretel/feed-reticulum)
and [reticulum-openwrt](https://github.com/gretel/reticulum-openwrt)
repositories for more information.
To install Reticulum on OpenWRT, first log into a command line session, and
then use the following instructions:
```shell
# Install dependencies
opkg install python3 python3-pip python3-cryptography python3-pyserial
# Install Reticulum
pip install rns
# Start rnsd with debug logging enabled
rnsd -vvv
```
#### NOTE
The above instructions have been verified and tested on OpenWRT 21.02 only.
It is likely that other versions may require slightly altered installation
commands or package names. You will also need enough free space in your
overlay FS, and enough free RAM to actually run Reticulum and any related
programs and utilities.
Depending on your device configuration, you may need to adjust firewall rules
for Reticulum connectivity to and from your device to work. Until proper
packaging is ready, you will also need to manually create a service or startup
script to automatically laucnh Reticulum at boot time.
Please also note that the AutoInterface requires link-local IPv6 addresses
to be enabled for any Ethernet and WiFi devices you intend to use. If `ip a`
shows an address starting with `fe80::` for the device in question,
`AutoInterface` should work for that device.
### Raspberry Pi
It is currently recommended to use a 64-bit version of the Raspberry Pi OS
if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
don’t always have packages available for some dependencies. If Python and the
pip package manager is not already installed, do that first, and then
install Reticulum using pip.
```shell
# Install dependencies
sudo apt install python3 python3-pip python3-cryptography python3-pyserial
# Install Reticulum
pip install rns --break-system-packages
```
#### NOTE
The `--break-system-packages` directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing `pip` packages user- and system-wide. While this *could* in rare
cases lead to version conflicts, it does not generally pose any problems, especially
not in the case of installing Reticulum.
While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
it will require manually configuring and installing required build dependencies,
and is not detailed in this manual.
### RISC-V
On some architectures, including RISC-V, not all dependencies have precompiled
binaries. On such systems, you may need to install `python3-dev` (or similar) before
installing Reticulum or programs that depend on Reticulum.
```shell
# Install Python and development packages
sudo apt update
sudo apt install python3 python3-pip python3-dev
# Install Reticulum
python3 -m pip install rns
```
With these packages installed, `pip` will be able to build any missing dependencies
on your system locally.
### Ubuntu Lunar
On versions of Ubuntu released after April 2023, it is no longer possible by default
to use `pip` to install packages onto your system. Unfortunately, you will need to
use the replacement `pipx` command instead, which places installed packages in an
isolated environment. This should not negatively affect Reticulum, but will not work
for including and using Reticulum in your own scripts and programs.
```shell
# Install pipx
sudo apt install pipx
# Make installed programs available on the command line
pipx ensurepath
# Install Reticulum
pipx install rns
```
Alternatively, you can restore normal behaviour to `pip` by creating or editing
the configuration file located at `~/.config/pip/pip.conf`, and adding the
following section:
```text
[global]
break-system-packages = true
```
For a one-shot installation of Reticulum, without globally enabling the `break-system-packages`
option, you can use the following command:
```text
pip install rns --break-system-packages
```
#### NOTE
The `--break-system-packages` directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing `pip` packages user- and system-wide. While this *could* in rare
cases lead to version conflicts, it does not generally pose any problems, especially
not in the case of installing Reticulum.
### Windows
On Windows operating systems, the easiest way to install Reticulum is by using the
`pip` package manager from the command line (either the command prompt or Windows
Powershell).
If you don’t already have Python installed, [download and install Python](https://www.python.org/downloads/).
At the time of publication of this manual, the recommended version is [Python 3.12.7](https://www.python.org/downloads/release/python-3127).
**Important!** When asked by the installer, make sure to add the Python program to
your PATH environment variables. If you don’t do this, you will not be able to
use the `pip` installer, or run the included Reticulum utility programs (such as
`rnsd` and `rnstatus`) from the command line.
After installing Python, open the command prompt or Windows Powershell, and type:
```shell
pip install rns
```
You can now use Reticulum and all included utility programs directly from your
preferred command line interface.
## Pure-Python Reticulum
#### WARNING
If you use the `rnspure` package to run Reticulum on systems that
do not support [PyCA/cryptography](https://github.com/pyca/cryptography), it is
important that you read and understand the [Cryptographic Primitives](understanding.md#understanding-primitives)
section of this manual.
In some rare cases, and on more obscure system types, it is not possible to
install one or more dependencies. In such situations,
you can use the `rnspure` package instead of the `rns` package, or use `pip`
with the `--no-dependencies` command-line option. The `rnspure`
package requires no external dependencies for installation. Please note that the
actual contents of the `rns` and `rnspure` packages are *completely identical*.
The only difference is that the `rnspure` package lists no dependencies required
for installation.
No matter how Reticulum is installed and started, it will load external dependencies
only if they are *needed* and *available*. If for example you want to use Reticulum
on a system that cannot support `pyserial`, it is perfectly possible to do so using
the rnspure package, but Reticulum will not be able to use serial-based interfaces.
All other available modules will still be loaded when needed.
docs/markdown/git.md
+561
View File
@@ -0,0 +1,561 @@
<a id="git-main"></a>
# Git Over Reticulum
A set of utilities for distributed collaborative software development and publishing is included in RNS.
The system consists of two parts: The `rngit` node that hosts repositories, and the `git-remote-rns` helper that enables Git to communicate with rngit nodes. As soon as you have RNS installed on your system, you can transparently use Git with Reticulum-hosted repositories just like any other type of remote. Git over Reticulum uses URLs in the following format: `rns://DESTINATION_HASH/group/repo`.
If you set a branch to track a Reticulum remote as the default upstream, you can simply use `git` as you normally would; all commands work transparently and as expected.
#### WARNING
**The rngit program is a new addition to RNS!** This functionality was introduced in RNS 1.2.0. While great care has been taken to design a secure, but highly configurable and flexible permission system for allowing many users to interact with many different repositories on a single node, `rngit` has not been tested extensively in the wild! Be careful when hosting repositories, especially if they are public or semi-public.
## The rngit Utility
The `rngit` utility provides full Git repository hosting and interaction over Reticulum. It allows you to host and manage Git repositories and releases on Reticulum nodes, and to interact with remote repositories using standard Git commands through the `rns://` URL scheme.
**Usage Examples**
Run `rngit` to start a repository node:
```text
$ rngit
[Notice] Starting Reticulum Git Node...
[Notice] Reticulum Git Node listening on <0d7334d411d00120cbad24edf355fdd2>
```
On the first run, `rngit` will create a default configuration file. You will then need to edit this, to point to your repository locations, configure access permissions, and perform any other necessary configuration.
View your identity and destination hashes:
```text
$ rngit --print-identity
Git Peer Identity : <959e10e5efc1bd9d97a4083babe51dea>
Repository Node Identity : <153cb870b4665b8c1c348896292b0bad>
Repositories Destination : <0d7334d411d00120cbad24edf355fdd2>
```
If the page node is enabled, the output will also include the Nomad Network destination hash.
You can run `rngit` in service mode with logging to file:
```text
$ rngit -s
```
Clone a repository from a remote `rngit` node:
```text
$ git clone rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo
```
Add a Reticulum remote to an existing repository:
```text
$ git remote add some_remote rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo
```
Push changes to the Reticulum remote:
```text
$ git push some_remote master
```
Get changes from a remote repository:
```text
$ git pull rns_remote master
```
**All Command-Line Options (rngit)**
```text
usage: rngit.py [-h] [--config CONFIG] [--rnsconfig RNSCONFIG] [-s] [-i] [-v]
[-q] [--version]
Reticulum Git Repository Node
options:
-h, --help show this help message and exit
--config CONFIG path to alternative config directory
--rnsconfig RNSCONFIG
path to alternative Reticulum config directory
-p, --print-identity print identity and destination info and exit
-s, --service rngit is running as a service and should log to file
-i, --interactive drop into interactive shell after initialisation
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
--version show program's version number and exit
```
**All Command-Line Options (git-remote-rns)**
The `git-remote-rns` helper is automatically invoked by Git when interacting with `rns://` URLs. It is not typically run directly by users, but accepts the following environment variables for configuration:
- `RNGIT_CONFIG` - Path to alternative client configuration directory
- `RNS_CONFIG` - Path to alternative Reticulum configuration directory
The client configuration file is located at `~/.rngit/client_config` and allows adjusting parameters such as the reference batch size for transfers.
## Repository Structure
The `rngit` node organizes repositories into groups. Each group is a directory containing bare Git repositories. The repository path format is `group_name/repo_name`. For example, a repository at `/var/git/public/myrepo` would be accessible as `public/myrepo` via the URL `rns://DESTINATION_HASH/public/myrepo`.
**Configuration**
The `rngit` node configuration file is located at `~/.rngit/config` (or `/etc/rngit/config` for system-wide installations). The default configuration includes:
- Repository group paths defining where to find bare repositories
- Access permissions for groups and individual repositories
- Announce intervals for network visibility
- Optional statistics recording for repository activity
Access permissions can be configured at the group level in the config file, or per-repository using `.allowed` files. Permissions use the format `permission:target` where permission is `r` (read), `w` (write), `rw` (read/write), `c` (create) or `s` (stats) and target is `all`, `none`, or a specific identity hash.
The `s` (stats) permission allows viewing repository activity statistics, including views, fetches and pushes over time. To enable statistics recording, set `record_stats = yes` in the `[rngit]` section of the configuration file. You can also exclude specific identities from statistics by adding their hashes to `stats_ignore_identities`.
Repository-specific `.allowed` files can be static text files or executable scripts that output permission rules to stdout. A `group.allowed` file in a repository group directory applies to all repositories within that group.
## Serving Pages Over Nomad Network
In addition to providing Git repository access via the Git remote helper protocol, `rngit` can also run a [Nomad Network](https://github.com/markqvist/nomadnet) compatible page node. This allows users to browse repository information, view file contents, inspect commit history and access repository statistics through any Nomad Network client.
When enabled, the page node provides a complete interface to your repositories, with automatic Markdown to Micron conversion, syntax-highlighted code browsing, and detailed commit, diff and statistics views.
**Enabling the Git Page Node**
To enable the page node, add the following to your `~/.rngit/config` file:
```text
[pages]
serve_nomadnet = yes
```
When the page node is enabled, `rngit` will listen on a Nomad Network node destination in addition to the Git repository destination. You can view the destination hash by running:
```text
$ rngit --print-identity
Git Peer Identity : <959e10e5efc1bd9d97a4083babe51dea>
Repository Node Identity : <153cb870b4665b8c1c348896292b0bad>
Repositories Destination : <0d7334d411d00120cbad24edf355fdd2>
Nomad Network Destination : <50824b711717f97c2fb1166ceddd5ea9>
```
**Accessing Repository Pages**
Once the page node is running, you can access it from any Nomad Network client by connecting to the Nomad Network destination. The page node provides the following views:
- **Front Page** - Lists all repository groups accessible to your identity
- **Group Page** - Shows all repositories within a group
- **Repository Page** - Displays repository overview, description and README
- **Releases** - List of releases for the repository, with information and downloads
- **File Browser** - Browse directory trees and view and download file contents
- **Commits View** - View commit history with pagination
- **Commit Details** - Detailed commit information with file changes and diffs
- **Refs View** - List branches and tags
- **Statistics** - Activity charts showing views, fetches and pushes over time
All pages respect the same permission system used for Git access. If an identity does not have read access to a repository, they will not be able to view its pages.
## Formatting & Syntax Highlighting
If the `pygments` Python module is installed on your system, the page node will automatically apply syntax highlighting to code files. The highlighting supports a wide range of programming languages and uses a color theme optimized for terminal display.
To enable syntax highlighting, install pygments:
```text
pip install pygments
```
**Markdown & Micron Support**
README files and other Markdown documents are automatically converted to Micron markup for display in Nomad Network clients. You can also write your README files directly in Micron, in which case they will display and render as such in any Nomad Network client. The file browser also supports viewing both rendered and raw Markdown and Micron documents.
Code blocks in Markdown can include language hints for syntax highlighting:
```text
```python
def hello_world():
print("Hello, Reticulum!")
```
```
## Customizing Templates
The page node uses a template system that allows complete customization of the generated pages. Templates are stored in the `~/.rngit/templates/` directory as Micron files.
The following template files are supported:
- `base.mu` - Base template wrapping all pages
- `front.mu` - Front page listing all groups
- `group.mu` - Group page listing repositories
- `repo.mu` - Repository overview page
- `releases.mu` - Release list page
- `release.mu` - Release details page
- `tree.mu` - File browser pages
- `blob.mu` - File content display
- `commits.mu` - Commit history listing
- `commit.mu` - Individual commit detail page
- `refs.mu` - Branches and tags listing
- `stats.mu` - Statistics page
Templates can include the following variables:
- `{PAGE_CONTENT}` - The main content of the page (required)
- `{NODE_NAME}` - The configured node name
- `{NAVIGATION}` - Breadcrumb navigation links
- `{VERSION}` - The rngit version number
- `{GEN_TIME}` - Page generation time
**Dynamic Templates**
Templates can be made executable to generate dynamic content. If a template file has the executable bit set, it will be executed and its stdout used as the template content.
**Icon Sets**
By default, the page node uses Nerd Font icons. If you prefer simpler icons or your terminal does not support Nerd Fonts, you can enable Unicode icons instead:
```text
[pages]
serve_nomadnet = yes
unicode_icons = yes
```
**Repository Statistics**
When statistics recording is enabled (see the `record_stats` configuration option), the page node can display activity charts for each repository. The statistics page shows:
- Total and peak views, fetches and pushes
- Daily activity charts over a 90-day period
- Combined activity visualization
To view statistics, a user must have the `s` (stats) permission for the repository. See the Access Configuration section for details on setting permissions.
**Repository Thanks**
The page node includes a “Thanks” feature that allows users to express appreciation for a repository. On each repository page, a “Thanks” link is displayed showing the current thanks count. Clicking this link registers a thank you for the repository.
**Configuration Example**
A complete page node configuration might look like this:
```text
[rngit]
node_name = My Git Node
announce_interval = 360
record_stats = yes
[repositories]
public = /var/git/public
internal = /var/git/internal
[access]
public = r:all
internal = rw:9710b86ba12c42d1d8f30f74fe509286
[pages]
serve_nomadnet = yes
unicode_icons = no
```
## Release Management
In addition to hosting Git repositories, `rngit` provides a complete release management system. This allows you to publish versioned releases with associated artifacts, release notes and metadata. Releases are managed through the `rngit release` subcommand, and are also viewable through the Nomad Network page interface.
**The Release Workflow**
Creating a release involves specifying a Git tag and a directory containing build artifacts or other files to distribute. The `rngit` client will open your configured `$EDITOR` to compose release notes, then upload all artifacts to the remote repository node.
To create a release, specify the tag name and path to artifacts:
```text
$ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo create v1.2.0:./dist
```
This will:
1. Verify that the tag `v1.2.0` exists in the repository
2. Open your editor to write release notes
3. Upload all files from the `./dist` directory
4. Publish the release
If no `$EDITOR` environment variable is set, `rngit` will try to use `nano`, `vim` or `vi`. The editor will show a template with instructions. Lines starting with `#` will be ignored, and if the remaining content is empty after stripping comments, the release creation will be cancelled.
**Release Storage & Structure**
Releases are stored on the node in a directory named `repo_name.releases` next to the bare repository. Each release is a subdirectory containing:
- `META` - Release metadata in ConfigObj format
- `RELEASE.md` or `RELEASE.mu` - Release notes
- `artifacts/` - All uploaded files
- `THANKS` - Appreciation count from users
**Listing Releases**
To view all releases for a repository:
```text
$ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo list
Tag Status Created Objs Notes
------------------------------------------------------------------
v1.2.0 published 2025-01-15 14:32 3 Another release
v1.1.0 published 2024-12-03 09:15 2 Bug fix release
v1.0.0 published 2024-10-20 16:45 2 Initial release
```
**Viewing Release Details**
To see full information about a specific release:
```text
$ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo view v1.2.0
Release : 0.9.2
Status : published
Created : 2026-05-04 23:53:09
Thanks : 5
Release Notes
=============
Version 1.2.0 release notes...
Artifacts (4)
=============
- myapp-1.2.0.tar.gz (1.5 MB)
- myapp-1.2.0.zip (1.6 MB)
- checksums.txt (256 B)
```
**Deleting Releases**
To remove a release:
```text
$ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo delete v1.2.0
Are you sure you want to delete release 'v1.2.0'? [y/N]: y
Release v1.2.0 deleted
```
**Requirements & Validation**
- The specified tag must exist in the remote repository
- You must have `release` permission for the repository
- The target artifacts directory must exist and contain at least one file
- Release notes cannot be empty
**Permissions**
Release management requires the `release` permission, configured the same way as other repository permissions. In the config file or `.allowed` files, use `rel:target` to grant release management rights:
```text
# In .allowed file or config
rel:all # Allow everyone
rel:9710b86... # Allow specific identity
rel:none # Deny everyone
```
**Nomad Network Interface**
When the Nomad Network page node is enabled, releases are displayed on a dedicated releases page for each repository. Each release is listed with its tag, creation date, artifact count and a preview of the release notes. Clicking a release shows the full details including formatted release notes and a listing of all artifacts with their sizes.
Only releases with `published` status are visible through the Nomad Network interface. Draft releases (if supported in future implementations) would only be visible through the command-line interface.
**All Command-Line Options (rngit release)**
```text
usage: rngit release [-h] [--config CONFIG] [--rnsconfig RNSCONFIG]
[-i PATH] [-v] [-q] [--version]
[repository] [operation] [target]
Reticulum Git Release Manager
positional arguments:
repository URL of remote repository
operation list, view, create or delete
target tag and path to release artifacts directory
options:
-h, --help show this help message and exit
--config CONFIG path to alternative config directory
--rnsconfig RNSCONFIG
path to alternative Reticulum config directory
-i, --identity PATH path to release identity
-v, --verbose
-q, --quiet
--version show program's version number and exit
```
## Work Documents
In addition to releases, `rngit` provides a work document management system for tracking tasks, investigations, issues and progress related to repositories. Work documents are stored as structured msgpack data and support threaded updates and comments.
**Listing Work Documents**
To view work documents for a repository:
```text
$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo list
Active documents
=================
ID Title Author Created Comments
---------------------------------------------------------------------------
1 Implemented new feature 9710b86ba12c4f2e… 2025-01-15 14:32 3
2 Fixed bug in parser 8f3a21c9d84e927b… 2025-01-14 09:15 1
```
Use `--scope completed` to view completed work documents, or `--scope all` to see both active and completed.
**Viewing a Work Document**
To view a specific work document with all its comments:
```text
$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo view -d 1
Implement new feature (active #1)
=================================
Author : 9710b86ba12c42d1d8f30f74fe509286
Status : active
Created : 2026-05-05 15:11:11
Edited : 2026-05-05 18:22:11
Format : markdown
Updates : 0
This work document tracks the implementation of the new feature...
Updates
=======
#1 by 9710b86ba12c42d1d8f30f74fe509286 at 2026-05-05 15:38:37
-------------------------------------------------------------
Initial analysis complete
```
**Creating Work Documents**
To create a new work document:
```text
$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo create --title "Investigate performance issue"
```
This will open your configured `$EDITOR` to compose the document content. Save and exit to create the document, or save an empty document to cancel.
**Editing Work Documents**
To edit an existing work document:
```text
$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo edit -d 1
```
This fetches the current content, opens it in your editor, and sends any changes back to the node.
**Adding Comments**
To add an update to a work document:
```text
$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo update -d 1
```
This opens your editor to compose the update.
**Completing Work Documents**
To mark a work document as completed (moving it from `active` to `completed`):
```text
$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo complete -d 1
Work document #1 completed
```
**Activating Work Documents**
To mark a work document as active (moving it from `completed` to `active`):
```text
$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo activate -d 1
Work document #1 activated
```
**Deleting Work Documents**
To delete a work document and all its comments:
```text
$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo delete -id 1
Are you sure you want to delete active work document #1? [y/N]: y
Work document #1 deleted
```
**Permissions**
Users can view work documents and updates if the have `read` permission for the repository. If users have `read` and `interact`, they can also post updates/comments on existing work documents. Work document management requires having `write` and `interact` permission to the repository. These permissions are configured the same way as any other repository permissions. In the config file or `.allowed` files, use `i:target` to grant work document interaction rights:
```text
# In .allowed file or config
i:all # Allow everyone
i:9710b86... # Allow specific identity
i:none # Deny everyone
```
**Author Verification**
Users can only edit or delete work documents and updates they created. The author is cryptographically verified from the interacting link’s `remote_identity`.
**Storage Format**
Work documents are stored in a `repo_name.work` directory next to the repository, containing:
- `active/` - Active work documents
- `completed/` - Completed work documents
Each document is a numbered directory containing:
- `root` - The work document content and metadata (msgpack format)
- `N` - Numbered comment files (msgpack format)
**Nomad Network Interface**
When the Nomad Network page node is enabled, work documents are viewable through the web interface. The work page lists all documents with their status, and clicking a document shows its full content and updates.
**All Command-Line Options (rngit work)**
```text
usage: rngit work [-h] [--config CONFIG] [--rnsconfig RNSCONFIG]
[-i PATH] [--scope SCOPE] [-t TITLE] [-d ID] [-v]
[-q] [--version]
[repository] [operation]
Reticulum Git Work Document Manager
positional arguments:
repository URL of remote repository
operation list, view, create, edit, delete, update or complete
options:
-h, --help show this help message and exit
--config CONFIG path to alternative config directory
--rnsconfig RNSCONFIG
path to alternative Reticulum config directory
-i, --identity PATH path to identity
--scope SCOPE document scope: active, completed or all
-t, --title TITLE document title for create
-d, --id ID document ID
-v, --verbose
-q, --quiet
--version show program's version number and exit
```
docs/markdown/hardware.md
+311
View File
@@ -0,0 +1,311 @@
<a id="hardware-main"></a>
# Communications Hardware
One of the truly valuable aspects of Reticulum is the ability to use it over
almost any conceivable kind of communications medium. The [interface types](interfaces.md#interfaces-main)
available for configuration in Reticulum are flexible enough to cover the use
of most wired and wireless communications hardware available, from decades-old
packet radio modems to modern millimeter-wave backhaul systems.
If you already have or operate some kind of communications hardware, there is a
very good chance that it will work with Reticulum out of the box. In case it does
not, it is possible to provide the necessary glue with very little effort using
for example the [PipeInterface](interfaces.md#interfaces-pipe) or the [TCPClientInterface](interfaces.md#interfaces-tcpc)
in combination with code like [TCP KISS Server](https://github.com/simplyequipped/tcpkissserver)
by [simplyequipped](https://github.com/simplyequipped).
It is also very easy to write and load [custom interface modules](interfaces.md#interfaces-custom)
into Reticulum, allowing you to communicate with more or less anything you can think of.
While this broad support and flexibility is very useful, an abundance of options
can sometimes make it difficult to know where to begin, especially when you are
starting from scratch.
This chapter will outline a few different sensible starting paths to get
real-world functional wireless communications up and running with minimal cost
and effort. Two fundamental devices categories will be covered, *RNodes* and
*WiFi-based radios*. Additionally, other common options will be briefly described.
Knowing how to employ just a few different types of hardware will make it possible
to build a wide range of useful networks with little effort.
## Combining Hardware Types
It is useful to combine different link and hardware types when designing and
building a network. One useful design pattern is to employ high-capacity point-to-point
links based on WiFi or millimeter-wave radios (with high-gain directional antennas)
for the network backbone, and using LoRa-based RNodes for covering large areas with
connectivity for client devices.
<a id="rnode-main"></a>
## RNode
Reliable and general-purpose long-range digital radio transceiver systems are
commonly either very expensive, difficult to set up and operate, hard to source,
power-hungry, or all of the above at the same time. In an attempt to alleviate
this situation, the transceiver system *RNode* was designed. It is important to
note that RNode is not one specific device, from one particular vendor, but
*an open plaform* that anyone can use to build interoperable digital transceivers
suited to their needs and particular situations.
An RNode is a general purpose, interoperable, low-power and long-range, reliable,
open and flexible radio communications device. Depending on its components, it can
operate on many different frequency bands, and use many different modulation
schemes, but most commonly, and for the purposes of this chapter, we will limit
the discussion to RNodes using *LoRa* modulation in common ISM bands.
**Avoid Confusion!** RNodes can use LoRa as a *physical-layer modulation*, but it
does not use, and has nothing to do with the *LoRaWAN* protocol and standard, commonly
used for centrally controlled IoT devices. RNodes use *raw LoRa modulation*, without
any additional protocol overhead. All high-level protocol functionality is handled
directly by Reticulum.
<a id="rnode-creating"></a>
### Creating RNodes
RNode has been designed as a system that is easy to replicate across time and
space. You can put together a functioning transceiver using commonly available
components, and a few open source software tools. While you can design and build RNodes
completely from scratch, to your exact desired specifications, this chapter
will explain the easiest possible approach to creating RNodes: Using common
LoRa development boards. This approach can be boiled down to two simple steps:
1. Obtain one or more [supported development boards](#rnode-supported)
2. Install the RNode firmware with the [automated installer](#rnode-installation)
Once the firmware has been installed and provisioned by the install script, it
is ready to use with any software that supports RNodes, including Reticulum.
The device can be used with Reticulum by adding an [RNodeInterface](interfaces.md#interfaces-rnode)
to the configuration.
<a id="rnode-supported"></a>
### Supported Boards and Devices
To create one or more RNodes, you will need to obtain supported development
boards or completed devices. The following boards and devices are supported
by the auto-installer.
---
![image](graphics/board_tbeam_supreme.png)
#### LilyGO T-Beam Supreme
- **Transceiver IC** Semtech SX1262 or SX1268
- **Device Platform** ESP32
- **Manufacturer** [LilyGO](https://lilygo.cn)
---
![image](graphics/board_tbeam.png)
#### LilyGO T-Beam
- **Transceiver IC** Semtech SX1262, SX1268, SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** [LilyGO](https://lilygo.cn)
---
![image](graphics/board_t3s3.png)
#### LilyGO T3S3
- **Transceiver IC** Semtech SX1262, SX1268, SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** [LilyGO](https://lilygo.cn)
---
![image](graphics/board_rak4631.png)
#### RAK4631-based Boards
- **Transceiver IC** Semtech SX1262 or SX1268
- **Device Platform** nRF52
- **Manufacturer** [RAK Wireless](https://www.rakwireless.com)
---
![image](graphics/board_opencomxl.png)
#### OpenCom XL
- **Transceiver ICs** Semtech SX1262 and SX1280 (dual transceiver)
- **Device Platform** nRF52
- **Manufacturer** [Liberated Embedded Systems](https://liberatedsystems.co.uk/)
---
![image](graphics/board_rnodev2.png)
#### Unsigned RNode v2.x
- **Transceiver IC** Semtech SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** [unsigned.io](https://unsigned.io)
---
![image](graphics/board_t3v21.png)
#### LilyGO LoRa32 v2.1
- **Transceiver IC** Semtech SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** [LilyGO](https://lilygo.cn)
---
![image](graphics/board_t3v20.png)
#### LilyGO LoRa32 v2.0
- **Transceiver IC** Semtech SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** [LilyGO](https://lilygo.cn)
---
![image](graphics/board_t3v10.png)
#### LilyGO LoRa32 v1.0
- **Transceiver IC** Semtech SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** [LilyGO](https://lilygo.cn)
---
![image](graphics/board_tdeck.png)
#### LilyGO T-Deck
- **Transceiver IC** Semtech SX1262 or SX1268
- **Device Platform** ESP32
- **Manufacturer** [LilyGO](https://lilygo.cn)
---
![image](graphics/board_techo.png)
#### LilyGO T-Echo
- **Transceiver IC** Semtech SX1262 or SX1268
- **Device Platform** nRF52
- **Manufacturer** [LilyGO](https://lilygo.cn)
---
![image](graphics/board_t114.png)
#### Heltec T114
- **Transceiver IC** Semtech SX1262 or SX1268
- **Device Platform** nRF52
- **Manufacturer** [Heltec Automation](https://heltec.org)
---
![image](graphics/board_heltec32v4.png)
#### Heltec LoRa32 v4.0
- **Transceiver IC** Semtech SX1262
- **Device Platform** ESP32
- **Manufacturer** [Heltec Automation](https://heltec.org)
---
![image](graphics/board_heltec32v30.png)
#### Heltec LoRa32 v3.0
- **Transceiver IC** Semtech SX1262 or SX1268
- **Device Platform** ESP32
- **Manufacturer** [Heltec Automation](https://heltec.org)
---
![image](graphics/board_heltec32v20.png)
#### Heltec LoRa32 v2.0
- **Transceiver IC** Semtech SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** [Heltec Automation](https://heltec.org)
---
<a id="rnode-installation"></a>
### Installation
Once you have obtained compatible boards, you can install the [RNode Firmware](https://github.com/markqvist/RNode_Firmware)
using the [RNode Configuration Utility](https://github.com/markqvist/rnodeconfigutil).
If you have installed Reticulum on your system, the `rnodeconf` program will already be
available. If not, make sure that `Python3` and `pip` is installed on your system, and
then install Reticulum with with `pip`:
```default
pip install rns
```
Once installation has completed, it is time to start installing the firmware on your
devices. Run `rnodeconf` in auto-install mode like so:
```default
rnodeconf --autoinstall
```
The utility will guide you through the installation process by asking a series of
questions about your hardware. Simply follow the guide, and the utility will
auto-install and configure your devices.
<a id="rnode-usage"></a>
### Usage with Reticulum
When the devices have been installed and provisioned, you can use them with Reticulum
by adding the [relevant interface section](interfaces.md#interfaces-rnode) to the configuration
file of Reticulum. In the configuraion you can specify all interface parameters,
such as serial port and on-air parameters.
## WiFi-based Hardware
It is possible to use all kinds of both short- and long-range WiFi-based hardware
with Reticulum. Any kind of hardware that fully supports bridged Ethernet over the
WiFi interface will work with the [AutoInterface](interfaces.md#interfaces-auto) in Reticulum.
Most devices will behave like this by default, or allow it via configuration options.
This means that you can simply configure the physical links of the WiFi based devices,
and start communicating over them using Reticulum. It is not necessary to enable any IP
infrastructure such as DHCP servers, DNS or similar, as long as at least Ethernet is
available, and packets are passed transparently over the physical WiFi-based devices.
Below is a list of example WiFi (and similar) radios that work well for high capacity
Reticulum links over long distances:
- [Ubiquiti airMAX radios](https://store.ui.com/collections/operator-airmax-devices)
- [Ubiquiti LTU radios](https://store.ui.com/collections/operator-ltu)
- [MikroTik radios](https://mikrotik.com/products/group/wireless-systems)
This list is by no means exhaustive, and only serves as a few examples of radio hardware
that is relatively cheap while providing long range and high capacity for Reticulum
networks. As in all other cases, it is also possible for Reticulum to co-exist with IP
networks running concurrently on such devices.
## Ethernet-based Hardware
Reticulum can run over any kind of hardware that can provide a switched Ethernet-based
medium. This means that anything from a plain Ethernet switch, to fiber-optic systems,
to data radios with Ethernet interfaces can be used by Reticulum.
The Ethernet medium does not need to have any IP infrastructure such as DHCP servers
or routing set up, but in case such infrastructure does exist, Reticulum will simply
co-exist with.
To use Reticulum over Ethernet-based mediums, it is generally enough to use the included
[AutoInterface](interfaces.md#interfaces-auto). This interface also works over any kind of
virtual networking adapter, such as `tun` and `tap` devices in Linux.
## Serial Lines & Devices
Using Reticulum over any kind of raw serial line is also possible with the
[SerialInterface](interfaces.md#interfaces-serial). This interface type is also useful for
using Reticulum over communications hardware that provides a serial port interface.
## Packet Radio Modems
Any packet radio modem that provides a standard KISS interface over USB, serial or TCP
can be used with Reticulum. This includes virtual software modems such as
[FreeDV TNC](https://github.com/xssfox/freedv-tnc) and [Dire Wolf](https://github.com/wb2osz/direwolf).
docs/markdown/index.md
+232
View File
@@ -0,0 +1,232 @@
# Reticulum Network Stack Manual
This manual aims to provide you with all the information you need to
understand Reticulum, build networks or develop programs using it, or
to participate in the development of Reticulum itself.
* [What is Reticulum?](whatis.md)
* [Current Status](whatis.md#current-status)
* [Reference Implementation](whatis.md#reference-implementation)
* [What does Reticulum Offer?](whatis.md#what-does-reticulum-offer)
* [Where can Reticulum be Used?](whatis.md#where-can-reticulum-be-used)
* [Interface Types and Devices](whatis.md#interface-types-and-devices)
* [Getting Started Fast](gettingstartedfast.md)
* [Standalone Reticulum Installation](gettingstartedfast.md#standalone-reticulum-installation)
* [Resolving Dependency & Installation Issues](gettingstartedfast.md#resolving-dependency-installation-issues)
* [Try Using a Reticulum-based Program](gettingstartedfast.md#try-using-a-reticulum-based-program)
* [Using the Included Utilities](gettingstartedfast.md#using-the-included-utilities)
* [Creating a Network With Reticulum](gettingstartedfast.md#creating-a-network-with-reticulum)
* [Bootstrapping Connectivity](gettingstartedfast.md#bootstrapping-connectivity)
* [Finding Your Way](gettingstartedfast.md#finding-your-way)
* [Build Personal Infrastructure](gettingstartedfast.md#build-personal-infrastructure)
* [Mixing Strategies](gettingstartedfast.md#mixing-strategies)
* [Network Health & Responsibility](gettingstartedfast.md#network-health-responsibility)
* [Contributing to the Global Ret](gettingstartedfast.md#contributing-to-the-global-ret)
* [Connect to the Distributed Backbone](gettingstartedfast.md#connect-to-the-distributed-backbone)
* [Hosting Public Entrypoints](gettingstartedfast.md#hosting-public-entrypoints)
* [Connecting Reticulum Instances Over the Internet](gettingstartedfast.md#connecting-reticulum-instances-over-the-internet)
* [Adding Radio Interfaces](gettingstartedfast.md#adding-radio-interfaces)
* [Creating and Using Custom Interfaces](gettingstartedfast.md#creating-and-using-custom-interfaces)
* [Develop a Program with Reticulum](gettingstartedfast.md#develop-a-program-with-reticulum)
* [Platform-Specific Install Notes](gettingstartedfast.md#platform-specific-install-notes)
* [Android](gettingstartedfast.md#android)
* [ARM64](gettingstartedfast.md#arm64)
* [Debian Bookworm](gettingstartedfast.md#debian-bookworm)
* [MacOS](gettingstartedfast.md#macos)
* [OpenWRT](gettingstartedfast.md#openwrt)
* [Raspberry Pi](gettingstartedfast.md#raspberry-pi)
* [RISC-V](gettingstartedfast.md#risc-v)
* [Ubuntu Lunar](gettingstartedfast.md#ubuntu-lunar)
* [Windows](gettingstartedfast.md#windows)
* [Pure-Python Reticulum](gettingstartedfast.md#pure-python-reticulum)
* [Zen of Reticulum](zen.md)
* [The Illusion Of The Center](zen.md#the-illusion-of-the-center)
* [Fallacy Of The Cloud](zen.md#fallacy-of-the-cloud)
* [Decentralization Or Uncentralizability?](zen.md#decentralization-or-uncentralizability)
* [Death To The Address](zen.md#death-to-the-address)
* [Physics Of Trust](zen.md#physics-of-trust)
* [Hostile Environments](zen.md#hostile-environments)
* [Encryption Is Not A Feature](zen.md#encryption-is-not-a-feature)
* [Zero-Trust Architectures](zen.md#zero-trust-architectures)
* [Merits Of Scarcity](zen.md#merits-of-scarcity)
* [The Bandwidth Fallacy](zen.md#the-bandwidth-fallacy)
* [Cost Of A Byte](zen.md#cost-of-a-byte)
* [Flow & Time](zen.md#flow-time)
* [Liberation From Limits](zen.md#liberation-from-limits)
* [Sovereignty Through Infrastructure](zen.md#sovereignty-through-infrastructure)
* [A Carrier-Grade Fallacy](zen.md#a-carrier-grade-fallacy)
* [Personal Infrastructure](zen.md#personal-infrastructure)
* [The Ability To Disconnect](zen.md#the-ability-to-disconnect)
* [Identity and Nomadism](zen.md#identity-and-nomadism)
* [Portable Existence](zen.md#portable-existence)
* [Roaming Nodes](zen.md#roaming-nodes)
* [Announcing Presence](zen.md#announcing-presence)
* [Anchor In The Flow](zen.md#anchor-in-the-flow)
* [Ethics Of The Tool](zen.md#ethics-of-the-tool)
* [The Harm Principle](zen.md#the-harm-principle)
* [Public Domain Protocol](zen.md#public-domain-protocol)
* [Preserving Human Agency](zen.md#preserving-human-agency)
* [Design Patterns For Post-IP Systems](zen.md#design-patterns-for-post-ip-systems)
* [Store & Forward](zen.md#store-forward)
* [Naming Is Power](zen.md#naming-is-power)
* [The Interface Is The Medium](zen.md#the-interface-is-the-medium)
* [Emergent Patterns](zen.md#emergent-patterns)
* [Fabric Of The Independent](zen.md#fabric-of-the-independent)
* [The Work Is Finished](zen.md#the-work-is-finished)
* [Open Sky](zen.md#open-sky)
* [Programs Using Reticulum](software.md)
* [Programs & Utilities](software.md#programs-utilities)
* [Remote Shell](software.md#remote-shell)
* [Nomad Network](software.md#nomad-network)
* [RNS Page Node](software.md#rns-page-node)
* [Retipedia](software.md#retipedia)
* [Sideband](software.md#sideband)
* [MeshChatX](software.md#meshchatx)
* [MeshChat](software.md#meshchat)
* [Columba](software.md#columba)
* [Reticulum Relay Chat](software.md#reticulum-relay-chat)
* [RetiBBS](software.md#retibbs)
* [RBrowser](software.md#rbrowser)
* [Reticulum Network Telephone](software.md#reticulum-network-telephone)
* [LXST Phone](software.md#lxst-phone)
* [LXMFy](software.md#lxmfy)
* [LXMF Interactive Client](software.md#lxmf-interactive-client)
* [RNS FileSync](software.md#rns-filesync)
* [Micron Parser JS](software.md#micron-parser-js)
* [RNMon](software.md#rnmon)
* [Protocols](software.md#protocols)
* [LXMF](software.md#lxmf)
* [LXST](software.md#id17)
* [RRC](software.md#rrc)
* [Interface Modules & Connectivity Resources](software.md#interface-modules-connectivity-resources)
* [Using Reticulum on Your System](using.md)
* [Configuration & Data](using.md#configuration-data)
* [Included Utility Programs](using.md#included-utility-programs)
* [The rnsd Utility](using.md#the-rnsd-utility)
* [The rnstatus Utility](using.md#the-rnstatus-utility)
* [The rnid Utility](using.md#the-rnid-utility)
* [The rnpath Utility](using.md#the-rnpath-utility)
* [The rnprobe Utility](using.md#the-rnprobe-utility)
* [The rncp Utility](using.md#the-rncp-utility)
* [The rngit Utility](using.md#the-rngit-utility)
* [The rnx Utility](using.md#the-rnx-utility)
* [The rnsh Utility](using.md#the-rnsh-utility)
* [The rnodeconf Utility](using.md#the-rnodeconf-utility)
* [Discovering Interfaces](using.md#discovering-interfaces)
* [Remote Management](using.md#remote-management)
* [Blackhole Management](using.md#blackhole-management)
* [Local Blackhole Management](using.md#local-blackhole-management)
* [Automated List Sourcing](using.md#automated-list-sourcing)
* [Publishing Blackhole Lists](using.md#publishing-blackhole-lists)
* [Improving System Configuration](using.md#improving-system-configuration)
* [Fixed Serial Port Names](using.md#fixed-serial-port-names)
* [Reticulum as a System Service](using.md#reticulum-as-a-system-service)
* [Understanding Reticulum](understanding.md)
* [Motivation](understanding.md#motivation)
* [Goals](understanding.md#goals)
* [Introduction & Basic Functionality](understanding.md#introduction-basic-functionality)
* [Destinations](understanding.md#destinations)
* [Public Key Announcements](understanding.md#public-key-announcements)
* [Identities](understanding.md#understanding-identities)
* [Getting Further](understanding.md#getting-further)
* [Reticulum Transport](understanding.md#reticulum-transport)
* [Node Types](understanding.md#node-types)
* [The Announce Mechanism in Detail](understanding.md#the-announce-mechanism-in-detail)
* [Reaching the Destination](understanding.md#reaching-the-destination)
* [Resources](understanding.md#resources)
* [Network Identities](understanding.md#network-identities)
* [Conceptual Overview](understanding.md#conceptual-overview)
* [Current Usage](understanding.md#current-usage)
* [Future Implications](understanding.md#future-implications)
* [Creating and Using a Network Identity](understanding.md#creating-and-using-a-network-identity)
* [Reference Setup](understanding.md#reference-setup)
* [Protocol Specifics](understanding.md#protocol-specifics)
* [Packet Prioritisation](understanding.md#packet-prioritisation)
* [Interface Access Codes](understanding.md#interface-access-codes)
* [Wire Format](understanding.md#wire-format)
* [Announce Propagation Rules](understanding.md#announce-propagation-rules)
* [Cryptographic Primitives](understanding.md#cryptographic-primitives)
* [Communications Hardware](hardware.md)
* [Combining Hardware Types](hardware.md#combining-hardware-types)
* [RNode](hardware.md#rnode)
* [Creating RNodes](hardware.md#creating-rnodes)
* [Supported Boards and Devices](hardware.md#supported-boards-and-devices)
* [Installation](hardware.md#installation)
* [Usage with Reticulum](hardware.md#usage-with-reticulum)
* [WiFi-based Hardware](hardware.md#wifi-based-hardware)
* [Ethernet-based Hardware](hardware.md#ethernet-based-hardware)
* [Serial Lines & Devices](hardware.md#serial-lines-devices)
* [Packet Radio Modems](hardware.md#packet-radio-modems)
* [Configuring Interfaces](interfaces.md)
* [Custom Interfaces](interfaces.md#custom-interfaces)
* [Auto Interface](interfaces.md#auto-interface)
* [Backbone Interface](interfaces.md#backbone-interface)
* [Listeners](interfaces.md#listeners)
* [Connecting Remotes](interfaces.md#connecting-remotes)
* [TCP Server Interface](interfaces.md#tcp-server-interface)
* [TCP Client Interface](interfaces.md#tcp-client-interface)
* [UDP Interface](interfaces.md#udp-interface)
* [I2P Interface](interfaces.md#i2p-interface)
* [RNode LoRa Interface](interfaces.md#rnode-lora-interface)
* [RNode Multi Interface](interfaces.md#rnode-multi-interface)
* [Serial Interface](interfaces.md#serial-interface)
* [Pipe Interface](interfaces.md#pipe-interface)
* [KISS Interface](interfaces.md#kiss-interface)
* [AX.25 KISS Interface](interfaces.md#ax-25-kiss-interface)
* [Discoverable Interfaces](interfaces.md#discoverable-interfaces)
* [Enabling Discovery](interfaces.md#enabling-discovery)
* [Discovery Parameters](interfaces.md#discovery-parameters)
* [Interface Modes](interfaces.md#interface-modes)
* [Security Considerations](interfaces.md#security-considerations)
* [Example Configuration](interfaces.md#example-configuration)
* [Common Interface Options](interfaces.md#common-interface-options)
* [Interface Modes](interfaces.md#interfaces-modes)
* [Announce Rate Control](interfaces.md#announce-rate-control)
* [New Destination Rate Limiting](interfaces.md#new-destination-rate-limiting)
* [Building Networks](networks.md)
* [Concepts & Overview](networks.md#concepts-overview)
* [Introductory Considerations](networks.md#introductory-considerations)
* [Destinations, Not Addresses](networks.md#destinations-not-addresses)
* [Transport Nodes and Instances](networks.md#transport-nodes-and-instances)
* [Trustless Networking](networks.md#trustless-networking)
* [Heterogeneous Connectivity](networks.md#heterogeneous-connectivity)
* [Git Over Reticulum](git.md)
* [The rngit Utility](git.md#the-rngit-utility)
* [Repository Structure](git.md#repository-structure)
* [Serving Pages Over Nomad Network](git.md#serving-pages-over-nomad-network)
* [Formatting & Syntax Highlighting](git.md#formatting-syntax-highlighting)
* [Customizing Templates](git.md#customizing-templates)
* [Release Management](git.md#release-management)
* [Work Documents](git.md#work-documents)
* [Support Reticulum](support.md)
* [Donations](support.md#donations)
* [Provide Feedback](support.md#provide-feedback)
* [Code Examples](examples.md)
* [Minimal](examples.md#minimal)
* [Announce](examples.md#announce)
* [Broadcast](examples.md#broadcast)
* [Echo](examples.md#echo)
* [Link](examples.md#link)
* [Identification](examples.md#example-identify)
* [Requests & Responses](examples.md#requests-responses)
* [Channel](examples.md#channel)
* [Buffer](examples.md#buffer)
* [Filetransfer](examples.md#filetransfer)
* [Custom Interfaces](examples.md#custom-interfaces)
* [Reticulum License](license.md)
* [API Reference](reference.md)
* [`Reticulum`](reference.md#RNS.Reticulum)
* [`Identity`](reference.md#RNS.Identity)
* [`Destination`](reference.md#RNS.Destination)
* [`Packet`](reference.md#RNS.Packet)
* [`PacketReceipt`](reference.md#RNS.PacketReceipt)
* [`Link`](reference.md#RNS.Link)
* [`RequestReceipt`](reference.md#RNS.RequestReceipt)
* [`Resource`](reference.md#RNS.Resource)
* [`Channel`](reference.md#RNS.Channel.Channel)
* [`MessageBase`](reference.md#RNS.MessageBase)
* [`Buffer`](reference.md#RNS.Buffer)
* [`RawChannelReader`](reference.md#RNS.RawChannelReader)
* [`RawChannelWriter`](reference.md#RNS.RawChannelWriter)
* [`Transport`](reference.md#RNS.Transport)
docs/markdown/interfaces.md
+1384
View File
File diff suppressed because it is too large Load Diff
docs/markdown/license.md
+35
View File
@@ -0,0 +1,35 @@
<a id="license"></a>
# Reticulum License
```text
Reticulum License
Copyright (c) 2016-2026 Mark Qvist
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
- The Software shall not be used in any kind of system which includes amongst
its functions the ability to purposefully do harm to human beings.
- The Software shall not be used, directly or indirectly, in the creation of
an artificial intelligence, machine learning or language model training
dataset, including but not limited to any use that contributes to the
training or development of such a model or algorithm.
- The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
docs/markdown/networks.md
+322
View File
@@ -0,0 +1,322 @@
<a id="networks-main"></a>
# Building Networks
This chapter will provide you with the high-level knowledge needed to build networks with
Reticulum. It will not, however tell you all you need to know to succesfully
design and configure every kind of network you can imagine. For this, you will
most likely need to read this manual in its entirity, invest significant time
into experimenting with the stack, and learning functionality intuitively.
Still, after reading this chapter, you should be well equipped to *start* that
journey. While Reticulum is **fundamentally different** compared to other
networking technologies, it can often be easier than using traditional stacks.
If you’ve built networks before, you will probably have to forget, or at least
temporarily ignore, a lot of things at this point. It will all makes sense in
the end though. Hopefully.
If you’re used to protocols like IP, let’s at least start with some relief:
You don’t have to worry about coordinating addresses, subnets and routing for an
entire network that you might not know how will evolve in the future. With
Reticulum, you can simply add more segments to your network when it becomes
necessary, and Reticulum will handle the convergence of the entire network
automatically. There’s plenty more neat aspects like that to Reticulum, but
we’re getting ahead of ourselves. Let’s cover the basics first.
## Concepts & Overview
Before you start building your own networks, it’s important to understand the
fundamental principles that distinguish Reticulum networks from traditional
networking approaches. These principles shape how you design your network,
what trade-offs you encounter, and what capabilities you can rely on.
Reticulum is not a single network you “join”, it is a toolkit for *creating* networks.
You decide what mediums to use, how nodes connect, what trust boundaries exist,
and what the network’s purpose is. Reticulum provides the cryptographic foundation,
the transport mechanisms, and the convergence algorithms that make your design
workable. You provide the intent and the structure.
This approach offers tremendous flexibility, but it requires thinking in terms of
different abstractions than those used in conventional networking.
### Introductory Considerations
There are important points that need to be kept in mind when building networks
with Reticulum:
> * In a Reticulum network, any node can autonomously generate as many addresses
> (called *destinations* in Reticulum terminology) as it needs, which become
> globally reachable to the rest of the network. There is no central point of
> control over the address space.
> <br/>
> * Reticulum was designed to handle both very small, and very large networks.
> While the address space can support billions of endpoints, Reticulum is
> also very useful when just a few devices needs to communicate.
> <br/>
> * Low-bandwidth networks, like LoRa and packet radio, can interoperate and
> interconnect with much larger and higher bandwidth networks without issue.
> Reticulum automatically manages the flow of information to and from various
> network segments, and when bandwidth is limited, local traffic is prioritised.
> You will, however, need to configure your interfaces correctly. If you tell
> Reticulum to pass all announce traffic from a gigabit link to a LoRa interfaces,
> it will try as best as possible to comply with this, while still respecting
> bandwidth limits, but you *will* waste a lot of precious bandwidth and airtime,
> and your LoRa network will not work very well.
> <br/>
> * Reticulum provides sender/initiator anonymity by default. There is no way
> to filter traffic or discriminate it based on the source of the traffic.
> <br/>
> * All traffic is encrypted using ephemeral keys generated by an Elliptic Curve
> Diffie-Hellman key exchange on Curve25519. There is no way to inspect traffic
> contents, and no way to prioritise or throttle certain kinds of traffic.
> All transport and routing layers are thus completely agnostic to traffic type,
> and will pass all traffic equally.
> <br/>
> * Reticulum can function both with and without infrastructure. When *transport
> nodes* are available, they can route traffic over multiple hops for other
> nodes, and will function as a distributed cryptographic keystore. When there
> is no transport nodes available, all nodes that are within communication range
> can still communicate.
> <br/>
> * Every node can become a transport node, simply by enabling it in it’s
> configuration, but there is no need for every node on the network to be a
> transport node. Letting every node be a transport node will in most cases
> degrade the performance and reliability of the network.
> <br/>
> > *In general terms, if a node is stationary, well-connected and kept running
> > most of the time, it is a good candidate to be a transport node. For optimal
> > performance, a network should contain the amount of transport nodes that
> > provides connectivity to the intended area / topography, and not many more
> > than that.*
> * Reticulum is designed to work reliably in open, trustless environments. This
> means you can use it to create open-access networks, where participants can
> join and leave in a free and unorganised manner. This property allows an
> entirely new, and so far, mostly unexplored class of networked applications,
> where networks, and the information flow within them can form and dissolve
> organically.
> <br/>
> * You can just as easily create closed networks, since Reticulum allows you to
> add authentication to any interface. This means you can restrict access on
> any interface type, even when using legacy devices, such as modems. You can
> also mix authenticated and open interfaces on the same system. See the
> [Common Interface Options](interfaces.md#interfaces-options) section of the [Interfaces](interfaces.md#interfaces-main)
> chapter of this manual for information on how to set up interface authentication.
> <br/>
Reticulum allows you to mix very different kinds of networking mediums into a
unified mesh, or to keep everything within one medium. You could build a “virtual
network” running entirely over the Internet, where all nodes communicate over TCP
and UDP “channels”. You could also build such a network using other already-established
communications channels as the underlying carrier for Reticulum.
However, most real-world networks will probably involve either some form of
wireless or direct hardline communications. To allow Reticulum to communicate
over any type of medium, you must specify it in the configuration file, by default
located at `~/.reticulum/config`. See the [Supported Interfaces](interfaces.md#interfaces-main)
chapter of this manual for interface configuration examples.
Any number of interfaces can be configured, and Reticulum will automatically
decide which are suitable to use in any given situation, depending on where
traffic needs to flow.
### Destinations, Not Addresses
In traditional networking, addresses are allocated from a managed space. If you want to
communicate with another node, you need to know its address, and that address
must be unique within the network segment. This requires coordination, either
through manual assignment, DHCP servers, or other allocation mechanisms.
Reticulum replaces addresses with **destinations**. A destination is identified by a 16-byte
hash (128 bits) derived from a SHA-256 hash of the destination’s identifying
characteristics. This hash serves as the address on the network. On the network, it
is represented in binary, but when displayed to human users, it will usually look something like
this `<13425ec15b621c1d928589718000d814>`.
The critical difference is that *any node can generate as many destinations as it
needs, without coordination*. A destination’s uniqueness is guaranteed by the
collision resistance of SHA-256 and the inclusion of the node’s public key in the
hash calculation. Two nodes can both use the destination name
`messenger.user.inbox`, but they will have different destination hashes because
their public keys differ. Both can coexist on the same network without conflict.
This has profound implications for network design:
* **No address allocation planning:** You never need to reserve address ranges,
plan subnets, or coordinate with other network operators. Nodes simply generate
destinations and announce them.
* **Global portability:** A destination is not tied to a physical location or
network segment. A node can move its destinations across interfaces, mediums,
or even between entirely separate Reticulum networks simply by sending an
announce on the new medium.
* **Implicit authentication:** Because destinations are bound to public keys,
communication to a destination is inherently cryptographically authenticated.
Only the holder of the corresponding private key can decrypt and respond to
traffic addressed to that destination. This also makes application-level
authentication *much* simpler, since it can directly use the foundational
identity verification built into the core networking layer.
* **Identity abstraction:** A single Reticulum Identity can create multiple
destinations. This allows a single entity (a person, a device, a service) to
present multiple endpoints without needing multiple cryptographic keypairs.
### Transport Nodes and Instances
Reticulum distinguishes between two types of nodes: **Instances**
and **Transport Nodes**. Every node running Reticulum is an Instance, but not
every Instance is a Transport Node.
A **Reticulum Instance** is any system running the Reticulum stack. It can create
destinations, send and receive packets, establish links, and communicate with
other nodes. It can also host destinations that are connectable for *anyone* else
in the network. This means you can easily host globally available services from
any location, including your home or office. Network-wide, global connectivity
for all destinations is guaranteed, as long as there is *some* physical way to
actually transport the packets. Instances are the default state and are appropriate for most end-user devices,
such as phones, laptops, sensors, or any device that primarily consumes network services.
A **Transport Node** is an Instance that has been explicitly configured to
participate in network-wide transport. Transport nodes forward packets across
hops, propagate announces, maintain path tables, and serve path requests on
behalf of other nodes. When a destination sends an announce, Transport Nodes
receive it, remember the path, and rebroadcast it to other interfaces. When a node
needs to reach a destination it doesn’t have a path for, Transport Nodes help
resolve the path through the network.
Even devices hosting services or serving content should probably just be configured
as instances, and themselves connect to wider networks via a Transport Node.
In some situations, this may not be practical though, and as an example, it is
entirely viable to host a personal Transport Node on a Raspberry Pi, while it
is at the same time running an LXMF propagation node, and hosting your personal
site or files over Reticulum.
The distinction is important. **Not** every node should be a Transport Node:
* **Resource consumption:** Transport nodes maintain path tables, process
announces, and forward traffic. This requires memory and CPU resources that
may be limited on low-powered devices.
* **Stability requirements:** Transport nodes contribute to network convergence.
If Transport Nodes frequently go offline, path tables become stale and
convergence suffers. Stable, always-on nodes make better Transport Nodes.
* **Bandwidth considerations:** Transport nodes process and rebroadcast network
maintenance traffic. On very low-bandwidth mediums, having too many Transport
Nodes will consume capacity that should be used for actual data.
In practice, a network typically has a relatively small number of Transport Nodes
strategically placed to provide coverage and connectivity. End-user devices run
as Instances, connecting through nearby Transport Nodes to reach the wider network.
This pattern mirrors traditional networking where routers forward traffic while
end hosts simply consume connectivity, but with the crucial difference that any
node *can* become a router if needed, and the decision is yours to make based on
your network’s requirements.
Transport nodes also function as distributed cryptographic keystores. When a
destination announces itself, Transport Nodes cache the public key and destination
information. Other nodes can request unknown public keys from the network, and
Transport Nodes respond with the cached information. This eliminates the need for
a central directory service while ensuring that public keys remain available
throughout the network.
### Trustless Networking
Traditional network security models assume high levels of trust at
specific layers. You might trust your ISP to deliver packets without inspection,
or trust your VPN provider to handle your traffic, or trust the network
administrator to configure firewalls appropriately. These trust relationships
create vulnerabilities and dependencies.
Reticulum is designed to function in **open, trustless environments**. This
means the protocol makes no assumptions about the trustworthiness of the network
infrastructure, the other participants, or the transport mediums. Every aspect
of communication is secured cryptographically:
* **Traffic encryption:** All traffic to single destinations is encrypted using
ephemeral keys.
* **Source anonymity:** Reticulum packets do not include source addresses.
An observer intercepting a packet cannot determine who sent it, only who it is
addressed to (unless IFAC is enabled, in which case nothing can be determined).
This provides initiator anonymity by default.
* **Path verification:** The announce mechanism includes cryptographic signatures that
prove the authenticity of destination announcements.
* **Unforgeable delivery confirmations:** When a destination proves receipt of a
packet, the proof is signed with the destination’s identity key. This prevents
false acknowledgments and ensures reliable delivery verification.
* **Interface authentication:** When using Interface Access Codes (IFAC), packets
on authenticated interfaces carry signatures derived from a shared secret. Only
nodes with the correct network name and passphrase can generate valid packets, allowing creation
of virtual private networks on shared mediums.
The trustless design has important consequences for network design:
* **Open-access networks are viable:** You can build networks that anyone can
join without pre-approval. Because traffic is encrypted and authenticated end-
to-end, participants cannot interfere with each other’s private communication,
even if they share the same transport infrastructure.
* **No traffic inspection or prioritization:** Because traffic contents and
sources are opaque to intermediate nodes, there is no mechanism for filtering,
prioritizing, or throttling traffic based on its type or origin. All traffic
is treated equally. From a neutrality perspective, this is a feature.
* **Adversarial resilience:** The network can operate even if some nodes are
malicious or controlled by adversaries. While a malicious Transport Node could
refuse to forward certain traffic or drop packets, it cannot decrypt, modify,
or impersonate legitimate traffic. Redundant paths and multiple Transport Nodes
mitigate the impact of malicious nodes.
Of course, you can also create closed networks. Interface Access
Codes allow you to restrict participation on specific interfaces. Network
Identities enable you to verify that discovered interfaces belong to trusted
operators. Blackhole management lets you block malicious identities. Reticulum
provides both the tools for open networks and the controls for closed ones. The
choice is yours based on your requirements.
### Heterogeneous Connectivity
In conventional networking, mixing different transport mediums typically requires
gateways, translation layers, and careful configuration. A WiFi network doesn’t
natively interoperate with a packet radio network without additional infrastructure,
and you can’t just download a car over a serial port, or send an encrypted message
in a QR code.
Reticulum treats **heterogeneity as a core premise**. The protocol is designed
to seamlessly mix mediums with vastly different characteristics:
* **Bandwidth:** LoRa links operating at a few hundred bits per second can
interconnect with gigabit Ethernet backbones. Reticulum automatically manages
the flow of information, prioritizing local traffic on slow segments while
allowing global convergence.
* **Latency:** Satellite links with multi-second latency can coexist with local
links measured in milliseconds. The transport system handles timing, asynchronous
delivery and retransmissions transparently.
* **Topology:** Point-to-point microwave links, broadcast radio networks,
switched Ethernet fabrics, and virtual tunnels over the Internet can all be
part of the same Reticulum network.
* **Reliability:** Intermittent connections that come and go (such as mobile
devices or opportunistic radio contacts) can participate alongside always-on
infrastructure. Reticulum gracefully handles link loss and reconnection.
This heterogeneity is achieved through several design elements:
* **Expandable, medium-agnostic interface system:** Reticulum communicates with the physical
world through interface modules. Adding support for a new medium is a matter
of implementing an interface class. The protocol itself remains unchanged.
* **Interface modes:** Different modes (`full`, `gateway`, `access_point`,
`roaming`, `boundary`) allow you to configure how interfaces interact with
the wider network based on their characteristics and role.
* **Announce propagation rules:** Announces are forwarded between interfaces
according to rules that account for bandwidth limitations and interface modes.
Slow segments are not overwhelmed by traffic from fast segments.
* **Local traffic prioritization:** When bandwidth is constrained, Reticulum
prioritizes announces for nearby destinations. This ensures that local
connectivity remains functional even when global convergence is incomplete.
For network designers, this means you are free to use whatever mediums are
available, affordable, or appropriate for your situation. You might use LoRa for
wide-area low-bandwidth coverage, WiFi for local high-capacity links, I2P for
anonymous Internet connectivity, and Ethernet for infrastructure backhauls, all
within the same network. Reticulum handles the translation and coordination
automatically.
The key design consideration is not whether different mediums can work together
(they can), but **how** they should work together based on your goals. A node
with multiple interfaces spanning heterogeneous mediums needs to be configured
with appropriate interface modes so that traffic flows efficiently. A gateway
connecting a slow LoRa segment to a fast Internet backbone should be configured
differently than a mobile device roaming between radio cells.
docs/markdown/reference.md
+1323
View File
File diff suppressed because it is too large Load Diff
docs/markdown/software.md
+201
View File
@@ -0,0 +1,201 @@
<a id="software-main"></a>
# Programs Using Reticulum
This chapter provides a non-exhaustive list of notable programs, systems and application-layer
protocols that have been built using Reticulum.
These programs will let you get a feel for how Reticulum works. Most of them have been designed
to run well even over slow networks based on LoRa or packet radio, but all can also be used over fast
links, such as local WiFi, wired Ethernet, the Internet, or any combination.
As such, it is easy to get started experimenting, without having to set up any radio
transceivers or infrastructure just to try it out. Launching the programs on separate
devices connected to the same WiFi network is enough to get started, and physical
radio interfaces can then be added later.
## Programs & Utilities
Many different applications using Reticulum already exist, serving a wide variety of purposes
from day-to-day communication and information sharing to systems administration and tackling
advanced networking and communications challenges.
Development of Reticulum-based applications and systems is ongoing, so consider this list
a non-exhaustive starting point of *some* of the options available. With a bit of searching,
primarily over Reticulum itself, you will find many more interesting things.
### Remote Shell
The [rnsh](https://github.com/acehoss/rnsh) program lets you establish fully interactive
remote shell sessions over Reticulum. It also allows you to pipe any program to or from a
remote system, and is similar to how `ssh` works. The `rnsh` program is very efficient, and
can facilitate fully interactive shell sessions, even over extremely low-bandwidth links,
such as LoRa or packet radio.
In addition to the default, fully interactive terminal mode,
for extremely limited links, `rnsh` offers line-interactive mode, allowing you to interact
with remote systems, even when link throughput is counted in a few hundreds of bits per second.
\\newpage
### Nomad Network
The terminal-based program [Nomad Network](https://github.com/markqvist/nomadnet)
provides a complete encrypted communications suite built with Reticulum. It features
encrypted messaging (both direct and delayed-delivery for offline users), file sharing,
and has a built-in text-browser and page server with support for dynamically rendered pages,
user authentication and more.
[![image](screenshots/nomadnet_3.png)](https://github.com/markqvist/nomadnet)
[Nomad Network](https://github.com/markqvist/nomadnet) is a user-facing client
for the messaging and information-sharing protocol LXMF.
### RNS Page Node
[RNS Page Node](https://git.quad4.io/RNS-Things/rns-page-node) is a simple way to serve pages and files to any other Nomad Network compatible client. Drop-in replacement for NomadNet nodes that primarily serve pages and files.
### Retipedia
You can host the entirity of Wikipedia (or any `.zim`) file to other Nomad Network clients using [Retipedia](https://github.com/RFnexus/Retipedia).
\\newpage
### Sideband
If you would rather use an LXMF client with a graphical user interface, you can take
a look at [Sideband](https://unsigned.io/sideband), which is available for Android,
Linux, macOS and Windows. Sideband is an advanced LXMF and LXST client, and a multi-purpose Reticulum
utility, with features and functionality targeted at advanced users.
Sideband allows you to communicate with other people or LXMF-compatible
systems over Reticulum networks using LoRa, Packet Radio, WiFi, I2P, Encrypted QR
Paper Messages, or anything else Reticulum supports.
It also interoperates with all other LXMF clients, and provides advanced features such as voice messaging,
real-time voice calls, file attachments, private telemetry sharing, and a full
plugin system for expandability.
\\newpage
### MeshChatX
A [Reticulum MeshChat fork from the future](https://git.quad4.io/RNS-Things/MeshChatX), with the goal of providing everything you need for Reticulum, LXMF, and LXST in one beautiful and feature-rich application. This project is separate from the original Reticulum MeshChat project, and is not affiliated with the original project.
Features include full LXST support, custom voicemail, phonebook, contact sharing, and ringtone support, multi-identity handling, modern UI/UX, offline documentation, expanded tools, page archiving, integrated maps, telemetry and improved application security.
\\newpage
### MeshChat
The [Reticulum MeshChat](https://github.com/liamcottle/reticulum-meshchat) application
is a user-friendly LXMF client for Linux, macOS and Windows, that also includes a Nomad Network
page browser and other interesting functionality.
Reticulum MeshChat is of course also compatible with Sideband and Nomad Network, or
any other LXMF client.
### Columba
[Columba](https://github.com/torlando-tech/columba/) is a simple and familiar LXMF
messaging app Android, built with a native Android interface and Material Design 3.
While still in early and very active development, it is of course also compatible
with all other LXMF clients, and allows you to message seamlessly with anyone else
using LXMF.
\\newpage
### Reticulum Relay Chat
[Reticulum Relay Chat](https://rrc.kc1awv.net/) is a live chat system built on top of the Reticulum Network Stack. It exists to let people talk to each other in real time over Reticulum without dragging in message databases, synchronization engines, or architectural commitments they did not ask for.
The [rrcd](https://github.com/kc1awv/rrcd) program provides a functional, reference RRC hub-server daemon implementation. RRC user clients include [rrc-gui](https://github.com/kc1awv/rrc-gui) and [rrc-web](https://github.com/kc1awv/rrc-web).
RRC is closer in spirit to IRC than to modern “everything platforms.” You connect, you join a room, you talk, and then you leave. If you were present, you saw the conversation. If you were not, the conversation did not wait for you. This is not an accident. This is the entire design.
### RetiBBS
[RetiBBS](https://github.com/kc1awv/RetiBBS) is a bulletin board system implementation for Reticulum networks.
RetiBBS allows users to communicate through message boards in a secure manner.
\\newpage
### RBrowser
The [rBrowser](https://github.com/fr33n0w/rBrowser) program is a cross-platform, standalone, web-based browser for exploring NomadNetwork Nodes over Reticulum Network. It automatically discovers NomadNet nodes through network announces and provides a user-friendly interface for browsing distributed content with Micron markup support.
Includes useful features like automatic listening for announce, adding nodes to favorites, browsing and rendering any kind of NomadNet links, downloading files from remote nodes, a unique local NomadNet Search Engine and more.
\\newpage
### Reticulum Network Telephone
The `rnphone` program, included as part of the [LXST](https://github.com/markqvist/LXST) package is a command-line Reticulum telephone utility and daemon, that allows building physical, hardware telephones for LXST and Reticulum, as well as simply performing calls via the command line.
It supports interfacing directly with hardware peripherals such as GPIO keypads and LCD displays, providing a modular system for building secure hardware telephones.
\\newpage
### LXST Phone
The [LXST Phone](https://github.com/kc1awv/lxst_phone) program is a cross-platform desktop application for performing LXST voice calls over Reticulum.
It supports various advanced features such as SAS verification, peer blocking, rate limiting, encrypted call history storage and contact management.
\\newpage
### LXMFy
[LXMFy](https://lxmfy.quad4.io/) is a comprehensive and advanced bot creation framework for LXMF, that allows building any kind of automation or bot system running over LXMF and Reticulum. [Bot implementations exist](https://github.com/lxmfy/awesome-lxmfy-bots) for Home Assistant control, LLM integrations, and various other purposes.
### LXMF Interactive Client
[LXMF Interactive Client](https://github.com/fr33n0w/lxmf-cli) is a feature-rich, terminal-based LXMF messaging client with many advanced features and an extensible plugin architecture.
### RNS FileSync
The [RNS FileSync](https://git.quad4.io/RNS-Things/RNS-Filesync) program enables automatic file synchronization between devices without requiring central servers, internet connectivity, or cloud services. It works over any network medium supported by Reticulum, including radio, LoRa, WiFi, or the internet, making it ideal for off-grid, privacy-focused, and resilient file sharing.
### Micron Parser JS
[Micron Parser JS](https://github.com/RFnexus/micron-parser-js) is the JavaScript-based parser for the Micron markup language, that most web-based Nomad Network browsers use. If you want to make utilities or tools that display Micron pages, this library is essential.
### RNMon
[RNMon](https://github.com/lbatalha/rnmon) is a monitoring daemon designed to monitor the status of multiple RNS applications and push the metrics to an InfluxDB instance over the influx line protocol.
\\newpage
## Protocols
A number of standard protocols have emerged through real-world usage and testing in the Reticulum community. While you may sometimes want to use completely custom protocols and implementations when writing Reticulum-based software, using these protocols provides application developers with an easy way to implement advanced functionality quickly and effortlessly. Using them also ensures compatibility and interoperability between many different client applications, creating an open communications ecosystem where users are free to choose the applications that suit their needs, while remaining connected to everyone else.
### LXMF
[LXMF](https://github.com/markqvist/lxmf) is a simple and flexible messaging format and delivery protocol that allows a wide variety of applications, while using as little bandwidth as possible. It offers zero-conf message routing, end-to-end encryption and Forward Secrecy, and can be transported over any kind of medium that Reticulum supports.
LXMF is efficient enough that it can deliver messages over extremely low-bandwidth systems such as packet radio or LoRa. Encrypted LXMF messages can also be encoded as QR-codes or text-based URIs, allowing completely analog paper message transport.
Using Propagation Nodes, LXMF also offer a way to store and forward messages to users or endpoints that are not directly reachable at the time of message emission.
### LXST
[LXST](https://github.com/markqvist/lxst) is a simple and flexible real-time streaming format and delivery protocol that allows a wide variety of applications, while using as little bandwidth as possible. It is built on top of Reticulum and offers zero-conf stream routing, end-to-end encryption and Forward Secrecy, and can be transported over any kind of medium that Reticulum supports. It currently powers real-time voice and telephony applications over Reticulum.
### RRC
The [Reticulum Relay Chat](https://rrc.kc1awv.net/) protocol, is a live chat system built on top of the Reticulum Network Stack. It exists to provide near real-time group communication without dragging in message history databases, federation machinery, or architectural guilt.
RRC is intentionally simple. It does not pretend to be email, a mailbox, or a distributed archive. It behaves more like a conversation in a room. If you were there, you heard it. If you were not, you did not. That is not a bug, that is the point.
## Interface Modules & Connectivity Resources
This section provides a list of various community-provided interface modules, guides and resources for creating Reticulum networks over special or challenging mediums.
* Custom interface module for running [RNS over HTTP](https://git.quad4.io/RNS-Things/RNS-over-HTTP)
* Guide for running [Reticulum over ICMP](https://github.com/matvik22000/rns-over-icmp) using `PipeInterface`
* Guide for running [Reticulum over DNS](https://github.com/markqvist/Reticulum/discussions/1002) with Iodine
* Guide for running [Reticulum over HF radio](https://github.com/RFnexus/reticulum-over-hf)
* [Modem73](https://github.com/RFnexus/modem73) is a KISS TNC OFDM modem frontend that can be used with Reticulum
docs/markdown/support.md
+57
View File
@@ -0,0 +1,57 @@
<a id="support-main"></a>
# Support Reticulum
You can help support the continued development of open, free and private communications
systems by donating, providing feedback and contributing code and learning resources.
## Donations
Donations are gratefully accepted via the following channels:
```text
Monero:
84FpY1QbxHcgdseePYNmhTHcrgMX4nFfBYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD19b3B8NiLCGVxzKV17UMmmeEsCrPyA5w
Bitcoin:
bc1pgqgu8h8xvj4jtafslq396v7ju7hkgymyrzyqft4llfslz5vp99psqfk3a6
Ethereum:
0x91C421DdfB8a30a49A71d63447ddb54cEBe3465E
Liberapay:
https://liberapay.com/Reticulum/
Ko-Fi:
https://ko-fi.com/markqvist
```
Are certain features in the development roadmap are important to you or your
organisation? Make them a reality quickly by sponsoring their implementation.
## Provide Feedback
Feedback on the usage, functioning and potential dysfunctioning of any and
all components of the system is very valuable to the continued development and
improvement of Reticulum. But…
#### WARNING
**Think before you speak**. As time has shown, over 80% of the “feedback”,
“bug reports” and “advice” the Reticulum project has received has been
irrelevant noise, stemming from erroneous assumptions, misunderstanding the
foundational functionality or philosophy behind the system, or simply
the malinformed (but overly opinionated) personal preferences of individual
drive-by architects. This wastes the time of everyone involved.
The Reticulum project is not a public teahouse for serving the attention
needs of random bypassers, but a highly complex system engineered and
refined over more than a decade, designed to provide communication and
connectivity guarantees in highly adversarial environments.
If you want to voice your opinion, it better be well-informed, and we
expect you to have a comprehensive and solid foundation for your points
of view. Everything else will be ignored.
Absolutely no automated analytics, telemetry, error
reporting or statistics is collected and reported by Reticulum under any
circumstances, so we rely on old-fashioned human feedback.
docs/markdown/understanding.md
+940
View File
@@ -0,0 +1,940 @@
<a id="understanding-main"></a>
# Understanding Reticulum
This chapter will briefly describe the overall purpose and operating principles of Reticulum.
It should give you an overview of how the stack works, and an understanding of how to
develop networked applications using Reticulum.
This chapter is not an exhaustive source of information on Reticulum, at least not yet. Currently,
the only complete repository, and final authority on how Reticulum actually functions, is the Python
reference implementation and API reference. That being said, this chapter is an essential resource in
understanding how Reticulum works from a high-level perspective, along with the general principles of
Reticulum, and how to apply them when creating your own networks or software.
After reading this chapter, you should be well-equipped to understand how a Reticulum network
operates, what it can achieve, and how you can use it yourself. This chapter also seeks to provide an overview of the
sentiments and the philosophy behind Reticulum, what problems it seeks to solve, and how it
approaches those solutions.
<a id="understanding-motivation"></a>
## Motivation
The primary motivation for designing and implementing Reticulum has been the current lack of
reliable, functional and secure minimal-infrastructure modes of digital communication. It is my
belief that it is highly desirable to create a reliable and efficient way to set up long-range digital
communication networks that can securely allow exchange of information between people and
machines, with no central point of authority, control, censorship or barrier to entry.
Almost all of the various networking systems in use today share a common limitation: They
require large amounts of coordination and centralised trust and power to function. To join such networks, you need approval
of gatekeepers in control. This need for coordination and trust inevitably leads to an environment of
central control, where it’s very easy for infrastructure operators or governments to control or alter
traffic, and censor or persecute unwanted actors. It also makes it completely impossible to freely deploy
and use networks at will, like one would use other common tools that enhance individual agency and freedom.
Reticulum aims to require as little coordination and trust as possible. It aims to make secure,
anonymous and permissionless networking and information exchange a tool that anyone can just pick up and use.
Since Reticulum is completely medium agnostic, it can be used to build networks on whatever is best
suited to the situation, or whatever you have available. In some cases, this might be packet radio
links over VHF frequencies, in other cases it might be a 2.4 GHz
network using off-the-shelf radios, or it might be using common LoRa development boards.
At the time of release of this document, the fastest and easiest setup for development and testing is using
LoRa radio modules with an open source firmware (see the section [Reference Setup](#understanding-referencesystem)),
connected to any kind of computer or mobile device that Reticulum can run on.
The ultimate aim of Reticulum is to allow anyone to be their own network operator, and to make it
cheap and easy to cover vast areas with a myriad of independent, interconnectable and autonomous networks.
Reticulum **is not** *one network*, it **is a tool** to build *thousands of networks*. Networks without
kill-switches, surveillance, censorship and control. Networks that can freely interoperate, associate and disassociate
with each other, and require no central oversight. Networks for human beings. *Networks for the people*.
<a id="understanding-goals"></a>
## Goals
To be as widely usable and efficient to deploy as possible, the following goals have been used to
guide the design of Reticulum:
* **Fully useable as open source software stack**
: Reticulum must be implemented with, and be able to run using only open source software. This is
critical to ensuring the availability, security and transparency of the system.
* **Hardware layer agnosticism**
: Reticulum must be fully hardware agnostic, and shall be useable over a wide range of
physical networking layers, such as data radios, serial lines, modems, handheld transceivers,
wired Ethernet, WiFi, or anything else that can carry a digital data stream. Hardware made for
dedicated Reticulum use shall be as cheap as possible and use off-the-shelf components, so
it can be easily modified and replicated by anyone interested in doing so.
* **Very low bandwidth requirements**
: Reticulum should be able to function reliably over links with a transmission capacity as low
as *5 bits per second*.
* **Encryption by default**
: Reticulum must use strong encryption by default for all communication.
* **Initiator Anonymity**
: It must be possible to communicate over a Reticulum network without revealing any identifying
information about oneself.
* **Unlicensed use**
: Reticulum shall be functional over physical communication mediums that do not require any
form of license to use. Reticulum must be designed in a way, so it is usable over ISM radio
frequency bands, and can provide functional long distance links in such conditions, for example
by connecting a modem to a PMR or CB radio, or by using LoRa or WiFi modules.
* **Supplied software**
: In addition to the core networking stack and API, that allows a developer to build
applications with Reticulum, a basic set of Reticulum-based communication tools must be
implemented and released along with Reticulum itself. These shall serve both as a
functional, basic communication suite, and as an example and learning resource to others wishing
to build applications with Reticulum.
* **Ease of use**
: The reference implementation of Reticulum is written in Python, to make it easy to use
and understand. A programmer with only basic experience should be able to use
Reticulum to write networked applications.
* **Low cost**
: It shall be as cheap as possible to deploy a communication system based on Reticulum. This
should be achieved by using cheap off-the-shelf hardware that potential users might already
own. The cost of setting up a functioning node should be less than $100 even if all parts
needs to be purchased.
<a id="understanding-basicfunctionality"></a>
## Introduction & Basic Functionality
Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at its
core a *message oriented* system. It is suited for both local point-to-point or point-to-multipoint
scenarios where all nodes are within range of each other, as well as scenarios where packets need
to be transported over multiple hops in a complex network to reach the recipient.
Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead
Reticulum uses the singular concept of *destinations*. Any application using Reticulum as its
networking stack will need to create one or more destinations to receive data, and know the
destinations it needs to send data to.
All destinations in Reticulum are *represented* as a 16 byte hash. This hash is derived from truncating a full
SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
will be displayed as 16 hexadecimal bytes, like this example: `<13425ec15b621c1d928589718000d814>`.
The truncation size of 16 bytes (128 bits) for destinations has been chosen as a reasonable trade-off
between address space
and packet overhead. The address space accommodated by this size can support many billions of
simultaneously active devices on the same network, while keeping packet overhead low, which is
essential on low-bandwidth networks. In the very unlikely case that this address space nears
congestion, a one-line code change can upgrade the Reticulum address space all the way up to 256
bits, ensuring the Reticulum address space could potentially support galactic-scale networks.
This is obviously complete and ridiculous over-allocation, and as such, the current 128 bits should
be sufficient, even far into the future.
By default Reticulum encrypts all data using elliptic curve cryptography and AES. Any packet sent to a
destination is encrypted with a per-packet derived key. Reticulum can also set up an encrypted
channel to a destination, called a *Link*. Both data sent over Links and single packets offer
*Initiator Anonymity*. Links additionally offer *Forward Secrecy* by default, employing an Elliptic Curve
Diffie Hellman key exchange on Curve25519 to derive per-link ephemeral keys. Asymmetric, link-less
packet communication can also provide forward secrecy, with automatic key ratcheting, by enabling
ratchets on a per-destination basis. The multi-hop transport, coordination, verification and reliability
layers are fully autonomous and also based on elliptic curve cryptography.
Reticulum also offers symmetric key encryption for group-oriented communications, as well as
unencrypted packets (for local broadcast purposes **only**).
Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports,
and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or
private IP networks.
<a id="understanding-destinations"></a>
### Destinations
To receive and send data with the Reticulum stack, an application needs to create one or more
destinations. Reticulum uses three different basic destination types, and one special:
* **Single**
: The *single* destination type is the most common type in Reticulum, and should be used for
most purposes. It is always identified by a unique public key. Any data sent to this
destination will be encrypted using ephemeral keys derived from an ECDH key exchange, and will
only be readable by the creator of the destination, who holds the corresponding private key.
* **Plain**
: A *plain* destination type is unencrypted, and suited for traffic that should be broadcast to a
number of users, or should be readable by anyone. Traffic to a *plain* destination is not encrypted.
Generally, *plain* destinations can be used for broadcast information intended to be public.
Plain destinations are only reachable directly, and packets addressed to plain destinations are
never transported over multiple hops in the network. To be transportable over multiple hops in Reticulum, information
*must* be encrypted, since Reticulum uses the per-packet encryption to verify routing paths and
keep them alive.
* **Group**
: The *group* special destination type, that defines a symmetrically encrypted virtual destination.
Data sent to this destination will be encrypted with a symmetric key, and will be readable by
anyone in possession of the key, but as with the *plain* destination type, packets to this type
of destination are not currently transported over multiple hops, although a planned upgrade
to Reticulum will allow globally reachable *group* destinations.
* **Link**
: A *link* is a special destination type, that serves as an abstract channel to a *single*
destination, directly connected or over multiple hops. The *link* also offers reliability and
more efficient encryption, forward secrecy, initiator anonymity, and as such can be useful even
when a node is directly reachable. It also offers a more capable API and allows easily carrying
out requests and responses, large data transfers and more.
<a id="understanding-destinationnaming"></a>
#### Destination Naming
Destinations are created and named in an easy to understand dotted notation of *aspects*, and
represented on the network as a hash of this value. The hash is a SHA-256 truncated to 128 bits. The
top level aspect should always be a unique identifier for the application using the destination.
The next levels of aspects can be defined in any way by the creator of the application.
Aspects can be as long and as plentiful as required, and a resulting long destination name will not
impact efficiency, as names are always represented as truncated SHA-256 hashes on the network.
As an example, a destination for a environmental monitoring application could be made up of the
application name, a device type and measurement type, like this:
```text
app name : environmentlogger
aspects : remotesensor, temperature
full name : environmentlogger.remotesensor.temperature
hash : 4faf1b2e0a077e6a9d92fa051f256038
```
For the *single* destination, Reticulum will automatically append the associated public key as a
destination aspect before hashing. This is done to ensure only the correct destination is reached,
since anyone can listen to any destination name. Appending the public key ensures that a given
packet is only directed at the destination that holds the corresponding private key to decrypt the
packet.
**Take note!** There is a very important concept to understand here:
* Anyone can use the destination name `environmentlogger.remotesensor.temperature`
* Each destination that does so will still have a unique destination hash, and thus be uniquely
addressable, because their public keys will differ.
In actual use of *single* destination naming, it is advisable not to use any uniquely identifying
features in aspect naming. Aspect names should be general terms describing what kind of destination
is represented. The uniquely identifying aspect is always achieved by appending the public key,
which expands the destination into a uniquely identifiable one. Reticulum does this automatically.
Any destination on a Reticulum network can be addressed and reached simply by knowing its
destination hash (and public key, but if the public key is not known, it can be requested from the
network simply by knowing the destination hash). The use of app names and aspects makes it easy to
structure Reticulum programs and makes it possible to filter what information and data your program
receives.
To recap, the different destination types should be used in the following situations:
* **Single**
: When private communication between two endpoints is needed. Supports multiple hops.
* **Group**
: When private communication between two or more endpoints is needed. Supports multiple hops
indirectly, but must first be established through a *single* destination.
* **Plain**
: When plain-text communication is desirable, for example when broadcasting information, or for local discovery purposes.
To communicate with a *single* destination, you need to know its public key. Any method for
obtaining the public key is valid, but Reticulum includes a simple mechanism for making other
nodes aware of your destinations public key, called the *announce*. It is also possible to request
an unknown public key from the network, as all transport instances serve as a distributed ledger
of public keys.
Note that public key information can be shared and verified in other ways than using the
built-in *announce* functionality, and that it is therefore not required to use the *announce* and *path request*
functionality to obtain public keys. It is by far the easiest though, and should definitely be used
if there is not a very good reason for doing it differently.
<a id="understanding-keyannouncements"></a>
### Public Key Announcements
An *announce* will send a special packet over any relevant interfaces, containing all needed
information about the destination hash and public key, and can also contain some additional,
application specific data. The entire packet is signed by the sender to ensure authenticity. It is not
required to use the announce functionality, but in many cases it will be the simplest way to share
public keys on the network. The announce mechanism also serves to establish end-to-end connectivity
to the announced destination, as the announce propagates through the network.
As an example, an announce in a simple messenger application might contain the following information:
* The announcers destination hash
* The announcers public key
* Application specific data, in this case the users nickname and availability status
* A random blob, making each new announce unique
* An Ed25519 signature of the above information, verifying authenticity
With this information, any Reticulum node that receives it will be able to reconstruct an outgoing
destination to securely communicate with that destination. You might have noticed that there is one
piece of information lacking to reconstruct full knowledge of the announced destination, and that is
the aspect names of the destination. These are intentionally left out to save bandwidth, since they
will be implicit in almost all cases. The receiving application will already know them. If a destination
name is not entirely implicit, information can be included in the application specific data part that
will allow the receiver to infer the naming.
It is important to note that announces will be forwarded throughout the network according to a
certain pattern. This will be detailed in the section
[The Announce Mechanism in Detail](#understanding-announce).
In Reticulum, destinations are allowed to move around the network at will. This is very different from
protocols such as IP, where an address is always expected to stay within the network segment it was assigned in.
This limitation does not exist in Reticulum, and any destination is *completely portable* over the entire topography
of the network, and *can even be moved to other Reticulum networks* than the one it was created in, and
still become reachable. To update its reachability, a destination simply needs to send an announce on any
networks it is part of. After a short while, it will be globally reachable in the network.
Seeing how *single* destinations are always tied to a private/public key pair leads us to the next topic.
<a id="understanding-identities"></a>
### Identities
In Reticulum, an *identity* does not necessarily represent a personal identity, but is an abstraction that
can represent any kind of *verifiable entity*. This could very well be a person, but it could also be the
control interface of a machine, a program, robot, computer, sensor or something else entirely. In
general, any kind of agent that can act, or be acted upon, or store or manipulate information, can be
represented as an identity. An *identity* can be used to create any number of destinations.
A *single* destination will always have an *identity* tied to it, but not *plain* or *group*
destinations. Destinations and identities share a multilateral connection. You can create a
destination, and if it is not connected to an identity upon creation, it will just create a new one to use
automatically. This may be desirable in some situations, but often you will probably want to create
the identity first, and then use it to create new destinations.
As an example, we could use an identity to represent the user of a messaging application.
Destinations can then be created by this identity to allow communication to reach the user.
In all cases it is of great importance to store the private keys associated with any
Reticulum Identity securely and privately, since obtaining access to the identity keys equals
obtaining access and controlling reachability to any destinations created by that identity.
<a id="understanding-gettingfurther"></a>
### Getting Further
The above functions and principles form the core of Reticulum, and would suffice to create
functional networked applications in local clusters, for example over radio links where all interested
nodes can directly hear each other. But to be truly useful, we need a way to direct traffic over multiple
hops in the network.
In the following sections, two concepts that allow this will be introduced, *paths* and *links*.
<a id="understanding-transport"></a>
## Reticulum Transport
The methods of routing used in traditional networks are fundamentally incompatible with the physical medium
types and circumstances that Reticulum was designed to handle. These mechanisms mostly assume trust at the physical layer,
and often needs a lot more bandwidth than Reticulum can assume is available. Since Reticulum is designed to
survive running over open radio spectrum, no such trust can be assumed, and bandwidth is often very limited.
To overcome such challenges, Reticulum’s *Transport* system uses asymmetric elliptic curve cryptography to
implement the concept of *paths* that allow discovery of how to get information closer to a certain
destination. It is important to note that no single node in a Reticulum network knows the complete
path to a destination. Every Transport node participating in a Reticulum network will only
know the most direct way to get a packet one hop closer to it’s destination.
<a id="understanding-nodetypes"></a>
### Node Types
Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network
are *Reticulum Instances*, and some are also *Transport Nodes*. If a system running Reticulum is fixed in
one place, and is intended to be kept available most of the time, it is a good contender to be a *Transport Node*.
Any Reticulum Instance can become a Transport Node by enabling it in the configuration.
This distinction is made by the user configuring the node, and is used to determine what nodes on the
network will help forward traffic, and what nodes rely on other nodes for wider connectivity.
If a node is an *Instance* it should be given the configuration directive `enable_transport = No`, which
is the default setting.
If it is a *Transport Node*, it should be given the configuration directive `enable_transport = Yes`.
<a id="understanding-announce"></a>
### The Announce Mechanism in Detail
When an *announce* for a destination is transmitted by a Reticulum instance, it will be forwarded by
any transport node receiving it, but according to some specific rules:
* If this exact announce has already been received before, ignore it.
<br/>
* If not, record into a table which Transport Node the announce was received from, and how many times in
total it has been retransmitted to get here.
<br/>
* If the announce has been retransmitted *m+1* times, it will not be forwarded any more. By default, *m* is
set to 128.
<br/>
* After a randomised delay, the announce will be retransmitted on all interfaces that have bandwidth
available for processing announces. By default, the maximum bandwidth allocation for processing
announces is set at 2%, but can be configured on a per-interface basis.
<br/>
* If any given interface does not have enough bandwidth available for retransmitting the announce,
the announce will be assigned a priority inversely proportional to its hop count, and be inserted
into a queue managed by the interface.
<br/>
* When the interface has bandwidth available for processing an announce, it will prioritise announces
for destinations that are closest in terms of hops, thus prioritising reachability and connectivity
of local nodes, even on slow networks that connect to wider and faster networks.
<br/>
* After the announce has been re-transmitted, and if no other nodes are heard retransmitting the announce
with a greater hop count than when it left this node, transmitting it will be retried *r* times. By default,
*r* is set to 1.
<br/>
* If a newer announce from the same destination arrives, while an identical one is already waiting
to be transmitted, the newest announce is discarded. If the newest announce contains different
application specific data, it will replace the old announce.
<br/>
Once an announce has reached a transport node in the network, any other node in direct contact with that
transport node will be able to reach the destination the announce originated from, simply by sending a packet
addressed to that destination. Any transport node with knowledge of the announce will be able to direct the
packet towards the destination by looking up the most efficient next node to the destination.
According to these rules, an announce will propagate throughout the network in a predictable way,
and make the announced destination reachable in a short amount of time. Fast networks that have the
capacity to process many announces can reach full convergence very quickly, even when constantly adding
new destinations. Slower segments of such networks might take a bit longer to gain full knowledge about
the wide and fast networks they are connected to, but can still do so over time, while prioritising full
and quickly converging end-to-end connectivity for their local, slower segments.
In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full
end-to-end connectivity in about one minute, given there is enough bandwidth available to process
the required amount of announces.
<a id="understanding-paths"></a>
### Reaching the Destination
In networks with changing topology and trustless connectivity, nodes need a way to establish
*verified connectivity* with each other. Since the underlying network mediums are assumed to be trustless, Reticulum
must provide a way to guarantee that the peer you are communicating with is actually who you
expect. Reticulum offers two ways to do this.
For exchanges of small amounts of information, Reticulum offers the *Packet* API, which works exactly like you would expect - on a per packet level. The following process is employed when sending a packet:
* A packet is always created with an associated destination and some payload data. When the packet is sent
to a *single* destination type, Reticulum will automatically create an ephemeral encryption key, perform
an ECDH key exchange with the destination’s public key (or ratchet key, if available), and encrypt the information.
<br/>
* It is important to note that this key exchange does not require any network traffic. The sender already
knows the public key of the destination from an earlier received announce, and can thus perform the ECDH
key exchange locally, before sending the packet.
<br/>
* The public part of the newly generated ephemeral key-pair is included with the encrypted token, and sent
along with the encrypted payload data in the packet.
<br/>
* When the destination receives the packet, it can itself perform an ECDH key exchange and decrypt the
packet.
<br/>
* A new ephemeral key is used for every packet sent in this way.
<br/>
* Once the packet has been received and decrypted by the addressed destination, that destination can opt
to *prove* its receipt of the packet. It does this by calculating the SHA-256 hash of the received packet,
and signing this hash with its Ed25519 signing key. Transport nodes in the network can then direct this
*proof* back to the packets origin, where the signature can be verified against the destination’s known
public signing key.
<br/>
* In case the packet is addressed to a *group* destination type, the packet will be encrypted with the
pre-shared AES-256 key associated with the destination. In case the packet is addressed to a *plain*
destination type, the payload data will not be encrypted. Neither of these two destination types can offer
forward secrecy. In general, it is recommended to always use the *single* destination type, unless it is
strictly necessary to use one of the others.
<br/>
For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the *Link* API. To establish a *link*, the following process is employed:
* First, the node that wishes to establish a link will send out a *link request* packet, that
traverses the network and locates the desired destination. Along the way, the Transport Nodes that
forward the packet will take note of this *link request*, and mark it as pending.
<br/>
* Second, if the destination accepts the *link request* , it will send back a packet that proves the
authenticity of its identity (and the receipt of the link request) to the initiating node. All
nodes that initially forwarded the packet will also be able to verify this proof, and thus
accept the validity of the *link* throughout the network. The link is now marked as *established*.
<br/>
* When the validity of the *link* has been accepted by forwarding nodes, these nodes will
remember the *link* , and it can subsequently be used by referring to a hash representing it.
<br/>
* As a part of the *link request*, an Elliptic Curve Diffie-Hellman key exchange takes place, that sets up an
efficiently encrypted tunnel between the two nodes. As such, this mode of communication is preferred,
even for situations when nodes can directly communicate, when the amount of data to be exchanged numbers
in the tens of packets, or whenever the use of the more advanced API functions is desired.
<br/>
* When a *link* has been set up, it automatically provides message receipt functionality, through
the same *proof* mechanism discussed before, so the sending node can obtain verified confirmation
that the information reached the intended recipient.
<br/>
* Once the *link* has been set up, the initiator can remain anonymous, or choose to authenticate towards
the destination using a Reticulum Identity. This authentication is happening inside the encrypted
link, and is only revealed to the verified destination, and no intermediaries.
<br/>
In a moment, we will discuss the details of how this methodology is
implemented, but let’s first recap what purposes this methodology serves. We
first ensure that the node answering our request is actually the one we want to
communicate with, and not a malicious actor pretending to be so. At the same
time we establish an efficient encrypted channel. The setup of this is
relatively cheap in terms of bandwidth, so it can be used just for a short
exchange, and then recreated as needed, which will also rotate encryption keys.
The link can also be kept alive for longer periods of time, if this is more
suitable to the application. The procedure also inserts the *link id* , a hash
calculated from the link request packet, into the memory of forwarding nodes,
which means that the communicating nodes can thereafter reach each other simply
by referring to this *link id*.
The combined bandwidth cost of setting up a link is 3 packets totalling 297 bytes (more info in the
[Binary Packet Format](#understanding-packetformat) section). The amount of bandwidth used on keeping
a link open is practically negligible, at 0.45 bits per second. Even on a slow 1200 bits per second packet
radio channel, 100 concurrent links will still leave 96% channel capacity for actual data.
#### Link Establishment in Detail
After exploring the basics of the announce mechanism, finding a path through the network, and an overview
of the link establishment procedure, this section will go into greater detail about the Reticulum link
establishment process.
The *link* in Reticulum terminology should not be viewed as a direct node-to-node link on the
physical layer, but as an abstract channel, that can be open for any amount of time, and can span
an arbitrary number of hops, where information will be exchanged between two nodes.
* When a node in the network wants to establish verified connectivity with another node, it
will randomly generate a new X25519 private/public key pair. It then creates a *link request*
packet, and broadcast it.
<br/>
<br/>
*It should be noted that the X25519 public/private keypair mentioned above is two separate keypairs:
An encryption key pair, used for derivation of a shared symmetric key, and a signing key pair, used
for signing and verifying messages on the link. They are sent together over the wire, and can be
considered as single public key for simplicity in this explanation.*
<br/>
* The *link request* is addressed to the destination hash of the desired destination, and
contains the following data: The newly generated X25519 public key *LKi*.
<br/>
* The broadcasted packet will be directed through the network according to the rules laid out
previously.
<br/>
* Any node that forwards the link request will store a *link id* in it’s *link table* , along with the
amount of hops the packet had taken when received. The link id is a hash of the entire link
request packet. If the link request packet is not *proven* by the addressed destination within some
set amount of time, the entry will be dropped from the *link table* again.
<br/>
* When the destination receives the link request packet, it will decide whether to accept the request.
If it is accepted, the destination will also generate a new X25519 private/public key pair, and
perform a Diffie Hellman Key Exchange, deriving a new symmetric key that will be used to encrypt the
channel, once it has been established.
<br/>
* A *link proof* packet is now constructed and transmitted over the network. This packet is
addressed to the *link id* of the *link*. It contains the following data: The newly generated X25519
public key *LKr* and an Ed25519 signature of the *link id* and *LKr* made by the *original signing key* of
the addressed destination.
<br/>
* By verifying this *link proof* packet, all nodes that originally transported the *link request*
packet to the destination from the originator can now verify that the intended destination received
the request and accepted it, and that the path they chose for forwarding the request was valid.
In successfully carrying out this verification, the transporting nodes marks the link as active.
An abstract bi-directional communication channel has now been established along a path in the network.
Packets can now be exchanged bi-directionally from either end of the link simply by adressing the
packets to the *link id* of the link.
<br/>
* When the source receives the *proof* , it will know unequivocally that a verified path has been
established to the destination. It can now also use the X25519 public key contained in the
*link proof* to perform it’s own Diffie Hellman Key Exchange and derive the symmetric key
that is used to encrypt the channel. Information can now be exchanged reliably and securely.
<br/>
#### NOTE
It’s important to note that this methodology ensures that the source of the request does not need to
reveal any identifying information about itself. **The link initiator remains completely anonymous**.
When using *links*, Reticulum will automatically verify all data sent over the link, and can also
automate retransmissions if *Resources* are used.
<a id="understanding-resources"></a>
### Resources
For exchanging small amounts of data over a Reticulum network, the [Packet](reference.md#api-packet) interface
is sufficient, but for exchanging data that would require many packets, an efficient way to coordinate
the transfer is needed.
This is the purpose of the Reticulum [Resource](reference.md#api-resource). A *Resource* can automatically
handle the reliable transfer of an arbitrary amount of data over an established [Link](reference.md#api-link).
Resources can auto-compress data, will handle breaking the data into individual packets, sequencing
the transfer, integrity verification and reassembling the data on the other end.
[Resources](reference.md#api-resource) are programmatically very simple to use, and only requires a few lines
of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
or stream data directly from files.
<a id="understanding-network-identities"></a>
## Network Identities
In Reticulum, every peer and application utilizes a cryptographic **Identity** to verify authenticity and establish encrypted channels. While standard identities are typically used to represent a single user, device, or service, Reticulum introduces the concept of a **Network Identity** to represent a logical group of nodes or an entire community infrastructure.
A Network Identity is, at its core, a standard Reticulum Identity keyset. However, its purpose and usage differ from a personal identity. Instead of identifying a single entity, a Network Identity acts as a shared credential that federates multiple independent Transport Instances under a single, verifiable administrative domain.
### Conceptual Overview
You can think of a standard Reticulum Identity as a self-sovereign, privately created passport for a single person. A Network Identity, conversely, is akin to a cryptographic flag, or a charter that flies over a fleet of ships. It signifies that while the ships may operate independently and be physically distant, they belong to the same organization, follow the same protocols, and are expected to act in concert.
When you configure a Network Identity on one or more of your nodes, you are effectively declaring that these nodes constitute a specific “network” within a broader Reticulum mesh. This allows other peers to recognize interfaces not just as “a node named Alice”, but as “a gateway belonging to The Eastern Ret Of Freedom”.
### Current Usage
At present, the primary function of a Network Identity is within the [Interface Discovery](using.md#using-interface-discovery) system.
When a Transport Instance broadcasts a discovery announce for an interface, it can optionally sign that announce with a Network Identity, instead of just its local transport identity. Remote peers receiving the announce can then verify the signature. This provides functionality for two important distinctions:
1. **Authenticity:** It proves that the interface was published by an operator who possesses the private key for that Network Identity.
2. **Trust Boundaries:** It allows users to configure their systems to only accept and connect to interfaces that belong to specific Network Identities, effectively creating “whitelisted” zones of trusted infrastructure.
#### NOTE
If you enable encryption on your discovery announces, the Network Identity is used as the shared secret. Only peers who have been explicitly provided with the Network Identity’s full keyset (and have it configured locally) will be able to decrypt and utilize the connection details.
This functionality will be expanded in the future, so that peers with delegated keys can be allowed to decrypt discovery announces without holding the root network key. Currently, the functionality is sufficient for sharing interface information privately where you control all nodes that must decrypt the discovered interfaces.
### Future Implications
While the current implementation focuses on interface discovery, the concept of Network Identities serves as the foundational building block for future Reticulum features designed to support large-scale, organic mesh formation.
As the ecosystem evolves, Network Identities will facilitate:
* **Distributed Name Resolution:** A system where networks can publish name-to-identity mappings, allowing human-readable names to resolve without centralized servers.
* **Service Publishing:** Networks will be able to announce specific capabilities, services, or information endpoints available publicly or to their members.
* **Inter-Network Federation:** Trust relationships between different networks, allowing for seamless but managed flow of traffic and information across distinct administrative boundaries.
* **Distributed Blackhole Management:** A reputation-based system for blackhole list distribution, where trusted Network Identities can sign and publish lists of blackholed identities. This allows communities to collaboratively enforce security standards and filter spam or malicious identities across the parts of the wider mesh that they are responsible for.
By adopting the use of Network Identities now, you are preparing your infrastructure to be compatible with this future functionality.
### Creating and Using a Network Identity
Since a Network Identity is simply a standard Reticulum Identity, you create one using the built-in tools.
1. **Generate the Identity:**
Use the `rnid` utility to generate a new identity file that will serve as your Network Identity.
```sh
$ rnid -g ~/.reticulum/storage/identities/my_network
```
2. **Distribute the Public Key:**
The public key must be distributed to any Transport Instance that needs to verify your network’s announces and discovery information. By default, if your node is set up to use a network identity, this happens automatically (using the standard announce mechanism).
3. **Configure Instances:**
In the `[reticulum]` section of the configuration file on every node within your network, point the `network_identity` option to the file you created.
```ini
[reticulum]
...
network_identity = ~/.reticulum/storage/identities/my_network
...
```
Once configured, your instances will automatically utilize this identity for signing discovery announces (and potentially decrypting network-private information), presenting a unified front to the wider network.
<a id="understanding-referencesystem"></a>
## Reference Setup
This section will detail a recommended *Reference Setup* for Reticulum. It is important to
note that Reticulum is designed to be usable on more or less any computing device, and over more
or less any medium that allows you to send and receive data, which satisfies some very low
minimum requirements.
The communication channel must support at least half-duplex operation, and provide an average
throughput of 5 bits per second or greater, and supports a physical layer MTU of 500 bytes. The
Reticulum stack should be able to run on more or less any hardware that can provide a Python 3.x
runtime environment.
That being said, this reference setup has been outlined to provide a common platform for anyone
who wants to help in the development of Reticulum, and for everyone who wants to know a
recommended setup to get started experimenting. A reference system consists of three parts:
* **An Interface Device**
: Which provides access to the physical medium whereupon the communication
takes place, for example a radio with an integrated modem. A setup with a separate modem
connected to a radio would also be an interface device.
* **A Host Device**
: Some sort of computing device that can run the necessary software, communicate with the
interface device, and provide user interaction.
* **A Software Stack**
: The software implementing the Reticulum protocol and applications using it.
The reference setup can be considered a relatively stable platform to develop on, and also to start
building networks or applications on. While details of the implementation might change at the current stage of
development, it is the goal to maintain hardware compatibility for as long as entirely possible, and
the current reference setup has been determined to provide a functional platform for many years
into the future. The current Reference System Setup is as follows:
* **Interface Device**
: A data radio consisting of a LoRa radio module, and a microcontroller with open source
firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
MHz frequency bands. More details can be found on the [RNode Page](https://github.com/markqvist/rnode_firmware).
* **Host Device**
: Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
a good place to start, but anything can be used.
* **Software Stack**
: The most recently released Python Implementation of Reticulum, running on a Linux-based
operating system.
#### NOTE
To avoid confusion, it is very important to note, that the reference interface device **does not**
use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
need a plain LoRa radio module connected to a controller with the correct firmware. Full details on how to
get or make such a device is available on the [RNode Page](https://github.com/markqvist/rnode_firmware).
With the current reference setup, it should be possible to get on a Reticulum network for around 100$
even if you have none of the hardware already, and need to purchase everything.
This reference setup is of course just a recommendation for getting started easily, and you should
tailor it to your own specific needs, or whatever hardware you have available.
<a id="understanding-protocolspecifics"></a>
## Protocol Specifics
This chapter will detail protocol specific information that is essential to the implementation of
Reticulum, but non-critical in understanding how the protocol works on a general level. It should be
treated more as a reference than as essential reading.
### Packet Prioritisation
Currently, Reticulum is completely priority-agnostic regarding *general* traffic. All traffic is handled
on a first-come, first-serve basis. Announce re-transmission and other maintenance traffic is handled
according to the re-transmission times and priorities described earlier in this chapter.
### Interface Access Codes
Reticulum can create named virtual networks, and networks that are only accessible by knowing a preshared
passphrase. The configuration of this is detailed in the [Common Interface Options](interfaces.md#interfaces-options)
section. To implement this feature, Reticulum uses the concept of Interface Access Codes, that are calculated
and verified per-packet.
An interface with a named virtual network or passphrase authentication enabled will derive a shared Ed25519
signing identity, and for every outbound packet generate a signature of the entire packet. This signature is
then inserted into the packet as an Interface Access Code before transmission. Depending on the speed and
capabilities of the interface, the IFAC can be the full 512-bit Ed25519 signature, or a truncated version.
Configured IFAC length can be inspected for all interfaces with the `rnstatus` utility.
Upon receipt, the interface will check that the signature matches the expected value, and drop the packet if it
does not. This ensures that only packets sent with the correct naming and/or passphrase parameters are allowed to
pass onto the network.
<a id="understanding-packetformat"></a>
### Wire Format
```text
== Reticulum Wire Format ======
A Reticulum packet is composed of the following fields:
[HEADER 2 bytes] [ADDRESSES 16/32 bytes] [CONTEXT 1 byte] [DATA 0-465 bytes]
* The HEADER field is 2 bytes long.
* Byte 1: [IFAC Flag], [Header Type], [Context Flag], [Propagation Type],
[Destination Type] and [Packet Type]
* Byte 2: Number of hops
* Interface Access Code field if the IFAC flag was set.
* The length of the Interface Access Code can vary from
1 to 64 bytes according to physical interface
capabilities and configuration.
* The ADDRESSES field contains either 1 or 2 addresses.
* Each address is 16 bytes long.
* The Header Type flag in the HEADER field determines
whether the ADDRESSES field contains 1 or 2 addresses.
* Addresses are SHA-256 hashes truncated to 16 bytes.
* The CONTEXT field is 1 byte.
* It is used by Reticulum to determine packet context.
* The DATA field is between 0 and 465 bytes.
* It contains the packets data payload.
IFAC Flag
-----------------
open 0 Packet for publically accessible interface
authenticated 1 Interface authentication is included in packet
Header Types
-----------------
type 1 0 Two byte header, one 16 byte address field
type 2 1 Two byte header, two 16 byte address fields
Context Flag
-----------------
unset 0 The context flag is used for various types
set 1 of signalling, depending on packet context
Propagation Types
-----------------
broadcast 0
transport 1
Destination Types
-----------------
single 00
group 01
plain 10
link 11
Packet Types
-----------------
data 00
announce 01
link request 10
proof 11
+- Packet Example -+
HEADER FIELD DESTINATION FIELDS CONTEXT FIELD DATA FIELD
_______|_______ ________________|________________ ________|______ __|_
| | | | | | | |
01010000 00000100 [HASH1, 16 bytes] [HASH2, 16 bytes] [CONTEXT, 1 byte] [DATA]
|| | | | |
|| | | | +-- Hops = 4
|| | | +------- Packet Type = DATA
|| | +--------- Destination Type = SINGLE
|| +----------- Propagation Type = TRANSPORT
|+------------- Header Type = HEADER_2 (two byte header, two address fields)
+-------------- Access Codes = DISABLED
+- Packet Example -+
HEADER FIELD DESTINATION FIELD CONTEXT FIELD DATA FIELD
_______|_______ _______|_______ ________|______ __|_
| | | | | | | |
00000000 00000111 [HASH1, 16 bytes] [CONTEXT, 1 byte] [DATA]
|| | | | |
|| | | | +-- Hops = 7
|| | | +------- Packet Type = DATA
|| | +--------- Destination Type = SINGLE
|| +----------- Propagation Type = BROADCAST
|+------------- Header Type = HEADER_1 (two byte header, one address field)
+-------------- Access Codes = DISABLED
+- Packet Example -+
HEADER FIELD IFAC FIELD DESTINATION FIELD CONTEXT FIELD DATA FIELD
_______|_______ ______|______ _______|_______ ________|______ __|_
| | | | | | | | | |
10000000 00000111 [IFAC, N bytes] [HASH1, 16 bytes] [CONTEXT, 1 byte] [DATA]
|| | | | |
|| | | | +-- Hops = 7
|| | | +------- Packet Type = DATA
|| | +--------- Destination Type = SINGLE
|| +----------- Propagation Type = BROADCAST
|+------------- Header Type = HEADER_1 (two byte header, one address field)
+-------------- Access Codes = ENABLED
Size examples of different packet types
---------------------------------------
The following table lists example sizes of various
packet types. The size listed are the complete on-
wire size counting all fields including headers,
but excluding any interface access codes.
- Path Request : 51 bytes
- Announce : 167 bytes
- Link Request : 83 bytes
- Link Proof : 115 bytes
- Link RTT packet : 99 bytes
- Link keepalive : 20 bytes
```
<a id="understanding-announcepropagation"></a>
### Announce Propagation Rules
The following table illustrates the rules for automatically propagating announces
from one interface type to another, for all possible combinations. For the purpose
of announce propagation, the *Full* and *Gateway* modes are identical.
![image](graphics/if_mode_graph_b.png)
See the [Interface Modes](interfaces.md#interfaces-modes) section for a conceptual overview
of the different interface modes, and how they are configured.
<!-- (.. code-block:: text)
Full ────── ✓ ──┐ ┌── ✓ ── Full
AP ──────── ✓ ──┼───> Full >───┼── ✕ ── AP
Boundary ── ✓ ──┤ ├── ✓ ── Boundary
Roaming ─── ✓ ──┘ └── ✓ ── Roaming
Full ────── ✕ ──┐ ┌── ✓ ── Full
AP ──────── ✕ ──┼────> AP >────┼── ✕ ── AP
Boundary ── ✕ ──┤ ├── ✓ ── Boundary
Roaming ─── ✕ ──┘ └── ✓ ── Roaming
Full ────── ✓ ──┐ ┌── ✓ ── Full
AP ──────── ✓ ──┼─> Roaming >──┼── ✕ ── AP
Boundary ── ✕ ──┤ ├── ✕ ── Boundary
Roaming ─── ✕ ──┘ └── ✕ ── Roaming
Full ────── ✓ ──┐ ┌── ✓ ── Full
AP ──────── ✓ ──┼─> Boundary >─┼── ✕ ── AP
Boundary ── ✓ ──┤ ├── ✓ ── Boundary
Roaming ─── ✕ ──┘ └── ✕ ── Roaming -->
<a id="understanding-primitives"></a>
### Cryptographic Primitives
Reticulum uses a simple suite of efficient, strong and well-tested cryptographic
primitives, with widely available implementations that can be used both on
general-purpose CPUs and on microcontrollers.
One of the primary considerations for choosing this particular set of primitives is
that they can be implemented *safely* with relatively few pitfalls, on practically
all current computing platforms.
The primitives listed here **are authoritative**. Anything claiming to be Reticulum,
but not using these exact primitives **is not** Reticulum, and possibly an
intentionally compromised or weakened clone. The utilised primitives are:
* Ed25519 for signatures
* X25519 for ECDH key exchanges
* HKDF for key derivation
* Encrypted tokens are based on the Fernet spec
* Ephemeral keys derived from an ECDH key exchange on Curve25519
* AES-256 in CBC mode with PKCS7 padding
* HMAC using SHA256 for message authentication
* IVs must be generated through `os.urandom()` or better
* No Fernet version and timestamp metadata fields
* SHA-256
* SHA-512
In the default installation configuration, the `X25519`, `Ed25519` and `AES-256-CBC`
primitives are provided by [OpenSSL](https://www.openssl.org/) (via the [PyCA/cryptography](https://github.com/pyca/cryptography)
package). The hashing functions `SHA-256` and `SHA-512` are provided by the standard
Python [hashlib](https://docs.python.org/3/library/hashlib.html). The `HKDF`, `HMAC`,
`Token` primitives, and the `PKCS7` padding function are always provided by the
following internal implementations:
- `RNS/Cryptography/HKDF.py`
- `RNS/Cryptography/HMAC.py`
- `RNS/Cryptography/Token.py`
- `RNS/Cryptography/PKCS7.py`
Reticulum also includes a complete implementation of all necessary primitives in pure Python.
If OpenSSL & PyCA are not available on the system when Reticulum is started, Reticulum will
instead use the internal pure-python primitives. A trivial consequence of this is performance,
with the OpenSSL backend being *much* faster. The most important consequence however, is the
potential loss of security by using primitives that has not seen the same amount of scrutiny,
testing and review as those from OpenSSL.
Using the normal RNS installation procedures, it is not possible to install Reticulum on a
system without the required OpenSSL primitives being available, and if they are not, they will
be resolved and installed as a dependency. It is only possible to use the pure-python primitives
by manually specifying this, for example by using the `rnspure` package.
#### WARNING
If you want to use the internal pure-python primitives, it is **highly advisable** that you
have a good understanding of the risks that this pose, and make an informed decision on whether
those risks are acceptable to you.
docs/markdown/using.md
+1471
View File
File diff suppressed because it is too large Load Diff
docs/markdown/whatis.md
+144
View File
@@ -0,0 +1,144 @@
# What is Reticulum?
Reticulum is a cryptography-based networking stack for building both local and
wide-area networks with readily available hardware, that can continue to operate
under adverse conditions, such as extremely low bandwidth and very high latency.
To understand the foundational philosophy and goals of this system, read the
[Zen of Reticulum](zen.md#zen).
Reticulum allows you to build wide-area networks with off-the-shelf tools, and
offers end-to-end encryption, forward secrecy, autoconfiguring cryptographically
backed multi-hop transport, efficient addressing, unforgeable packet
acknowledgements and more.
From a users perspective, Reticulum allows the creation of applications that
respect and empower the autonomy and sovereignty of communities and individuals.
Reticulum enables secure digital communication that cannot be subjected to
outside control, manipulation or censorship.
Reticulum enables the construction of both small and potentially planetary-scale
networks, without any need for hierarchical or bureaucratic structures to control
or manage them, while ensuring individuals and communities full sovereignty
over their own network segments.
Reticulum is a **complete networking stack**, and does not need IP or higher
layers, although it is easy to utilise IP (with TCP or UDP) as the underlying
carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the
Internet or private IP networks. Reticulum is built directly on cryptographic
principles, allowing resilience and stable functionality in open and trustless
networks.
No kernel modules or drivers are required. Reticulum can run completely in
userland, and will run on practically any system that runs Python 3. Reticulum
runs well even on small single-board computers like the Pi Zero.
## Current Status
All core protocol features are implemented and functioning, but additions will probably occur as
real-world use is explored. The API and wire-format can be considered complete and stable, but
could change if absolutely warranted.
## Reference Implementation
The Python code, for which this documentation is written, and known as the Reticulum Network Stack,
is the Reference Implementation of Reticulum. The Reticulum Protocol is defined entirely
and authoritatively by this reference implementation, and this manual. It is maintained by Mark Qvist,
identified by the Reticulum Identity `<bc7291552be7a58f361522990465165c>`.
Compatibility with the Reticulum Protocol is defined as having full interoperability,
and sufficient functional parity with this reference implementation. Any specific protocol
implementation that achieves this is Reticulum. Any that does not is not Reticulum.
The reference implementation is licensed under the [Reticulum License](license.md#license).
The Reticulum Protocol was dedicated to the Public Domain in 2016.
## What does Reticulum Offer?
* Coordination-less globally unique addressing and identification
* Fully self-configuring multi-hop routing over heterogeneous carriers
* Flexible scalability over heterogeneous topologies
* Reticulum can carry data over any mixture of physical mediums and topologies
* Low-bandwidth networks can co-exist and interoperate with large, high-bandwidth networks
* Initiator anonymity, communicate without revealing your identity
* Reticulum does not include source addresses on any packets
* Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication
* The foundational Reticulum Identity Keys are 512-bit Elliptic Curve keysets
* Forward Secrecy is available for all communication types, both for single packets and over links
* Reticulum uses the following format for encrypted tokens:
* Ephemeral per-packet and link keys and derived from an ECDH key exchange on Curve25519
* AES-256 in CBC mode with PKCS7 padding
* HMAC using SHA256 for authentication
* IVs are generated through os.urandom()
* Unforgeable packet delivery confirmations
* Flexible and extensible interface system
* Reticulum includes a large variety of built-in interface types
* Ability to load and utilise custom user- or community-supplied interface types
* Easily create your own custom interfaces for communicating over anything
* Authentication and virtual network segmentation on all supported interface types
* An intuitive and easy-to-use API
* Simpler and easier to use than sockets APIs and simpler, but more powerful
* Makes building distributed and decentralised applications much simpler
* Reliable and efficient transfer of arbitrary amounts of data
* Reticulum can handle a few bytes of data or files of many gigabytes
* Sequencing, compression, transfer coordination and checksumming are automatic
* The API is very easy to use, and provides transfer progress
* Lightweight, flexible and expandable Request/Response mechanism
* Efficient link establishment
* Total cost of setting up an encrypted and verified link is only 3 packets, totalling 297 bytes
* Low cost of keeping links open at only 0.44 bits per second
* Reliable sequential delivery with Channel and Buffer mechanisms
## Where can Reticulum be Used?
Over practically any medium that can support at least a half-duplex channel
with greater throughput than 5 bits per second, and an MTU of 500 bytes. Data radios,
modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes,
ad-hoc WiFi, free-space optical links and similar systems are all examples
of the types of interfaces Reticulum was designed for.
An open-source LoRa-based interface called [RNode](https://unsigned.io/rnode)
has been designed as an example transceiver that is very suitable for
Reticulum. It is possible to build it yourself, to transform a common LoRa
development board into one, or it can be purchased as a complete transceiver
from various vendors.
Reticulum can also be encapsulated over existing IP networks, so there’s
nothing stopping you from using it over wired Ethernet or your local WiFi
network, where it’ll work just as well. In fact, one of the strengths of
Reticulum is how easily it allows you to connect different mediums into a
self-configuring, resilient and encrypted mesh.
As an example, it’s possible to set up a Raspberry Pi connected to both a
LoRa radio, a packet radio TNC and a WiFi network. Once the interfaces are
added, Reticulum will take care of the rest, and any device on the WiFi
network can communicate with nodes on the LoRa and packet radio sides of the
network, and vice versa.
## Interface Types and Devices
Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it’s simple to [implement an interface class](examples.md#example-custominterface). Currently, Reticulum can use the following devices and communication mediums:
* Any Ethernet device
* WiFi devices
* Wired Ethernet devices
* Fibre-optic transceivers
* Data radios with Ethernet ports
* LoRa using [RNode](https://unsigned.io/rnode)
* Can be installed on [many popular LoRa boards](https://github.com/markqvist/rnodeconfigutil#supported-devices)
* Can be purchased as a [ready to use transceiver](https://unsigned.io/rnode)
* Packet Radio TNCs, such as [OpenModem](https://unsigned.io/openmodem)
* Any packet radio TNC in KISS mode
* Ideal for VHF and UHF radio
* Any device with a serial port
* The I2P network
* TCP over IP networks
* UDP over IP networks
* Anything you can connect via stdio
* Reticulum can use external programs and pipes as interfaces
* This can be used to easily hack in virtual interfaces
* Or to quickly create interfaces with custom hardware
* Anything else using [custom interface modules](interfaces.md#interfaces-custom) written in Python
For a full list and more details, see the [Supported Interfaces](interfaces.md#interfaces-main) chapter.
docs/markdown/zen.md
+416
View File
@@ -0,0 +1,416 @@
<a id="zen"></a>
# Zen of Reticulum
## The Illusion Of The Center
For the better part of a generation, we have been taught to visualize the digital world through the lens of hierarchy. The mental maps we carry are dominated by a single, misleading image: **The Cloud**.
We imagine the network as a vast, ethereal space “up there” or “out there”. A centralized repository of services and data to which we, the lowly clients, must connect. We build our software with this assumption hardcoded into our logic: *There is a server. The server has the authority. The server knows the way. I must find the server to function*.
This is the Client-Server mental model, and it is the primary obstacle to understanding Reticulum.
### Fallacy Of The Cloud
The first step in the Zen of Reticulum is to realize that *there is no cloud*. There is only other people’s computers. When you build for the cloud, you are building *for* a landlord. You are accepting that your application’s existence is conditional on the permission, uptime, and continued goodwill of a central authority.
In Reticulum, you must shift your thinking from “connecting to” to “being among”. Reticulum is not a service you subscribe to - *it is a fabric you inhabit*. There is no “up there”. There is only *here* and *there*, and the space between them is peer-to-peer.
### Decentralization Or Uncentralizability?
It is common to hear the word “decentralized” thrown around in modern tech circles. But often, this is merely a marketing term for “slightly distributed centralization”. A blockchain with a few dominant miners, or a federated protocol with a few giant servers. *In practice*, it’s still centralized. It simply has a few centers instead of one.
Reticulum goes further. It wants **Uncentralizability**.
This is not a wishful political stance, but a foundational mathematical characteristic of the protocol, onto which everything else has been built. Reticulum assumes that every peer on the network is potentially hostile, and every link is potentially compromised. It is designed with no “privileged” nodes. While some nodes may act as Transport Instances - forwarding traffic for others - they do so *blindly*, and they only know about their immediate surroundings, and nothing more. They route based on cryptographic proofs, not on administrative privilege. They cannot see who is talking to whom, nor can they selectively manipulate traffic without breaking their own ability to route entirely.
The system is designed to make hierarchy structurally impossible. You cannot hijack an address, because there is no central registry to hijack. You cannot block a user, because there is no central switch to flip. You can offer paths through the network, but you can’t force anyone to use them.
### Death To The Address
To break free of the center, you must also let go of the concept of the “Address”.
In the IP world, an address is a location. It is a coordinate in a *deeply hierarchical* and static grid. If you move your computer to a different house, your address changes. If your router reboots, your address might change. Your *identity* is bound to your *location*, and therefore, it is fragile, and easily controlled.
Reticulum abolishes this link between *Identity* and *Location*.
In Reticulum, an address is not a place; it is a **Hash of an Identity**. It is a cryptographic representation of *who* you are, not *where* you are. Because of this, your address is portable. You can take a laptop from a WiFi cafe in Berlin, to a LoRa mesh in the mountains, to a packet radio link on a boat, and your “address” - your *Destination Hash* - never changes.
The network does not route to a place; it routes to a *person* (or a machine). When you send a packet, you are not targeting a coordinate in a grid; you are encrypting a message for a specific entity. The network dynamically discovers where that entity currently resides, and it does so in a way where no one really knows where that entity is actually located physically.
**Consider:**
- **The Old Way:** *“I am at* `192.168.1.5`. *Come find me”*.
- **The Zen Way:** *“I am* `<327c1b2f87c9353e01769b01090b18f2>`. *Wherever I am, my peers can reach me”*.
Once you stop thinking about servers and start thinking about portable identities, where everyone can always reach everyone else directly, the illusion of the center fades away. You realize there *is* no center holding the network together. No coordinators or bureaucrats required. The network is simply the sum of its peers, communicating directly, sovereignly, and without a master.
## Physics Of Trust
*Paranoia Is A Great Design Principle*
If we accept that there is no center - that the network is a chaotic, peer-to-peer mesh - we are forced to confront a terrifying reality: **There is no one guarding the door**.
In the traditional networking mindset, we rely on the concept of the “trusted core”. We assume our local coffee shop WiFi is safe, or that the backbone providers are neutral custodians. We build our security like a castle: strong walls on the outside, soft and trusting on the inside. We use encryption only when we step out into the “wild” internet.
### Hostile Environments
The Zen of Reticulum requires you to invert this. You must assume that *every* environment is hostile. This isn’t cynicism, just uncaring physics.
When you transmit information over radio waves, you are shouting into a crowded room. Anyone can listen. When you traverse the internet, your packets pass through routers controlled by strangers, corporations, and state actors. Assuming privacy in this environment without cryptographic protection is not optimism but gross negligence.
Reticulum is built on the premise that every link is tapped, and every peer is a potential adversary. If your system cannot survive an adversary owning the physical layer, it cannot survive at all.
But this is the paradox: By assuming the network is hostile, you make it safe. When you accept the dangers for what they are, they become manageable. When you stop trusting the infrastructure and start trusting the math, you eliminate the single point of failure: Human integrity.
### Encryption Is Not A Feature
In the world of TCP/IP, encryption is an afterthought. It is a layer we slap on top of the protocol (HTTPS, TLS) to patch the security holes of the original design. It is a “feature” you sometimes *enable* for “sensitive data”. This is fundamentally flawed, since all data is sensitive.
In Reticulum, encryption is **gravity**.
It is not optional. It is not a plugin. It is the *fundamental force that allows the network to exist*. If you were to strip the encryption from Reticulum, the routing would break. The Transport system uses cryptographic signatures and entropy to verify paths and pass information. If packets were plaintext, intermediate nodes could not prove that a route was valid, nor could endpoints prevent spoofing or tampering.
In Reticulum, the entropy of the encrypted packet *is* the routing logic.
To ask for a version of Reticulum without encryption is like asking for a version of the ocean without liquid. You are not asking for a feature change; you’re asking for a different physical universe. We design for a universe where information has mass, structure, and integrity.
### Zero-Trust Architectures
We must unlearn our reliance on **Institutional Trust**.
For decades, we have been trained to trust authorities. We trust a website because a chain of Certificate Authorities (companies we don’t know) vouches for it. We trust an app because it is in an app store (run by a corporation we don’t control). We trust a message because it comes from a phone number assigned by a telecom. Yet, everything in our digital information sphere today is more untrustworthy and risky than a medieval second-hand underwear market.
Reticulum replaces institutional trust with **Cryptographic Proof**.
In Reticulum, you do not trust a node because it has a nice hostname or because it is listed in a directory. You trust it because it holds the private key corresponding to the Destination Hash you are communicating with. This trust is binary, mathematical, and **absolute**. Either the signature matches, or it does not. There is no “maybe”.
This shift moves the power from the institution to the individual. You become the ultimate arbiter of your own trust relationships. You decide which keys to accept, which paths to follow, and which identities to recognize.
**Consider:**
- **The Old Way:** *“I trust this site because the browser says the lock icon is green”*.
- **The Zen Way:** *“I trust this destination because I have verified its hash fingerprint out-of-band, and the math confirms the signature”*.
When you internalize the Physics of Trust, you stop looking for protection from firewalls, VPNs, and Terms of Service agreements. You realize that true security comes from the design of the protocol itself. You can stop trusting the cloud, and you start trusting the code - because you can verify it yourself.
## Merits Of Scarcity
*Every Bit Counts*
We have grown addicted to abundance. In the modern digital ecosystem, bandwidth is treated as an endless, flat ocean. We stream high-definition video without a thought, we ship entire libraries of code just to render a single button, and we measure performance in gigabits per second. This abundance has hollowed out our craft. When constraints vanish, efficiency dies, and with it, a certain kind of Clarity and Quality.
Reticulum asks you to step out of the ocean and onto the tightrope.
### The Bandwidth Fallacy
The Zen of Reticulum requires the realization that **5 bits per second is a valid speed**.
To a modern developer, this sounds like paralysis. But there is a profound freedom in limits: When you have a gigabit connection, you can be incredibly sloppy. You can be wasteful. You can push your problems onto the infrastructure. *“It’s slow? Get a faster router”*.
But on a high-latency, low-bandwidth link (be it a noisy HF radio channel or a tenuous LoRa hop) you cannot push problems anywhere. You must solve them. The network does not negotiate with waste.
This forces a shift from consumption to interaction. You are no longer, then, consuming a service provided by a fat pipe; you are engaging in a careful negotiation with the physical medium. The medium becomes a partner in the conversation, not just a dumb conduit. You suddenly need to *understand the world to be in it*.
### Cost Of A Byte
In a scarce economy, a byte is not just data, but energy, time, and space.
Every byte you transmit consumes battery life on a solar-powered node. It occupies valuable airtime that could have been used by another peer. It represents a measurable slice of the electromagnetic spectrum.
When you internalize this, you begin to write code differently. You stop asking, “How much data can I send?” and start asking, “What is the *minimum* amount of information required to convey this intent? How can I best utilize my informational entropy?”
This is where the elegance of Reticulum shines. The protocol is designed to strip away the non-essential. A link establishment takes three very small packets. A destination hash fits in 16 bytes. The overhead is vanishingly small, leaving almost the entire channel for the message itself.
**Consider:**
- **The Old Way:** *“I need to send a status update. I’ll send a JSON object with metadata, timestamps, and user profile info (15KB).”*
- **The Zen Way:** *“I need to send a status update. I’ll send a single byte representing the state code. The context is already known.”*
This is of course optimization, but more importantly, *it is a form of respect*. Efficiency in a shared medium is an act of stewardship. By taking only what you need from the network, you leave room for others. The network listens to those who speak with purpose.
### Flow & Time
Scarcity also teaches us about time. We have become addicted to the *synchronous* now - the instant ping, the real-time stream. But Reticulum embraces *asynchronous* time.
When links are intermittent and latency is measured in minutes or hours, “real-time” is an illusion. Reticulum doesn’t encourage **Store and Forward** as a mere fallback, but as a primary mode of existence. You write a message, it propagates when it can, and it arrives when it arrives.
This changes the psychological texture of communication. It removes the anxiety of the immediate response. It allows for contemplation. You are not demanding the recipient’s attention *right now*; you are placing a gift in their path, to be found when they are ready.
By designing for delay, you design for resilience. You are no longer building a house of cards that collapses when a single packet drops. You are building a stone arch that distributes the load *over time*.
### Liberation From Limits
There is a strange optimism in scarcity. When you are forced to work within strict constraints, you are forced to prioritize. *You* must decide what truly matters. *That* is the real core of agency.
In the infinite fantasy world of The Cloud, everything is urgent, so nothing is. In the economy of Reticulum, the cost of transmission forces you to weigh the value of your message. Do you really need to send that heart beat? Is that photo essential?
When you strip away the noise, what remains is *signal*.
This discipline creates a different kind of developer. It creates a craftsman who understands that the best code is the code you don’t have to write. It creates a user who understands that the most powerful message is the one that is *understood*, not the one that is loudest. In the world of Reticulum, you are not a mere consumer of bandwidth; you are an architect of intent.
## Sovereignty Through Infrastructure
**Be Your Own Network**
We live in an era of digital tenancy. We lease our connectivity from ISPs. We rent our storage from cloud providers. We even borrow our identity from social media platforms. We are tenants in a house we did not build, governed by rules we did not write, subject to eviction at the whim of a landlord who has never met us.
The Zen of Reticulum is the realization that you *can* own the house.
### A Carrier-Grade Fallacy
For decades, we have been gaslit into believing that networking is really not just hard, but impossible. It is presented as a dark art reserved for telcos and billionaires, requiring millions of dollars of fiber optics, climate-controlled data centers, and armies of engineers. We are told that building reliable infrastructure is “too complex” for the individual or small organization.
This is a big, fat lie.
Physics is simple. A radio wave needs a transmitter and a receiver. A packet needs a path. The “complexity” of the modern internet is largely bureaucratic - a mountain of billing systems, regulatory capture, and legacy cruft designed to keep the gatekeepers in power.
Reticulum strips away the bureaucracy. It runs on hardware that costs the price of a dinner. It runs on spectrum that is free to use. It demonstrates that a robust, planetary-scale network does not require a Fortune 500 company. It requires only the will to deploy, and the distributed, uncoordinated efforts of many individuals.
### Personal Infrastructure
This is where the rubber meets the road. You can read about Reticulum, you can understand the theory, but the insights only arrive when you plug in a radio and run a Transport Node. Suddenly, you are no longer a consumer. You’re an operator.
This shift is subtle but profound. When you run your own infrastructure, the network ceases to be a service that is provided *to* you. It becomes a space that you *inhabit*. You become responsible for the flow of information. You gain an intimate understanding of the medium - the way the weather affects the radio waves, the way the topology changes, the way the packets dance through the ether.
There is a quiet competence that comes from this. You stop asking “Is the internet down?” and start asking “Is *my* links up?” You stop waiting for a technician and start checking the logs. This is a form of strength. To understand the system that carries your words is to be free from the mystery that keeps you dependent.
### The Ability To Disconnect
Why go to the trouble? Why buy the radio, write the config, and leave the Pi running in the corner?
Because the old, centralized network is fragile. And because most of us doesn’t even really want to be there anymore.
The internet we rely on today is a chain of single points of failure. Cut the undersea cable, and a continent goes dark. Shut down the power grid, and the cloud evaporates. Deprioritize the “wrong” traffic, and the flow of information is strangled.
Sovereignty is the ability to survive the cut, whether or not that cut was an accident or on purpose.
When you build your own infrastructure, you build a lifeline. Reticulum is designed to function over media that the traditional internet cannot touch - bare wires, battery-powered radios, ad-hoc WiFi meshes. When the grid fails, or the censors arrive, or the bill goes unpaid, your Reticulum network continues to hum.
This is not about “dropping out” of society. It is about building a substrate on which an actual *Society* can function.
**Consider:**
- **The Old Way:** “My connection is slow. I should call my ISP and complain.”
- **The Zen Way:** “The path is noisy. I will adjust the antenna or find a better route.”
By taking ownership of the infrastructure, you take ownership of your voice. You stop shouting into someone else’s megaphone and start building your own. The network is no longer something that happens to you; it is something you make happen.
## Identity and Nomadism
**A Fluid Self**
In the old world, you are defined by your coordinates. If you are at `34.109.71.5`, you’re *here*. If you unplug the cable and walk down the street, you vanish. Your digital self evaporates because it was tethered to the wall. You are a ghost in the endless machinations of gears, levers and transistors, bound to the hardware, and those that own it.
This creates a subtle, constant anxiety. We are terrified of disconnecting because, in the architecture of the old web, disconnecting is a kind of death.
The Zen of Reticulum offers a different way to be.
### Portable Existence
In Reticulum, your identity is not a location, or a username granted by a service. It is a cryptographic key - a complex, unique mathematical signature that exists independently of the physical world. You can carry it only in your mind, if you want to.
Think of it less like a street address and more like a name. *A true name*.
If you travel from Berlin to Tokyo, you do not change your name. You are still you. The people who know you can still recognize you. Reticulum applies this principle to the network layer. Your Destination Hash is **invariant**. It travels with you, stored securely on your device, *immutable as a stone*.
This changes the relationship between you and the machine. You are not “logged into” the network via a specific gateway. You *are* the endpoint. The network does not connect to a place; *it converges on you*.
### Roaming Nodes
This freedom introduces a new concept of time and space: **Nomadism**.
Because your identity is portable, your connectivity can be fluid. You can be sitting at a desk connected to a fiber backbone one moment, and walking through a field connected only to a long-range LoRa mesh the next. To the rest of the network, nothing has changed. Your friends do not need to update your contact info. The messages they send do not bounce back. The network senses the shift in the medium and reroutes the flow of data automatically.
You are no longer a stationary node in a fixed grid. You are a wanderer in a fluid medium.
The interfaces - whether it is WiFi, Ethernet, Packet Radio, or a physical wire - is merely the clothing your node wears. You change it to suit the environment. Underneath, you remain the same. This is the liberation of the protocol. It treats the physical medium as a transient circumstance, not a definition of self.
**Consider:**
- **The Old Way:** *“I lost connection. I have to reconnect to the VPN to tell them where I am now.”*
- **The Zen Way:** *“I moved. The network subtly bends to accomodate this new reality.”*
### Announcing Presence
How does the network find a wanderer? It listens.
In the IP world, we query directories. We ask a server, “Where is Mark?” The server checks its database and gives us a coordinate. This means that someone, somewhere, is keeping track of you. It assumes and *requires* surveillance.
Reticulum replaces surveillance with **Announces**.
Instead of asking a central authority where you are, you simply state your presence. You broadcast a cryptographic proof: “I am here, and I am who I say I am”. This ripples out through the mesh. Your neighbors hear it, update their path tables, and pass it on.
This is a quiet, organic process. It is the digital equivalent of lighting lanterns in the dark. You do not need to chase the light; you let the light find you. It respects your autonomy. You choose when to announce, how often to speak, and to whom. You also choose when to disappear - for but a moment or perpetually.
### Anchor In The Flow
There is a deep peace in this nomadism. It teaches you that stability does not come from standing still. Stability comes from *internal coherence*.
By holding your own private key, you hold your own center of gravity. The world around you; the infrastructure, the topography and the availability of links can all shift chaotically. Storms can knock out towers. Cables can be cut. The internet can go down.
But as long as you possess your key, you possess your identity. The entire infrastructure can be destroyed and rebuilt, and you are still you. Nothing lasts, yet nothing is lost.
You become a sovereign entity moving through the noise, connected not by the rigidity of cables, but by the fluidity of recognition. The network becomes a place you inhabit, rather than a utility you subscribe to: You are at home in the ether.
## Ethics Of The Tool
**Technology With Conscience**
You have unlearned the center. You have accepted the physics of trust. You have embraced the economy of scarcity and the freedom of unbound nomadism. You are standing in a new space. Now, look at the tool in your hand.
In the old world, we were taught that technology is neutral. We are told that “guns don’t kill people, people do”, or that a component is just a component, indifferent to what its combinatorial potential is. This is a convenient lie. It serves only to allow the builders to wash their hands of responsibility.
But we know better now. We know that **architecture is politics**, and *politics is control*. The way you build a system determines how it will be used. If you build a system optimized for mass surveillance, you *will* get a panopticon. If you build a system optimized for centralized control, you *will* get a dictatorship. If you build a system optimized for extraction, you *will* get a parasite.
The Zen of Reticulum asserts that a tool is never neutral.
On the very contrary: A tool is intent, **crystallized**.
### The Harm Principle
Why does the Reticulum License forbid the software from being used in systems designed to harm humans? Is it not just a restriction on freedom?
It is a restriction on *license*, yes, but it is an expansion of *freedom*.
Building powerful tools without a moral compass is in no way virtuous or commendable, it is plain and simple irresponsibility.
A tool that can easily be used to oppress is a real danger to the user. If you build a network that can be turned against you by a tyrant, you are not free. You are merely waiting for the leash to tighten. By encoding the “Harm Principle” into the legal DNA of the reference implementation, we are building a safeguard. We are stating, clearly and immutably, that *this tool* is for **life**, not for death.
This aligns the software with the interests of humanity. It cements that the network cannot be conscripted into a kill-system, a weaponized drone controller, or a torture device without breaking the license and the law. It is a line drawn in the sand - not by a government or external authority, but by the creators of the tool itself.
**Consider:**
- **The Old Way:** *“It’s just software. How people use it is not my problem.”*
- **The Zen Way:** *“This software is a habitat. I will not allow it to be used to build a cage.”*
It is *your* choice whether to align with this - we are not forcing this stance on anyone. If you choose to align with life over death, with creativity over destruction, we grant you an immensely powerful tool, to own and build with as you please. If you do not, we deny it.
If you do not like this, we most assuredly do not need you here, and you are on your own.
### Public Domain Protocol
This leads to a vital distinction: The difference between the *idea* and the *implementation*.
The protocol - the mathematical rules of how Reticulum works - is dedicated to the Public Domain. It belongs to humanity. **No one can own it**. Anyone can implement it, improve it, or adapt it. This is the core idea of free communication, which itself must be forever free.
But the functional, deployed *reference implementation* - the Python code, the maintenance, the years of labor - has a conscience. This distinction is the engine of sustainability. It allows the protocol to be universal, while ensuring that the specific labor of the builders is not hijacked to undermine the foundational intent of the project itself. From this document, it should be very clear what this intent is.
If you want to build a system with Reticulum that manipulates and damages users for profits or targets missiles, you can use the public domain protocol, and start from scratch. But you cannot take our work. You must do your own. This serves as a pillar of accountability. If you want to build a weapon, *you* go and forge the steel yourself, while the world observes. And when the blood is drawn - it is on **your** hands.
### Preserving Human Agency
We live in an era of predatory extraction. The open-source commons is being scraped, ingested, and regurgitated by machine learning algorithms, whose corporate owners seek to replace the very humans who built those commons. Our code, our words, and our creativity is being used to train systems that are specifically designed to make us obsolete, without offering anything else in return than serfdom and leashes.
Reticulum stands against this.
The license protects the software from being used to feed the beast. It draws a hard line: This tool is for *people*. It is for human-to-human connection. It is not a dataset to be strip-mined for the purpose of building a synthetic overlord, puppeteered by a miniscule conglomerate of controllers.
This is a radical act of preservation. By protecting the code from AI appropriation, we are protecting space for human agency. We are ensuring that there remains a digital realm where the actors are flesh, blood and soul, where decisions are made by minds, not overlords hiding behind models.
When you use Reticulum, you are using a tool that respects you. It does not see you as a product to be tracked. It does not see your data as fuel for an algorithm. It sees you as a sovereign, equal peer.
This changes the foundational premise of using the technology. It restores dignity to the interaction. You are not the user of a service; you are a participant in a mutual covenant. The tool aligns with your autonomy, rather than eroding it.
In this way, ethics is not a restriction, but a foundation. It is the foundation that helps ensure the network will still belong to you tomorrow.
## Design Patterns For Post-IP Systems
**Practical Philosophy for Developers**
The philosophy is useless if it cannot be hammered into code. The metaphors we have explored - nomadism, scarcity, trust - are not just poetry, but real-world engineering constraints. When you sit down to write software for Reticulum, these concepts must shape the very structure of your application.
We are now moving from the *why* to the *how*. This is where the abstract becomes concrete, and where you will see the true depth of the patterns we have been weaving.
### Store & Forward
The web has trained us to be impatient. We write synchronous code. We fire a request and we wait, blocking the UI, holding our breath. If the response doesn’t come in 250 milliseconds, we show a spinner. If it doesn’t come in five seconds, we show an error. We treat network connectivity as a binary state: either we are “online” or we are “broken”.
This is brittle. It is a rejection of reality.
In Reticulum, connectivity is a spectrum, and presence is asynchronous. If at all applicable to your intent, you must design your applications to embrace **Store & Forward**.
Instead of demanding an immediate answer, your application should act as a patient participant. You create a message for someone or something in the mesh. The network holds it. It carries it from node to node, perhaps over hours or days, waiting for the recipient to appear. When they finally surface, the message is delivered. This requires a shift from “request/response” to “event/handler”. How exactly you do this is a challenge for you to solve intelligently within your problem domain, but Reticulum-based systems already exist that does this extremely well, and you can use them for inspiration.
**Consider:**
- **The Old Way:** `Connect() -> Send() -> Wait() -> Crash if timeout.`
- **The Zen Way:** `Send() -> Continue living. -> Receive() when it arrives.`
This changes the user experience profoundly. It removes the anxiety of the loading bar. It creates a sense of continuity. The user is not “waiting for the network”; they are interacting with a persistent log of communication that lives in the network itself.
### Naming Is Power
In the IP world, we are slaves to the Domain Name System. We rely on a hierarchy of registrars to map human-readable names to machine-readable addresses. This hierarchy is a choke point. If the registrar revokes your domain, or if the DNS server goes down, you vanish.
Reticulum dissolves this hierarchy with **Hash-based Identity**.
In this design pattern, a name is not a string you look up; it is a cryptographic destination you verify. When you design for Reticulum, you stop asking the user for a URL and start asking for a Destination or Identity Hash.
This feels strange at first. A hash like `<83b7328926fed0d2e6a10a7671f9e237>` looks alien compared to `myfriend.com`. But that alienness is the armor. It **cannot** be spoofed. It **cannot** be censored by a registrar. It is **absolute**.
Designing for this means shifting your UI metaphors. You are no longer browsing a web of pages; you are managing a ledger of keys. You are building an “Address Book” that is actually a keyring. The names are given by the user, and the power stays with them. That hashes look complex is directly analogous to the strengths of the bonds formed by their use. It forces the user to engage in a moment of verification, an out-of-band handshake, which restores the human element of trust that SSL certificates stripped away.
### The Interface Is The Medium
One of the most liberating patterns in Reticulum is **Transport Agnosticism**.
In traditional networking, your code is often littered with transport logic. “Am I on WiFi? Check bandwidth. Am I on Cellular? Check data plan. Am I on Ethernet?”. You are constantly micromanaging the pipe.
In Reticulum, you write to the API, and the API writes to the medium. You send a packet to a Destination. You do not care if that packet travels over a TCP tunnel, a LoRa radio wave, or a serial wire interface. That is the stack’s concern.
This allows you to write **Universal Applications**.
Imagine a messaging app. You write it once. It works on a laptop connected to fiber. It works on a phone in the city using WiFi. And, without a single line of code changed, it works on a device in the wilderness, talking only to other devices via radio.
The pattern is simple: **Never code to the hardware. Code to the intent.**
**Consider:**
- **The Old Way:** `socket.connect(ip, port)`, and then a whole lot more
- **The Zen Way:** `RNS.Packet(destination, data).send()`
By abstracting the medium, you make your software immortal to changes in infrastructure. The user might switch from a 4G hotspot to a HF modem tomorrow. Your software doesn’t need to know. It simply continues the conversation.
### Emergent Patterns
When you combine these patterns - *Store & Forward*, *Hash-based Identity*, and *Transport Agnosticism* - you create software that feels fundamentally different.
It feels *grounded*. It doesn’t flicker when the signal drops. It doesn’t panic when the server is down. It has weight. It has persistence. It has *relevance*.
You are no longer building a “client” that begs a “server” for attention. You are building an autonomous agent that exists within the mesh. It speaks when it needs to, listens when it can, and carries its identity with it wherever it goes.
This is the culmination of the Zen. The code is not just a set of instructions: It is a behavioral envelope. It is a way of *being* in the network.
## Fabric Of The Independent
We have stripped away the illusions. We have seen that the center is empty, that trust *must* be hard, that resources are finite, and that we must own our infrastructure. We have seen that tools have ethics and that our identity can move fluidly.
This is a reclaiming of the commons. For too long, we have allowed the most vital substrate of human society - *our ability to speak to one another* - to be colonized by entities that do not share our interests. We have allowed the architecture of our communication to be designed by accountants rather than architects.
We are taking it back. Not by petitioning the masters, but by building the new world within, over, under and around the shell of the old.
### The Work Is Finished
The heavy lifting is done.
The protocol is in the public domain, a gift to humanity that can never be taken away. The software is written, tested, and running on devices scattered across the globe. The manual lies open before you. The source code for the reference implementation is now distributed on hundreds of thousands of devices across the planet. No one can delete or destroy it. The hardware is accessible and abundant.
It was a hard road to get here, but we got here. Now, there is no roadmap committee waiting for approval. There is no venture capital dictating the user experience. There is no CEO to sign off on the next feature release.
There is only you.
The barrier to entry is no longer complexity: It is the mere habit of dependency. You were conditioned to wait. Wait for the app update. Wait for the ISP to fix the line. Wait for the platform to allow the post. Wait for the government to change the policies. Wait for the likes. Wait for the revolution to be televised.
The revolution never was televised.
It is packetized.
### Open Sky
The future of this technology is a construction project.
It looks like a single node on a windowsill, listening to the static. It looks like a message sent to a neighbor, bypassing the noise of the commercial web. It looks like a community mesh that grows, link by link, hop by hop, carried by hands that care more about connection than profit.
You have the blueprints. You have the tools. You have the philosophy. The noise of the old world has fallen away, leaving you with the quiet clarity of the open spectrum.
*Mark, early 2026*