markqvist/Reticulum
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated docs

Browse source
This commit is contained in:
Mark Qvist 2026-01-04 00:00:02 +01:00
parent 15a123875f
commit 58a20fffb5
11 changed files with 735 additions and 219 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/manual/.buildinfo
View file

@ -1,4 +1,4 @@
# Sphinx build info version 1 # Sphinx build info version 1
# This file records the configuration used when building these files. When it is not found, a full rebuild will be done. # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
config: c3849c16b3b83f052a917bd19fa2d896 config: e189c8207645fa72ffb805cde7491052
tags: 645f666f9bcd5a90fca523b33c5a78b7 tags: 645f666f9bcd5a90fca523b33c5a78b7

311
docs/manual/_sources/networks.rst.txt
View file

@ -4,17 +4,47 @@
Building Networks Building Networks
***************** *****************
This chapter will provide you with the knowledge needed to build networks with This chapter will provide you with the high-level knowledge needed to build networks with
Reticulum, which can often be easier than using traditional stacks, since you Reticulum. It will not, however tell you all you need to know to succesfully
don't have to worry about coordinating addresses, subnets and routing for an 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 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 Reticulum, you can simply add more segments to your network when it becomes
necessary, and Reticulum will handle the convergence of the entire network necessary, and Reticulum will handle the convergence of the entire network
automatically. 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 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 There are important points that need to be kept in mind when building networks
with Reticulum: with Reticulum:
@ -31,6 +61,11 @@ with Reticulum:
interconnect with much larger and higher bandwidth networks without issue. interconnect with much larger and higher bandwidth networks without issue.
Reticulum automatically manages the flow of information to and from various Reticulum automatically manages the flow of information to and from various
network segments, and when bandwidth is limited, local traffic is prioritised. 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 * | Reticulum provides sender/initiator anonymity by default. There is no way
to filter traffic or discriminate it based on the source of the traffic. to filter traffic or discriminate it based on the source of the traffic.
@ -89,81 +124,227 @@ Any number of interfaces can be configured, and Reticulum will automatically
decide which are suitable to use in any given situation, depending on where decide which are suitable to use in any given situation, depending on where
traffic needs to flow. traffic needs to flow.
Example Scenarios Destinations, Not Addresses
----------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^
This section illustrates a few example scenarios, and how they would, in general In traditional networking, addresses are allocated from a managed space. If you want to
terms, be planned, implemented and configured. 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.
Interconnected LoRa Sites 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>``.
An organisation wants to provide communication and information services to it's The critical difference is that *any node can generate as many destinations as it
members, which are located mainly in three separate areas. Three suitable hill-top needs, without coordination*. A destination's uniqueness is guaranteed by the
locations are found, where the organisation can install equipment: Site A, B and C. 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.
Since the amount of data that needs to be exchanged between users is mainly text- This has profound implications for network design:
based, the bandwidth requirements are low, and LoRa radios are chosen to connect
users to the network.
Due to the hill-top locations found, there is radio line-of-sight between site A * **No address allocation planning:** You never need to reserve address ranges,
and B, and also between site B and C. Because of this, the organisation does not plan subnets, or coordinate with other network operators. Nodes simply generate
need to use the Internet to interconnect the sites, but purchases four Point-to-Point destinations and announce them.
WiFi based radios for interconnecting the sites.
At each site, a Raspberry Pi is installed to function as a gateway. A LoRa radio * **Global portability:** A destination is not tied to a physical location or
is connected to the Pi with a USB cable, and the WiFi radio is connected to the network segment. A node can move its destinations across interfaces, mediums,
Ethernet port of the Pi. At site B, two WiFi radios are needed to be able to reach or even between entirely separate Reticulum networks simply by sending an
both site A and site C, so an extra Ethernet adapter is connected to the Pi in announce on the new medium.
this location.
Once the hardware has been installed, Reticulum is installed on all the Pis, and at * **Implicit authentication:** Because destinations are bound to public keys,
site A and C, one interface is added for the LoRa radio, as well as one for the WiFi communication to a destination is inherently cryptographically authenticated.
radio. At site B, an interface for the LoRa radio, and one interface for each WiFi Only the holder of the corresponding private key can decrypt and respond to
radio is added to the Reticulum configuration file. The transport node option is traffic addressed to that destination. This also makes application-level
enabled in the configuration of all three gateways. authentication *much* simpler, since it can directly use the foundational
identity verification built into the core networking layer.
The network is now operational, and ready to serve users across all three areas. * **Identity abstraction:** A single Reticulum Identity can create multiple
The organisation prepares a LoRa radio that is supplied to the end users, along destinations. This allows a single entity (a person, a device, a service) to
with a Reticulum configuration file, that contains the right parameters for present multiple endpoints without needing multiple cryptographic keypairs.
communicating with the LoRa radios installed at the gateway sites.
Once users connect to the network, anyone will be able to communicate with anyone
else across all three sites.
Bridging Over the Internet Transport Nodes and Instances
========================== ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As the organisation grows, several new communities form in places too far away Reticulum distinguishes between two types of nodes: **Instances**
from the core network to be reachable over WiFi links. New gateways similar to those and **Transport Nodes**. Every node running Reticulum is an Instance, but not
previously installed are set up for the new communities at the new sites D and E, but every Instance is a Transport Node.
they are islanded from the core network, and only serve the local users.
After investigating the options, it is found that it is possible to install an A **Reticulum Instance** is any system running the Reticulum stack. It can create
Internet connection at site A, and an interface on the Internet connection is destinations, send and receive packets, establish links, and communicate with
configured for Reticulum on the Raspberry Pi at site A. 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 member of the organisation at site D, named Dori, is willing to help by sharing A **Transport Node** is an Instance that has been explicitly configured to
the Internet connection she already has in her home, and is able to leave a Raspberry participate in network-wide transport. Transport nodes forward packets across
Pi running. A new Reticulum interface is configured on her Pi, connecting to the newly hops, propagate announces, maintain path tables, and serve path requests on
enabled Internet interface on the gateway at site A. Dori is now connected to both behalf of other nodes. When a destination sends an announce, Transport Nodes
the nodes at her own local site (through the hill-top LoRa gateway), and all the receive it, remember the path, and rebroadcast it to other interfaces. When a node
combined users of sites A, B and C. She then enables transport on her node, and needs to reach a destination it doesn't have a path for, Transport Nodes help
traffic from site D can now reach everyone at site A, B and C, and vice versa. resolve the path through the network.
Growth and Convergence 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.
As the organisation grows, more gateways are added to keep up with the growing user The distinction is important. **Not** every node should be a Transport Node:
base. Some local gateways even add VHF radios and packet modems to reach outlying users
and communities that are out of reach for the LoRa radios and WiFi backhauls.
As more sites, gateways and users are connected, the amount of coordination required * **Resource consumption:** Transport nodes maintain path tables, process
is kept to a minimum. If one community wants to add connectivity to the next one announces, and forward traffic. This requires memory and CPU resources that
over, it can simply be done without having to involve everyone or coordinate address may be limited on low-powered devices.
space or routing tables.
With the added geographical coverage, the operators at site A one day find that * **Stability requirements:** Transport nodes contribute to network convergence.
the original internet bridged interfaces are no longer utilised. The network has If Transport Nodes frequently go offline, path tables become stale and
converged to be completely self-connected, and the sites that were once poorly convergence suffers. Stable, always-on nodes make better Transport Nodes.
connected outliers are now an integral part of the network.
* **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.

