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

Added markdown manual

Browse Source
This commit is contained in:
Mark Qvist
2026-05-06 19:25:28 +02:00
parent b8d6a14599
commit 49f56e7d0d
18 changed files with 11464 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/markdown/networks.md
+322
View File
@@ -0,0 +1,322 @@
<a id="networks-main"></a>
# Building Networks
This chapter will provide you with the high-level knowledge needed to build networks with
Reticulum. It will not, however tell you all you need to know to succesfully
design and configure every kind of network you can imagine. For this, you will
most likely need to read this manual in its entirity, invest significant time
into experimenting with the stack, and learning functionality intuitively.
Still, after reading this chapter, you should be well equipped to *start* that
journey. While Reticulum is **fundamentally different** compared to other
networking technologies, it can often be easier than using traditional stacks.
If you’ve built networks before, you will probably have to forget, or at least
temporarily ignore, a lot of things at this point. It will all makes sense in
the end though. Hopefully.
If you’re used to protocols like IP, let’s at least start with some relief:
You don’t have to worry about coordinating addresses, subnets and routing for an
entire network that you might not know how will evolve in the future. With
Reticulum, you can simply add more segments to your network when it becomes
necessary, and Reticulum will handle the convergence of the entire network
automatically. There’s plenty more neat aspects like that to Reticulum, but
we’re getting ahead of ourselves. Let’s cover the basics first.
## Concepts & Overview
Before you start building your own networks, it’s important to understand the
fundamental principles that distinguish Reticulum networks from traditional
networking approaches. These principles shape how you design your network,
what trade-offs you encounter, and what capabilities you can rely on.
Reticulum is not a single network you “join”, it is a toolkit for *creating* networks.
You decide what mediums to use, how nodes connect, what trust boundaries exist,
and what the network’s purpose is. Reticulum provides the cryptographic foundation,
the transport mechanisms, and the convergence algorithms that make your design
workable. You provide the intent and the structure.
This approach offers tremendous flexibility, but it requires thinking in terms of
different abstractions than those used in conventional networking.
### Introductory Considerations
There are important points that need to be kept in mind when building networks
with Reticulum:
> * In a Reticulum network, any node can autonomously generate as many addresses
> (called *destinations* in Reticulum terminology) as it needs, which become
> globally reachable to the rest of the network. There is no central point of
> control over the address space.
> <br/>
> * Reticulum was designed to handle both very small, and very large networks.
> While the address space can support billions of endpoints, Reticulum is
> also very useful when just a few devices needs to communicate.
> <br/>
> * Low-bandwidth networks, like LoRa and packet radio, can interoperate and
> interconnect with much larger and higher bandwidth networks without issue.
> Reticulum automatically manages the flow of information to and from various
> network segments, and when bandwidth is limited, local traffic is prioritised.
> You will, however, need to configure your interfaces correctly. If you tell
> Reticulum to pass all announce traffic from a gigabit link to a LoRa interfaces,
> it will try as best as possible to comply with this, while still respecting
> bandwidth limits, but you *will* waste a lot of precious bandwidth and airtime,
> and your LoRa network will not work very well.
> <br/>
> * Reticulum provides sender/initiator anonymity by default. There is no way
> to filter traffic or discriminate it based on the source of the traffic.
> <br/>
> * All traffic is encrypted using ephemeral keys generated by an Elliptic Curve
> Diffie-Hellman key exchange on Curve25519. There is no way to inspect traffic
> contents, and no way to prioritise or throttle certain kinds of traffic.
> All transport and routing layers are thus completely agnostic to traffic type,
> and will pass all traffic equally.
> <br/>
> * Reticulum can function both with and without infrastructure. When *transport
> nodes* are available, they can route traffic over multiple hops for other
> nodes, and will function as a distributed cryptographic keystore. When there
> is no transport nodes available, all nodes that are within communication range
> can still communicate.
> <br/>
> * Every node can become a transport node, simply by enabling it in it’s
> configuration, but there is no need for every node on the network to be a
> transport node. Letting every node be a transport node will in most cases
> degrade the performance and reliability of the network.
> <br/>
> > *In general terms, if a node is stationary, well-connected and kept running
> > most of the time, it is a good candidate to be a transport node. For optimal
> > performance, a network should contain the amount of transport nodes that
> > provides connectivity to the intended area / topography, and not many more
> > than that.*
> * Reticulum is designed to work reliably in open, trustless environments. This
> means you can use it to create open-access networks, where participants can
> join and leave in a free and unorganised manner. This property allows an
> entirely new, and so far, mostly unexplored class of networked applications,
> where networks, and the information flow within them can form and dissolve
> organically.
> <br/>
> * You can just as easily create closed networks, since Reticulum allows you to
> add authentication to any interface. This means you can restrict access on
> any interface type, even when using legacy devices, such as modems. You can
> also mix authenticated and open interfaces on the same system. See the
> [Common Interface Options](interfaces.md#interfaces-options) section of the [Interfaces](interfaces.md#interfaces-main)
> chapter of this manual for information on how to set up interface authentication.
> <br/>
Reticulum allows you to mix very different kinds of networking mediums into a
unified mesh, or to keep everything within one medium. You could build a “virtual
network” running entirely over the Internet, where all nodes communicate over TCP
and UDP “channels”. You could also build such a network using other already-established
communications channels as the underlying carrier for Reticulum.
However, most real-world networks will probably involve either some form of
wireless or direct hardline communications. To allow Reticulum to communicate
over any type of medium, you must specify it in the configuration file, by default
located at `~/.reticulum/config`. See the [Supported Interfaces](interfaces.md#interfaces-main)
chapter of this manual for interface configuration examples.
Any number of interfaces can be configured, and Reticulum will automatically
decide which are suitable to use in any given situation, depending on where
traffic needs to flow.
### Destinations, Not Addresses
In traditional networking, addresses are allocated from a managed space. If you want to
communicate with another node, you need to know its address, and that address
must be unique within the network segment. This requires coordination, either
through manual assignment, DHCP servers, or other allocation mechanisms.
Reticulum replaces addresses with **destinations**. A destination is identified by a 16-byte
hash (128 bits) derived from a SHA-256 hash of the destination’s identifying
characteristics. This hash serves as the address on the network. On the network, it
is represented in binary, but when displayed to human users, it will usually look something like
this `<13425ec15b621c1d928589718000d814>`.
The critical difference is that *any node can generate as many destinations as it
needs, without coordination*. A destination’s uniqueness is guaranteed by the
collision resistance of SHA-256 and the inclusion of the node’s public key in the
hash calculation. Two nodes can both use the destination name
`messenger.user.inbox`, but they will have different destination hashes because
their public keys differ. Both can coexist on the same network without conflict.
This has profound implications for network design:
* **No address allocation planning:** You never need to reserve address ranges,
plan subnets, or coordinate with other network operators. Nodes simply generate
destinations and announce them.
* **Global portability:** A destination is not tied to a physical location or
network segment. A node can move its destinations across interfaces, mediums,
or even between entirely separate Reticulum networks simply by sending an
announce on the new medium.
* **Implicit authentication:** Because destinations are bound to public keys,
communication to a destination is inherently cryptographically authenticated.
Only the holder of the corresponding private key can decrypt and respond to
traffic addressed to that destination. This also makes application-level
authentication *much* simpler, since it can directly use the foundational
identity verification built into the core networking layer.
* **Identity abstraction:** A single Reticulum Identity can create multiple
destinations. This allows a single entity (a person, a device, a service) to
present multiple endpoints without needing multiple cryptographic keypairs.
### Transport Nodes and Instances
Reticulum distinguishes between two types of nodes: **Instances**
and **Transport Nodes**. Every node running Reticulum is an Instance, but not
every Instance is a Transport Node.
A **Reticulum Instance** is any system running the Reticulum stack. It can create
destinations, send and receive packets, establish links, and communicate with
other nodes. It can also host destinations that are connectable for *anyone* else
in the network. This means you can easily host globally available services from
any location, including your home or office. Network-wide, global connectivity
for all destinations is guaranteed, as long as there is *some* physical way to
actually transport the packets. Instances are the default state and are appropriate for most end-user devices,
such as phones, laptops, sensors, or any device that primarily consumes network services.
A **Transport Node** is an Instance that has been explicitly configured to
participate in network-wide transport. Transport nodes forward packets across
hops, propagate announces, maintain path tables, and serve path requests on
behalf of other nodes. When a destination sends an announce, Transport Nodes
receive it, remember the path, and rebroadcast it to other interfaces. When a node
needs to reach a destination it doesn’t have a path for, Transport Nodes help
resolve the path through the network.
Even devices hosting services or serving content should probably just be configured
as instances, and themselves connect to wider networks via a Transport Node.
In some situations, this may not be practical though, and as an example, it is
entirely viable to host a personal Transport Node on a Raspberry Pi, while it
is at the same time running an LXMF propagation node, and hosting your personal
site or files over Reticulum.
The distinction is important. **Not** every node should be a Transport Node:
* **Resource consumption:** Transport nodes maintain path tables, process
announces, and forward traffic. This requires memory and CPU resources that
may be limited on low-powered devices.
* **Stability requirements:** Transport nodes contribute to network convergence.
If Transport Nodes frequently go offline, path tables become stale and
convergence suffers. Stable, always-on nodes make better Transport Nodes.
* **Bandwidth considerations:** Transport nodes process and rebroadcast network
maintenance traffic. On very low-bandwidth mediums, having too many Transport
Nodes will consume capacity that should be used for actual data.
In practice, a network typically has a relatively small number of Transport Nodes
strategically placed to provide coverage and connectivity. End-user devices run
as Instances, connecting through nearby Transport Nodes to reach the wider network.
This pattern mirrors traditional networking where routers forward traffic while
end hosts simply consume connectivity, but with the crucial difference that any
node *can* become a router if needed, and the decision is yours to make based on
your network’s requirements.
Transport nodes also function as distributed cryptographic keystores. When a
destination announces itself, Transport Nodes cache the public key and destination
information. Other nodes can request unknown public keys from the network, and
Transport Nodes respond with the cached information. This eliminates the need for
a central directory service while ensuring that public keys remain available
throughout the network.
### Trustless Networking
Traditional network security models assume high levels of trust at
specific layers. You might trust your ISP to deliver packets without inspection,
or trust your VPN provider to handle your traffic, or trust the network
administrator to configure firewalls appropriately. These trust relationships
create vulnerabilities and dependencies.
Reticulum is designed to function in **open, trustless environments**. This
means the protocol makes no assumptions about the trustworthiness of the network
infrastructure, the other participants, or the transport mediums. Every aspect
of communication is secured cryptographically:
* **Traffic encryption:** All traffic to single destinations is encrypted using
ephemeral keys.
* **Source anonymity:** Reticulum packets do not include source addresses.
An observer intercepting a packet cannot determine who sent it, only who it is
addressed to (unless IFAC is enabled, in which case nothing can be determined).
This provides initiator anonymity by default.
* **Path verification:** The announce mechanism includes cryptographic signatures that
prove the authenticity of destination announcements.
* **Unforgeable delivery confirmations:** When a destination proves receipt of a
packet, the proof is signed with the destination’s identity key. This prevents
false acknowledgments and ensures reliable delivery verification.
* **Interface authentication:** When using Interface Access Codes (IFAC), packets
on authenticated interfaces carry signatures derived from a shared secret. Only
nodes with the correct network name and passphrase can generate valid packets, allowing creation
of virtual private networks on shared mediums.
The trustless design has important consequences for network design:
* **Open-access networks are viable:** You can build networks that anyone can
join without pre-approval. Because traffic is encrypted and authenticated end-
to-end, participants cannot interfere with each other’s private communication,
even if they share the same transport infrastructure.
* **No traffic inspection or prioritization:** Because traffic contents and
sources are opaque to intermediate nodes, there is no mechanism for filtering,
prioritizing, or throttling traffic based on its type or origin. All traffic
is treated equally. From a neutrality perspective, this is a feature.
* **Adversarial resilience:** The network can operate even if some nodes are
malicious or controlled by adversaries. While a malicious Transport Node could
refuse to forward certain traffic or drop packets, it cannot decrypt, modify,
or impersonate legitimate traffic. Redundant paths and multiple Transport Nodes
mitigate the impact of malicious nodes.
Of course, you can also create closed networks. Interface Access
Codes allow you to restrict participation on specific interfaces. Network
Identities enable you to verify that discovered interfaces belong to trusted
operators. Blackhole management lets you block malicious identities. Reticulum
provides both the tools for open networks and the controls for closed ones. The
choice is yours based on your requirements.
### Heterogeneous Connectivity
In conventional networking, mixing different transport mediums typically requires
gateways, translation layers, and careful configuration. A WiFi network doesn’t
natively interoperate with a packet radio network without additional infrastructure,
and you can’t just download a car over a serial port, or send an encrypted message
in a QR code.
Reticulum treats **heterogeneity as a core premise**. The protocol is designed
to seamlessly mix mediums with vastly different characteristics:
* **Bandwidth:** LoRa links operating at a few hundred bits per second can
interconnect with gigabit Ethernet backbones. Reticulum automatically manages
the flow of information, prioritizing local traffic on slow segments while
allowing global convergence.
* **Latency:** Satellite links with multi-second latency can coexist with local
links measured in milliseconds. The transport system handles timing, asynchronous
delivery and retransmissions transparently.
* **Topology:** Point-to-point microwave links, broadcast radio networks,
switched Ethernet fabrics, and virtual tunnels over the Internet can all be
part of the same Reticulum network.
* **Reliability:** Intermittent connections that come and go (such as mobile
devices or opportunistic radio contacts) can participate alongside always-on
infrastructure. Reticulum gracefully handles link loss and reconnection.
This heterogeneity is achieved through several design elements:
* **Expandable, medium-agnostic interface system:** Reticulum communicates with the physical
world through interface modules. Adding support for a new medium is a matter
of implementing an interface class. The protocol itself remains unchanged.
* **Interface modes:** Different modes (`full`, `gateway`, `access_point`,
`roaming`, `boundary`) allow you to configure how interfaces interact with
the wider network based on their characteristics and role.
* **Announce propagation rules:** Announces are forwarded between interfaces
according to rules that account for bandwidth limitations and interface modes.
Slow segments are not overwhelmed by traffic from fast segments.
* **Local traffic prioritization:** When bandwidth is constrained, Reticulum
prioritizes announces for nearby destinations. This ensures that local
connectivity remains functional even when global convergence is incomplete.
For network designers, this means you are free to use whatever mediums are
available, affordable, or appropriate for your situation. You might use LoRa for
wide-area low-bandwidth coverage, WiFi for local high-capacity links, I2P for
anonymous Internet connectivity, and Ethernet for infrastructure backhauls, all
within the same network. Reticulum handles the translation and coordination
automatically.
The key design consideration is not whether different mediums can work together
(they can), but **how** they should work together based on your goals. A node
with multiple interfaces spanning heterogeneous mediums needs to be configured
with appropriate interface modes so that traffic flows efficiently. A gateway
connecting a slow LoRa segment to a fast Internet backbone should be configured
differently than a mobile device roaming between radio cells.