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

Updated docs

Browse Source
This commit is contained in:
Mark Qvist
2026-04-20 11:38:14 +02:00
parent 294408b0bb
commit ce5ab902b6
90 changed files with 27271 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/manual/_sources/examples.rst.txt
+142
View File
@@ -0,0 +1,142 @@
.. _examples-main:
*************
Code Examples
*************
A number of examples are included in the source distribution of Reticulum.
You can use these examples to learn how to write your own programs.
.. _example-minimal:
Minimal
=======
The *Minimal* example demonstrates the bare-minimum setup required to connect to
a Reticulum network from your program. In about five lines of code, you will
have the Reticulum Network Stack initialised, and ready to pass traffic in your
program.
.. literalinclude:: ../../Examples/Minimal.py
This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Minimal.py>`_.
.. _example-announce:
Announce
========
The *Announce* example builds upon the previous example by exploring how to
announce a destination on the network, and how to let your program receive
notifications about announces from relevant destinations.
.. literalinclude:: ../../Examples/Announce.py
This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Announce.py>`_.
.. _example-broadcast:
Broadcast
=========
The *Broadcast* example explores how to transmit plaintext broadcast messages
over the network.
.. literalinclude:: ../../Examples/Broadcast.py
This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Broadcast.py>`_.
.. _example-echo:
Echo
====
The *Echo* example demonstrates communication between two destinations using
the Packet interface.
.. literalinclude:: ../../Examples/Echo.py
This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Echo.py>`_.
.. _example-link:
Link
====
The *Link* example explores establishing an encrypted link to a remote
destination, and passing traffic back and forth over the link.
.. literalinclude:: ../../Examples/Link.py
This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Link.py>`_.
.. _example-identify:
Identification
==============
The *Identify* example explores identifying an intiator of a link, once
the link has been established.
.. literalinclude:: ../../Examples/Identify.py
This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Identify.py>`_.
.. _example-request:
Requests & Responses
====================
The *Request* example explores sending requests and receiving responses.
.. literalinclude:: ../../Examples/Request.py
This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Request.py>`_.
.. _example-channel:
Channel
=======
The *Channel* example explores using a ``Channel`` to send structured
data between peers of a ``Link``.
.. literalinclude:: ../../Examples/Channel.py
This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Channel.py>`_.
Buffer
======
The *Buffer* example explores using buffered readers and writers to send
binary data between peers of a ``Link``.
.. literalinclude:: ../../Examples/Buffer.py
This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Buffer.py>`_.
.. _example-filetransfer:
Filetransfer
============
The *Filetransfer* example implements a basic file-server program that
allow clients to connect and download files. The program uses the Resource
interface to efficiently pass files of any size over a Reticulum :ref:`Link<api-link>`.
.. literalinclude:: ../../Examples/Filetransfer.py
This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py>`_.
.. _example-custominterface:
Custom Interfaces
=================
The *ExampleInterface* demonstrates creating custom interfaces for Reticulum.
Any number of custom interfaces can be loaded and utilised by Reticulum, and
will be fully on-par with natively included interfaces, including all supported
:ref:`interface modes<interfaces-modes>` and :ref:`common configuration options<interfaces-options>`.
.. literalinclude:: ../../Examples/ExampleInterface.py
This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/ExampleInterface.py>`_.
docs/manual/_sources/forhumans.rst.txt
+4
View File
@@ -0,0 +1,4 @@
********************************************
An Explanation of Reticulum for Human Beings
********************************************
docs/manual/_sources/gettingstartedfast.rst.txt
+731
View File
@@ -0,0 +1,731 @@
********************
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:
.. code:: 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``:
.. code:: 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.
.. code:: shell
pip install rns --break-system-packages
For more detailed installation instructions, please see the
:ref:`Platform-Specific Install Notes<install-guides>` section.
After installation is complete, it might be helpful to refer to the
:ref:`Using Reticulum on Your System<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:
.. code:: 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 :ref:`range of different
programs <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
:ref:`Using Reticulum on Your System<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 (:ref:`AutoInterface<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 :ref:`Building Networks<networks-main>`
and :ref:`Interfaces<interfaces-main>` chapters of this manual, but most importantly,
start with reading the next section, :ref:`Bootstrapping Connectivity<bootstrapping-connectivity>`,
as this provides the most essential understanding of how to ensure reliable
connectivity with a minimum of maintenance.
.. _bootstrapping-connectivity:
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 :ref:`interface discovery<using-interface_discovery>` and either manually select relevant, local interfaces, or enable discovered interface auto-connection.
A relevant option in this context is the :ref:`bootstrap only<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 :ref:`Blackhole Management<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 :ref:`Public Entrypoint<hosting-entrypoints>`. By :ref:`publishing your interface as discoverable<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 :ref:`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/>`_.
.. tip::
Don't rely on just a single connection to the distributed backbone for everyday use. It is much better to have several redundant connections configured, and enable the interface discovery options, so your nodes can continously discover peering opportunities as the network evolves. Refer to the :ref:`Bootstrapping Connectivity<bootstrapping-connectivity>` section to understand the options.
.. _hosting-entrypoints:
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 :ref:`make it discoverable over Reticulum<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.
.. code:: 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 can be
# a good idea to configure sensible announce
# rate targets.
announce_rate_target = 3600
announce_rate_penalty = 3600
announce_rate_grace = 12
If instead you want to make a private entry-point from the Internet, you can use the
:ref:`IFAC name and passphrase options<interfaces-options>` to secure your interface with a network name and passphrase.
.. code:: 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: :ref:`Backbone<interfaces-backbone>`, :ref:`TCP<interfaces-tcps>`
and :ref:`I2P<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
:ref:`Interfaces<interfaces-main>` section of this manual.
If you do not already have transceiver hardware available, you can easily and
cheaply build an :ref:`RNode<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 :ref:`Communications Hardware<hardware-main>` chapter for a guide.
If you prefer purchasing a ready-made unit, you can refer to the
:ref:`list of suppliers<rnode-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
:ref:`existing interface types<interfaces-main>`, it is easy to write (and potentially
publish) a :ref:`custom interface module<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 :ref:`Configuring Interfaces<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:
.. code::
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 :ref:`Example Programs<examples-main>`.
The entire Reticulum API is documented in the :ref:`API Reference<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 :ref:`Understanding Reticulum<understanding-main>` chapter.
.. _install-guides:
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:
.. code:: 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:
.. code:: 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.
.. code:: 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.
.. code:: 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:
.. code:: 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:
.. code:: 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:
.. code:: 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:
.. code:: 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:
.. code:: 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`.
.. code:: 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.
.. code:: 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.
.. code:: 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:
.. code:: 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:
.. code:: 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:
.. code:: 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 :ref:`Cryptographic Primitives <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/manual/_sources/hardware.rst.txt
+375
View File
@@ -0,0 +1,375 @@
.. _hardware-main:
***********************
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 :ref:`interface types<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 :ref:`PipeInterface<interfaces-pipe>` or the :ref:`TCPClientInterface<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 :ref:`custom interface modules<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.
.. _rnode-main:
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.
.. _rnode-creating:
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 :ref:`supported development boards<rnode-supported>`
2. Install the RNode firmware with the :ref:`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 :ref:`RNodeInterface<interfaces-rnode>`
to the configuration.
.. _rnode-supported:
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
:width: 75%
:align: center
LilyGO T-Beam Supreme
"""""""""""""
- **Transceiver IC** Semtech SX1262 or SX1268
- **Device Platform** ESP32
- **Manufacturer** `LilyGO <https://lilygo.cn>`_
------------
.. image:: graphics/board_tbeam.png
:width: 75%
:align: center
LilyGO T-Beam
"""""""""""""
- **Transceiver IC** Semtech SX1262, SX1268, SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** `LilyGO <https://lilygo.cn>`_
------------
.. image:: graphics/board_t3s3.png
:width: 50%
:align: center
LilyGO T3S3
"""""""""""
- **Transceiver IC** Semtech SX1262, SX1268, SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** `LilyGO <https://lilygo.cn>`_
------------
.. image:: graphics/board_rak4631.png
:width: 45%
:align: center
RAK4631-based Boards
""""""""""""""""""""
- **Transceiver IC** Semtech SX1262 or SX1268
- **Device Platform** nRF52
- **Manufacturer** `RAK Wireless <https://www.rakwireless.com>`_
------------
.. image:: graphics/board_opencomxl.png
:width: 45%
:align: center
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
:width: 68%
:align: center
Unsigned RNode v2.x
"""""""""""""""""""
- **Transceiver IC** Semtech SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** `unsigned.io <https://unsigned.io>`_
------------
.. image:: graphics/board_t3v21.png
:width: 46%
:align: center
LilyGO LoRa32 v2.1
""""""""""""""""""
- **Transceiver IC** Semtech SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** `LilyGO <https://lilygo.cn>`_
------------
.. image:: graphics/board_t3v20.png
:width: 46%
:align: center
LilyGO LoRa32 v2.0
""""""""""""""""""
- **Transceiver IC** Semtech SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** `LilyGO <https://lilygo.cn>`_
------------
.. image:: graphics/board_t3v10.png
:width: 46%
:align: center
LilyGO LoRa32 v1.0
""""""""""""""""""
- **Transceiver IC** Semtech SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** `LilyGO <https://lilygo.cn>`_
------------
.. image:: graphics/board_tdeck.png
:width: 45%
:align: center
LilyGO T-Deck
"""""""""""""
- **Transceiver IC** Semtech SX1262 or SX1268
- **Device Platform** ESP32
- **Manufacturer** `LilyGO <https://lilygo.cn>`_
------------
.. image:: graphics/board_techo.png
:width: 45%
:align: center
LilyGO T-Echo
"""""""""""""
- **Transceiver IC** Semtech SX1262 or SX1268
- **Device Platform** nRF52
- **Manufacturer** `LilyGO <https://lilygo.cn>`_
------------
.. image:: graphics/board_t114.png
:width: 58%
:align: center
Heltec T114
"""""""""""
- **Transceiver IC** Semtech SX1262 or SX1268
- **Device Platform** nRF52
- **Manufacturer** `Heltec Automation <https://heltec.org>`_
------------
.. image:: graphics/board_heltec32v4.png
:width: 58%
:align: center
Heltec LoRa32 v4.0
""""""""""""""""""
- **Transceiver IC** Semtech SX1262
- **Device Platform** ESP32
- **Manufacturer** `Heltec Automation <https://heltec.org>`_
------------
.. image:: graphics/board_heltec32v30.png
:width: 58%
:align: center
Heltec LoRa32 v3.0
""""""""""""""""""
- **Transceiver IC** Semtech SX1262 or SX1268
- **Device Platform** ESP32
- **Manufacturer** `Heltec Automation <https://heltec.org>`_
------------
.. image:: graphics/board_heltec32v20.png
:width: 58%
:align: center
Heltec LoRa32 v2.0
""""""""""""""""""
- **Transceiver IC** Semtech SX1276 or SX1278
- **Device Platform** ESP32
- **Manufacturer** `Heltec Automation <https://heltec.org>`_
------------
.. _rnode-installation:
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``:
.. code::
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:
.. code::
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.
.. _rnode-usage:
Usage with Reticulum
^^^^^^^^^^^^^^^^^^^^
When the devices have been installed and provisioned, you can use them with Reticulum
by adding the :ref:`relevant interface section<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 :ref:`AutoInterface<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.
.. only:: html
.. image:: graphics/radio_rblhg5.png
:width: 49%
.. image:: graphics/radio_is5ac.png
:width: 49%
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
:ref:`AutoInterface<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
:ref:`SerialInterface<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/manual/_sources/index.rst.txt
+46
View File
@@ -0,0 +1,46 @@
******************************
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.
.. only:: builder_html
This manual is also available in `PDF <https://github.com/markqvist/Reticulum/releases/latest/download/Reticulum.Manual.pdf>`_ and `EPUB <https://github.com/markqvist/Reticulum/releases/latest/download/Reticulum.Manual.epub>`_ formats.
.. only:: builder_html
Table Of Contents
=================
.. toctree::
:maxdepth: 3
whatis
gettingstartedfast
zen
software
using
understanding
hardware
interfaces
networks
support
examples
license
.. toctree::
:maxdepth: 2
reference
.. only:: html
Indices and Tables
==================
* :ref:`genindex`
* :ref:`search`
docs/manual/_sources/interfaces.rst.txt
+1404
View File
File diff suppressed because it is too large Load Diff
docs/manual/_sources/license.rst.txt
+36
View File
@@ -0,0 +1,36 @@
.. _license:
Reticulum License
=================
.. code:: 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/manual/_sources/networks.rst.txt
+350
View File
@@ -0,0 +1,350 @@
.. _networks-main:
*****************
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.
* | 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.
* | 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.
* | Reticulum provides sender/initiator anonymity by default. There is no way
to filter traffic or discriminate it based on the source of the traffic.
* | 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.
* | 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.
* | 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.
*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.
* | 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
:ref:`Common Interface Options<interfaces-options>` section of the :ref:`Interfaces<interfaces-main>`
chapter of this manual for information on how to set up interface authentication.
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 :ref:`Supported Interfaces<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/manual/_sources/reference.rst.txt
+214
View File
@@ -0,0 +1,214 @@
:tocdepth: 4
.. _api-main:
*************
API Reference
*************
Communication over Reticulum networks is achieved by using a simple set of classes exposed by the RNS API.
This chapter lists and explains all classes exposed by the Reticulum Network Stack API, along with their method signatures and usage. It can be used as a reference while writing applications that utilise Reticulum, or it can be read in entirity to gain an understanding of the complete functionality of RNS from a developers perspective.
.. _api-reticulum:
.. only:: html
|start-h3| Reticulum |end-h3|
.. only:: latex
Reticulum
---------
.. autoclass:: RNS.Reticulum
:members:
.. _api-identity:
.. only:: html
|start-h3| Identity |end-h3|
.. only:: latex
Identity
--------
.. autoclass:: RNS.Identity
:members:
.. _api-destination:
.. only:: html
|start-h3| Destination |end-h3|
.. only:: latex
Destination
-----------
.. autoclass:: RNS.Destination
:members:
.. _api-packet:
.. only:: html
|start-h3| Packet |end-h3|
.. only:: latex
Packet
------
.. autoclass:: RNS.Packet(destination, data, create_receipt = True)
:members:
.. _api-packetreceipt:
.. only:: html
|start-h3| Packet Receipt |end-h3|
.. only:: latex
Packet Receipt
--------------
.. autoclass:: RNS.PacketReceipt()
:members:
.. _api-link:
.. only:: html
|start-h3| Link |end-h3|
.. only:: latex
Link
----
.. autoclass:: RNS.Link(destination, established_callback=None, closed_callback = None)
:members:
.. _api-requestreceipt:
.. only:: html
|start-h3| Request Receipt |end-h3|
.. only:: latex
Request Receipt
---------------
.. autoclass:: RNS.RequestReceipt()
:members:
.. _api-resource:
.. only:: html
|start-h3| Resource |end-h3|
.. only:: latex
Resource
--------
.. autoclass:: RNS.Resource(data, link, advertise=True, auto_compress=True, callback=None, progress_callback=None, timeout=None)
:members:
.. _api-channel:
.. only:: html
|start-h3| Channel |end-h3|
.. only:: latex
Channel
-------
.. autoclass:: RNS.Channel.Channel()
:members:
.. _api-messsagebase:
.. only:: html
|start-h3| MessageBase |end-h3|
.. only:: latex
MessageBase
-----------
.. autoclass:: RNS.MessageBase()
:members:
.. _api-buffer:
.. only:: html
|start-h3| Buffer |end-h3|
.. only:: latex
Buffer
------
.. autoclass:: RNS.Buffer
:members:
.. _api-rawchannelreader:
.. only:: html
|start-h3| RawChannelReader |end-h3|
.. only:: latex
RawChannelReader
----------------
.. autoclass:: RNS.RawChannelReader
:members: __init__, add_ready_callback, remove_ready_callback
.. _api-rawchannelwriter:
.. only:: html
|start-h3| RawChannelWriter |end-h3|
.. only:: latex
RawChannelWriter
----------------
.. autoclass:: RNS.RawChannelWriter
:members: __init__
.. _api-transport:
.. only:: html
|start-h3| Transport |end-h3|
.. only:: latex
Transport
---------
.. autoclass:: RNS.Transport
:members:
.. |start-h3| raw:: html
<h3>
.. |end-h3| raw:: html
</h3>
docs/manual/_sources/software.rst.txt
+355
View File
@@ -0,0 +1,355 @@
.. _software-main:
************************
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.
.. raw:: latex
\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
:target: 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>`_.
.. raw:: latex
\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.
.. only:: html
.. image:: screenshots/sideband_devices.webp
:align: center
:target: https://unsigned.io/sideband
.. only:: latex
.. image:: screenshots/sideband_devices.png
:align: center
:target: https://unsigned.io/sideband
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.
.. raw:: latex
\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.
.. only:: html
.. image:: screenshots/meshchatx.webp
:align: center
:target: https://git.quad4.io/RNS-Things/MeshChatX
.. only:: latex
.. image:: screenshots/meshchatx.png
:align: center
:target: https://git.quad4.io/RNS-Things/MeshChatX
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.
.. raw:: latex
\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.
.. only:: html
.. image:: screenshots/meshchat_1.webp
:align: center
:target: https://github.com/liamcottle/reticulum-meshchat
.. only:: latex
.. image:: screenshots/meshchat_1.png
:align: center
:target: https://github.com/liamcottle/reticulum-meshchat
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.
.. only:: html
.. image:: screenshots/columba.webp
:align: center
:width: 25%
:target: https://github.com/torlando-tech/columba/
.. only:: latex
.. image:: screenshots/columba.png
:align: center
:width: 25%
:target: https://github.com/torlando-tech/columba/
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.
.. raw:: latex
\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.
.. only:: html
.. image:: screenshots/retibbs.webp
:align: center
:target: https://github.com/kc1awv/RetiBBS
.. only:: latex
.. image:: screenshots/retibbs.png
:align: center
:target: https://github.com/kc1awv/RetiBBS
RetiBBS allows users to communicate through message boards in a secure manner.
.. raw:: latex
\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.
.. only:: html
.. image:: screenshots/rbrowser.webp
:align: center
:target: https://github.com/fr33n0w/rBrowser
.. only:: latex
.. image:: screenshots/rbrowser.png
:align: center
:target: https://github.com/fr33n0w/rBrowser
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.
.. raw:: latex
\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.
.. only:: html
.. image:: screenshots/rnphone.webp
:align: center
:target: https://github.com/markqvist/LXST
.. only:: latex
.. image:: screenshots/rnphone.jpg
:align: center
:target: https://github.com/markqvist/LXST
It supports interfacing directly with hardware peripherals such as GPIO keypads and LCD displays, providing a modular system for building secure hardware telephones.
.. raw:: latex
\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.
.. only:: html
.. image:: screenshots/lxst_phone.webp
:align: center
:target: https://github.com/kc1awv/lxst_phone
.. only:: latex
.. image:: screenshots/lxst_phone.png
:align: center
:target: https://github.com/kc1awv/lxst_phone
It supports various advanced features such as SAS verification, peer blocking, rate limiting, encrypted call history storage and contact management.
.. raw:: latex
\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.
.. raw:: latex
\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/manual/_sources/support.rst.txt
+60
View File
@@ -0,0 +1,60 @@
.. _support-main:
*****************
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:
.. code:: 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/manual/_sources/understanding.rst.txt
+1011
View File
File diff suppressed because it is too large Load Diff
docs/manual/_sources/using.rst.txt
+1227
View File
File diff suppressed because it is too large Load Diff
docs/manual/_sources/whatis.rst.txt
+203
View File
@@ -0,0 +1,203 @@
******************
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
:ref:`Zen of Reticulum <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 :ref:`Reticulum License <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 :ref:`implement an interface class<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 :ref:`custom interface modules<interfaces-custom>` written in Python
For a full list and more details, see the :ref:`Supported Interfaces<interfaces-main>` chapter.
docs/manual/_sources/zen.rst.txt
+453
View File
@@ -0,0 +1,453 @@
.. _zen:
****************
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*