4
docs/manual/_sources/whatis.rst.txt
View file

@ -188,6 +188,4 @@ Caveat Emptor
Reticulum is an experimental networking stack, and should be considered as Reticulum is an experimental networking stack, and should be considered as
such. While it has been built with cryptography best-practices very foremost in such. While it has been built with cryptography best-practices very foremost in
mind, it has not yet been externally security audited, and there could very well be mind, it has not yet been externally security audited, and there could very well be
privacy-breaking bugs. To be considered secure, Reticulum needs a thorough privacy-breaking bugs.
security review by independent cryptographers and security researchers. If you
want to help out with this, or can help sponsor an audit, please do get in touch.

11
docs/manual/index.html
View file

@ -430,11 +430,12 @@ to participate in the development of Reticulum itself.</p>
</ul> </ul>
</li> </li>
<li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a><ul> <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a><ul>
<li class="toctree-l2"><a class="reference internal" href="networks.html#concepts-overview">Concepts &amp; Overview</a></li> <li class="toctree-l2"><a class="reference internal" href="networks.html#concepts-overview">Concepts &amp; Overview</a><ul>
<li class="toctree-l2"><a class="reference internal" href="networks.html#example-scenarios">Example Scenarios</a><ul> <li class="toctree-l3"><a class="reference internal" href="networks.html#introductory-considerations">Introductory Considerations</a></li>
<li class="toctree-l3"><a class="reference internal" href="networks.html#interconnected-lora-sites">Interconnected LoRa Sites</a></li> <li class="toctree-l3"><a class="reference internal" href="networks.html#destinations-not-addresses">Destinations, Not Addresses</a></li>
<li class="toctree-l3"><a class="reference internal" href="networks.html#bridging-over-the-internet">Bridging Over the Internet</a></li> <li class="toctree-l3"><a class="reference internal" href="networks.html#transport-nodes-and-instances">Transport Nodes and Instances</a></li>
<li class="toctree-l3"><a class="reference internal" href="networks.html#growth-and-convergence">Growth and Convergence</a></li> <li class="toctree-l3"><a class="reference internal" href="networks.html#trustless-networking">Trustless Networking</a></li>
<li class="toctree-l3"><a class="reference internal" href="networks.html#heterogeneous-connectivity">Heterogeneous Connectivity</a></li>
</ul> </ul>
</li> </li>
</ul> </ul>

300
docs/manual/networks.html
View file

@ -259,15 +259,39 @@
<article role="main" id="furo-main-content"> <article role="main" id="furo-main-content">
<section id="building-networks"> <section id="building-networks">
<span id="networks-main"></span><h1>Building Networks<a class="headerlink" href="#building-networks" title="Link to this heading"></a></h1> <span id="networks-main"></span><h1>Building Networks<a class="headerlink" href="#building-networks" title="Link to this heading"></a></h1>
<p>This chapter will provide you with the knowledge needed to build networks with <p>This chapter will provide you with the high-level knowledge needed to build networks with
Reticulum, which can often be easier than using traditional stacks, since you Reticulum. It will not, however tell you all you need to know to succesfully
don’t have to worry about coordinating addresses, subnets and routing for an 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.</p>
<p>Still, after reading this chapter, you should be well equipped to <em>start</em> that
journey. While Reticulum is <strong>fundamentally different</strong> 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.</p>
<p>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 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 Reticulum, you can simply add more segments to your network when it becomes
necessary, and Reticulum will handle the convergence of the entire network necessary, and Reticulum will handle the convergence of the entire network
automatically.</p> automatically. There’s plenty more neat aspects like that to Reticulum, but
we’re getting ahead of ourselves. Let’s cover the basics first.</p>
<section id="concepts-overview"> <section id="concepts-overview">
<h2>Concepts &amp; Overview<a class="headerlink" href="#concepts-overview" title="Link to this heading"></a></h2> <h2>Concepts &amp; Overview<a class="headerlink" href="#concepts-overview" title="Link to this heading"></a></h2>
<p>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.</p>
<p>Reticulum is not a single network you “join”, it is a toolkit for <em>creating</em> 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.</p>
<p>This approach offers tremendous flexibility, but it requires thinking in terms of
different abstractions than those used in conventional networking.</p>
<section id="introductory-considerations">
<h3>Introductory Considerations<a class="headerlink" href="#introductory-considerations" title="Link to this heading"></a></h3>
<p>There are important points that need to be kept in mind when building networks <p>There are important points that need to be kept in mind when building networks
with Reticulum:</p> with Reticulum:</p>
<blockquote> <blockquote>
@ -289,7 +313,12 @@ also very useful when just a few devices needs to communicate.</div>
<div class="line">Low-bandwidth networks, like LoRa and packet radio, can interoperate and <div class="line">Low-bandwidth networks, like LoRa and packet radio, can interoperate and
interconnect with much larger and higher bandwidth networks without issue. interconnect with much larger and higher bandwidth networks without issue.
Reticulum automatically manages the flow of information to and from various Reticulum automatically manages the flow of information to and from various
network segments, and when bandwidth is limited, local traffic is prioritised.</div> 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 <em>will</em> waste a lot of precious bandwidth and airtime,
and your LoRa network will not work very well.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
@ -361,69 +390,197 @@ chapter of this manual for interface configuration examples.</p>
decide which are suitable to use in any given situation, depending on where decide which are suitable to use in any given situation, depending on where
traffic needs to flow.</p> traffic needs to flow.</p>
</section> </section>
<section id="example-scenarios"> <section id="destinations-not-addresses">
<h2>Example Scenarios<a class="headerlink" href="#example-scenarios" title="Link to this heading"></a></h2> <h3>Destinations, Not Addresses<a class="headerlink" href="#destinations-not-addresses" title="Link to this heading"></a></h3>
<p>This section illustrates a few example scenarios, and how they would, in general <p>In traditional networking, addresses are allocated from a managed space. If you want to
terms, be planned, implemented and configured.</p> communicate with another node, you need to know its address, and that address
<section id="interconnected-lora-sites"> must be unique within the network segment. This requires coordination, either
<h3>Interconnected LoRa Sites<a class="headerlink" href="#interconnected-lora-sites" title="Link to this heading"></a></h3> through manual assignment, DHCP servers, or other allocation mechanisms.</p>
<p>An organisation wants to provide communication and information services to it’s <p>Reticulum replaces addresses with <strong>destinations</strong>. A destination is identified by a 16-byte
members, which are located mainly in three separate areas. Three suitable hill-top hash (128 bits) derived from a SHA-256 hash of the destination’s identifying
locations are found, where the organisation can install equipment: Site A, B and C.</p> characteristics. This hash serves as the address on the network. On the network, it
<p>Since the amount of data that needs to be exchanged between users is mainly text- is represented in binary, but when displayed to human users, it will usually look something like
based, the bandwidth requirements are low, and LoRa radios are chosen to connect this <code class="docutils literal notranslate"><span class="pre">&lt;13425ec15b621c1d928589718000d814&gt;</span></code>.</p>
users to the network.</p> <p>The critical difference is that <em>any node can generate as many destinations as it
<p>Due to the hill-top locations found, there is radio line-of-sight between site A needs, without coordination</em>. A destination’s uniqueness is guaranteed by the
and B, and also between site B and C. Because of this, the organisation does not collision resistance of SHA-256 and the inclusion of the node’s public key in the
need to use the Internet to interconnect the sites, but purchases four Point-to-Point hash calculation. Two nodes can both use the destination name
WiFi based radios for interconnecting the sites.</p> <code class="docutils literal notranslate"><span class="pre">messenger.user.inbox</span></code>, but they will have different destination hashes because
<p>At each site, a Raspberry Pi is installed to function as a gateway. A LoRa radio their public keys differ. Both can coexist on the same network without conflict.</p>
is connected to the Pi with a USB cable, and the WiFi radio is connected to the <p>This has profound implications for network design:</p>
Ethernet port of the Pi. At site B, two WiFi radios are needed to be able to reach <ul class="simple">
both site A and site C, so an extra Ethernet adapter is connected to the Pi in <li><p><strong>No address allocation planning:</strong> You never need to reserve address ranges,
this location.</p> plan subnets, or coordinate with other network operators. Nodes simply generate
<p>Once the hardware has been installed, Reticulum is installed on all the Pis, and at destinations and announce them.</p></li>
site A and C, one interface is added for the LoRa radio, as well as one for the WiFi <li><p><strong>Global portability:</strong> A destination is not tied to a physical location or
radio. At site B, an interface for the LoRa radio, and one interface for each WiFi network segment. A node can move its destinations across interfaces, mediums,
radio is added to the Reticulum configuration file. The transport node option is or even between entirely separate Reticulum networks simply by sending an
enabled in the configuration of all three gateways.</p> announce on the new medium.</p></li>
<p>The network is now operational, and ready to serve users across all three areas. <li><p><strong>Implicit authentication:</strong> Because destinations are bound to public keys,
The organisation prepares a LoRa radio that is supplied to the end users, along communication to a destination is inherently cryptographically authenticated.
with a Reticulum configuration file, that contains the right parameters for Only the holder of the corresponding private key can decrypt and respond to
communicating with the LoRa radios installed at the gateway sites.</p> traffic addressed to that destination. This also makes application-level
<p>Once users connect to the network, anyone will be able to communicate with anyone authentication <em>much</em> simpler, since it can directly use the foundational
else across all three sites.</p> identity verification built into the core networking layer.</p></li>
<li><p><strong>Identity abstraction:</strong> 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.</p></li>
</ul>
</section> </section>
<section id="bridging-over-the-internet"> <section id="transport-nodes-and-instances">
<h3>Bridging Over the Internet<a class="headerlink" href="#bridging-over-the-internet" title="Link to this heading"></a></h3> <h3>Transport Nodes and Instances<a class="headerlink" href="#transport-nodes-and-instances" title="Link to this heading"></a></h3>
<p>As the organisation grows, several new communities form in places too far away <p>Reticulum distinguishes between two types of nodes: <strong>Instances</strong>
from the core network to be reachable over WiFi links. New gateways similar to those and <strong>Transport Nodes</strong>. Every node running Reticulum is an Instance, but not
previously installed are set up for the new communities at the new sites D and E, but every Instance is a Transport Node.</p>
they are islanded from the core network, and only serve the local users.</p> <p>A <strong>Reticulum Instance</strong> is any system running the Reticulum stack. It can create
<p>After investigating the options, it is found that it is possible to install an destinations, send and receive packets, establish links, and communicate with
Internet connection at site A, and an interface on the Internet connection is other nodes. It can also host destinations that are connectable for <em>anyone</em> else
configured for Reticulum on the Raspberry Pi at site A.</p> in the network. This means you can easily host globally available services from
<p>A member of the organisation at site D, named Dori, is willing to help by sharing any location, including your home or office. Network-wide, global connectivity
the Internet connection she already has in her home, and is able to leave a Raspberry for all destinations is guaranteed, as long as there is <em>some</em> physical way to
Pi running. A new Reticulum interface is configured on her Pi, connecting to the newly actually transport the packets. Instances are the default state and are appropriate for most end-user devices,
enabled Internet interface on the gateway at site A. Dori is now connected to both such as phones, laptops, sensors, or any device that primarily consumes network services.</p>
the nodes at her own local site (through the hill-top LoRa gateway), and all the <p>A <strong>Transport Node</strong> is an Instance that has been explicitly configured to
combined users of sites A, B and C. She then enables transport on her node, and participate in network-wide transport. Transport nodes forward packets across
traffic from site D can now reach everyone at site A, B and C, and vice versa.</p> 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.</p>
<p>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.</p>
<p>The distinction is important. <strong>Not</strong> every node should be a Transport Node:</p>
<ul class="simple">
<li><p><strong>Resource consumption:</strong> Transport nodes maintain path tables, process
announces, and forward traffic. This requires memory and CPU resources that
may be limited on low-powered devices.</p></li>
<li><p><strong>Stability requirements:</strong> 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.</p></li>
<li><p><strong>Bandwidth considerations:</strong> 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.</p></li>
</ul>
<p>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 <em>can</em> become a router if needed, and the decision is yours to make based on
your network’s requirements.</p>
<p>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.</p>
</section> </section>
<section id="growth-and-convergence"> <section id="trustless-networking">
<h3>Growth and Convergence<a class="headerlink" href="#growth-and-convergence" title="Link to this heading"></a></h3> <h3>Trustless Networking<a class="headerlink" href="#trustless-networking" title="Link to this heading"></a></h3>
<p>As the organisation grows, more gateways are added to keep up with the growing user <p>Traditional network security models assume high levels of trust at
base. Some local gateways even add VHF radios and packet modems to reach outlying users specific layers. You might trust your ISP to deliver packets without inspection,
and communities that are out of reach for the LoRa radios and WiFi backhauls.</p> or trust your VPN provider to handle your traffic, or trust the network
<p>As more sites, gateways and users are connected, the amount of coordination required administrator to configure firewalls appropriately. These trust relationships
is kept to a minimum. If one community wants to add connectivity to the next one create vulnerabilities and dependencies.</p>
over, it can simply be done without having to involve everyone or coordinate address <p>Reticulum is designed to function in <strong>open, trustless environments</strong>. This
space or routing tables.</p> means the protocol makes no assumptions about the trustworthiness of the network
<p>With the added geographical coverage, the operators at site A one day find that infrastructure, the other participants, or the transport mediums. Every aspect
the original internet bridged interfaces are no longer utilised. The network has of communication is secured cryptographically:</p>
converged to be completely self-connected, and the sites that were once poorly <ul class="simple">
connected outliers are now an integral part of the network.</p> <li><p><strong>Traffic encryption:</strong> All traffic to single destinations is encrypted using
ephemeral keys.</p></li>
<li><p><strong>Source anonymity:</strong> 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.</p></li>
<li><p><strong>Path verification:</strong> The announce mechanism includes cryptographic signatures that
prove the authenticity of destination announcements.</p></li>
<li><p><strong>Unforgeable delivery confirmations:</strong> 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.</p></li>
<li><p><strong>Interface authentication:</strong> 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.</p></li>
</ul>
<p>The trustless design has important consequences for network design:</p>
<ul class="simple">
<li><p><strong>Open-access networks are viable:</strong> 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.</p></li>
<li><p><strong>No traffic inspection or prioritization:</strong> 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.</p></li>
<li><p><strong>Adversarial resilience:</strong> 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.</p></li>
</ul>
<p>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.</p>
</section>
<section id="heterogeneous-connectivity">
<h3>Heterogeneous Connectivity<a class="headerlink" href="#heterogeneous-connectivity" title="Link to this heading"></a></h3>
<p>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.</p>
<p>Reticulum treats <strong>heterogeneity as a core premise</strong>. The protocol is designed
to seamlessly mix mediums with vastly different characteristics:</p>
<ul class="simple">
<li><p><strong>Bandwidth:</strong> 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.</p></li>
<li><p><strong>Latency:</strong> Satellite links with multi-second latency can coexist with local
links measured in milliseconds. The transport system handles timing, asynchronous
delivery and retransmissions transparently.</p></li>
<li><p><strong>Topology:</strong> 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.</p></li>
<li><p><strong>Reliability:</strong> 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.</p></li>
</ul>
<p>This heterogeneity is achieved through several design elements:</p>
<ul class="simple">
<li><p><strong>Expandable, medium-agnostic interface system:</strong> 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.</p></li>
<li><p><strong>Interface modes:</strong> Different modes (<code class="docutils literal notranslate"><span class="pre">full</span></code>, <code class="docutils literal notranslate"><span class="pre">gateway</span></code>, <code class="docutils literal notranslate"><span class="pre">access_point</span></code>,
<code class="docutils literal notranslate"><span class="pre">roaming</span></code>, <code class="docutils literal notranslate"><span class="pre">boundary</span></code>) allow you to configure how interfaces interact with
the wider network based on their characteristics and role.</p></li>
<li><p><strong>Announce propagation rules:</strong> 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.</p></li>
<li><p><strong>Local traffic prioritization:</strong> When bandwidth is constrained, Reticulum
prioritizes announces for nearby destinations. This ensures that local
connectivity remains functional even when global convergence is incomplete.</p></li>
</ul>
<p>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.</p>
<p>The key design consideration is not whether different mediums can work together
(they can), but <strong>how</strong> 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.</p>
</section> </section>
</section> </section>
</section> </section>
@ -483,11 +640,12 @@ connected outliers are now an integral part of the network.</p>
<div class="toc-tree"> <div class="toc-tree">
<ul> <ul>
<li><a class="reference internal" href="#">Building Networks</a><ul> <li><a class="reference internal" href="#">Building Networks</a><ul>
<li><a class="reference internal" href="#concepts-overview">Concepts &amp; Overview</a></li> <li><a class="reference internal" href="#concepts-overview">Concepts &amp; Overview</a><ul>
<li><a class="reference internal" href="#example-scenarios">Example Scenarios</a><ul> <li><a class="reference internal" href="#introductory-considerations">Introductory Considerations</a></li>
<li><a class="reference internal" href="#interconnected-lora-sites">Interconnected LoRa Sites</a></li> <li><a class="reference internal" href="#destinations-not-addresses">Destinations, Not Addresses</a></li>
<li><a class="reference internal" href="#bridging-over-the-internet">Bridging Over the Internet</a></li> <li><a class="reference internal" href="#transport-nodes-and-instances">Transport Nodes and Instances</a></li>
<li><a class="reference internal" href="#growth-and-convergence">Growth and Convergence</a></li> <li><a class="reference internal" href="#trustless-networking">Trustless Networking</a></li>
<li><a class="reference internal" href="#heterogeneous-connectivity">Heterogeneous Connectivity</a></li>
</ul> </ul>
</li> </li>
</ul> </ul>

2
docs/manual/reference.html
View file

@ -219,7 +219,7 @@
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li> <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li> <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li> <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
<li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li> <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks with Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li> <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li> <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
</ul> </ul>

2
docs/manual/searchindex.js
View file

File diff suppressed because one or more lines are too long

6
docs/manual/whatis.html
View file

@ -219,7 +219,7 @@
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li> <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li> <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li> <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
<li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li> <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks with Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li> <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li> <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
</ul> </ul>
@ -418,9 +418,7 @@ network, and vice versa.</p>
<p>Reticulum is an experimental networking stack, and should be considered as <p>Reticulum is an experimental networking stack, and should be considered as
such. While it has been built with cryptography best-practices very foremost in such. While it has been built with cryptography best-practices very foremost in
mind, it has not yet been externally security audited, and there could very well be mind, it has not yet been externally security audited, and there could very well be
privacy-breaking bugs. To be considered secure, Reticulum needs a thorough privacy-breaking bugs.</p>
security review by independent cryptographers and security researchers. If you
want to help out with this, or can help sponsor an audit, please do get in touch.</p>
</section> </section>
</section> </section>

1
docs/source/conf.py
View file

@ -24,6 +24,7 @@ release = RNS._version.__version__
extensions = [ extensions = [
"sphinx.ext.autodoc", "sphinx.ext.autodoc",
"sphinx_copybutton", "sphinx_copybutton",
"sphinx_markdown_builder",
] ]
autodoc_member_order = "bysource" autodoc_member_order = "bysource"

311
docs/source/networks.rst
View file

@ -4,17 +4,47 @@
Building Networks Building Networks
***************** *****************
This chapter will provide you with the knowledge needed to build networks with This chapter will provide you with the high-level knowledge needed to build networks with
Reticulum, which can often be easier than using traditional stacks, since you Reticulum. It will not, however tell you all you need to know to succesfully
don't have to worry about coordinating addresses, subnets and routing for an 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 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 Reticulum, you can simply add more segments to your network when it becomes
necessary, and Reticulum will handle the convergence of the entire network necessary, and Reticulum will handle the convergence of the entire network
automatically. 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 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 There are important points that need to be kept in mind when building networks
with Reticulum: with Reticulum:
@ -31,6 +61,11 @@ with Reticulum:
interconnect with much larger and higher bandwidth networks without issue. interconnect with much larger and higher bandwidth networks without issue.
Reticulum automatically manages the flow of information to and from various Reticulum automatically manages the flow of information to and from various
network segments, and when bandwidth is limited, local traffic is prioritised. 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 * | Reticulum provides sender/initiator anonymity by default. There is no way
to filter traffic or discriminate it based on the source of the traffic. to filter traffic or discriminate it based on the source of the traffic.
@ -89,81 +124,227 @@ Any number of interfaces can be configured, and Reticulum will automatically
decide which are suitable to use in any given situation, depending on where decide which are suitable to use in any given situation, depending on where
traffic needs to flow. traffic needs to flow.
Example Scenarios Destinations, Not Addresses
----------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^
This section illustrates a few example scenarios, and how they would, in general In traditional networking, addresses are allocated from a managed space. If you want to
terms, be planned, implemented and configured. 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.
Interconnected LoRa Sites 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>``.
An organisation wants to provide communication and information services to it's The critical difference is that *any node can generate as many destinations as it
members, which are located mainly in three separate areas. Three suitable hill-top needs, without coordination*. A destination's uniqueness is guaranteed by the
locations are found, where the organisation can install equipment: Site A, B and C. 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.
Since the amount of data that needs to be exchanged between users is mainly text- This has profound implications for network design:
based, the bandwidth requirements are low, and LoRa radios are chosen to connect
users to the network.
Due to the hill-top locations found, there is radio line-of-sight between site A * **No address allocation planning:** You never need to reserve address ranges,
and B, and also between site B and C. Because of this, the organisation does not plan subnets, or coordinate with other network operators. Nodes simply generate
need to use the Internet to interconnect the sites, but purchases four Point-to-Point destinations and announce them.
WiFi based radios for interconnecting the sites.
At each site, a Raspberry Pi is installed to function as a gateway. A LoRa radio * **Global portability:** A destination is not tied to a physical location or
is connected to the Pi with a USB cable, and the WiFi radio is connected to the network segment. A node can move its destinations across interfaces, mediums,
Ethernet port of the Pi. At site B, two WiFi radios are needed to be able to reach or even between entirely separate Reticulum networks simply by sending an
both site A and site C, so an extra Ethernet adapter is connected to the Pi in announce on the new medium.
this location.
Once the hardware has been installed, Reticulum is installed on all the Pis, and at * **Implicit authentication:** Because destinations are bound to public keys,
site A and C, one interface is added for the LoRa radio, as well as one for the WiFi communication to a destination is inherently cryptographically authenticated.
radio. At site B, an interface for the LoRa radio, and one interface for each WiFi Only the holder of the corresponding private key can decrypt and respond to
radio is added to the Reticulum configuration file. The transport node option is traffic addressed to that destination. This also makes application-level
enabled in the configuration of all three gateways. authentication *much* simpler, since it can directly use the foundational
identity verification built into the core networking layer.
The network is now operational, and ready to serve users across all three areas. * **Identity abstraction:** A single Reticulum Identity can create multiple
The organisation prepares a LoRa radio that is supplied to the end users, along destinations. This allows a single entity (a person, a device, a service) to
with a Reticulum configuration file, that contains the right parameters for present multiple endpoints without needing multiple cryptographic keypairs.
communicating with the LoRa radios installed at the gateway sites.
Once users connect to the network, anyone will be able to communicate with anyone
else across all three sites.
Bridging Over the Internet Transport Nodes and Instances
========================== ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As the organisation grows, several new communities form in places too far away Reticulum distinguishes between two types of nodes: **Instances**
from the core network to be reachable over WiFi links. New gateways similar to those and **Transport Nodes**. Every node running Reticulum is an Instance, but not
previously installed are set up for the new communities at the new sites D and E, but every Instance is a Transport Node.
they are islanded from the core network, and only serve the local users.
After investigating the options, it is found that it is possible to install an A **Reticulum Instance** is any system running the Reticulum stack. It can create
Internet connection at site A, and an interface on the Internet connection is destinations, send and receive packets, establish links, and communicate with
configured for Reticulum on the Raspberry Pi at site A. 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 member of the organisation at site D, named Dori, is willing to help by sharing A **Transport Node** is an Instance that has been explicitly configured to
the Internet connection she already has in her home, and is able to leave a Raspberry participate in network-wide transport. Transport nodes forward packets across
Pi running. A new Reticulum interface is configured on her Pi, connecting to the newly hops, propagate announces, maintain path tables, and serve path requests on
enabled Internet interface on the gateway at site A. Dori is now connected to both behalf of other nodes. When a destination sends an announce, Transport Nodes
the nodes at her own local site (through the hill-top LoRa gateway), and all the receive it, remember the path, and rebroadcast it to other interfaces. When a node
combined users of sites A, B and C. She then enables transport on her node, and needs to reach a destination it doesn't have a path for, Transport Nodes help
traffic from site D can now reach everyone at site A, B and C, and vice versa. resolve the path through the network.
Growth and Convergence 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.
As the organisation grows, more gateways are added to keep up with the growing user The distinction is important. **Not** every node should be a Transport Node:
base. Some local gateways even add VHF radios and packet modems to reach outlying users
and communities that are out of reach for the LoRa radios and WiFi backhauls.
As more sites, gateways and users are connected, the amount of coordination required * **Resource consumption:** Transport nodes maintain path tables, process
is kept to a minimum. If one community wants to add connectivity to the next one announces, and forward traffic. This requires memory and CPU resources that
over, it can simply be done without having to involve everyone or coordinate address may be limited on low-powered devices.
space or routing tables.
With the added geographical coverage, the operators at site A one day find that * **Stability requirements:** Transport nodes contribute to network convergence.
the original internet bridged interfaces are no longer utilised. The network has If Transport Nodes frequently go offline, path tables become stale and
converged to be completely self-connected, and the sites that were once poorly convergence suffers. Stable, always-on nodes make better Transport Nodes.
connected outliers are now an integral part of the network.
* **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.

4
docs/source/whatis.rst
View file

@ -188,6 +188,4 @@ Caveat Emptor
Reticulum is an experimental networking stack, and should be considered as Reticulum is an experimental networking stack, and should be considered as
such. While it has been built with cryptography best-practices very foremost in such. While it has been built with cryptography best-practices very foremost in
mind, it has not yet been externally security audited, and there could very well be mind, it has not yet been externally security audited, and there could very well be
privacy-breaking bugs. To be considered secure, Reticulum needs a thorough privacy-breaking bugs.
security review by independent cryptographers and security researchers. If you
want to help out with this, or can help sponsor an audit, please do get in touch.